(a) In a multi-thread environment

PROCEDURE DIVISION

 
CALL 'CBLDCCLS' USING identifier-1 identifier-2 identifier-3
 

DATA DIVISION

 
01 identifier-1.
   02 data-name-A PIC X(8)  VALUE 'EXCLTIN '.
   02 data-name-B PIC X(5).
   02 FILLER     PIC X(3).
   02 data-name-C PIC S9(9) COMP VALUE ZERO.
   02 data-name-D PIC X(16).
   02 data-name-E PIC X(16).
   02 data-name-F PIC X(n).
01 identifier-2.
   02 FILLER     PIC X(9) COMP.
   02 data-name-G PIC X(n).
01 identifier-3.
   02 data-name-H PIC 9(9) COMP.
   02 FILLER     PIC 9(4) COMP.
   02 FILLER     PIC X(2).
   02 data-name-I  PIC X(n).
 

(b) In a single-thread environment

PROCEDURE DIVISION

 
CALL 'CBLDCCLT' USING identifier-1 identifier-2
 

DATA DIVISION

 
01 identifier-1.
   02 data-name-A PIC X(8)  VALUE 'EXCLTIN '.
   02 data-name-B PIC X(5).
   02 FILLER     PIC X(3).
   02 data-name-C PIC S9(9) COMP VALUE ZERO.
   02 data-name-D PIC X(16).
   02 data-name-E PIC X(16).
   02 data-name-F PIC X(n).
01 identifier-2.
   02 FILLER     PIC X(9) COMP.
   02 data-name-G  PIC X(n).
 

Requests authentication of the client user specified with the login name corresponding to the specified TP1/Server to be used as a gateway.

Always execute CBLDCCLS('EXCLTIN '), even if you have suppressed user authentication.

Use this function when using the host name extension function.

• data-name-A
  Set VALUE 'EXCLTIN' as a request code for the client user authentication request.
  
• data-name-C
  Set -2147483648 to suppress user authentication for using the remote API facility. Set 0 not to suppress user authentication.
  
• data-name-D
  Set the client user's login name.
  Terminate the character string with a blank.
  
• data-name-E
  Set a password for the login name specified with data-name-D. If no password is available, place a blank at the beginning of data-name-E.
  Terminate the character string with a blank.
  
• data-name-F
  Set the host name and port number of the TP1/Server you want to use as a gateway when issuing an authentication request. You can specify more than one TP1/Server for use as a gateway by separating them with a comma (,).
  You can also specify an IP address in decimal dot notation for the host name.
  

  Format

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

  host-name~<character string>

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

  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 data-name-F. Terminate the character string with a blank.
  Do not place a blank character (space or tab) except after the separator (,). When the port number is omitted, the system assumes the value for DCNAMPORT in the client environment definition.
  When you have specified more than one TP1/Server in data-name-F 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, the system attempts to replace the failed node by referencing the next TP1/Server of the currently used TP1/Server. If Y is specified, the system selects a TP1/Server at random (except for the TP1/Server in which the error was detected) and attempts to replace the failed node.
  When data-name-F starts with a blank, the program references DCHOST in the client environment definition.
  If data-name-F starts with a blank and DCHOST is not set, a broadcast is performed to determine the TP1/Server to be used as a gateway.
  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, CBLDCCLS('EXCLTIN ') returns an error with status code 02518.
  Terminate the character string with a blank.
  

  # 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 data-name-F.

• data-name-G
  Specify an area of 64 bytes^# or more for storing the host name of the server that actually performed user authentication.
  

  # This area must be larger than 255 bytes if you specify 00000008 for DCCLTOPTION in the client environment definition.

• data-name-I
  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 data-name-I 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 data-name-I.
    
  You can omit the path name by specifying a blank at the beginning of data-name-I. 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 data-name-I 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.
    

• data-name-B
  5-digit status code.
  
• data-name-G
  The 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.
  The stored host name ends with a blank.
  
• data-name-H
  A client ID is set when client user authentication is completed successfully. Do not destroy the client ID before CBLDCCLS('CLTOUT ') is executed.
  

Status code	Meaning
00000	Normal termination
02501	Invalid value for the data name. The request code (data-name-A) may be invalid.
02502	CBLDCCLT('EXCLTIN ') has already been executed. This status code is not returned if CBLDCCLS('EXCLTIN ') is executed.
02503	An attempt to initialize the communication path failed. Alternatively, the client environment definition is specified incorrectly.
02504	A necessary amount of buffer could not be allocated.
02506	Network error
02515	OpenTP1 is not running on the node that has the specified service.
02518	System error
02527	This status code is returned because of one of the following reasons: The specified login name (data-name-D) is not registered in the target host. The password (data-name-E) does not match. The OpenTP1 server may not support user authentication. Check whether client_uid_check is specified correctly in the system common definition.
02547	The specified port number is in use. Alternatively, port numbers that can be assigned automatically by the operating system are insufficient.