[z/OS]

Optimized local adapters for z/OS APIs

The WebSphere® Application Server on z/OS® optimized local adapters are supported by a set of z/OS native language callable services, or application programming interfaces (APIs), as well as the Java EE Connector Architecture (JCA).

These callable services can be used from the following native programming languages:

Each callable service has a 31-bit version. The naming convention used is the prefix BBOA1.

When the term local connection is used in this API documentation, we are referring to a cross-memory link that is created for communication between an external address space on the z/OS system and the WebSphere Application Server on the same z/OS system. The WebSphere Application Server and exploiter address space have to be running on the same z/OS image. The adapter API manages these local connections in pools that are associated with each uniquely registered caller. The 12-character registration name can only be used for one set of connection pools per address space. There is no limit to the number of unique registrations in a single address space. It is limited only by the amount of available storage.

The API services are listed according to user goal, for example, the first section listed is Register. This section explains the APIs that are used in the task of registering an optimized local adapter so that it can be used in a call.

Register

Using the BBOA1REG API, you can register with a local WebSphere Application Server for z/OS daemon group and server. The BBOA1REG API requests that a group of optimized connections to a local WebSphere Application Server daemon group and server be allocated and registered under the specified "registername."

Table 1. BBOA1REG API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1REG

BBOA1REG ( daemongroupname , nodename , servername , registername , minconn , maxconn , registerflags , rc, rsn )

Parameters

[Updated in July 2012] daemongroupname [Updated in July 2012]
jul2012
(input)

An entry variable or entry constant containing the name of the WebSphere Application Server for z/OS daemon group to be joined. The daemon group name must be the same as the cell short name, not the daemon job name.

This entry variable or constant must be a null-terminated string of exactly 8 characters, and it must be passed by reference. The WebSphere Application Server for z/OS daemon must be running and initialized on the local system.

nodename (input)

An entry variable or entry constant containing the name of the WebSphere Application Server for z/OS node (short name) to be joined. The entry variable or constant must be passed by reference. The WebSphere Application Server z/OS Server must be running and completely initialized on the local system. This must be a blank padded string of exactly 8 characters.

servername (input)

An entry variable or entry constant containing the name of the WebSphere Application Server for z/OS Server (short name) to be joined. The entry variable or constant must be passed by reference. The WebSphere Application Server z/OS server must be running and completely initialized on the local system. This must be a blank padded string of exactly 8 characters.

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 can not be already in use in the current address space.

minconn (input)
An integer containing 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 MINCONN is specified as zero (0). Specifying 0 is the same as 1.
maxconn (input)

An integer containing 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 request when the minimum number of connections are all in use.

registerflags (input)
A 32-bit flag word containing registration flags.
  • reg_flag_trans - bit 30

    Contains a 1 if the transactional recovery is to be supported over connections under this registration and a 0 (zero) if the transactional recovery is not to be supported. When the transactional parameter is enabled, the adapter API attempts to register with the z/OS Resource Recovery Services (RRS) and a global transaction supporting two-phase commit is created between WebSphere Application Server and the API exploiter's environment.

  • reg_flag_W2Cprop - bit 31

    The reg_flag_W2Cprop controls WebSphere Application Server to CICS® outbound transaction security propagation.

  • reg_flag_C2Wprop - bit 29
    Propagates the identity on the calling task from CICS to WebSphere Application Server. For transactions that are inbound from CICS to WebSphere Application Server, registration flag reg_flag_C2Wprop controls how the identity is determined. When this bit is turned on, the CICS application task identity is used in the WebSphere server authorization process. When this bit is turned off, the CICS region identity is used.
    Attention: You have to enable WebSphere Application Server for CICS application level security to be requested. Set the WebSphere environment variable, ola_cicsuser_identity_propagate, to 1 through the administrative console to set this type of security propagation.
  • reg_flag_trcmod - bit 0

    Set reg_flag_trcmod 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

    With reg_flag_trcmod set to 1, set either reg_flag_trcmore or reg_flag_trcsome to specify a trace setting if you want detailed tracing or coarse level tracing for the registration. Leaving both of them set to "off" with reg_flag_trcmod set to 1 forces no tracing for the registration no matter what pre-definitions or defaults are set.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
  • The minimum connections requested is validated against the server maximum connections, which is configurable using the WebSphere Application Server administrative console. A minimum connection (minconn) value of 3 means that three connections are reserved during the register call. If more than three connections are requested at a given time, the connection pool can increase to the maximum connection (maxconn) value. When the number of all connections to a server reaches the maximum that is permitted, all subsequent Connection Get API requests for that server are rejected, even if the maxconn value is not yet reached.
    Important: Use caution in setting the minimum connections value. Except in specific instances, a large setting is not advised as resources in the WebSphere Application Server control region are reserved for each connection.
  • Multiple calls to the Register API can be made under the same address space, thread, or Customer Information Control System (CICS) task, however, they can not share the same register name. The register name must be a unique name.
  • Setting the transactional parameter to 1 results in all connections for this registration running with transactionality. This means that RRS is attached from the current address space. Refer to the section on Propagating Transactions for more details on the requirements and set up for this. Transactionality is only supported between WebSphere Application Server and CICS. Requests for transactional(1) from other environments results in a warning during the register call, the flag is ignored, and processing continues.
  • Use the Unregister API call to remove this registration and release the connection pool associated with it.
  • When the address space that makes a register call terminates, the registration is automatically terminated and the connections are released.
Return and reason codes
Table 2. BBOA1REG API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
  4 The transactional register flag was set to 1 in an environment where the adapter does not support global transactions. This setting is ignored and processing continues.
8 - Error - see reason code  
  8 The registration name token already exists. You must unregister this name before calling the Register API for it.
  10 The maximum connections parameter exceeds the maximum number of connections permitted for any single registration. The Register API request is rejected. Ensure that the target server maximum optimized local adapter value is large enough to accommodate this and all other requests. For more information about the WAS_DAEMON_ONLY_adapter_max_conn environment variable see the topic, Optimized local adapters custom properties, and the topic, Enabling the server environment to use optimized local adapters.
  12 The specified minimum connections parameter is larger than the maximum. Ensure that the minimum connections setting is less than, or equal to, the maximum setting.
  14 Out of shared memory while trying to create registration. Increase the shared memory allocation for the optimized local adapter or issue unregister calls to reduce resource consumption.
  21 An error occurred while attempting to make contact with the local WebSphere Application Server. If you set the reg_flag_C2Wprop bit (bit 29) to 1, ensure that the WebSphere environment variable, ola_cicsuser_identity_propagate, is set to 1.
  25 The transaction manager cannot be initiated. Call IBM® Support for assistance.
  70 Out of shared memory while trying to create a new connection. Increase the shared memory allocation for the optimized local adapter.
  74 Input register name contains a null. Blank pad the register name before invoking the Register API.
12 - Severe error - see reason code  
  4 An error occurred while locating the BBOACALL module. Ensure that the data set that contains the WebSphere Application Server BBOACALL module is available in the STEPLIB, LNKLST.
  10 Unable to locate the selected WebSphere Application Server daemon group. Ensure that theWebSphere Application Server daemon and target server are started, verify that the optimized local adapters support is active and retry.
  14 The User ID is not authorized for the requested WebSphere Application Server. Ensure that the user ID is authorized to the CBIND SAF class for the requested WebSphere Application Server.
  16 The node name or server name is not found. Ensure that the node name and server name parameters that are being passed are valid and that the server is active.
  23 An error occurred while naming the token. Call IBM Support for assistance.
  24 An error occurred while establishing the initial WebSphere Application Server local communication connection. Refer to the WebSphere Application Server control region logs for details on the local communication connect call.
  28 The registration identified with this name is not valid. The specified register name is already registered, but the RGE is missing. Contact IBM support and report the error. A workaround is to call the Unregister API and attempt to call the Register API again.
  30 The daemon group is not running with WAS_DAEMON_ONLY_enable_adapter property set to 1. Add the variable :WAS_DAEMON_ONLY_enable_adapter=1 through the WebSphere Application Server administrative console.
  68 An attachment to shared memory failed. Call IBM Support for assistance.

Unregister

Unregister from the local WebSphere Application Server for z/OS daemon group and server using the BBOA1URG API.
Table 3. BB0A1URG API syntax. This API requests that a group of optimized connections to a local WebSphere Application Server daemon group and server be released using the specified register name.
API Syntax
BBOA1URG

BBOA1URG (registername, unregflags, rc, rsn)

Parameters

registername (input)

An entry variable or entry constant containing the name to be used to unregister a set of local connections. This must be exactly 12 characters, blank padded, and the same name used on BBOA1REG.

unregisterflags (input)
A 32-bit flag word that contains unregistration flags.
  • Reserved - bit 0-30
  • Force (0|1) - bit 31

    Contains a 1 if the unregister request should be forced. By default, an unregister request is complete if all the connections have been returned to the connection pool. If all the connections are not returned to the pool, a warning is returned to the caller. The unregister is complete when the last connection has been returned to the pool. A second unregister request can be made with the force bit set to 1, which forces the unregister to complete and all remaining connection handles for that registration are invalidated.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • If the Unregister API is not called, and the address space that made a register call terminates, an unregister call is done automatically and the connections are released.
  • Any connection handles for this registration that are in use or active when the unregister call occurs may continue to be valid until they are returned to the connection pool using the BBOA1CNR API. To force the connection handles to be cleaned up, a second unregister call must be made, specifying the force flag. This invalidates all outstanding connection handles.
Return and reason codes
Table 4. BBOA1URG API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
  66 The unregister call is delayed until all the connections are returned to the pool. Unregistration completes when the last connection is returned to the free pool.
8 - Error - see reason code  
  8 Registration token name does not exist. You must register this name before calling the Unregister API for it.
  64 The force option cannot be specified until a normal unregister is issued. Call the Unregister API without specifying the force option.
  76 An attempt to communicate with the server failed because the server is no longer running. Start the server and retry the communication.
  82 An attempt has already been made to unregister this registration. Wait for the previous unregister request to complete or reissue this unregister with the force option.
  96 This API cannot be driven during Information Management System (IMS) initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe error - see reason code  

Connection Get

This API requests that an available connection from the pool created with the selected registration name be returned.
Table 5. BBOA1CNG API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1CNG

BBOA1CNG ( registername, connectionhandle, waittime, rc, rsn )

Parameters

registername (input)

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 (output)

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

waittime (input)

An integer containing the number of seconds to wait for the connection to complete before returning a connection unavailable reason code. A value of 0 (zero) implies there is no wait time and the API should wait indefinitely.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that theWebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • Ensure that a successful register (BBOA1REG) call was completed in the current address space with a matching name before using the Connection Get API.
Return and reason codes
Table 6. BBOA1CNG API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 The registration name token does not exist. Ensure that you have registered this name before you try to call the name with the Connection Get API.
  10 The connection is unavailable. The wait time expired before the connection request could be obtained. The application behavior varies. Wait and retry, or abend this connection. Another option is to increase the maximum connections setting on the Register API call.
  24 After a successful register call, an error occurred when getting a connection from the pool. Verify that the server is started. If it is not working, restart the server and retry the API request.
  28 Registration is found, but is inactive.  
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe error - see reason code  
  10 Unable to locate the WebSphere Application Server daemon group or server. Ensure that the WebSphere Application Server daemon and server are started and the local connections support is active and retry.

Connection Release

The Connection Release API requests that a connection be returned to the pool that it was retrieved from and be made available for another requestor.
Table 7. BBOA1CNR API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1CNR

BBOA1CNR ( connectionhandle, rc, rsn )

Parameters

connectionhandle (input)

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

rc (output)

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

rsn (output)

An integer reason code that describes the reason that the call failed.

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server that are specified on this call are started and the support for the local adapters is enabled.
  • Before using the Connection Release API, ensure that a successful register (BBOA1REG API) call is completed in the current address space with a matching name, and a successful Connection Get (BBOA1CNG) call completed to obtain the connection that is now to be released.
Table 8. BBOA1CNR API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Unable to locate the WebSphere Application Server daemon group and server. Any resources that are related to this connection have been cleared. None
8 - Error-see reason code  
  36 The connection state is not valid. The connection handle that is used for this request is in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle that is used for this request is not valid. Refer to the API documentation for information about client connection handles.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe error - see reason code  
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.

Send Request

These APIs send a request into the local WebSphere Application Server for processing.
Table 9. BBOA1SRQ API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1SRQ

BBOA1SRQ ( connectionhandle, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, async(0|1), responsedatalen, rc, rsn )

Parameters

connectionhandle (input)

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

requesttype (input)

An integer containing request type to indicate the type of method to call. Supported type values: 1 - EJB

requestservicename (input)

An EBCDIC character string up to 256 bytes containing the name of the service. For Type=1, EJB, this is the JNDI home name for the target EJB. The string must be null terminated, or the length must be given in the requestservicenamel parameter.

requestservicenamel (input)

An integer containing the length of the service name to invoke or 0 (zero) if the service name is null terminated.

requestdata (input)

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

requestdatalen (input)

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

async(0|1) (input)

An integer value that when set to 1 indicates that the caller wants control returned immediately, even though the response length may not yet be known. For async(0), the current thread is requesting to wait for the response to be returned from the WebSphere Application Server and the response length is returned in the responsedatalen output argument.

responsedatalen (output)

A 32-bit unsigned value that contains the length of the response. This length can then be used by the caller to acquire storage before calling the Get Data API to copy it in. When async is set to 1, indicating the caller wants control back immediately, this is set to all 0xFFs if the response is not yet received.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
  • Ensure that a successful register (BBOA1REG) call was completed in the current address space with a matching name before using the Send Request API.
Return and reason codes
Table 10. BBOA1SRQ API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  14 An out of memory condition occurred while saving the message. There is not enough memory available for Send Request to process the message. The current address space is out of private storage.
  16 The request service name length is not valid. Correct the program and retry.
  18 The request length exceeds the system limits. The message size is larger than the WebSphere Application Server size can support. Verify that the size is valid. If the size is valid, ensure that the WebSphere Application Server size is large enough to accommodate the message size.
  26 Global transaction could not begin.  
  32 The API call request type is not valid. The request type is not valid. Correct the program and retry the call.
  34 The target service is not found. Ensure that the application that contains the target enterprise bean is installed and started in the target server for WebSphere Application Server.
  36 The connection state is not valid. The connection handle that is used for the request is in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle that is used for the request is not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  44 An exception or unexpected condition occurred in the target enterprise bean. Refer to the WebSphere Application Server logs to review the exception data.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe error - see reason code  
  10 Unable to locate the WebSphere Application Server daemon group or server. Ensure that the WebSphere Application Server daemon and server are started and the local connections support is active. Retry to locate the WebSphere Application Server daemon group and server.
  14 The API calling vector using the provided connections handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.

Send Response

This API sends a response to a request back to the local WebSphere Application Server.
Table 11. BBOA1SRP API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1SRP

BBOA1SRP ( connectionhandle, responsedata, responsedatalen, rc, rsn )

Parameters

connectionhandle (input)

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

responsedata (input)

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

responsedatalen (input)

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

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using the Send Response API.
  • Ensure that a successful connection get (BBOA1CNG) call completed and the handle for this is provided as input on this call.
  • Ensure that a successful receive Request Any, Receive Request Specific or Host API call was issued and returned with request data for the connection handle. The connection must be in a state where the Send Response API is valid.
Return and reason codes
Table 12. BBOA1SRP API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  14 An out of memory condition occurred while saving the message. There is not enough memory available for Send Response to process the message. The current address space is out of private storage.
  18 The response length exceeds the system limits. The message size is larger than the WebSphere Application Server size can support. Verify that the size is valid. If the size is valid, ensure that the WebSphere Application Server size is large enough to accommodate the message size.
  34 The target service is not found. Ensure that the application containing the target EJB is installed and started in the target WebSphere Application Server.
  36 The connection state is not valid. The connection handle used for this request is in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request is not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 Unable to locate toWebSphere Application Server daemon group or server. Ensure that the WebSphere Application Server daemon and server are started and local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG) might have invalidated the connection pool.

Send Response Exception

This API sends an exception response data back to the JCA caller in the local WebSphere Application Server. The response is a ResourceAdapterException with the specified exception response data returned.

Table 13. BBOA1SRX API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1SRX

BBOA1SRX ( connectionhandle, excresponsedata, exresponsedatalen, rc, rsn )

Parameters

connectionhandle (input)

A 12-byte connection handle that is used for the response.

excresponsedata (input)

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

excresponsedatalen (input)

Specifies a 31-bit pointer to the address of the start of the exception response data to send. Exception response data is an EBCDIC string describing the error.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server that are specified on this call are started and the support for local adapters is enabled.
  • Ensure that a successful register (BBOA1REG API) call completed in the current address space with a matching name before using the send response call.
  • Ensure that a successful connection get (BBOA1CNG API) call completed and the handle for this is provided as input on this call.
  • Ensure that a successful Receive Request Any or Receive Request Specific or Host API call was issued and returned with request data for the connection handle. The connection must be in a state where the Send Response and Send Response Exception APIs are valid.
Return and reason codes
Table 14. BBOA1SRX API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  10 The connection handle is in a released or not valid state. Ensure that a proper connection handle was passed.
  14 An out of memory condition occurred while saving the message. There is not enough memory available for Send Response Exception to process the message. The current address space is out of private storage.
  16 One or more parameters are not valid. Verify that all the parameters are valid and retry the call.
  18 The response length exceeds the system limits. The message size is larger than the WebSphere Application Server size can support. Verify that the size is valid. If the size is valid, ensure that the WebSphere Application Server size is large enough to accommodate the message size.
  20 One or more parameters are not valid. Verify that all the parameters are valid and retry the call.
  28 The registration that the connection handle was associated with is no longer active. Call register with the registration name again before making the connection get and send request calls.
  36 The connection state is not valid. The connection handle used for this request is in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request is not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 Unable to locate to WebSphere Application Server daemon group or server. Ensure that the WebSphere Application Server daemon and server are started and local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.

Receive Request Any

Receive a request from a local WebSphere Application Server on any connection. Receive a request and related data on any available connection in the pool for the passed register name. Returns request data length as an output parameter. A connection handle is also an output parameter returned to the caller. A Get Data API call with the returned connection handle returns the received message data.

Table 15. BBOA1RCA API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1RCA

BBOA1RCA ( registername, connectionhandle, requestservicename, requestservicenamel, requestdatalen, waittime, rc, rsn )

Parameters

registername (input)

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 (output)

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

requestservicename (input/output)

An EBCDIC character string up to 256 bytes containing the name of the service. This is the name of the target service specified on the InteractionSpec by the WebSphere Application Server application. A value of ‘*' indicates a receive request for all service names arriving under the current register name.

requestservicenamel (input/output)

An integer containing the length of the service name to invoke or 0 (zero) if the service name is null terminated.

requestdatalen (output)

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

waittime (input)

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 (zero) indicates that there is not wait time and that the API should wait indefinitely.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using this API.
Return and reason codes
Table 16. BBOA1RCA API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  11 Bad data was sent from WebSphere Application Server  
  16 The request service name length is not valid. Correct the program and retry the call.
  19 Local communication existing data failure  
  21 Local communication preview data failure  
  38 The client connection handle is not valid. The client connection handle used for this request was determined to be not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  76 An attempt to communicate with the server failed because the server is no longer running. Start the server and retry the communication.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe error - see reason code  
  10 WebSphere Application Server daemon group or server cannot be located. Ensure that the WebSphere Application Server daemon and server are started and that the local connections support is active and retry the call.
  24 After a successful registration call, an error occurred when getting a connection from the pool. Verify that the server is started. If the server is not started, restart the server and retry the API request.
  44 Bad CP build for service call  
  46 Bad CP get for service cell  
  48 Bad CP free for service cell  
  60 Unable to get SRVQ lock  
  62 Unable to unlock SRVQ lock  

Receive Request Specific

Receive a request from a local WebSphere Application Server on a specific connection. Receive a request and related data for the supplied input connection handle. Returns request data length. A Get Data API call with the returned connection handle returns the received message data.
Table 17. BBOA1RCS API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1RCS

BBOA1RCS ( connectionhandle, requestservicename, requestservicenamel, requestdatalen, async(0|1), rc, rsn )

Parameters

connectionhandle (input)

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

requestservicename (input/output)

An EBCDIC character string up to 256 bytes containing the name of the service. This is the name of the target service specified on the InteractionSpec by the WebSphere Application Server application. A value of * (asterik) indicates that set up as a server for all service names arriving under the current register name.

requestservicenamel (input/output)

An integer containing the length of the service name to invoke or 0 (zero) if the service name is null terminated.

requestdatalen (output)

A 32-bit unsigned value is returned that contains the length of the request data received. This length can then be used by the caller to acquire storage before calling the Get Data API to copy it in. When async is set to 1, indicating the caller wants control back immediately, this is set to all 0xFFs if the request data has not yet been received. In this case, the API must be called again to retrieve an inbound request.

async(0|1) (input)

An integer value that when set to 1 indicates the caller wants control returned immediately, even though the request length may not yet be known. When async is set to 0, this call will wait for a request from the WebSphere Application Server to be received.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using this API.
Return and reason codes
Table 18. BBOA1RCS API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  10 The connection handle is in a released state improper state. Ensure that a proper connection handle passed.
  11 Bad data was sent from the WebSphere Application Server  
  16 The request service name length is not valid. Correct the program and retry the call.
  19 Local communication existing data failure  
  21 Local communication preview data failure  
  28 The registration that the connection handle was associated with is no longer active. Call the registration name again before calling connection get and receive request specific.
  36 The connection state is not valid. The connection handle used for this request is in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request is not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  76 An attempt to communicate with the server failed because the server is no longer running. Start the server and retry the communication.
  78 An internal error occurred that caused the connection to select a request that was not a part of the transaction being processed by this connection. Return the connection to the connection pool. If the problem persists, contact IBM Support.
  80 The transaction that is active on this connection has timed out and the connection state could not be reset so that another request is processed. Return the connection to the connection pool. If the problem persists, contact IBM Support.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 The WebSphere Application Server daemon group or server cannot be located. Ensure that WebSphere Application Server daemon and server are started and local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.
  44 Bad CP build for service cell  
  46 Bad CP get for service call  
  48 Bad CP free for service cell  
  60 Unable to get SRVQ lock  
  62 Unable to unlock SRVQ lock  

Receive Response Length

Receive response length is used to retrieve the length of the response data from a prior send request call.
Table 19. BBOA1RCL API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1RCL

BBOA1RCL ( connectionhandle, async(0|1), responsedatalen, rc, rsn )

Parameters

connectionhandle (input)

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

async (input)

An integer value that when set to 1 indicates the caller wants control returned immediately, even though the response length may not yet be known. When async is set to 0 this call will wait for the response to be returned from the WebSphere Application Server and supply the response length in the responsedatalen parameter value.

responsedatalen (output)

A 32-bit unsigned value containing the length of the data received is returned. This length can be used by the caller to acquire storage before calling the Get Data API to copy it in. If async is 1 this may be returned as all FFs if the response data is not yet received

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using this API.
  • Ensure that a successful Connection Get (BBOA1CNG API) call completed and the handle is provided as input on this call.
  • Ensure that a successful Send Request (BBOA1SRQ API) call was completed before making this call.
Return and reason codes
Table 20. BBOA1RCL API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  11 Bad data was sent from the WebSphere Application Server.  
  19 Local communication existing data failure  
  21 Local communication preview data failure  
  36 The connection state is not valid. The connection handle used for this request was determined to be in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request was determined to be not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 The WebSphere Application Server daemon group or server cannot be located. Ensure that the WebSphere Application Server daemon and server are started and local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.

Get Message Data

This API is used to copy the received message data. On return from this call, the message is removed from the adapter message cache.
Table 21. BBOA1GET API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1GET

BBGA1GET ( connectionhandle, msgdata, msgdatalen, rc, rsn, rv )

Parameters

connectionhandle (input)

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

msgdata (input)

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

msgdatalen (input)

A 32-bit unsigned value containing the length of the data to be copied.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

rv (output)

An 32-bit integer return value containing the size of the context buffer for this request.

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using the Send Request API.
  • Ensure that a successful connection get (BBOA1CNG API) call completed and the handle is provided as input on this call.
  • If the API caller input msgdatalen parameter is larger than the actual message response, the return code contains a 0 (zero) and the actual message length is provided to the return value.
  • Important: Once the get message data call returns to the caller, the message data does not persist and the connection is returned to a state where it can be used for another send or receive request call. A subsequent call to get message data or receive response length is returned in error.
Return and reason codes
Table 22. BBOA1GET API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  36 The connection state is not valid. The connection handle used for this request was determined to be in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request was determined to be not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  48 An error occurred in the local communication read request. Check the WebSphere Application Server logs to determine the error.
  50 The connection with the WebSphere Application Server is terminated. Check WebSphere Application Server logs to determine the error.
  72 Response length input parameter is not large enough to contain the response message. Only a portion of the message is returned. The remainder is discarded. Refer to the return value for the size of the message response.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 The WebSphere Application Server daemon group or server cannot be located. Ensure that the WebSphere Application Server daemon and server are started and the local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.

Invoke

This API uses other underlying primitive API functions to call a method in a local WebSphere Application Server. It is designed to be used in situations where the response output area maximum size is known in advance.
Table 23. BBOA1INV API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1INV

BBOA1INV ( registername, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, responsedata, responsedatalen, waittime, rc, rsn, rv )

Parameters

registername (input)

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

requesttype (input)

An integer containing request type to indicate the type of method to call. Supported type values : 1 - EJB

requestservicename (input)

An EBCDIC character string up to 256 bytes in length containing the name of the service to invoke. For Type=1, EJB, this is the JNDI Home name for the target EJB.

requestservicenamel (input)

An integer containing the length of the service name to invoke or 0 (zero) if the service name is null terminated.

requestdata (input)

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

requestdatalen (input)

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

responsedata (input)

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

responsedatalen (input)

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

waittime (input)

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 (zero) indicates that there is no timeout and that this API should wait indefinitely.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

rv (output)

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

Usage notes
  • Ensure that the WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
  • Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using the Send Request API.
  • If the API caller input responsedatalen parameter is larger than the actual message response, the return code contains a 0 (zero) and the actual message length is provided in the return value.
Return and reason codes
Table 24. BBOA1INV API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  10 The connection is unavailable. The wait time expired before the connection request could be obtained. The application behavior varies. Wait and retry, or accept this failed Invoke API call. Another option is to increase the maximum connections setting on the Register API call.
  11 Bad data was sent from the WebSphere Application Server.  
  14 An out of memory condition occurred while saving the message. There is not enough memory available for the invoke to process the message. The current address space is out of private storage.
  16 The request service name length is not valid. Correct the program and retry the call.
  18 The response length exceeded the system limits. The message size is larger than the WebSphere Application Server size can support. Verify that the size is valid. If the size is valid, ensure that the WebSphere Application Server size is large enough to accommodate the message size.
  19 Local communication existing data failure.  
  21 Local communication preview data failure.  
24 After a successful register call, an error occurred when getting a connection from the pool. Verify that the server is started. If it is not working, restart the server and retry the API request.
  26 Global transaction could not begin.  
  28 Registration is found, but is inactive.  
  32 The request type on the API call is not valid. The request type parameter is not valid. Correct the program and retry the call.
  34 The target service not found. Ensure the application containing the target enterprise bean is installed and started in the target WebSphere Application Server.
  36 The connection state is not valid. The connection handle used for this request was determined to be in the wrong state. Refer to the API documentation for the rules on connection states.
  38 The client connection handle is not valid. The client connection handle used for this request was determined to be not valid. Refer to the API documentation for information about client connection handles.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  44 An exception or unexpected condition occurred in the target enterprise bean. Refer to the WebSphere Application Server logs to review the exception data.
  46 An error occurred in the local communication send request. Refer to the WebSphere Application Server logs to determine the error.
  48 An error occurred in the local communication read request. Check the WebSphere Application Server logs to determine the error.
  50 The connection with theWebSphere Application Server is terminated. Check the WebSphere Application Server logs to determine the error.
  72 Response length input parameter is not large enough to contain the response message. Only a portion of the message is returned. The remainder is discarded. Refer to the return value for the size of the message response.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 The WebSphere Application Server daemon group or server cannot be located. Ensure that the WebSphere Application Server daemon and server are started and local connections support is active and retry the call.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.
  24 After a successful register call, an error occurred while getting a connection from the connection pool. Verify that the server is started. If it is not started, restart the server and retry the API request.

Host Service

Host Service for a local WebSphere Application Server. This API uses other underlying primitive API functions to setup a native language z/OS program as a server and target for optimized local adapter calls from a local WebSphere Application Server. It is designed to be used in situations where the request area maximum size is known in advance.
Table 25. BBOA1SRV API syntax. The syntax is explained in the Parameters section.
API Syntax
BBOA1SRV

BBOA1SRV ( registername, requestservicename, requestservicenamel, requestdata, requestdatalen, connectionhandle, waittime, rc, rsn, rv )

Parameters

registername (input)

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

requestservicename (input/output)

An EBCDIC character string up to 256 bytes containing the name of the service. This is the name of the target service specified on the InteractionSpec by the WebSphere Application Server application. A value of ‘*' indicates set up as a server for all service names arriving under the current register name.

requestservicenamel (input/output)

An integer containing the length of the service name to invoke or 0 (zero) if the service name is null terminated.

requestdata (input)

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

requestdatalen (input)

A 32-bit unsigned value containing the length of the data area to receive the message into.

connectionhandle (output)

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

waittime (input)

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 (zero) implies that there is no timeout and that the API should wait indefinitely.

rc (output)

An integer return code indicating success or failure of this call.

rsn (output)

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

rv (output)

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

Usage notes
Return and reason codes
Table 26. BBOA1SRV API return and reason codes. The following table also recommends appropriate actions.
Return Code Reason Code Description Action
0 - Success  
4 - Warning - see reason code  
8 - Error - see reason code  
  8 Register name token already exists. Ensure that the register name passed is valid.
  10 The connection handle is in a released state. Ensure that a proper connection handle passed.
  12 The connection handle is not in the connection that is in the registration name. Correct to program and retry the call.
  16 The request service name length is not valid. Correct the program and retry the call.
  18 The response length exceeds the system limits. The message size is larger than the WebSphere Application Server size can support. Verify that the size is valid. If the size is valid, ensure that the WebSphere Application Server size is large enough to accommodate the message size.
  40 A local communication error occurred. Check the WebSphere Application Server server log for any local communication error messages.
  46 An error occurred in the local communication send request call. Check the WebSphere Application Server logs to determine the error.
  48 An error occurred in the local communication read request. Check the WebSphere Application Server logs to determine the error.
  50 The connection with the WebSphere Application Serverr is terminated. Check the WebSphere Application Server logs to determine the error.
  72 Response length input parameter is not large enough to contain the response message. Only a portion of the message is returned. The remainder is discarded. Refer to the return value for the size of the message response.
  76 An attempt to communicate with the server failed because the server is no longer running. Start the server and retry the communication.
  96 This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. Call this API after IMS initialization is complete.
12 - Severe user error - see reason code  
  10 The WebSphere Application Server daemon group or server cannot be located. Ensure WebSphere Application Server daemon and server are started and local connections support is active and retry.
  14 The API calling vector using the provided connection handle cannot be located or verified. The connection handle is not valid or an unregister call (BBOA1URG API) might have invalidated the connection pool.
  44 Bad CP build for service cell.  
  46 Bad CP get for service cell.  
  48 Bad CP free for service cell.  
  60 Unable to get SRVQ lock.  
  62 Unable to unlock SRVQ lock.  

JCA adapters APIs

For calls from WebSphere Application Server into a batch program or subsystem, the WebSphere application uses the standard JCA APIs. The objects that are customized for this adapter are as follows:
  • ConnectionSpec
  • InteractionSpec
  • Record I/O
See the related links for additional information about these standard JCA APIs in the information center.

The ConnectionSpec API is used to indicate which register name to communicate with. The register name is created when the Register API is used. This also identifies which subsystem to connect to. A subsystem can have more than one register name.

The name of the Program Link transaction ID can be passed from WebSphere Application Server to CICS, and is used to run the Program Link invocation task. This must be 4 characters and defined in the CICS region. You must set it up with the same attributes and program name as the BBO# transaction (program: BBOACLNK). When this transaction ID is passed using the setLinkTaskTranid method, it overrides the BBO# API and any transaction ID that was specified using BBOC with the LTX=xxxx parameter.

A setUseCICSContainer method is provided on the ConnectionSpecImpl. When this is set to 1, the name and type of a message request CICS container can be passed to CICS using the methods, setLinkTaskReqContid() and setLinkTaskReqContType(0|1), where 0=CHAR and 1=BIT. When this is passed, the target program has its own input data passed in the named container, which is created with the selected type of BIT or CHAR.

The name and type of a message response CICS container can be passed to CICS using the methods, setLinkTaskRspContid() and setLinkTaskRspContType(bit|char). When this is passed, the target program's response is expected to come from the named container with the selected type of BIT or CHAR.

For IMS application transactions, use the setOTMAMaxRecvSize(nnn) method on the Connection Specification to set the Maximum Message Receive size. To set the Maximum Segments connection level value use the setOTMAMaxSegments(nnn) method on the Connection Specification. For more information about using optimized local adapters with IMS over OTMA, see the topic Calling existing IMS transactions with optimized local adapters over OTMA.

InteractionSpec

The InteractionSpec API is used to specify which service should be invoked by the target. This is dependent on what subsystem or batch process is invoked. The process can choose to receive requests for a specific service, or for any service. For CICS, the service name should be the name of the program to execute in CICS.

Record I/O

Applications can pass data to and receive data from the adapter using the JCA record interface. This adapter API proposes to use the indexed record interface to allow the caller to pass one or more data structures, including Cobol copybooks and C structures, to the external address space. Each index in the list is taken as a separate copybook and passed to the target in that order.

When used to accept return parameters from a function call, the IndexedRecordImpl can be predefined to accept a particular number of parameters, and the class names generated by the assembly tools for the individual copybooks and structures can be provided. The IndexedRecordImpl inflates the serialized copybooks and structures and sets them into the IndexedRecordImpl so that they can be retrieved and used without dealing with the serialized byte[] representations.

To give a general idea of how this API works, only selected methods are shown. All of the methods on the interface are implemented.




Related concepts
Optimized local adapters for z/OS usage scenarios
Optimized local adapters environment variables
olaInstall.sh script file
Related tasks
Using optimized local adapters for inbound support
Using optimized local adapters for outbound support
Accessing data using Java EE Connector Architecture connectors
Enabling the server environment to use optimized local adapters
Related reference
Related information
Calling existing IMS transactions with optimized local adapters over OTMA


Terms and conditions for information centers | Feedback

Last updatedLast updated: Feb 5, 2014 9:49:51 PM CST
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-mp&topic=cdat_olaapis
File name: cdat_olaapis.html