ATMI COBOL Function Reference
TPINITIALIZE()
- joins a BEA Tuxedo ATMI application
01
TPINFDEF-REC
.
COPY TPINFDEF.
01USER-DATA-REC
PIC X(any-length).
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPINITIALIZE"TPINFDEF-REC
USER-DATA-REC
TPSTATUS-REC
.
TPINITIALIZE()
allows a client to join a BEA Tuxedo ATMI application. Before a client can use any of the BEA Tuxedo communication or transaction routines, it must first join a BEA Tuxedo ATMI 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 multi-context 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:
Select unsolicited notification by signals. This setting is not allowed in conjunction with the TP-MULTI-CONTEXTS
setting of CONTEXTS-FLAG
.
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. 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:
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.
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.
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.
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.
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.
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.
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"
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.
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.
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.
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
.
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.
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.
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"
Signal-based notification is not allowed in multi-context 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:
The ID for the application administrator is identified in the configuration file 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.