dblogin

Description

Allocates a login record for use in dbopen.

Syntax

LOGINREC *dblogin()

Returns

A pointer to a LOGINREC structure. dblogin returns NULL if the structure could not be allocated.

Usage

• This routine allocates a LOGINREC structure for use with dbopen.

• There are various routines available to supply components of the LOGINREC. The program may supply the host name, user name, user password, and application name—via DBSETLHOST, DBSETLUSER, DBSETLPWD, and DBSETAPP, respectively. It is generally only necessary for the program to supply the user password (and even this can be eliminated if the password is a null value). The other variables in the LOGINREC structure will be set to default values.

• Other components of the LOGINREC may also be changed:

  • The national language name can be set in a LOGINREC structure using DBSETLNATLANG. Call DBSETLNATLANG only if you do not wish to use the server’s default national language.

  • The TDS packet size can be set in a LOGINREC using DBSETLPACKET. If not explicitly set, the TDS packet size defaults to 512 bytes. TDS is an application protocol used for the exchange of information between clients and servers.

  • The character set can be set in a LOGINREC using DBSETLCHARSET. An application needs to call DBSETLCHARSET only if it is not using ISO-8859-1 (known to the server as “iso_1”).

• When a connection attempt is made between a client and a server, there are two ways in which the connection can fail (assuming that the system is correctly configured):

  • The machine that the server is supposed to be on is running correctly and the network is running correctly.

    In this case, if there is no server listening on the specified port, the machine the server is supposed to be on will signal the client, using a network error, that the connection cannot be formed. Regardless of dbsetlogintime, the connection will fail.

  • The machine that the server is on is down.

    In this case, the machine that the server is supposed to be on will not respond. Because “no response” is not considered to be an error, the network will not signal the client that an error has occurred. However, if dbsetlogintime has been called to set a timeout period, a timeout error will occur when the client fails to receive a response within the set period.

• Here is a program fragment that uses dblogin:

  DBPROCESS    *dbproc; 
  

  LOGINREC     *loginrec; 
  

   loginrec = dblogin(); 
  

   DBSETLPWD(loginrec, "server_password"); 
  

   DBSETLAPP(loginrec, "my_program"); 
  

   dbproc = dbopen(loginrec, "my_server"); 
  

• Once the application has made all its dbopen calls, the LOGINREC structure is no longer necessary. The program can then call dbloginfree to free the LOGINREC structure.

See also