(a) TP1/Client/W

_s version of the function

#include <dcvclt.h>
DCLONG dc_clt_cltin_s(HWND hWnd, DCCLT_ID *cltid,
                      char *defpath,
                      char *target_host,
                      char *logname,
                      char *passwd,
                      char *set_host, DCLONG flags)

Non-_s version of the function

#include <dcvclt.h>
int dc_clt_cltin(char *target_host,
                 char *logname,
                 char *passwd,
                 char *set_host, DCLONG flags)

(b) TP1/Client/P

_s version of the function

#include <dcvclt.h>
DCLONG dc_clt_cltin_s(HWND hWnd, DCCLT_ID CLTFAR *cltid,
                      char CLTFAR *defpath,
                      char CLTFAR *target_host,
                      char CLTFAR *logname,
                      char CLTFAR *passwd,
                      char CLTFAR *set_host, DCLONG flags)

Non-_s version of the function

#include <dcvclt.h>
int dc_clt_cltin(char CLTFAR *target_host,
                 char CLTFAR *logname,
                 char CLTFAR *passwd,
                 char CLTFAR *set_host, DCLONG flags)

Requests TP1/Server as a gateway to verify the client user specified by the login name.

Always execute the dc_clt_cltin_s function even when you suppress user authentication.

• hWnd
  Specify NULL.
  
• cltid
  Pointer to the area that receives the client ID (defined in the header file dcvclt.h; its type is DCCLT_ID).
  When authentication of the client user terminates normally, the client ID is set in the specified area. The client ID must not be destroyed before the dc_clt_cltout_s function is issued.
  The acquired client ID can only be used within the thread in which this function was issued. If you use dc_rpc_call_s or other functions to pass the client ID to another thread, the other thread may operate incorrectly.
  
• defpath
  Specify the path name of the client environment definition file. The path name must be specified with the full path or with a relative path from the current drive and the current directory. The following shows the order in which files are loaded when the path name is specified.
  
  • In TP1/Client/P
    Client environment definition files are loaded in the following order:
    1. The BETRAN.INI file in the Windows directory
    2. The client environment definition file specified in the defpath argument
    The definitions in both the client environment definition file and the BETRAN.INI file take effect.
    If the same definition is specified in each file with a different value, the value specified in the client environment definition file takes effect.
    If neither the client environment definition file nor the BETRAN.INI file contains the necessary specification, TP1/Client/P uses the defaults.
    
  • In TP1/Client/W
    All definitions specified in the environment variables will be invalid. TP1/Client/W uses the defaults for definitions that are not specified in the client environment definition file specified in the defpath argument.
    
  You can omit the path name by specifying NULL at the beginning of the defpath argument. The following describes the operation when the path name is omitted.
  
  • In TP1/Client/P
    TP1/Client/P uses the BETRAN.INI file in the Windows directory as the client environment definition file. If the BETRAN.INI file does not exist or if the contents of the definition file are invalid, TP1/Client/P uses the defaults.
    
  • In TP1/Client/W
    TP1/Client/W uses the values specified in the environment variables. If an environment variable is not specified, TP1/Client/W uses the default.
    
  The following describes operation when the client environment definition file specified in the defpath argument does not exist or when the contents of the definition file are invalid.
  
  • In TP1/Client/P
    TP1/Client/P uses the BETRAN.INI file in the Windows directory as the client environment definition file. If the BETRAN.INI file does not exist or if the contents of the definition file are invalid, TP1/Client/P uses the defaults.
    
  • In TP1/Client/W
    TP1/Client/W uses the defaults. The values specified in the environment variables will be invalid.
    
• target_host
  Specify the host name and port number of TP1/Server that is used as a gateway when authentication is requested. Multiple TP1/Servers can be specified as gateways (use commas (,) to delimit them).
  You can specify a maximum of 63^# characters for the host name. When specifying multiple host names, you can specify a maximum of 255^# characters, including port numbers, in the target_host argument.
  

  Form:

  host-computer-name[:port-number][,host-computer-name[:port-number],...]

  host-computer-name~<character string>

  port-number~<unsigned integer>((5001-65535))

  Do not place a null character (space or tab) except after the separator (,).

  You can specify an IP address in decimal dot notation for the host name.
  When the port number is omitted, the value for client environment definition DCNAMPORT is assumed.
  When you have specified more than one TP1/Server in the target_host argument and an error is detected in the TP1/Server being used as a gateway, system operation depends on the specification of DCHOSTSELECT in the client environment definition. If N is specified for DCHOSTSELECT, the system attempts to replace the failed node by referencing the next TP1/Server of the currently used TP1/Server. If Y is specified for DCHOSTSELECT, the system selects a TP1/Server at random (excluding the TP1/Server in which the error was detected) and attempts to replace the failed node.
  When NULL is specified, the function references client environment definition DCHOST. If target_host is NULL and DCHOST is not set, a broadcast is performed to determine the target host computer.
  To perform a broadcast in TP1/Client/P, you must specify the broadcast address in the hosts file (the host name must be broadcast). If the host name is not specified, the dc_clt_cltin_s function returns a DCCLTER_SYSERR error.
  

  # If you specify 00000008 for DCCLTOPTION in the client environment definition, you can specify a maximum of 255 characters for the host name. When specifying multiple host names, you can specify a maximum of 1023 characters, including port numbers, in the target_host argument.

• logname
  Specify the login name of the client user. The login name can have a maximum of 15 characters. To communicate with a server other than TP1/Server, specify a value other than NULL. If you specify NULL, the function returns an error.
  
• passwd
  Specify the password for the login name specified for logname. The password can have a maximum of 15 characters. Set passwd to NULL if not setting the password.
  
• set_host
  Pointer to a 64-byte^# area containing the name of the host that actually received the client user authentication request. The host name is not stored if NULL is specified.
  

  ^# If you specify 00000008 for DCCLTOPTION in the client environment definition, this value is 256 bytes, not 64 bytes.

• flags
  Specify DCCLT_NO_AUTHENT to suppress user authentication for using the remote API facility. Specify DCNOFLAGS not to suppress user authentication.
  

• cltid
  Specifies the area for containing the returned client ID.
  
• set_host
  Specifies the area for storing the returned host name (or IP address in decimal-dot notation) of the server that actually performed user authentication. Nothing is returned if you suppress user authentication.
  

Return Value	Value (decimal)	Meaning
DC_OK	0	Normal termination
DCCLTER_INVALID_ARGS	-2501	Invalid argument
DCCLTER_PROTO	-2502	The dc_clt_cltin function has already been issued. This value is not returned if the dc_clt_cltin_s function is executed.
DCCLTER_FATAL	-2503	Channel initialization failed. Or, the client environment is wrongly specified.
DCCLTER_NO_BUFS	-2504	A necessary amount of buffer could not be allocated. Alternatively, the resource became insufficient.
DCCLTER_NET_DOWN	-2506	Communication fault
DCCLTER_OLTF_NOT_UP	-2515	OpenTP1 is not running on the requested service node.
DCCLTER_SYSERR	-2518	System error
DCCLTER_REJECT	-2527	The specified login name is not registered in the target host, or the password does not match. Alternatively, the OpenTP1 server may not support user authentication. Check whether client_uid_check is specified correctly in the system common definition.
DCCLTER_PORT_IN_USE	-2547	A specified port number is in use. Alternatively, port numbers that can be assigned automatically by the operating system are insufficient.

• When TP1/Server runs on UNIX and an asterisk (*) is set in the encryption password field by the security facility, TP1/Server cannot perform user authentication. In this case, the dc_clt_cltin_s function returns a DCCLTER_REJECT error.
• If the dc_clt_cltin_s function returns an error, you cannot specify the cltid argument in a TP1/Client function to be issued because the specified cltid argument will be invalid. You will need to start over from execution of the dc_clt_cltin_s function.
• When you specify the area for receiving the value of the set_host argument, you must specify at least 64 bytes^#. If the area is smaller than 64 bytes^#, the area may be corrupted during TP1/Client internal processing. The argument value is not stored when you suppress user authentication.
  

  # If you specify 00000008 for DCCLTOPTION in the client environment definition, this value is 256 bytes, not 64 bytes.

• In TP1/Client, you can use a different client environment definition for each dc_clt_cltin_s function call. To do so, create a separate client environment definition file for each dc_clt_cltin_s function call, and specify the file name in the defpath argument of the function.