Optimized local adapters APIs on Liberty for z/OS

Register

Using the BBOA1REG API, you can register with a local Liberty server. The BBOA1REG API requests that a group of optimized connections to a local Liberty server be allocated and registered under the specified register name.

wolagroupnamepart1

An entry variable or entry constant that contains the first part of the name of the optimized local adapter group to be joined. It must be a null-terminated string of exactly 8 characters, and it must be passed by reference.

wolagroupnamepart2

An entry variable or entry constant that contains the second part of the name of the optimized local adapter group to be joined. It must be a blank-padded string of exactly 8 characters, and it must be passed by reference.

wolagroupnamepart3

An entry variable or entry constant that contains the third part of the name of the optimized local adapter group to be joined. It must be a blank-padded string of exactly 8 characters, and it must be passed by reference.

registername (input)

An entry variable or entry constant containing the name to be used to register a set of local connections. Later calls require this name to identify the pool of connections to use. This must be a blank padded string of exactly 12 characters and cannot be used by another client in the daemon group. If this client connects to multiple daemon groups, the registername can be used only once in this client.

minconn

An integer that contains the initial minimum number of connections to allocate for this registration. The adapter attempts to reserve this number of connections with the associated server during registration.

Important: At minimum, one connection is allocated to bind with the target server even if the minconn parameter is specified as 0, so specifying 0 is the same as specifying 1.

maxconn

An integer that contains the maximum number of connections to allocate for this registration. The adapter attempts to extend the local connection pool up to this number during a Connection Get API request when the minimum number of connections are all in use.

registerflags

A 32-bit flag word that contains registration flags.

• reg_flag_W2Cprop - bit 31

  The reg_flag_W2Cprop flag controls outbound transaction security propagation from the Liberty server to CICS®.

• reg_flag_C2Wprop - bit 29

  The reg_flat_C2Wprop flag propagates the identity on the calling task from CICS to the Liberty server. For transactions that are inbound from CICS, the flag controls how the identity is determined. When this bit is turned on, the CICS application task identity is used in the Liberty server authorization process if the useCicsTaskUserId attribute for the zosLocalAdapters configuration element is set to true in the server.xml file. When this bit is turned off, the CICS region identity is used.

• reg_flag_trcmod - bit 0

  Set the reg_flag_trcmod flag if you want to modify the optimized local adapter trace settings for the requested registration. If you do not set this flag, no change to the trace setting is made, and the system defaults or predefined trace settings that apply to the registration name or job name are used.

• reg_flag_trcmore - bit 1 and reg_flag_trcsome - bit 2

  If you set reg_flag_trcmod flag to 1, you must also specify the level of tracing for the registration by setting the reg_flag_trcmore flag for detailed tracing or the reg_flag_trcsome flag for coarse-level tracing. If reg_flag_trcmod is set to 1, setting both the reg_flag_trcmore flag and the reg_flag_trcsome flag to 0 forces no tracing for the registration regardless of what pre-definitions or defaults are set.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Unregister

registername

An entry variable or entry constant that contains the name to use to unregister a set of local connections. The value must be exactly 12 characters, blank padded, and the same name that is used on the Register API call.

unregisterflags

A 32-bit flag word that contains unregistration flags.

• Reserved - bit 0-30
• Force (0|1) - bit 31

  Specify 1 to force the unregister request. By default, an unregister request is complete if all connections are returned to the connection pool. If all the connections are not returned to the pool, a warning is returned to the caller. The unregister process is complete when the last connection is returned to the pool. Make a second unregister request with the force bit set to 1 to force the unregister process to complete and invalidate all remaining connection handles for that registration.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Connection Get

registername

An entry variable or entry constant that contains the name to be used to locate the connection pool from which to retrieve a connection. This must be a blank padded string of exactly 12 characters.

connectionhandle

A 12-byte area that stores the connection handle, which must be passed on later requests for actions on this connection.

waittime

An integer that contains the number of seconds to wait for the connection to complete before returning a connection unavailable reason code. A value of 0 implies there is no wait time and the API waits indefinitely. The waittime parameter applies only to the process of obtaining a WOLA connection from the connection pool. When the connection is obtained, it is used to receive a request from the server with an unlimited wait time.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Connection Release

connectionhandle

A 12-byte area into which the connection handle that indicates the previously obtained connection that is to be released back into the connection pool.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Send Request

connectionhandle

A 12-byte connection handle that is to be used for this request.

requesttype

An integer that contains the request type that indicates the type of work request to process. The only supported value is 1 for local EJB work requests.

requestservicename

An EBCDIC character string up to 256 bytes in length that contains the name of the service to invoke. This parameter specifies the JNDI name of the local business interface.

requestservicenamel

An integer that contains the length of the service name to start or 0 (zero) if the service name is null terminated.

requestdata

A 31-bit pointer to the address of the start of the request data to send.

requestdatalen

A 32-bit unsigned value that contains the length of the data to send.

async(0|1)

Set async to 1 to indicate that the caller wants control returned immediately, even though the response length might not yet be known. If you set async to 0, the current thread waits for the Liberty server to return the response, and the API returns the response length in the responsedatalen output parameter.

responsedatalen

A 32-bit unsigned value that contains the length of the response. The caller can use this length to acquire storage before you call the Get Data API to copy the data in. When you set async to 1, indicating the caller wants control back immediately, the value is set to 0xFFFFFFFF if the response is not yet received.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Send Response

connectionhandle

A 12-byte connection handle that is to be used for this response.

responsedata

A 31-bit pointer to the address of the start of the response data to send.

requestdatalen

A 32-bit unsigned value that contains the length of the data to send.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Send Response Exception

This API sends a ResourceException exception that contains response data back to the JCA caller in the local Liberty server.

connectionhandle

A 12-byte connection handle that is to be used for this response.

excresponsedata

A 31-bit pointer to the address of the start of the exception response data to send.

excresponsedatalen

A 32-bit unsigned value that contains the length of the exception response data to send. Exception response data is an EBCDIC string that describes the error.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Receive Request Any

This API receives a request and related data from a local Liberty server on any connection in the pool for the passed register name. The API returns request data length and a connection handle as output parameters. Calling the Get Data API with the returned connection handle returns the received message data.

registername

An entry variable or entry constant that contains the name to be used to locate the connection pool from which to retrieve a connection. The value must be a blank padded string of exactly 12 characters.

waittime

An integer that contains the number of seconds to wait for the connection to complete before it returns a connection unavailable reason code. A value of 0 indicates that there is no wait time and that the API waits indefinitely. The waittime parameter applies only to the process of obtaining a WOLA connection from the connection pool. When the connection is obtained, it is used to receive a request from the server with an unlimited wait time.

requestservicename

An EBCDIC character string up to 256 bytes that contains the name of the service. This parameter is the name of the target service that is specified on the InteractionSpec interface by the Liberty server application. A value of * indicates a receive request for all service names that arrive under the current register name.

requestservicenamel

An integer that contains the length of the service name to start or 0 if the service name is null terminated.

connectionhandle

A 12-byte connection handle that is returned and must be passed on later requests for actions on this connection.

requestdatalen

A 32-bit unsigned value is returned with the length of the data to receive.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Receive Request Specific

connectionhandle

A 12-byte connection handle that is to be used for the receive request.

async(0|1)

Set async to 1 to indicate that the caller wants control returned immediately, even though the response length might not yet be known. If you set async to 0, this call waits to receive a request from the Liberty server.

requestservicename

An EBCDIC character string up to 256 bytes that contains the name of the service. This parameter is the name of the target service that is specified on the InteractionSpec interface by the Liberty server application. A value of * indicates that set up as a server for all service names that arrive under the current register name.

requestservicenamel

An integer that contains the length of the service name to start or 0 if the service name is null terminated.

requestdatalen

A 32-bit unsigned value is returned that contains the length of the request data received. The caller can then use this length to acquire storage before you call the Get Data API to copy the data in. When async is set to 1, indicating the caller wants control back immediately, the value is set to 0xFFFFFFFF if the request data is not yet received. In this case, you must call the API again to retrieve an inbound request.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Receive Response Length

connectionhandle

A 12-byte connection handle that is to be used for this request.

async(0|1)

Set async to 1 to indicate that the caller wants control returned immediately, even though the response length might not be known. If you set async to 0, this call waits for the Liberty server to return the response, and the API returns the response length in the responsedatalen parameter.

requestdatalen

A 32-bit unsigned value with the length of the received data is returned. The caller can use this length to acquire storage before you call the Get Data API to copy the data in. If you set async to 1, the value is set to 0xFFFFFFFF if the response data is not yet received.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

Get Message Data

connectionhandle

A 12-byte connection handle that is to be used for this request.

msgdata

A 31-bit pointer to the address of the start of the data area to copy into. The storage that this parameter points to must be in a key that the caller can write in.

msgdatalen

A 32-bit unsigned value that contains the length of the data to copy.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

rv

A 32-bit integer return value that contains the size of the context buffer for this request.

Invoke

registername

An entry variable or entry constant that contains the name to be used to locate the connection pool to retrieve a connection for this invocation. The value must be a blank padded string of exactly 12 characters.

requesttype

An integer that contains the request type, which indicates the type of work request to process. The only supported value is 1 for local EJB work requests.

requestservicename

An EBCDIC character string up to 256 bytes in length that contains the name of the service to invoke. This parameter specifies the JNDI name of the local business interface.

requestservicenamel

An integer that contains the length of the service name to start or 0 if the service name is null terminated.

requestdata

A 31-bit pointer to the address of the start of the request data to send.

requestdatalen

A 32-bit unsigned value that contains the length of the request data to send.

responsedata

A 31-bit pointer to the address of the start of the response data area to copy into. The storage this parameter points to must be in a key that the caller can write in.

responsedatalen

A 32-bit unsigned value that contains the length of the response data to send.

waittime

An integer that contains the number of seconds to wait for the connection to complete before it returns a connection unavailable reason code. A value of 0 (zero) indicates that there is no timeout and that this API waits indefinitely. The waittime parameter applies only to the process of obtaining a WOLA connection from the connection pool. When the connection is obtained, it is used to receive a request from the server with an unlimited wait time.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

rv

A 32-bit integer return value that contains the size of the message data that was received and copied into the caller response area.

Host Service

registername

An entry variable or entry constant that contains the name to be used to locate the connection pool to retrieve a connection from for this call. The value must be a blank-padded string of exactly 12 characters.

requestdata

A 31-bit pointer to the address of the start of the request data received. The storage that this parameter points to must be in a key that the caller can write in.

requestdatalen

A 32-bit unsigned value that contains the length of the data area into which the message is received.

connectionhandle

A 12-byte connection handle that is returned to the caller and used for sending a response for this request.

waittime

An integer that contains the number of seconds to wait for the connection to complete before it returns a connection unavailable reason code. A value of 0 (zero) implies that there is no timeout, and the API waits indefinitely. The waittime parameter applies only to the process of obtaining a WOLA connection from the connection pool. When the connection is obtained, it is used to receive a request from the server with an unlimited wait time.

requestservicename

An EBCDIC character string up to 256 bytes that contains the name of the service. This parameter is the name of the target service that is specified on the InteractionSpec interface by the Liberty server application. A value of * indicates set up as a server for all service names that arrive under the current register name.

requestservicenamel

An integer that contains the length of the service name to start or 0 if the service name is null terminated.

rc

An integer return code that indicates success or failure of this call.

rsn

An integer reason code that describes the reason for a failure on this call.

rv

A 32-bit integer return value that contains the size of the message data that was received and copied into the caller response area.

Java EE Connector Architecture (JCA) adapters APIs

ConnectionSpec

When you communicate with a CICS link server, the ConnectionSpecImpl class provides methods that you can use to override values that the link server uses. For example, you can specify the four-character transaction ID of the link server invocation transaction, BBO#. You can also specify whether to store request data in a CICS COMMAREA or CONTAINER object.

For information about methods in the ConnectionSpecImpl class, see the generated API documentation.

InteractionSpec

For information about methods in the InteractionSpecImpl class, see the generated API documentation.

Record I/O

Use an IndexedRecord object if you are passing data to a Batch or UNIX System Services program or if you are communicating with CICS using a COMMAREA or a single CONTAINER object. Add a byte array (byte[]) to the IndexRecord object to represent the data that the program sends on the request. The response is also received into an IndexedRecord object. You can obtain the response data by retrieving the first entry from the IndexedRecord object and casting it to a byte array.

Use a MappedRecord object if you are passing data to CICS in multiple CONTAINER objects. The MappedRecord object contains name-value pairs, similar to what Map objects store. In the name-value pairs, the name is the name of the container that the data is transferred to, and the value is the actual data, specified as a byte array (byte[]). When you use a MappedRecord object to send a request, the response is also sent back using a MappedRecord object. The response contains the name of each container that contained response data and the associated data.