Application Interfaces

This chapter describes types and usage of the interface that COBOL written in the OSI environment uses.

1. Overview

In the OSI environment, applications must follow the certain interface (DL/I call function) to access a database or MQ. Each function is used in the OSI area (online program) as well as the database. Their method of use is the same. Specific options such as segment search argument (SSA) are not used online. A database can be thought of as a Message Queue (MQ) online and assigned functions.

If a user do not follow the interface, return the status code which a user can recognize as a return value. Refer to DL/I Status code for detailed information about the status code.

For more information about DL/I call functions, refer to OpenFrame HiDB Guide.

2. Database Call Functions

The following shows how to use functions that applications use to access a database.

  • Usage

    CALL 'CBLTDLI' USING argument 1, argument 2, ..., argument n

  • Parameters

    • argument 1

      Refers to the DL/I function of CBLTDLI. A function code determines the type of processing a database segment. This field’s length is 4 bytes and it is declared within the application.

      These are functions that can be specified in argument 1.

      Function Description

      GU(GET UNIQUE) /

      GHU(GET HOLD UNIQUE)

      A function code that searches a specific segment of a database. Segments can be gained by specifying SSA(Specify from the 4th to n-th of argument.).

      In online programs, it requires messages that are loaded in the MQ to be read.

      GN(GET NEXT) /

      GHN(GET HOLD NEXT)

      A function code that searches the segment following the currently positioned segment (a retrieved segment right before Call issue). It is used when a database segment is searched in hierarchical order.

      In online programs, MQ functions as a database. Features of a function do not target the database but the MQ.

      GNP(GET NEXT WITHIN PARENT) /

      GHNP(GET HOLD NEXT WITHIN PARENT)

      Certain segment types of the data structure are parents and can contain a segment in the lower level of the segment. It is called a family segment and GNP and GHNP function codes are searched in hierarchical order of this family segment.

      It is not used when an online program (IO-PCB) is used.

      ISRT(INSERT)

      Insert data that is typed in the argument 3 into a specified database or MQ.

      DLET(DELETE)

      A function code to delete a segment. When deleting a segment, use DLET Call after positioning a segment using a hold-based search Call. The segment is removed from the database according to the delete rule.

      REPL(REPLACE)

      A function code to implement substitution of a segment. Like DLET Call, use REPL Call after positioning a segment using a hold-based search Call. Do not change a segment key using the REPL Call.

      It is not used when an online program(IO-PCB) is used.

    • argument 2

      To make applications use data access and interface, define PCB Mask as either DB-PCB, IO-PCB, or ALT-PCB. When applications were written in COBOL, define PCB in linkage. When PCB that is defined in applications functions as Call, it is linked with the control section of OSI.

      PCB Mask Description

      DB-PCB

      Regarding database Call features, the defined PCB is DB-PCB.

      IO-PCB

      It is used when online feaures are used.

      ALT-PCB

      When data needs to be sent to another transaction or terminal, it is used.

    • argument 3

      Specifies the data area within the application. Data processing of applications and data access is used by specifying it in the data area. A user must declare a segment length and a necessary length by Command Code of SSA in the XX area within the application.

    • argument 4

      Defines the conditions for segments that are the subject of the process of SSA and sensitive segments. Specify SSA’s leading name in accordance with the hierarchy level that is defined as the data structure. The maximum of n is 18. When OP-PCB Mask is used, the screen on the terminal can be changed by configuring the MOD name.

      SSA is a specific argument of a database Call feature and divided into unqualified SSA and qualified SSA depending on the presence of the condition that is forwarded to a segment.

      SSA Description

      unqualified SSA

      Processes SSA using the segment name and does not attach conditions to the field information in the segment.

      qualified SSA

      Attaches conditions to the field information in the segment.

For more information about database call functions, refer to IBM’s IMS Application Programming: Database Manager.

3. Data Communication Call Functions

The following describes features of the data communications Call function.

  • Sending and receiving message segments

  • Changes to the destination of transmission messages

  • Transmission of the Scratch Pad Area (SPA)

Features of the data communications Call function is the same as those of the database Call function. But, messages that are loaded in MQ and messages in the SPA area do not have a hierarchical structure (a characteristic structure of OpenFrame/HiDB). Therefore, the SSA of the database Call, which is a hierarchical search condition, is not needed.

For more information about Scratch Pad Area (SPA), refer to IBM IMS Conversational Transactions.

  • Usage

    Function Code(argument 1) PCB(argument 2) Data Area (argument 3) MOD Name (argument 4)

  • Parameters

    • argument 1

      Specifies function codes which define message segments and SPA type processing. As a 4 byte area, like the database Call feature, it is declared in the application.

      The following shows functions that can be specified in argument 1.

      Function Description

      GU(GET UNIQUE)

      Receives the first segment (header segment) of a message. Applications must call GU first when receiving a message.

      SPA is received during conversation mode.

      GN(GET NEXT)

      Receives message segments following header segment.

      ISRT(INSERT)

      Sends message segments or SPA.

      PURG(PURGE)

      Outputs message segments that are sent by ISRT, as a message to the terminal.

      CHNG(CHANGE)

      Uses ALT-PCB and sends messages to another terminal or transaction.

    • argument 2

      PCB for a data communications Call function is defined in the same way as the database PCB and called a logic terminal PCB.

      The following shows the type of logic PCB terminals which can be specified in argument 2.

      PCB Description

      IO-PCB

      To input and output messages from the logic terminal that requested the transaction.

      Alternative PCB

      To send messages using another terminal rather than the default terminal.

      Alternative Program PCB

      To send messages to another program.

      1. Alternative Program PCB is called ALT-PCB. This logic terminal PCB within the application must be defined IO-PCB and ALT-PCB in order.

      2. IO-PCB is automatically managed in the OSI system and ALT-PCB is defined as program definition utility.

    • argument 3

      A data area that is used for message segments, commands, and the SPA’s sending/receiving.

    • argument 4

      For the terminal that performs MFS, define the address of the area where the MOD name (8Byte), which is defined by the message format definition utility, is configured. The MOD name is specified only if it is inserted.

For more information about data communication call functions, refer to IBM’s IMS Application Programming: Transaction Manager.