Home

 

The xa_open string

This section describes the format of an xa_open string and provides more details about how an extended transactional client uses the information in an xa_open string.

 

The format of an xa_open string

An xa_open string has the following format: 

parm_name1=parm_value1,parm_name2=parm_value2, ...

where

parm_name is the name of a parameter and parm_value is the value of a parameter. The names of the parameters are not case sensitive but, unless stated otherwise subsequently, the values of the parameters are case sensitive. We can specify the parameters in any order.

The names, meanings, and valid values of the parameters are as follows:

Name
Meaning and valid values

CHANNEL

The name of an MQI channel.

This is an optional parameter. If this parameter is supplied, the CONNAME parameter must also be supplied.

TRPTYPE

The communications protocol for the MQI channel. The following are valid values:

LU62

SNA LU 6.2

NETBIOS

NetBIOS

SPX

IPX/SPX

TCP

TCP/IP

This is an optional parameter. If it is omitted, the default value of TCP is assumed. The values of the parameter are not case sensitive.

CONNAME

The network address of the queue manager at the server end of the MQI channel. The valid values of this parameter depend on the value of the TRPTYPE parameter:

LU62

A symbolic destination name, which identifies a CPI-C side information entry.

Note that the network qualified name of a partner LU is not a valid value, nor is a partner LU alias. This is because there are no additional parameters to specify a transaction program (TP) name and a mode name.

NETBIOS

A NetBIOS name.

SPX

A 4-byte network address, a 6-byte node address, and an optional 2-byte socket number. These values must be specified in hexadecimal notation. A period must separate the network and node addresses, and the socket number, if supplied, must be enclosed in parentheses. For example: 

0a0b0c0d.804abcde23a1(5e86)
If the socket number is omitted, the default value of 5e86 is assumed.

TCP

A host name or an IP address, optionally followed by a port number in parentheses. If the port number is omitted, the default value of 1414 is assumed.

This is an optional parameter. If this parameter is supplied, the CHANNEL parameter must also be supplied.

QMNAME

The name of the queue manager at the server end of the MQI channel. The name cannot be blank or a single asterisk (*), nor can the name start with an asterisk. This means that the parameter must identify a specific queue manager by name.

This is a mandatory parameter.

TPM

The transaction manager being used. The valid values are CICS and TUXEDO.

An extended transactional client uses this parameter and the AXLIB parameter for the same purpose. For more information these parameters, see The TPM and AXLIB parameters.

This is an optional parameter. The values of the parameter are not case sensitive.

AXLIB

The name of the library that contains the transaction manager's ax_reg and ax_unreg functions.

This is an optional parameter.

Here is an example of an xa_open string: 

channel=MARS.SVR,trptype=tcp,conname=MARS(1415),qmname=MARS,tpm=cics

 

How an extended transactional client uses an xa_open string

The following sections describe how an extended transactional client uses the parameters in an xa_open string.

The CHANNEL, TRPTYPE, CONNAME, and QMNAME parameters

If the CHANNEL and CONNAME parameters are supplied in the xa_open string, the extended transactional client uses these parameters, and the TRPTYPE parameter, to start an MQI channel to the server queue manager.

If the CHANNEL and CONNAME parameters are not supplied in the xa_open string, the extended transactional client uses the value of the MQSERVER environment variable to start an MQI channel. If the MQSERVER environment variable is not defined, the extended transactional client uses the entry in the client channel definition identified by the QMNAME parameter.

In each of these cases, the extended transactional client checks that the value of the QMNAME parameter is the name of the queue manager at the server end of the MQI channel. If it is not, the xa_open call fails and the transaction manager reports the failure to the application.

When the client application calls MQCONN or MQCONNX subsequently on the same thread that the transaction manager used to issue the xa_open call, the application receives a connection handle for the MQI channel that was started by the xa_open call. A second MQI channel is not started. The extended transactional client checks that the value of the QMgrName parameter on the MQCONN or MQCONNX call is the name of the queue manager at the server end of the MQI channel. If it is not, the MQCONN or MQCONNX call fails with a reason code of MQRC_ANOTHER_Q_MGR_CONNECTED. If the value of the QMgrName parameter is blank or a single asterisk (*), or starts with an asterisk, the MQCONN or MQCONNX call fails with a reason code of MQRC_Q_MGR_NAME_ERROR.

If the client application has already started an MQI channel by calling MQCONN or MQCONNX before the transaction manager calls xa_open on the same thread, the transaction manager uses this MQI channel instead. A second MQI channel is not started. The extended transactional client checks that the value of the QMNAME parameter in the xa_open string is the name of the server queue manager. If it is not, the xa_open call fails.

If a client application starts an MQI channel first, the value of the QMgrName parameter on the MQCONN or MQCONNX call can be blank or a single asterisk (*), or it can start with an asterisk. Under these circumstances, however, ensure that the queue manager to which the application connects is the same as the queue manager that the transaction manager intends to open as a resource manager when it calls xa_open subsequently on the same thread. You might encounter fewer problems, therefore, if the value of the QMgrName parameter identifies the queue manager explicitly by name.

The TPM and AXLIB parameters

An extended transactional client uses the TPM and AXLIB parameters to locate the transaction manager's ax_reg and ax_unreg functions. These functions are used only if the queue manager uses dynamic registration.

If the TPM parameter is supplied in an xa_open string, but the AXLIB parameter is not supplied, the extended transactional client assumes a value for the AXLIB parameter based on the value of the TPM parameter. See Table 13 for the assumed values of the AXLIB parameter.

Table 13. Assumed values of the AXLIB parameter
Value of TPM Platform Assumed value of AXLIB
CICS AIX /usr/lpp/encina/lib/libEncServer.a(EncServer_shr.o)
CICS HP-UX /opt/encina/lib/libEncServer.sl
CICS Solaris /opt/encina/lib/libEncServer.so
CICS Windows systems libEncServer
Tuxedo AIX /usr/lpp/tuxedo/lib/libtux.a(libtux.so.60)
Tuxedo HP-UX /opt/tuxedo/lib/libtux.sl
Tuxedo Solaris /opt/tuxedo/lib/libtux.so.60
Tuxedo Windows systems libtux

If the AXLIB parameter is supplied in an xa_open string, the extended transactional client uses its value to override any assumed value based on the value of the TPM parameter. The AXLIB parameter can also be used for a transaction manager for which the TPM parameter does not have a specified value.

Additional error processing

The xa_open call also fails if any of the following occur:

Recovery processing

Following a failure, a transaction manager must be able to recover any incomplete units of work. To do this, the transaction manager must be able to open as a resource manager any queue manager that was participating in an incomplete unit of work at the time of the failure.

If you ever need to change any configuration information, therefore, you must ensure that all incomplete units of work have been resolved before making the changes. Alternatively, ensure that the configuration changes do not affect the transaction manager's ability to open the queue managers it needs to open. The following are examples of such configuration changes:




 

Home