+

Search Tips   |   Advanced Search

(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:

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

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.

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:

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.

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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.

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