WebSphere® Application Server for z/OS® optimized local adapters are supported by a set of z/OS native language callable services, or application programming interfaces (APIs), and the Java EE Connector Architecture (JCA).
A caller running in AMODE 64 can use the AMODE 31 versions of the APIs, provided the parameter list is below the bar and it passes parameter using 31-bit conventions (each parameter’s pointer is a 31 bit address). Callers running in 64-bit must be in either C, C++, or assembler, and execute in 64-bit addressing mode. When using the BBGA1* 64-bit APIs from assembler applications, a format 4, or F4SA, 64-bit save area is required, which is used by the optimized local adapters stubs to save and restore the caller's registers. When calling from C or C++, the sample header in <Prod_FS_root>/util/zos/OLASamples/bboaapi.h defines the 64-bit APIs as external OS_NOSTACK, which ensures that they are called with the proper linkage and save area conventions.
When the term local connection is used in this API documentation, a reference is being made 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 the same z/OS system. The client address space must 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 be used for one set only 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 (for 31-bit callers) and BBGA1REG (for 64-bit callers) APIs, you can register with a local WebSphere Application Server for z/OS daemon group and server. The BBOA1REG and BBGA1REG APIs request 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 or BBGA1REG | BBOA1REG ( daemongroupname , nodename , servername , registername , minconn , maxconn , registerflags , rc, rsn ) BBGA1REG ( 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 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 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 cannot be used 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.
Prior to Version 8.0.0.4, 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.
Starting with Version 8.0.0.4, if you are running in an IMS dependent region and set this flag to 1, you make sure that you are running your IMS environment with RRS=YES, and the server, or node-level environment variable ola_rrs_context_propagate has been added to your configuration and is set to true (or 1). Under IMS, the RRS context is in effect on the thread when the Invoke or Send Request WOLA API call is propagated and asserted in the WebSphere Application Server for z/OS EJB container.
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 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 connection. | Increase the shared memory allocation for the optimized local adapter. | |
74 | Input register name contains a null. | Blank pad the register name before starting the Register API. | |
12 | 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 selectedWebSphere Application Server daemon group. | Ensure that the WebSphere Application Server daemon and target server are started, verify that the optimized local adapters support is active and try again. | |
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 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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
68 | An attachment to shared memory failed. | Call IBM Support for assistance. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1URG or BBGA1URG | BBOA1URG (registername, unregflags, rc, rsn) BBGA1URG (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 process 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 process 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 try the communication again. | |
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 | 34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1CNG or BBGA1CNG | BBOA1CNG ( registername, connectionhandle, waittime, rc, rsn ) BBGA1CNG ( 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 implies there is no wait time and the API waits 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 try again, 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 try the API request again. | |
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 | 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 try again. |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1CNR or BBGA1CNR | BBOA1CNR ( connectionhandle, rc, rsn ) BBGA1CNR ( 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 | 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. |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1SRQ or BBGA1SRQ | BBOA1SRQ ( connectionhandle, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, async(0|1), responsedatalen, rc, rsn ) BBGA1SRQ ( 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 the request type that indicates the type of work request to process. Supported type values: 1 = local EJB work requests, 2 = Remote EJB work requests.
requestservicename (input) An EBCDIC character string
up to 256 bytes in length containing the name of the service to invoke.
For Type=1, EJB and Type 2, remote EJB, this is the JNDI Home name
for the target.
An integer containing the length of the service name to start or 0 (zero) if the service name is null terminated.
requestdata (input)A 31-bit or 64-bit pointer to the address of the start of the request data to send.
requestdatalen (input)A 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 might 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 in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 try again. | |
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 try the call again. | |
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. | |
98 | The beginning of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
100 | The end of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
12 | 10 | Unable to locate theWebSphere 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 theWebSphere 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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
or BBGA1SRP | ( connectionhandle, responsedata, responsedatalen, rc, rsn ) BBGA1SRP ( 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 or 64-bit pointer to the address of the start of the response data to send.
responsedatalen (input)A 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64 bit mode 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. | |
102 | The beginning of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
104 | The end of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
12 | 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 try the call again. |
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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
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 or BBGA1SRX | BBOA1SRX ( connectionhandle, excresponsedata, exresponsedatalen, rc, rsn ) BBGA1SRX ( 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 or 64-bit pointer to the address of the start of the exception response data to send.
excresponsedatalen (input)Specifies a 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64-bit mode of the length 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 valid 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 try the call again. | |
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 try the call again. | |
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. | |
102 | The beginning of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
104 | The end of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
12 | 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 try the call again. |
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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
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 or BBGA1RCA | BBOA1RCA ( registername, connectionhandle, requestservicename, requestservicenamel, requestdatalen, waittime, rc, rsn ) BBGA1RCA ( 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 start or 0 if the service name is null terminated.
requestdatalen (output)A 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 indicates that there is no wait time and that the API waits 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 try the call again. | |
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 try the communication again. | |
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 | 10 | WebSphere Application Server daemon group or server cannot be located. | Ensure that theWebSphere Application Server daemon and server are started and that the local connections support is active and try the call again. |
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 try the API request again. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
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 | ||
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1RCS or BBGA1RCS | BBOA1RCS ( connectionhandle, requestservicename, requestservicenamel, requestdatalen, async(0|1), rc, rsn ) BBGA1RCS ( 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 * 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 start or 0 if the service name is null terminated.
requestdatalen (output)A 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 waits 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 valid 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 try the call again. | |
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 try the communication again. | |
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 | 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 try the call again. |
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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
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 | ||
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1RCL or BBGA1RCL | BBOA1RCL ( connectionhandle, async(0|1), responsedatalen, rc, rsn ) BBGA1RCL ( 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 might not be known. When async is set to 0, this call waits 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 in 31-bit mode and a 64-bit unsigned value in 64-bit mode 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 might 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 | 10 | The WebSphere Application Server daemon group or server cannot be located. | Ensure that the WebSphere Application Serverdaemon and server are started and local connections support is active and try the call again. |
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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1GET or BBGA1GET | BBOA1GET ( connectionhandle, msgdata, msgdatalen, rc, rsn, rv ) 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 or 64-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 in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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)A 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 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. | |
98 | The beginning of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
100 | The end of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
102 | The beginning of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
104 | The end of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
12 | 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 try the call again. |
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. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1INV or BBGA1INV | BBOA1INV ( registername, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, responsedata, responsedatalen, waittime, rc, rsn, rv ) BBGA1INV ( 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 the request type that indicates the type of work request to process. Supported type values: 1 = local EJB work requests, 2 = Remote EJB work requests.
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.
requestservicenamel (input)An integer containing the length of the service name to start or 0 if the service name is null terminated.
requestdata (input)A 31-bit or 64-bit pointer to the address of the start of the request data to send.
requestdatalen (input)A 32-bit unsigned value in 31-bit mode or a 64-bit unsigned value in 64-bit mode containing the length of the data to send.
responsedata (input)A 31-bit or 64-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 in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 waits 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 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 is 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 try the call again. | |
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 try the API request again. | |
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 try the call again. | |
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 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 | 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 try the call again. |
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 try the API request again. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0.1 level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0.1 level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
API | Syntax |
---|---|
BBOA1SRV or BBGA1SRV | BBOA1SRV ( registername, requestservicename, requestservicenamel, requestdata, requestdatalen, connectionhandle, waittime, rc, rsn, rv ) BBGA1SRV ( 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 start or 0 if the service name is null terminated.
requestdata (input)A 31-bit or 64-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 in 31-bit mode or a 64-bit unsigned value in 64-bit mode 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 waits 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 right connection handle passed. | |
12 | The connection handle is not in the connection that is in the registration name. | Correct to program and try the call again. | |
16 | The request service name length is not valid. | Correct the program and try the call again. | |
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 Server is terminated. | Check theWebSphere 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 try the communication again. | |
96 | This API cannot be driven during IMS initialization or during an IMS pre-initialization exit. | Call this API after IMS initialization is complete. | |
98 | The beginning of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
100 | The end of the supplied request buffer could not be accessed. | Ensure that the supplied request buffer address and length are correct. | |
102 | The beginning of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
104 | The end of the supplied response buffer could not be accessed. | Ensure that the supplied response buffer address and length are correct. | |
12 | 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 try again. |
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 or BBGA1URG API) might have invalidated the connection pool. | |
34 | A 64-bit API stub was used in an IMS environment. | The 64-bit APIs are not supported under IMS. | |
38 | A 64-bit API stub was used in a CICS environment. | The 64 bit APIs are not supported under CICS. | |
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. | ||
86 | WebSphere Application Server for z/OS master BGVT could not be located | WebSphere has not been started yet on the current z/OS system image. Ensure the daemon and a node/server are started before starting any WebSphere Application Server optimized local adapters client processes. | |
88 | WebSphere Application Server for z/OS master client stub table could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. | |
90 | WebSphere Application Server for z/OS optimized local adapters master client stub table slot could not be located. | A WebSphere Application Server has been started on the current z/OS system image, but is not running at the level where the optimized local adapters client stub table is supported. You are possibly running with a WebSphere Application Server Version 8.0.0.1 optimized local adapters stub interface that is not compatible with the maintenance level of the application server. To use the V8.0.0.1 optimized local adapters stubs, the application server must also be running at the WebSphere Application Server Version 8.0.0. level. Ensure your application is running with the level of the optimized local adapters stubs that are compatible with WebSphere Application Server on this z/OS system. |
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 fromWebSphere 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=xxx parameter.
You can use either the setUseCICSContainer method or the JCA MappedRecord interface to send applications to CICS using channels and containers.
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 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 is to be started by the target. This is dependent on what subsystem or batch process is started. The process can choose to receive requests for a specific service, or for any service. For CICS, the service name is the name of the program to start 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.