DL/I Database Features

This chapter describes the EXEC DLI and CBLTDLI call interfaces, and their commands.

1. Overview

OSC application servers provide DL/I database features based on OpenFrame HiDB, the OpenFrame equivalent of IBM’s IMS/DB. DL/I database features supported are the EXEC DLI command interface and the CBLTDLI call interface.

EXEC DLI Command Interface

EXEC DLI interface is a command interface used for accessing a DL/I database. OSC application servers provide a control block called the DL/I Interface Block (DIB) to give application programs access to certain data related to current status code and DL/I whenever they execute a command through the EXEC DLI interface. You can check to see if a command has been successfully executed by viewing information stored in the block.

The DIB contains the following data:

Classification	Description
DIBSTAT	After a command is executed through the EXEC DLI interface, information about the current state (called the state code) will be stored here as a 2 byte character string.
DIBSEGM	If a GN, GNP, GU, or ISRT command is successfully executed, the lowest level segment name will be stored here as an 8 byte character string.
DIBSEGLV	If a GN, GNP, GU, or ISRT command is successfully executed, the lowest level segment value will be stored here as a 2 byte character string.
DIBKFBL	If the KEYFEEDBACK option is specified for a GN, GNP, or GU command, the concatenated key length will be stored here as a 2 byte binary number.

Classification

Description

DIBSTAT

After a command is executed through the EXEC DLI interface, information about the current state (called the state code) will be stored here as a 2 byte character string.

DIBSEGM

If a GN, GNP, GU, or ISRT command is successfully executed, the lowest level segment name will be stored here as an 8 byte character string.

DIBSEGLV

If a GN, GNP, GU, or ISRT command is successfully executed, the lowest level segment value will be stored here as a 2 byte character string.

DIBKFBL

If the KEYFEEDBACK option is specified for a GN, GNP, or GU command, the concatenated key length will be stored here as a 2 byte binary number.

The first step of accessing a DL/I database is scheduling a Program Specification Block (PSB). A PSB is a collection of Program Communication Blocks (PCBs), which define the view that will be used to display the database. There are several types of PCBs, but OSC applications support only the DB type. Each EXEC DLI command uses one of the PCBs specified in the PSB to indicate which database must be accessed.

The following is an example of an EXEC DLI command.

* Schedules PSB.
EXEC DLI SCHD PSB(PSB-NAME) END-EXEC.

* Retrieves SEGA segement value whose FIELDA field value is 123.
MOVE ‘123’ TO FIELD1.
EXEC DLI GU SEGMENT(SEGA) INTO(SEGA-AREA) WHERE(FIELDA=FIELD1) END-EXEC.

* Ends the PSB.
EXEC DLI TERM END-EXEC.

If a PSB is scheduled successfully, the databases in the PSB can be accessed by using the commands explained in the following section.

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

CBLTDLI Call Interface

The CBLTDLI interface is a call interface that allows COBOL programs to access a DL/I database by using the CALL keyword. It is a low-level alternative to the EXEC DLI interface. The CBLTDLI interface can be used by application programs in OpenFrame/Batch as well as in OSC, but is used differently in each case.

2. EXEC DLI Command Interface

The EXEC DLI command interface is divided into two groups: database access control commands and access commands.

EXEC DLI Commands

DL/I database access control commands

The following is a list of DL/I database access control commands. For more information about each command, refer to the respective section.

Command Description

SCHD

Schedules a PSB for use.

TERM

Terminates the use of the current PSB.

Command	Description
SCHD	Schedules a PSB for use.
TERM	Terminates the use of the current PSB.

DL/I database access commands

The following is a list of DL/I database access commands. For more information about each command, refer to the respective section.

Command	Description
DLET	Deletes the segment and its child segments from the database.
GN	Reads segments sequentially from the database.
GNP	Reads only the child segments of a specific parent.
GU	Retrieves specific segments and specifies the start point for a sequential search.
ISRT	Adds segments to the database.
REPL	Modifies the values of fields in a segment.

Command

Description

DLET

Deletes the segment and its child segments from the database.

Reads segments sequentially from the database.

GNP

Reads only the child segments of a specific parent.

Retrieves specific segments and specifies the start point for a sequential search.

ISRT

Adds segments to the database.

REPL

Modifies the values of fields in a segment.

2.1. SCHD (SCHEDULE)

Schedules a PSB. It notifies the DL/I database that it will be accessed with PSB scheduling.

Syntax
```
EXEC DLI SCHD [option …] END-EXEC.
```
Options

Option Description

PSB

Specifies the name of the PSB to be scheduled.

To stop using a PSB or to use another PSB, terminate the existing PSB with the TERM command.

Option	Description
PSB	Specifies the name of the PSB to be scheduled.

2.2. TERM (TERMINATE)

Terminates the use of the current PSB and applies all of the changes made to the databases. The current PSB must be terminated before another can be scheduled. There are no options for this command.

Syntax
```
EXEC DLI TERM END-EXEC.
```

State information cannot be recovered after the TERM command is given.

2.3. DLET (DELETE)

Deletes the segment and its child segments from the database. Segments to be deleted must be retrieved first before using this command.

Syntax
```
EXEC DLI DLET [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to be used.
FROM	Specifies the location of the segment to be deleted.
SEGMENT	Specifies the type of the segment to be deleted.
SEGLENGTH	Specifies the length of the segment to be deleted.

Option

Description

USING PCB

Specifies the DB-PCB to be used.

FROM

Specifies the location of the segment to be deleted.

SEGMENT

Specifies the type of the segment to be deleted.

SEGLENGTH

Specifies the length of the segment to be deleted.

2.4. GN (GET NEXT)

Reads segments sequentially from the database according to the options specified with the command. Before using GN, the starting point for the sequential search must be set with the GU command.

The SEGMENT and WHERE options can be used to narrow the search parameters.

Syntax
```
EXEC DLI GN [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to use.
CURRENT	Adds a segment based on the current position.
FEEDBACKLEN	Specifies the length of the KEYFEEDBACK data area.
FIELDLENGTH	Specifies the length of the field listed in the WHERE option.
FIRST	Retrieves the first segment of the segment type.
KEYFEEDBACK	Specifies the data area where the concatenated segment key will be stored.
INTO	Specifies the data area where the segment to be read will be stored.
LAST	Retrieves the last segment of the segment type.
SEGLENGTH	Specifies the length of the data area where the segment to be read will be stored.
SEGMENT	Specifies the type of segment to be read.
WHERE	Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements: Name of a field in the segment Relational operator Data area containing the value that will be compared to the value in the field.

Option

Description

USING PCB

Specifies the DB-PCB to use.

CURRENT

Adds a segment based on the current position.

FEEDBACKLEN

Specifies the length of the KEYFEEDBACK data area.

FIELDLENGTH

Specifies the length of the field listed in the WHERE option.

FIRST

Retrieves the first segment of the segment type.

KEYFEEDBACK

Specifies the data area where the concatenated segment key will be stored.

INTO

Specifies the data area where the segment to be read will be stored.

LAST

Retrieves the last segment of the segment type.

SEGLENGTH

Specifies the length of the data area where the segment to be read will be stored.

SEGMENT

Specifies the type of segment to be read.

WHERE

Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements:

Name of a field in the segment
Relational operator
Data area containing the value that will be compared to the value in the field.

2.5. GNP (GET NEXT IN PARENT)

Reads sequentially the child segments of a specified segment. A GU or GN command must be used before calling GNP.

The SEGMENT and WHERE options can be used to narrow the search parameters.

Syntax
```
EXEC DLI GNP [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to use.
CURRENT	Adds a segment based on the current position.
FIELDLENGTH	Specifies the length of field value in WHERE option.
FEEDBACKLEN	Specifies the length of the KEYFEEDBACK data area.
FIRST	Retrieves the first segment of the segment type.
KEYFEEDBACK	Specifies the data area where the concatenated segment key will be stored.
INTO	Specifies the data area where the segment to be read will be stored.
LAST	Retrieves the last segment of the segment type.
SEGMENT	Specifies the type of segment to be read.
SEGLENGTH	Specifies the length of the data area where the segment to be read will be stored.
WHERE	Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements: Name of a field in the segment Relational operator Data area containing the value that will be compared to the value in the field.

Option

Description

USING PCB

Specifies the DB-PCB to use.

CURRENT

Adds a segment based on the current position.

FIELDLENGTH

Specifies the length of field value in WHERE option.

FEEDBACKLEN

Specifies the length of the KEYFEEDBACK data area.

FIRST

Retrieves the first segment of the segment type.

KEYFEEDBACK

Specifies the data area where the concatenated segment key will be stored.

INTO

Specifies the data area where the segment to be read will be stored.

LAST

Retrieves the last segment of the segment type.

SEGMENT

Specifies the type of segment to be read.

SEGLENGTH

Specifies the length of the data area where the segment to be read will be stored.

WHERE

Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements:

Name of a field in the segment
Relational operator
Data area containing the value that will be compared to the value in the field.

2.6. GU (GET UNIQUE)

Retrieves specific segments and sets the starting point for a sequential search. The SEGMENT option must be used to specify the type of segment to be retrieved; other search parameters can be specified with the WHERE option.

Syntax
```
EXEC DLI GU [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to use.
FIELDLENGTH	Specifies the length of the field listed in the WHERE option.
FEEDBACKLEN	Specifies the length of the KEYFEEDBACK data area.
KEYFEEDBACK	Specifies the data area where the concatenated segment key will be stored.
INTO	Specifies the data area where the segment to be read will be stored.
LAST	Retrieves the last segment of the segment type.
SEGMENT	Specifies the type of segment to be read.
SEGLENGTH	Specifies the length of the data area where the segment to be read will be stored.
WHERE	Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements: Name of a field in the segment Relational operator Data area containing the value that will be compared to the value in the field.

Option

Description

USING PCB

Specifies the DB-PCB to use.

FIELDLENGTH

Specifies the length of the field listed in the WHERE option.

FEEDBACKLEN

Specifies the length of the KEYFEEDBACK data area.

KEYFEEDBACK

Specifies the data area where the concatenated segment key will be stored.

INTO

Specifies the data area where the segment to be read will be stored.

LAST

Retrieves the last segment of the segment type.

SEGMENT

Specifies the type of segment to be read.

SEGLENGTH

Specifies the length of the data area where the segment to be read will be stored.

WHERE

Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements:

Name of a field in the segment
Relational operator
Data area containing the value that will be compared to the value in the field.

2.7. ISRT (INSERT)

Adds segments to the DL/I database. Specify the position to add the segment before executing the ISRT command.

Syntax
```
EXEC DLI ISRT [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to use.
CURRENT	Adds the segment based on the current cursor position.
FIELDLENGTH	Specifies the length of the field listed in the WHERE option.
FROM	Specifies the data area containing the data for the segment to be added.
FIRST	Adds the segment as the first occurrence of the segment type.
LAST	Adds the segment as the last occurrence of the segment type.
SEGMENT	Specifies the type of segment to be added.
SEGLENGTH	Specifies the length of the data area where the segment to be inserted is stored.
WHERE	Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements: Name of a field in the segment Relational operator Data area containing the value that will be compared to the value in the field.

Option

Description

USING PCB

Specifies the DB-PCB to use.

CURRENT

Adds the segment based on the current cursor position.

FIELDLENGTH

Specifies the length of the field listed in the WHERE option.

FROM

Specifies the data area containing the data for the segment to be added.

FIRST

Adds the segment as the first occurrence of the segment type.

LAST

Adds the segment as the last occurrence of the segment type.

SEGMENT

Specifies the type of segment to be added.

SEGLENGTH

Specifies the length of the data area where the segment to be inserted is stored.

WHERE

Specifies the qualification statement(s) for the segment to be read. A qualification statement is composed of three elements:

Name of a field in the segment
Relational operator
Data area containing the value that will be compared to the value in the field.

2.8. REPL (REPLACE)

Changes one or more field values in a specific segment. To change field values, first retrieve the segment by using the GU command and then make the modifications with REPL. For the REPL command, at least one item for each SEGMENT option and FROM option must be specified.

Syntax
```
EXEC DLI REPL [option …] END-EXEC.
```

Options

Option	Description
USING PCB	Specifies the DB-PCB to use.
FROM	Specifies the data area containing the replacement data.
SEGLENGTH	Specifies the length of the data area that stores the replacement data.
SEGMENT	Specifies the type of segment to be replaced.

Option

Description

USING PCB

Specifies the DB-PCB to use.

FROM

Specifies the data area containing the replacement data.

SEGLENGTH

Specifies the length of the data area that stores the replacement data.

SEGMENT

Specifies the type of segment to be replaced.

3. CBLTDLI Call Interface

This section briefly explains some of the differences between the EXEC DLI interface and the CBLTDLI call interface. It also explains how the CBTDLI interface is used differently by OSC and Batch.

Comparison with EXEC DLI Interface

Unlike the EXEC DLI interface, the CBLTDLI interface requires that the DLIUIB (DL/I User Interface Block) and PCB MASK are specified manually, as they are in CICS. To access the DL/I database and identify the segment to be accessed, SSAs (Segment Search Arguments) must be created and described manually.

In the following example, a PSB is scheduled with the CBLTDLI interface.

CALL ‘CBLTDLI’  USING ‘PCB ‘ PSBNAME ADDRESS OF DLIUIB

The next example is of retrieving a segment value that satisfies specific field conditions.

CALL ‘CBLTDLI’ USING ‘GU  ‘ THE-PCB-MASK SEGA-AREA FIELDA-SSA.

Comparison with CBLTDLI Interface used in Batch Programs

In the OSC system, there are two major differences between how the CBLTDLI interface is used by OSC and by Batch. In OpenFrame/Batch,

PSB scheduling is required for the CBLTDLI interface, just as it is for the EXEC DLI interface.
There is a difference in state checking for the results of a CBLTDLI call.

UIBRCODE, the part of the DLIUIB that determines if a CBLTDLI call has been successful or not, is divided into two parts: UIBFCTR, which displays general error information; and UIBDLTR, which displays additional error information. When an error occurs after a CBLTDLI call in OpenFrame/Batch, UIBFCTR is checked first to determine if the error is serious; if it is, CBLTDLI will not handle the error directly. Instead, you must terminate the task with the EXEC CICS ABEND command. Like Batch DL/I program, the PCB MASK state code can be used to check if the CBLTDLI call has been successful.

For more information about the CBLTDLI interface, refer to OpenFrame HiDB Guide.