Joining an Application


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using COBOL

Before a client can perform any service request, it must join the BEA Tuxedo application, either explicitly or implicitly. Once the client has joined the application, it can initiate requests and receive replies.

A client joins an application explicitly by calling TPINITIALIZE(3cbl) with the following signature.

01 TPINFDEF-REC.
   COPY TPINFDEF.
01 USER-DATA-REC      PIC X(any-length).
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPINITIALIZE" USING TPINFDEF-REC USER-DATA-REC TPSTATUS-REC.

A client joins an application implicitly by issuing a service request (or any ATMI call) without first calling TPINITIALIZE. In this case, TPINITIALIZE is called by the BEA Tuxedo system on behalf of the client with the SPACES parameter.The TPINFDEF-REC record is a special BEA Tuxedo system typed record used by a client program to pass client identification and authentication information to the system when the client attempts to join the application. It is defined in a COBOL COPY file, as follows.

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.

The following table lists the fields that are defined in a COBOL COPY file.

COBOL COPY File Fields

Field
Description

USRNAME

Name representing the caller. You may want to specify the value returned by the UNIX command getuid(2) within this field. The value of USRNAME may contain up to MAXTIDENT characters (which is defined as 30).

CLTNAME

Name of a client for which the semantics are application-defined. The value of CLTNAME may contain up to MAXTIDENT characters (which is defined as 30).

PASSWD

Application password in unencrypted format that is used by TPINITIALIZE for validation against the application password stored in the TUXCONFIG file. PASSWD is a string of up to MAXTIDENT characters.

GRPNAME

Resource manager group name with which you want to associate the client. The client can access an XA-compliant resource manager as part of a global transaction. The GRPNAME can be a value up to MAXTIDENT characters (which is defined as 30). Currently, however, the GRPNAME must be passed as SPACES specifying that the client is not associated with a resource manager group and is in the default client group.

NOTIFICATION-FLAG

Notification mechanism and system access mode to be used. Refer to Unsolicited Notification Handling for a list of valid values.

ACCESS-FLAG

System access mode used. Refer to System Access Mode for a list of values.

DATALEN

Length of the application-specific data that will be sent to the authentication service. For native clients, it is not encoded by the system, but passed to the authentication service as provided by the client. For workstation clients, client authentication is handled by the system, and passed over the network in encrypted form.

Field	Description
USRNAME	Name representing the caller. You may want to specify the value returned by the UNIX command getuid(2) within this field. The value of USRNAME may contain up to MAXTIDENT characters (which is defined as 30).
CLTNAME	Name of a client for which the semantics are application-defined. The value of CLTNAME may contain up to MAXTIDENT characters (which is defined as 30).
PASSWD	Application password in unencrypted format that is used by TPINITIALIZE for validation against the application password stored in the TUXCONFIG file. PASSWD is a string of up to MAXTIDENT characters.
GRPNAME	Resource manager group name with which you want to associate the client. The client can access an XA-compliant resource manager as part of a global transaction. The GRPNAME can be a value up to MAXTIDENT characters (which is defined as 30). Currently, however, the GRPNAME must be passed as SPACES specifying that the client is not associated with a resource manager group and is in the default client group.
NOTIFICATION-FLAG	Notification mechanism and system access mode to be used. Refer to Unsolicited Notification Handling for a list of valid values.
ACCESS-FLAG	System access mode used. Refer to System Access Mode for a list of values.
DATALEN	Length of the application-specific data that will be sent to the authentication service. For native clients, it is not encoded by the system, but passed to the authentication service as provided by the client. For workstation clients, client authentication is handled by the system, and passed over the network in encrypted form.

The USRNAME and CLTNAME fields are associated with the client process when TPINITIALIZE is called. Both fields are used for both broadcast notification and the retrieval of administrative statistics.