(ZOS) Optimized local adapters for z/OS APIs
WebSphere Application Server for z/OS optimized local adapters are supported by a set of z/OS native language callable services, or APIs, and the Java EE Connector Architecture (JCA).
These callable services can be used from the following native programming languages:
- Cobol
- C/C++
- PL/I
- High Level Assembler
Each callable service has a 31-bit and a 64-bit version. The naming convention is BBOA1- for 31-bit API stubs and BBGA1- for 64-bit API callers.
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 created for communication between an external address space on the z/OS system and the WAS on 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.
The API services are listed according to user goal, for example, the first section listed is Register. This section explains the APIs used in the task of registering an optimized local adapter so that it can be used in a call.
- Register - BBOA1REG/BBGA1REG
- Unregister - BBOA1URG/BBGA1URG
- Connection Get - BBOA1CNG/BBGA1CNG
- Connection Release - BBOA1CNR/BBGA1CNR
- Send Request - BBOA1SRQ/BBGA1SRQ
- Send Response - BBOA1SRP/BBGA1SRP
- Send Response Exception - BBOA1SRX/BBGA1SRX
- Receive Request Any - BBOA1RCA/BBGA1RCA
- Receive Request Specific - BBOA1RCS/BBGA1RCS
- Receive Response Length - BBOA1RCL/BBGA1RCL
- Get Message Data - BBOA1GET/BBGA1GET
- Invoke - BBOA1INV/BBGA1INV
- Host Service - BBOA1SRV/BBGA1SRV
- JCA Adapter APIs
Register
Use the BBOA1REG (for 31-bit callers) and BBGA1REG (for 64-bit callers) APIs, we can register with a local WAS for z/OS daemon group and server. The BBOA1REG and BBGA1REG APIs request that a group of optimized connections to a local WAS 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
daemongroupname (input)An entry variable or entry constant containing the name of the WAS 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 WAS 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 WAS for z/OS node (short name) to be joined. The entry variable or constant must be passed by reference. The WAS 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 WAS for z/OS Server (short name) to be joined. The entry variable or constant must be passed by reference. The WAS 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 initial minimum number of connections to allocate for this registration. The adapter attempts to reserve this number of connections with the associated server during registration.
Important: At minimum, one connection is allocated to bind with the target server, even if MINCONN is specified as zero (0). Specifying 0 is the same as 1. maxconn (input)
An integer containing the maximum number of connections to allocate for this registration. The adapter attempts to extend the local connection pool up to this number during a Connection Get request when the minimum number of connections are all in use.
registerflags (input)A 32 - bit flag word containing registration flags.
- reg_flag_trans - bit 30
Contains a 1 if the transactional recovery is to be supported over connections under this registration and a 0 (zero) if the transactional recovery is not to be supported.
When the transactional parameter is enabled, the adapter API attempts to register with the z/OS Resource Recovery Services (RRS) and a global transaction supporting two-phase commit is created between WAS and the API exploiter's environment.
Starting with v8.5.0.2, if we are running in an IMS™ dependent region and set this flag to 1, we make sure that we are running your IMS environment with RRS=YES, and the server, or node-level environment variable ola_rrs_context_propagate has been added to the 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 WAS for z/OS EJB container.
If we need to add the ola_rrs_context_propagate variable to the configuration settings, or change the setting on this variable to true, we must restart the server after making this configuration change..
- reg_flag_W2Cprop - bit 31 or bit 64
The reg_flag_W2Cprop controls WAS to CICS outbound transaction security propagation.
- reg_flag_C2Wprop - bit 29
Propagates the identity on the calling task from CICS to WAS. For transactions inbound from CICS to WAS, registration flag reg_flag_C2Wprop controls how the identity is determined. When this bit is turned on, the CICS application task identity is used in the WAS server authorization process. When this bit is turned off, the CICS region identity is used.
We must enable WAS for CICS application level security to be requested. Set the WebSphere environment variable, ola_cicsuser_identity_propagate, to 1 through the administrative console to set this type of security propagation.
- reg_flag_trcmod - bit 0
Set reg_flag_trcmod to modify the optimized local adapter trace settings for the requested registration. If we do not set this flag, no change to the trace setting is made, and the system defaults or predefined trace settings that apply to the registration name or job name are used.
- reg_flag_trcmore - bit 1 and reg_flag_trcsome - bit 2
With reg_flag_trcmod set to 1, set either reg_flag_trcmore or reg_flag_trcsome to specify a trace setting if we want detailed tracing or coarse level tracing for the registration. Leaving both of them set to "off" with reg_flag_trcmod set to 1 forces no tracing for the registration no matter what pre-definitions or defaults are set.
rc (output)
An integer return code indicating success or failure of this call.
rsn (output)An integer reason code describing the reason for a failure on this call.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- The minimum connections requested is validated against the server maximum connections, which is configurable using the WAS administrative console. A minimum connection (minconn) value of 3 means that three connections are reserved during the register call. If more than three connections are requested at a given time, the connection pool can increase to the maximum connection (maxconn) value. When the number of all connections to a server reaches the maximum that is permitted, all subsequent Connection Get API requests for that server are rejected, even if the maxconn value is not yet reached.
Important: Use caution in setting the minimum connections value. Except in specific instances, a large setting is not advised as resources in the WAS control region are reserved for each connection.
- Multiple calls to the Register API can be made under the same address space, thread, or Customer Information Control System (CICS) task, however, they cannot share the same register name. The register name must be a unique name.
- Setting the transactional parameter to 1 results in all connections for this registration running with transactionality. This means that RRS is attached from the current address space. See the section on Propagating Transactions for more details on the requirements and set up for this. Transactionality is only supported between WAS and CICS. Requests for transactional(1) from other environments results in a warning during the register call, the flag is ignored, and processing continues.
- Use the Unregister API call to remove this registration and release the connection pool associated with it.
- When the address space (or job step within a batch job address space) that makes a register call terminates, the registration is automatically terminated and the connections are released.
Return and reason codes:
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. We 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 WAS. If we 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 containing the WAS BBOACALL module is available in the STEPLIB, LNKLST.
10 Unable to locate the selectedWAS daemon group. Ensure that the WAS 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 WAS. Ensure that the user ID is authorized to the CBIND SAF class for the requested WAS.
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 WAS local communication connection. Refer to the WAS 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 WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Unregister
Unregister from the local WAS for z/OS daemon group and server using the BBOA1URG (for 31-bit callers) and BBGA1URG (for 64-bit callers) APIs.
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)A 32 - bit flag word containing unregistration flags.
- Reserved - bit 0-30
- Force (0|1) - bit 31 or bit 64
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.
rc (output)
An integer return code indicating success or failure of this call.
rsn (output)An integer reason code describing the reason for a failure on this call.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- If the Unregister API is not called, and the address space that made a register call terminates, an unregister call is done automatically and the connections are released.
- Any connection handles for this registration that are active when the unregister call occurs might continue to be valid until they are returned to the connection pool using the BBOA1CNR API. To force the connection handles to be cleaned up, a second unregister call must be made, specifying the force flag. This invalidates all outstanding connection handles.
Return and reason codes:
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. We 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Connection Get
This API requests an available connection from the pool created with the selected registration name is returned.
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 containing 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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- Ensure that a successful register (BBOA1REG) call was completed in the current address space with a matching name before using the Connection Get API.
Return and reason codes:
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 we have registered this name before we 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 WAS daemon group or server. Ensure that the WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Connection Release
The Connection Release API requests that a connection is returned to the pool that it was retrieved from and is made available for another requestor.
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.
Usage notes
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for the local adapters is enabled.
- Before using the Connection Release API, ensure that a successful register (BBOA1REG or BBGA1REG API) call is completed in the current address space with a matching name, and a successful Connection Get (BBOA1CNG or BBGA1CNG) call completed to obtain the connection that is now to be released.
Return Code Reason Code Description Action 0 - Success
4 - Unable to locate the WAS daemon group and server. Any resources related to this connection have been cleared. None 8 - Error-see reason code
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.
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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Send Request
These APIs send a request into the local WAS for processing.
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.
requestservicenamel (input)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 WAS 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 containing the length of the response. This length can then be used by the caller to acquire storage before calling the Get Data API to copy it in. When async is set to 1, indicating the caller wants control back immediately, this is set to all 0xFFs if the response is not yet received.
rc (output)An integer return code indicating success or failure of this call.
rsn (output)An integer reason code describing the reason for a failure on this call.
Usage notes:
- Ensure that theWAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- Ensure that a successful register (BBOA1REG) call was completed in the current address space with a matching name before using the Send Request API.
Return and reason codes:
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 WAS size can support. Verify that the size is valid. If the size is valid, ensure that the WAS 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 containing the target enterprise bean is installed and started in the target server for WAS.
36 The connection state is not valid. The connection handle 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 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 WAS server log for any local communication error messages.
44 An exception or unexpected condition occurred in the target enterprise bean. Refer to the WAS logs to review the exception data.
46 An error occurred in the local communication send request call. Check the WAS 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 theWAS daemon group or server. Ensure that the WAS daemon and server are started and the local connections support is active. Retry to locate theWAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Send Response
This API sends a response to a request back to the local WAS.
API Syntax BBOA1SRP or BBGA1SRP BBOA1SRP ( 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.
Usage notes:
- Ensure that theWAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using the Send Response API.
- Ensure that a successful connection get (BBOA1CNG or BBGA1CNG) call completed and the handle is provided as input on this call.
- Ensure that a successful receive Request Any, Receive Request Specific, or Host API call was issued and returned with request data for the connection handle. The connection must be in a state where the Send Response API is valid.
Return and reason codes:
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 WAS size can support. Verify that the size is valid. If the size is valid, ensure that the WAS 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 WAS.
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 WAS server log for any local communication error messages.
46 An error occurred in the local communication send request call. Check the WAS 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 WAS daemon group or server. Ensure that the WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Send Response Exception
This API sends an exception response data back to the JCA caller in the local WAS. 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 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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- Ensure that a successful register (BBOA1REG or BBGAREG API) call completed in the current address space with a matching name before using the send response call.
- Ensure that a successful connection get (BBOA1CNG or BBGA1CNG API) call completed and the handle for this is provided as input on this call.
- Ensure that a successful Receive Request Any or Receive Request Specific or Host API call was issued and returned with request data for the connection handle. The connection must be in a state where the Send Response and Send Response Exception APIs are valid.
Return and reason codes:
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 WAS size can support. Verify that the size is valid. If the size is valid, ensure that the WAS 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 WAS server log for any local communication error messages.
46 An error occurred in the local communication send request call. Check the WAS 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 WAS daemon group or server. Ensure that the WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Receive Request Any
Receive a request from a local WAS 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 containing 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 WAS 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 containing 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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using this API.
Return and reason codes:
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 WAS
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 WAS server log for any local communication error messages.
46 An error occurred in the local communication send request call. Check the WAS 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 WAS daemon group or server cannot be located. Ensure that theWAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Receive Request Specific
Receive a request from a local WAS on a specific connection. Receive a request and related data for the supplied input connection handle. Returns request data length. A Get Data API call with the returned connection handle returns the received message data.
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 WAS 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 containing 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 WAS to be received.
rc (output)An integer return code indicating success or failure of this call.
rsn (output)An integer reason code describing the reason for a failure on this call.
Usage notes:
- Ensure that theWAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- Ensure that a successful register (BBOA1REG API) call was completed in the current address space with a matching name before using this API.
Return and reason codes:
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 WAS
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 WAS server log for any local communication error messages.
46 An error occurred in the local communication send request call. Check the WAS 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 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 WAS daemon group or server cannot be located. Ensure that WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Receive Response Length
Receive response length is used to retrieve the length of the response data from a prior send request call.
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 WAS 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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using this API.
- Ensure that a successful Connection Get (BBOA1CNG or BBGA1CNG API) call completed and the handle is provided as input on this call.
- Ensure that a successful Send Request (BBOA1SRQ or BBGA1SRQ API) call was completed before making this call.
Return and reason codes:
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 WAS.
19 Local communication existing data failure
21 Local communication preview data failure
34 The target service not found. Ensure the application containing the target enterprise bean is installed and started in the target WAS.
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 WAS 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 WAS daemon group or server cannot be located. Ensure that the WASdaemon 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Get Message Data
This API is used to copy the received message data. On return from this call, the message is removed from the adapter message cache.
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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using the Send Request API.
- Ensure that a successful connection get (BBOA1CNG or BBGA1CNG API) call completed and the handle is provided as input on this call.
- If the API caller input msgdatalen parameter is larger than the actual message response, the return code contains a 0 and the actual message length is provided to the return value.
- Important: Once the get message data call returns to the caller, the message data does not persist and the connection is returned to a state where it can be used for another send or receive request call. A subsequent call to get message data or receive response length is returned in error.
Return and reason codes:
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 WAS server log for any local communication error messages.
48 An error occurred in the local communication read request. Check the WAS logs to determine the error.
50 The connection with the WAS is terminated. Check the WAS 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 WAS daemon group or server cannot be located. Ensure WAS daemon and server are started and local connections support is active and try again. 12 10 The WAS daemon group or server cannot be located. Ensure that the WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Invoke
This API uses other underlying primitive API functions to call a method in a local WAS. It is designed to be used in situations where the response output area maximum size is known in advance.
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 containing 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.
Usage notes:
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled .
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using the Send Request API.
- If the API caller input responsedatalen parameter is larger than the actual message response, the return code contains a 0 (zero) and the actual message length is provided in the return value.
Return and reason codes:
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 WAS.
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 WAS size can support. Verify that the size is valid. If the size is valid, ensure that the WAS 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 WAS.
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 WAS server log for any local communication error messages.
44 An exception or unexpected condition occurred in the target enterprise bean. Refer to the WAS logs to review the exception data.
46 An error occurred in the local communication send request. Refer to the WAS logs to determine the error.
48 An error occurred in the local communication read request. Check the WAS logs to determine the error.
50 The connection with theWAS is terminated. Check the WAS 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 WAS daemon group or server cannot be located. Ensure that the WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
Host Service
Host Service for a local WAS. This API uses other underlying primitive API functions to set up a native language z/OS program as a server and target for optimized local adapter calls from a localWAS. It is designed to be used in situations where the request area maximum size is known in advance.
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 WAS 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 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 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 notes
- Ensure that the WAS for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
- Ensure that a successful register (BBOA1REG or BBGA1REG API) call was completed in the current address space with a matching name before using this API.
- If the API caller input requestdatalen parameter is larger than the actual message response, the return code contains a 0 (zero) and the actual message length is provided in the return value.
- The returned connection handle must be supplied on any response for this Host call using the BBOA1SRP or BBGA1SRP API. A subsequent BBOA1SRV or BBGA1SRVAPI call reuses the same connection handle. If so, the API assumes that there is no response for the earlier request.
- Important: Once the Host Service call returns to the caller, the message data is not persisted and the connection is returned to a state where it can be used for another API request.
Return and reason codes:
Return Code Reason Code Description Action 0 - Success
4 - Warning - see reason code
8 - Error - see reason code
8 Register name token already exists. Ensure that the register name passed is valid.
10 The connection handle is in a released state. Ensure that a 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 WAS size can support. Verify that the size is valid. If the size is valid, ensure that the WAS size is large enough to accommodate the message size.
40 A local communication error occurred. Check the WAS server log for any local communication error messages.
46 An error occurred in the local communication send request call. Check the WAS logs to determine the error.
48 An error occurred in the local communication read request. Check the WAS logs to determine the error.
50 The connection with the WAS is terminated. Check theWAS 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 IMSinitialization 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 The WAS daemon group or server cannot be located. Ensure WAS 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 WAS 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 WAS optimized local adapters client processes.
88 WAS for z/OS master client stub table could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
90 WAS for z/OS optimized local adapters master client stub table slot could not be located. A WAS 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. We are possibly running with a WAS v8.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 WAS v8.0.0. level. Ensure the application is running with the level of the optimized local adapters stubs that are compatible with WAS on this z/OS system.
JCA adapters APIs
For calls from WAS into a batch program or subsystem, the WAS application uses the standard JCA APIs. The objects that are customized for this adapter are as follows:
- ConnectionSpec
- InteractionSpec
- Record I/O
See the related links for additional information about these standard JCA APIs in the information center.
The ConnectionSpec API is used to indicate which register name to communicate with. The register name is created when the Register API is used. This also identifies which subsystem to connect to. A subsystem can have more than one register name.
The name of the Program Link transaction ID can be passed fromWAS to CICS, and is used to run the Program Link invocation task. This must be 4 characters and defined in the CICS region. We 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.
Use either the setUseCICSContainer method or the JCA MappedRecord interface to send applications to CICS using channels and containers.
- The 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 the message request CICS container is passed to CICS, 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 response is expected to come from the named container with the selected type of BIT or CHAR.
- The JCA MappedRecord interface can be used to pass one or more containers to CICS. When we use the JCA MappedRecord interface, the named channel is used to communicate with the target program. If we use the MappedRecord interface, we must set UseCICSContainer to 1, and the name and type of a CICS channel must be passed to CICS using the methods setLinkTaskChanID() and setLinkTaskChanType(bit|char).
The JCA MappedRecord interface used to pass containers to CICS is obtained by calling the recordFactory.createMappedRecord() method, using the recordFactory obtained from the WOLA connection object. Do not use the setLinkTaskReqContId(), setLinkTaskReqContType(), setLinkTaskRspContId() or SetLinkTaskRspContType() method with the JCA MappedRecord interface.
For IMS application transactions, use the setOTMAMaxRecvSize(nnn) method on the Connection Specification to set the Maximum Message Receive size. To set the aximum Segments connection level value use the setOTMAMaxSegments(nnn) method on the Connection Specification. For more information about using optimized local adapters with IMS over OTMA, see the topic Calling existing IMS transactions with optimized local adapters over OTMA.
InteractionSpec
The InteractionSpec API specifies 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.
Record I/O
Applications can pass data to and receive data from the adapter using the JCA record interface. This adapter API proposes to use the indexed record interface to allow the caller to pass one or more data structures, including Cobol copybooks and C structures, to the external address space. Each index in the list is taken as a separate copybook and passed to the target in that order.
When used to accept return parameters from a function call, the IndexedRecordImpl can be predefined to accept a particular number of parameters, and the class names generated by the assembly tools for the individual copybooks and structures can be provided. The IndexedRecordImpl inflates the serialized copybooks and structures and sets them into the IndexedRecordImpl so that they can be retrieved and used without dealing with the serialized byte[] representations.
To give a general idea of how this API works, only selected methods are shown. All of the methods on the interface are implemented.
Related:
Optimized local adapters for z/OS usage scenarios Optimized local adapters environment variables Calling existing IMS transactions with optimized local adapters over OTMA z/OS: Use optimized local adapters for inbound support z/OS: Use optimized local adapters for outbound support Accessing data using Java EE Connector Architecture connectors Enable the server environment to use optimized local adapters Extensions to data access APIs