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).
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.
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."
API | Syntax |
---|---|
BBOA1REG | BBOA1REG ( daemongroupname , nodename , servername , registername , minconn , maxconn , registerflags , rc, rsn ) |
Parameters
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 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)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.
The reg_flag_W2Cprop controls WebSphere Application Server to CICS® outbound transaction security propagation.
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.
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.
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.
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. |
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)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.
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.
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 |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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.
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 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.
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.
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 |
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.
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 |
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.
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. |
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.
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. |
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.
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. |
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 notesReturn 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. |
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.
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.
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.