TPINITIALIZE - join a TUXEDO/System/T application
01 TPINFDEF-REC.
COPY TPINFDEF.
01 USER-DATA-REC PIC X(any-length).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPINITIALIZE" TPINFDEF-REC USER-DATA-REC TPSTATUS-REC.
TPINITIALIZE allows a client to join a System/T application. Before a client can use any of the System/T communication or transaction routines, it must first join a System/T application. Because calling TPINITIALIZE is optional, a client may also join an application by calling many ATMI routines (for example, TPACALL(3cbl) or TPCALL(3cbl)) which transparently call TPINITIALIZE with default values for the members of TPINFDEF-REC. A client may want to call TPINITIALIZE directly so that it can set the parameters described below. In addition, TPINITIALIZE must be used when application authentication is required (see the description of the SECURITY keyword in ubbconfig(5)). After TPINITIALIZE successfully returns, the client can initiate service requests and define transactions.
If TPINITIALIZE is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.
TPINITIALIZE's argument, TPINFDEF-REC record includes the following members:
05 USRNAME PIC X(30). 05 CLTNAME PIC X(30). 05 PASSWD PIC X(30). 05 GRPNAME PIC X(30). 05 NOTIFICATION-FLAG PIC S9(9) COMP-5. 88 TPU-SIG VALUE 1. 88 TPU-DIP VALUE 2. 88 TPU-IGN VALUE 3. 05 ACCESS-FLAG PIC S9(9) COMP-5. 88 TPSA-FASTPATH VALUE 1. 88 TPSA-PROTECTED VALUE 2. 05 DATALEN PIC S9(9) COMP-5.
USRNAME is a name representing the caller. CLTNAME is a client name whose semantics are application defined. The value sysclient is reserved by the system for the CLTNAME field. The USRNAME and CLTNAME fields are associated with the client at TPINITIALIZE time and are used for both broadcast notification and administrative statistics retrieval. PASSWD is an application password in unencrypted format that is used for validation against the application password. Due to UNIX restrictions on one-way encryption, the PASSWD is significant only to 8 characters. GRPNAME is used to associate the client with a resource manager group name. If GRPNAME is SPACES, then the client is not associated with a resource manager and is in the default client group.
The settings of TPINFDEF-REC are used to indicate both the client specific notification mechanism and the mode of system access. These settings may override the application default; however, in the event that they cannot, TPINITIALIZE will print a warning in a log file, ignore the setting and return the application default setting in TPINFDEF-REC upon return from TPINITIALIZE. For client notification, the possible settings are as follows:
Only one of the above can be used at a time. If the client does not select a notification method, then the application default method will be set upon return from TPINITIALIZE.
For setting the mode of system access, the possible settings are as follows:
Only one of the above can be used at a time. If the client does not select a notification method or a system access mode, then the application default method(s) will be set upon return from TPINITIALIZE. See ubbconfig(5) for details on both client notification methods and system access modes.
DATALEN is the length of the application specific data that will be sent to the service. TPINITIALIZENEED(8) will return A SPACES value for USRNAME and CLTNAME is allowed for applications not making use of the application authentication feature of System/T. Currently, GRPNAME must be SPACES. Clients using this option will get defined in System/T with default values for USRNAME, CLTNAME and GRPNAME; default settings and no application data.
Upon successful completion, TPINITIALIZE sets TP-STATUS to [TPOK].
Under the following conditions, TPINITIALIZE fails and sets TP-STATUS to:
TPCHKAUTH(3cbl) and
The interfaces described in TPINITIALIZE(3cbl) are supported on UNIX System and MS-DOS operating systems. However, signal-based notification is not supported on MS-DOS. If it is selected at TPINITIALIZE time, then a USERLOG(3cbl) message is generated and the method is automatically set to dip-in.
TCP/IP addresses may be specified in the following forms:
"//host.name:port_number" "//#.#.#.#:port_number"
In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine. .P In the second example, the "#.#.#.#" is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine. .P In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests. port_number can either be a number between 0 and 65535 or a name. If port_number is a name, then it must be found in the network services database on your local machine. .P The address can also be specified in hexadecimal format when preceded by the characters "0x". Each character after the initial "0x" is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP. .P The address can also be specified as an arbitrary string. The value should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file. .P More than one address can be specified if desired by specifying a comma-separated list of pathnames for WSNADDR Addresses are tried in order until a connection is established. Any member of an address list can be specified as a parenthesized grouping of pipe-separated network addresses. For example,
WSNADDR="(//m1.acme.com:3050|//m2.acme.com:3050),//m3.acme.com:3050"
TUXEDO randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. Addresses are tried in order until a connection is established. Use the value specified in the application configuration file for the workstation listener to be called. If the value begins with the characters ``0x'', it is interpreted as a string of hex-digits, otherwise it is interpreted as ASCII characters.
Clients that select signal-based notification may not be signal-able by the system due to signal restrictions. When this happens, the system generates a log message that it is switching notification for the selected client to dip-in and the client is notified then and thereafter via dip-in notification. (See ubbconfig(5) description of the \(**RESOURCES NOTIFY parameter for a detailed discussion of notification methods.) Note that signaling of clients is always done by the system so that the behavior of notification is consistent regardless of where the originating notification call is made. Because of this, only clients running as the application administrator can use signal-based notification. The id for the application administrator is identified as part of the configuration for the application.
If signal-based notification is selected for a client, then certain ATMI calls may fail, returning TPGOTSIG due to receipt of an unsolicited message if TPSIGRSTRT is not specified.