Optimized local adapters for z/OS APIs

Register

Using the BBOA1REG (for 31-bit callers) and BBGA1REG (for 64-bit callers) APIs, you can register with a local WebSphere Application Server for z/OS daemon group and server. The BBOA1REG and BBGA1REG APIs request that a group of optimized connections to a local WebSphere Application Server daemon group and server be allocated and registered under the specified "registername."

Parameters

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

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

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

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

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 by another client in the daemon group unless you are also using the ola_locate_service_search_algorithm variable on the target WebSphere Application Server.  If this client connects to multiple daemon groups, the registername can be used only once in this client.

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.

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

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

Unregister

Parameters:

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.

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

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

Connection Get

Parameters:

An entry variable or entry constant that contains the name to be used to locate the connection pool from which to retrieve a connection. This must be a blank padded string of exactly 12 characters.

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

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.

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

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

Connection Release

Parameters:

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

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

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

Send Request

Parameters:

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

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.

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

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

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

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.

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

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

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

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

Send Response

Parameters:

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

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

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.

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

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

Send Response Exception

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

Parameters:

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

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

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.

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

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

Receive Request Any

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

Parameters:

An entry variable or entry constant that contains the name to be used to locate the connection pool from which to retrieve a connection. This must be a blank padded string of exactly 12 characters.

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

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

An integer containing the length of the service name to start or 0 if the service name is null terminated.

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.

An integer that contains the number of seconds to wait for the connection to complete before returning a connection unavailable reason code. A value of 0 indicates that there is no wait time and that the API waits indefinitely.

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

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

Receive Request Specific

Parameters:

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

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

An integer containing the length of the service name to start or 0 if the service name is null terminated.

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

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

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

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

Receive Response Length

Parameters:

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

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

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

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

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

Get Message Data

Parameters:

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

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.

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.

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

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

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

Invoke

Parameters:

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.

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.

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.

An integer containing the length of the service name to start or 0 if the service name is null terminated.

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

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.

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.

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.

An integer that contains the number of seconds to wait for the connection to complete before returning a connection unavailable reason code. A value of 0 (zero) indicates that there is no timeout and that this API waits indefinitely.

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

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

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

Host Service

Parameters:

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.

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

An integer containing the length of the service name to start or 0 if the service name is null terminated.

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.

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.

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

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

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

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

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 WebSphere Application Server for z/OS daemon group and server specified on this call are started and the support for local adapters is enabled.
• Ensure that a successful register (BBOA1REG 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.

JCA adapters APIs

• ConnectionSpec

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

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

  You can 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 you use the JCA MappedRecord interface, the named channel is used to communicate with the target program. If you use the MappedRecord interface, you 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).
    Avoid trouble: 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 Maximum Segments connection level value use the setOTMAMaxSegments(nnn) method on the Connection Specification. For more information about using optimized local adapters with IMS over OTMA, see the topic Calling existing IMS transactions with optimized local adapters over OTMA.

• InteractionSpec

  The InteractionSpec API is used to specify which service 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.