General application program flow of ODBA application programs

An ODBA application program issues calls, including DL/I calls, using the AERTDLI interface of an application interface block (AIB).

Several conditions must be met for the AIB call to succeed:

  1. If an AIB is not passed in the call, a U261 abend is issued.
  2. If the AIB that is passed is not valid, a U476 abend is issued.
  3. If the AIB that is passed is not large enough (264 bytes), the AIB return and reason codes are set to X'104' and X'228'.
  4. If the AIB that is passed is not on a fullword boundary, the z/OS® system will return an abend S201.
  5. If there are other internal problems with the call, other return and reason codes are passed back to the z/OS application program. See IMS Version 15.4 Messages and Codes, Volume 4: IMSComponent Codes for a complete list of these return and reason codes.

The ODBA application program must link edit with a language module (DFSCDLI0) or this module can be loaded into the z/OS application region. The entry point for DFSCDLI0 is AERTDLI.

Restriction: The ODBA interface does not support calls into batch DL/I regions.

The basic program flow for an ODBA application program is:

Procedure

  1. Establish the application execution environment.
    The application execution environment must be initialized in the z/OS application region.

    To initialize the environment, use either the CIMS INIT call or, if you need to establish connections to multiple IMS systems, the CIMS CONNECT call.

    If you use the INIT subfunction of CIMS you can include a startup table ID in the optional AIBRSNM2 field of the AIB to connect to the IMS DB system listed in the startup table. If the AIBRSNM2 field is blank, connect to the IMS DB when you allocate a PSB.

    The form of the connection call is: 
    CALL AERTDLI parmcount, CIMS, AIB
    Where:
    CIMS
    Is the required call function.
    AIB
    Has the following fields:
    AIBSFUNC
    The subfunction is either INIT or CONNECT. This field is mandatory.
    AIBRSNM1
    An optional field that provides an eye catcher identifier of the application server that is associated with the AIB. This field is 8 bytes.
    AIBRSNM2
    An optional field for the INIT subfunction in which you can specify an optional 4-byte startup table ID. The ID is optional if the call is issued as preconditioning only. If the ID is given, the z/OS application region connects to the IMS DB specified in the DBCTLID parameter of the selected startup table. The AIBRSNM2 field is not supported with the CONNECT subfunction.

    The characteristics of the connection are determined from the DRA startup table. The startup table name is DFSxxxx0, where xxxx is the startup table ID that is used in the CIMS and APSB calls. Each startup table defines a combination of connection attributes, one of which is a subsystem ID of the IMS DB.

    If you use the CONNECT subfunction, the calling application program can optionally supply its own connection properties table by specifying the address of the table in an entry in the ODBA data store connection table used by the CONNECT subfunction. The connection properties table is mapped by the DFSPRP macro.

    Related Reading: For more information about building a DRA startup table, see IMS Version 15.4 System Definition.

  2. Allocate a PSB.
    The APSB call, introduced for CPIC-driven programs, is used with the ODBA interface to allocate a PSB for the z/OS application region.

    Security is checked before the call can succeed. For more information, see Accessing IMS databases through the ODBA interface in IMS Version 15.4 Communications and Connections.

    The APSB call is in the following form: 
    CALL AERTDLI parmcount, APSB, AIB
    Where:
    APSB
    Is the required call function.
    AIB
    Is the name of the application interface block. The fields in the AIB must be filled in:
    AIBRSNM1
    Is the 8-character PSB name.
    AIBRSNM2
    Is the 4-byte IMS alias name that is used as the startup table ID.

    Several conditions must be met for the allocation request to succeed.

    • The PSB must exist and security checking through RACF® must succeed.
    • An ODBA environment must have been established by either a CIMS INIT call or a CIMS CONNECT call.
    • z/OS Resource Recovery Services (RRS) must be active when the APSB call is made.

    Multiple PSBs can be active at the same time, which is typical for server environments. No token is specifically provided to identify which PSB is to be used for a given call to a given IMS DB, so the same AIB must be used for all calls to the same PSB instance (APSB, DB calls, DPSB). This enables multiple instances of the same PSB to be in use for the same IMS DB at the same time. The parallelism is controlled by the thread count specified in the startup table. The maximum number of threads and dependent regions supported by an IMS DB instance is 999.

  3. Perform DB calls.
    All DL/I calls, with a few exceptions, are supported through the AIB. The unsupported calls entail message handling (the IOPCB is available only for system calls), CKPT, ROLL, ROLB, and INQY PROGRAM. Alternate destination PCBs cannot be used. Both full-function databases and DEDBs are available.
  4. Commit the changes.
    Synchronization is performed by issuing the distributed commit calls, SRRCMIT or ATRCMIT, or possibly their rollback forms of SRRBACK or ATRBACK. IMS sync-point calls are not allowed. Commit is effective for all RRS controlled resources in the z/OS task.
  5. Deallocate the PSB.

    The DPSB call is used when the work unit is complete. In the default case, a commit call must be issued before a DPSB call can be issued. No DL/I call, including system service calls, can be made between the commit and the DPSB call.

    The DPSB call is in the following form: 
    CALL AERTDLI parmcount, DPSB, AIB
    Where:
    DPSB
    Is the required call function.
    AIB
    Is the name of the application interface block. The following fields in the AIB must be filled in:
    AIBRSNM1
    Is the 8-character PSB name.
    AIBSFUNC
    Is an optional field. Set it to 'PREPbbbb' when you want to deallocate the PSB before initialization of commit processing and when the commit processing is provided from outside the application.

    IMS performs phase 1 commit processing and returns control to the requestor, but holds the in-doubt work until RRS (the commit manager) requests full commit processing. An example is in DB2® UDB for z/OS Stored Procedures, whereDb2 for z/OS initializes commit processing on behalf of the procedure. See Db2 for z/OS for a discussion of this scenario.

  6. Terminate the connection.
    The termination call is in the following form: 
    CALL AERTDLI parmcount, CIMS, AIB
    Where:
    CIMS
    Is the required call function.
    AIB
    Is the name of the application interface block. The following fields in the AIB must be filled in:
    AIBSFUNC
    Is a mandatory field whose value is TERM or TALL. Use TERM to sever a single IMS DB connection. Use TALL to sever all connections for this z/OS application region and remove the DRA from the address space.
    AIBRSNM1
    Is an optional field that provides an eye catcher identifier of the application server associated with the AIB. This field is 8 bytes in length.
    AIBRSNM2
    When subfunction equals TERM, provides the 4-byte startup table ID used in a previous APSB call. This field is not needed when the subfunction equals TALL.