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   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo COBOL Function Reference

TPINITIALIZE() - joins a BEA Tuxedo system 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 BEA Tuxedo system application. Before a client can use any of the BEA Tuxedo communication or transaction routines, it must first join a BEA Tuxedo system application. TPINITIALIZE() has two modes of operation: single-context mode and multi-context mode, which will be discussed in greater detail below. Because calling TPINITIALIE() is optional when in single-context mode, a single-context client may also join an application by calling many ATMI routines (for example, TPACALL() or TPCALL()) 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 multicontext mode is required or 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.

In single-context mode, 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.

The 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 CONTEXTS-FLAG      PIC S9(9) COMP-5.
  88 TP-SINGLE-CONTEXT   VALUE 0.
  88 TP-MULTI-CONTEXTS   VALUE 1.
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. The PASSWD is significant up to 30 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.

TPINITIALIZE() has two modes of operation: single-context mode and multi-context mode. In single-context mode, a process may join at most one application at any one time. Single-context mode is specified by calling TPINITIALIZE() with the TP-SINGLE-CONTEXT setting of CONTEXTS-FLAG or by calling another function that invokes TPINITIALIZE() implicitly.

In single-context mode, 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.

Multi-context mode is entered by calling TPINITIALIZE() with the TP-MULTI-CONTEXTS setting of CONTEXTS-FLAG. In multi-context mode, each call to TPINITIALIZE() results in the creation of a separate application association.

An application association is a context that associates a process and a BEA Tuxedo application. A client may have associations with multiple BEA Tuxedo applications, and may also have multiple associations with the same application. All of a client's associations must be made to applications running the same release of the BEA Tuxedo system, and either all associations must be native clients or all associations must be workstation clients.

For native clients, the value of the TUXCONFIG environment variable is used to identify the application to which the new association will be made. For workstation clients, the value of the WSNADDR or WSENVFILE environment variable is used to identify the application to which the new association will be made. The context for the current COBOL process is set to the new association.

In multi-context mode the application can get a handle for the current context, by calling TPGETCTXT(), and pass that handle as a parameter to TPSETCTXT(), thus setting the context in which a particular COBOL process will operate.

Mixing single-context mode and multi-context mode is not allowed. Once an application has chosen one of these modes, calling TPINITIALIZE() in the other mode is not allowed unless TPTERM() is first called for all application associations.

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:

TPU-SIG

Select unsolicited notification by signals. This setting is not allowed in conjunction with the TP-MULTI-CONTEXTS setting of CONTEXTS-FLAG.

TPU-DIP

Select unsolicited notification by dip-in.

TPU-IGN

Ignore unsolicited notification.

TPSA-FASTPATH

Set system access to fastpath.

TPSA-PROTECTED

Set system access to protected.

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. A SPACES value for USRNAME and CLTNAME is allowed for applications not making use of the application authentication feature of the BEA Tuxedo system. Currently, GRPNAME must be SPACES. Clients using this option will get defined in the BEA Tuxedo system with the following: default values for USRNAME, CLTNAME, and GRPNAME; default settings; and no application data.

Upon successful completion, TPINITIALIZE() sets TP-STATUS to [TPOK]. Upon failure, TPINITIALIZE() leaves the calling process in its original context, returns -1, and sets TP-STATUS to indicate the error condition.

Upon failure, TPINITIALIZE() sets TP-STATUS to:

[TPEINVAL]

Invalid arguments were specified.

[TPENOENT]

The client cannot join the application because of space limitations.

[TPEPERM]

The client cannot join the application because it does not have permission to do so or because it has not supplied the correct application password. Permission may be denied based on an invalid application password, failure to pass application specific authentication or use of restricted names.

[TPEPROTO]

TPINITIALIZE() was called improperly. For example: (a) the caller is a server; (b) the TP-MULTI-CONTEXTS setting was specified in single-context mode; or (c) the TP-MULTI-CONTEXTS setting was not specified in multi-context mode.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

The interfaces described in TPINITIALIZE() 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() message is generated and the method is automatically set to dip-in.

TUXCONFIG

is used within TPINITIALIZE() when invoked by a non-workstation native client. It indicates the application to which the client should connect. Note that this environment variable is referenced only when TPINITIALIZE() is called. Subsequent calls make use of the application context.

WSENVFILE

is used within TPINITIALIZE() when invoked by a workstation client. It indicates a file containing environment variable settings that should be set in the caller's environment. See compilation(5) for more details on environment variable settings necessary for workstation clients. Note that this file is processed only when TPINITIALIZE() is called and not before.

WSNADDR

is used within TPINITIALIZE() when invoked by a workstation client. It indicates the network address(es) of the workstation listener that is to be contacted for access to the application. This variable is required for Workstation clients and is ignored for native clients.

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.

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.

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.

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.

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 NETWORKS section of the configuration file.

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"

For users running under Windows, the address string looks like the following:

set WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050

Because the pipe symbol (|) is considered a special character in Windows, it must be preceded by a carat ( ^ )-an escape character in the Windows environment-when it is specified on the command line. However, if WSNADDR is defined in an envfile, the BEA Tuxedo system gets the values defined by WSNADDR through the tuxgetenv(3c) function. In this context, the pipe symbol (|) is not considered a special character, so you do not need to escape it with a carat (^).

The BEA Tuxedo system 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.

WSFADDR

Used within TPINITIALIZE() when invoked by a workstation client. It specifies the network address used by the workstation client when connecting to the workstation listener or workstation handler. This variable, along with the WSFRANGE variable, determines the range of TCP/IP ports to which a workstation client will attempt to bind before making an outbound connection. This address must be a TCP/IP address. The port portion of the TCP/IP address represents the base address from which a range of TCP/IP ports can be bound by the workstation client. The WSFRANGE variable specifies the size of the range. For example, if this address is //mymachine.bea.com:30000 and WSFRANGE is 200, then all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com between 30000 and 30200. If not set, this variable defaults to the empty string, which implies the operating system chooses a local port randomly.

WSFRANGE

Used within TPINITIALIZE() when invoked by a workstation client. It specifies the range of TCP/IP ports to which a workstation client process will attempt to bind before making an outbound connection. The WSFADDR parameter specifies the base address of the range. For example, if the WSFADDR parameter is set to //mymachine.bea.com:30000 and WSFRANGE is set to 200, then all native processes attempting to make outbound connections from this LMID will bind a port on mymachine.bea.com between 30000 and 30200. The valid range is 1-65535. The default is 1.

WSDEVICE

is used within TPINITIALIZE() when invoked by a workstation client. It indicates the device name to be used to access the network. This variable is used by workstation clients and ignored for native clients. Note that certain supported transport level network interfaces do not require a device name; for example, sockets and NetBIOS. Workstation clients supported by such interfaces need not specify WSDEVICE.

WSTYPE

is used within TPINITIALIZE() when invoked by a workstation client to negotiate encode/decode responsibilities with the native site. This variable is optional for workstation clients and ignored for native clients.

WSRPLYMAX

is used by TPINITIALIZE() to set the maximum amount of core memory that should be used for buffering application replies before they are dumped to file. The default value for this parameter varies with each instantiation. The instantiation specific programmer's guide should be consulted for further information.

TMMINENCRYPTBITS

is used to establish the minimum level of encryption required to connect to the BEA Tuxedo system. "0" means no encryption, while "56" and "128" specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment will fail. The default is "0"

TMMAXENCRYPTBITS

is used to negotiate the level of encryption up to this level when connecting to the BEA Tuxedo system. "0" means no encryption, while "56" and "128" specify the encryption length (in bits). The default value is "128."

Signal-based notification is not allowed in multicontext mode. In addition, clients that select signal-based notification may not be able to receive signals from the system due to signal restrictions. When clients cannot receive signals, 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 the description of the NOTIFY parameter in the RESOURCES section of UBBCONFIG(5) for a detailed discussion of notification methods.

Because signaling of clients is always done by the system, the behavior of notification is always consistent, regardless of where the originating notification call is made. Therefore to use signal-based notification:

• A native client must be running as an application administrator

• A Workstation client is not required to be running as the application administrator

The ID for the application administrator is identified in the configuration file for the application.

TPGETCTXT(3cbl), TPSETCTXT(3cbl), TPTERM(3cbl)