Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 7 Using the TIBCO Service Gateway for CICS : Passing the COMMAREA Between a TIBCO Object Service Broker CICS Client and a Session

Passing the COMMAREA Between a TIBCO Object Service Broker CICS Client and a Session
The CICS COMMAREA is used to:
Whether the TIBCO Object Service Broker CICS client is non-seamless or seamless determines how the COMMAREA must be set up.
Non-Seamless COMMAREA
The non-seamless COMMAREA is arranged as shown in the following illustration:
The non-seamless TIBCO Object Service Broker client passes the session parameter string and the data area to the session when the session is started. Using this method, the client can pass data to a session through the arguments to the RULE parameter in the session parameter string or in the data area.
COMMAREA Requirements For the Non-Seamless TIBCO Object Service Broker Interface
Before you use any of the CICS instructions to invoke a non-seamless TIBCO Object Service Broker client, the invoking CICS program must set up a COMMAREA that meets the following requirements:
The non-seamless TIBCO Object Service Broker client supports a session parameter string and an optional data area, so the COMMAREA must be large enough to contain the parameters you pass to TIBCO Object Service Broker (preceded by a two-byte field containing the length of the parameters) and the data itself.
The parameter length is a two-byte binary field (marked ll in the previous figure), which must precede the session parameter string.
The session parameter string must follow standard TIBCO Object Service Broker syntax, with brackets and commas where required. The session parameter string must not contain embedded nulls (0x00 characters), because a null is interpreted as the end of the string.
The value in the parameter length field must be at least the total length of the parameters, including the parentheses and commas. The value does not include the length of the parameter length field itself.
Seamless COMMAREA
The seamless TIBCO Object Service Broker client uses the entire externally established COMMAREA as a data area to be passed to the session when the session is started, as shown in the following illustration:
COMMAREA Requirements for the Seamless TIBCO Object Service Broker Interface
The COMMAREA should be a minimum of 256 bytes long to accommodate error messages.
Retrieving the COMMAREA in a Rule
Using TIBCO Object Service Broker rules, you can access only the data area portion of the COMMAREA. If the client is non-seamless, you can access only the data area following the session parameter string. If you use the seamless interface, you can access the data area consisting of the entire COMMAREA. The data area of the COMMAREA can be accessed using MAP tables or using the $GETENVCOMMAREA tool.
Using $GETENVCOMMAREA
$GETENVCOMMAREA returns the data portion of the COMMAREA as a syntax V string including the two byte ll length header. The maximum length of the returned string is 31K. To avoid local variable storage overflow, consider increasing the values of the session parameters EXECLOCALSIZE and EXECSTACKSIZE. Settings of 128K for both variables are usually sufficient.
The syntax for using the $GETENVCOMMAREA tool is:
COMM = $GETENVCOMMAREA(0);
The value returned in COMM is as follows:
Error Messages in the COMMAREA
If the session terminates abnormally or if you use the ENDMSG tool to generate an error message, the message is put into the COMMAREA starting at the first byte, overlaying other data in that area. It is the responsibility of the CICS program that subsequently receives control to check for the four-byte error token HERR at the start of the COMMAREA.
The format of the error message is shown in the following illustration:
If the error messages cannot fit into the COMMAREA, it is truncated. To avoid truncating error messages, the size of the COMMAREA should be at least 256 bytes. For diagnostic purposes, a message that does not fit is sent to the console by WTO and appended to the CICS joblog.
See Also
TIBCO Object Service Broker Managing Data about MAP tables.
TIBCO Object Service Broker Shareable Tools about the tools.
TIBCO Object Service Broker Parameters about parameters.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved