DL/I Call

To use the system service function in application programs, use DL/I calls. This appendix describes the system service and transaction management calls that OSI supports.

For detailed information about DL/I calls, refer to IBM IMS Version 7 Application Programming: Transaction Manager.

1. System Service DL/I Calls

1.1. CHKP (basic)

The basic CHKP call is used to specify a recovery point when an application program applies changes or terminates abnormally.

  • Format

    >>-CHKP--+-i/o pcb---+--i/o area-------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies an 8-byte checkpoint ID as an input parameter.

1.2. CHKP (symbolic)

The symbolic CHKP call is used to specify a recovery point when an application program attempts to apply changes or terminates abnormally. The Extended Restart (XRST) call is used to restart the program that has terminated abnormally. Up to 7 data entries can be saved and restored when a program restarts.

  • Format

    >>-CHKP--+-i/o pcb---+--i/o area length--i/o area--+-----------------------+--><
                                                   | .-------------------. |
                                                   | V                   | |
                                                   '---area length--area-+-'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies an 8-byte checkpoint ID as an input parameter.

    area length

    Specifies the length of the area as 4 bytes. This is an input parameter.

    area

    Stores data of the specified area length. This is an input parameter.

1.3. INIT

In IBM mainframe IMS/DC, the INIT call allows an application program to verify the data availability status code by checking the data availability of each DB PCB.

In OSI, an INIT call is used only to set a flag for checking whether the application program has invoked the INIT call.

  • Format

    >>-INIT--+-i/o pcb---+--i/o area-------------------------------><
         '---aib-----'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    aib

    Specifies the aib as an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an input and output parameter.

1.4. INQY

The INQY call is used to request information containing the execution environment, destination type and status, and session status. In OSI, AIBSFUNC can be set to ENVIRON or FIND.

  • Format

    >>-INQY--+-aib---+--i/o area-----------------------------------><

  • Parameter

    Parameter Description

    aib

    Specifies the aib as an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an input and output parameter.

1.4.1. ENVIRON

The ENVIRON subfunction obtains the application’s execution environment information.

  • Output

    Type

    Length

    Value

    Description

    IMS ID

    8

    IMS ID.

    Release level

    4

    Currently not supported.

    CTL Reg Type

    8

    Currently not supported.

    App Reg Type

    8

    MPP, BMP

    Type of the running application.

    Reg ID

    4

    Currently not supported.

    App Pgm Name

    8

    Name of the running application.

    PSB Name

    8

    Name of the running PSB.

    Tran Name

    8

    Name of the running transaction.

    User ID

    8

    Currently not supported.

    Group Name

    8

    Currently not supported.

    Stat Grp Indicator

    4

    Currently not supported.

    Addr of Recovery Token

    4

    Currently not supported.

    Addr of the App Param Str

    4

    Currently not supported.

    Shared Queues Indicator

    4

    Currently not supported.

    User ID of Address Space

    8

    Currently not supported.

    User ID Indicator

    1

    Currently not supported.

    Res. Recov. Serv. Ind.

    3

    Currently not supported.

    catalog enablement indi.

    8

    Currently not supported.

1.4.2. FIND

In IBM mainframe IMS/DC, the FIND subfunction returns the PCB address for the requested PCB name.

In OSI, the FIND subfunction retrieves information about the application’s execution environment.

1.5. LOG

In IBM mainframe IMS/DC, the LOG call is used to store information to the IMS system log.

In OSI, the LOG call stores information in the OFM_OSI_LOG table. Currently, OSI only supports AIB.

  • Format

    >>-LOG--+-aib---+------------------------------------------------><

  • Parameter

    Parameter Description

    aib

    Specifies the aib as an input and output parameter.

1.6. ROLB

The ROLB call is used by application programs to cancel output messages and database changes.

  • Format

    >>-ROLB--+-i/o pcb---+-----------------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

  • Limitations

    • OSC messages do not support ROLB calls.

1.7. SYNC

The SYNC call is used for the application program to commit. It only applies in the BMP program.

  • Format

    >>-SYNC--+-i/o pcb---+-----------------------------------------><
         '-aib-------'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    aib

    Specifies the aib as an input and output parameter.

1.8. XRST

The XRST call is used to restart application program from a symbolic checkpoint of a previous execution of the program.

  • Format

    >>-XRST--+-i/o pcb---+--i/o area length--i/o area--+-----------------------+--><
                                                   | .-------------------. |
                                                   | V                   | |
                                                   '---area length--area-+-'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area length

    This is an input and output parameter and currently not used

    i/o area

    Specifies a checkpoint ID as an input parameter.

    area length

    Specifies the length of the area as 4 bytes. This is an input parameter.

    area

    Restores data of the specified area length. This is an input and output parameter.

2. Transaction Management DL/I Calls

2.1. CHNG

The CHNG (Change) call is used to change where the message segment is sent. The destination of the modifiable ALT-PCB can be specified with logical terminal, LU 6.2 descriptor, or transaction codes using CHNG call.

  • Format

    >>-CHNG--+-alternate pcb-+--destination name-------------------><

  • Parameter

    Parameter Description

    alternate pcb

    To use CHNG call, specify the modifiable ALT-PCB as an input and output parameter.

    destination name

    Specifies the destination of the message segment that will be changed.

2.2. CMD

The CMD call allows application programs to input IMS commands. It can be used with the GCMD call to send commands to the OSI command server and receive responses. It retrieves the first segment of a command response message.

  • Format

    >>-CMD--+-i/o pcb-+--i/o area----------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an input and output parameter.

2.3. GCMD

The GCMD call retrieves the subsequent segment of a command response message processed by a CMD call.

  • Format

    >>-GCMD--+-i/o pcb-+--i/o area---------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an output parameter.

2.4. GN

When an input message contains more than one segment, a GU call retrieves the first segment of the message and a GN call retrieves the subsequent segments.

  • Format

    >>-GN--+-i/o pcb-+--i/o area-----------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an output parameter.

2.5. GU

The GU call retrieves the first segment of a message.

  • Format

    >>-GU--+-i/o pcb-+--i/o area-----------------------------------><

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an output parameter.

2.6. ISRT

The ISRT call is used to send a message segment to a specific destination. The destination is specified by IO-PCB and alternate PCB.

  • Format

    >>-ISRT--+-i/o pcb-------+--i/o area--+----------+-------------><
         '-alternate pcb-'            '-mod name-'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    alternate pcb

    Specifies the PCB as an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an output parameter.

    mod name

    Specifies the MOD name as an 8-byte input parameter for sending output messages. The output message is formatted according to the specified MOD.

2.7. PURG

The PURG call is used to output message segments sent by the ISRT call. When more than one message segments are sent in application programs, it is used to purge the previous messages or complete sending a message.

  • Format

    >>-PURG--+-i/o pcb-------+--+------------------------+---------><
         '-alternate pcb-'  '-i/o area--+----------+-'
                                        '-mod name-'

  • Parameter

    Parameter Description

    i/o pcb

    Specifies the IO-PCB that will be sent as the first PCB of the applicable program. This is an input and output parameter.

    alternate pcb

    Specifies the PCB as an input and output parameter.

    i/o area

    Specifies the I/O area that is sufficient for sending segments. This is an output parameter.

    mod name

    Specifies the MOD name as an 8-byte input parameter for sending output messages. The output message is formatted according to the specified MOD.

    The PURG call specifies the MOD name for the first segment of the output message.