DL/I Commands

Contents
idms
Contents
The DL/I commands constitute the run-time database interface for an application. Collectively, the DL/I commands are a procedural language for data access, data retrieval, and data manipulation. They are implemented as a set of subroutine calls or preprocessed commands with various parameters. An application requests desired database operations by embedding the appropriate calls at specific points in the source code. Separate DL/I compilers are provided for a number of application programming languages.
The DL/I commands are both navigation- and access-path-oriented.
Basic Operations
The basic DL/I commands are:
  • GET UNIQUE (GU)
    ── Retrieves a named segment occurrence (direct retrieval)
  • GET NEXT (GN)
    ── Retrieves the next segment occurrence in the hierarchical access path
  • GET NEXT WITHIN PARENT (GNP)
    ── Retrieves the next segment occurrence under the current parent occurrence
  • GET HOLD UNIQUE (GHU)
    ── Same as GU, but permits a subsequent DELETE or REPLACE
  • GET HOLD NEXT (GHN)
    ── Same as GN, but permits a subsequent DELETE or REPLACE
  • GET HOLD NEXT WITHIN PARENT (GHNP)
    ── Same as GNP, but permits a subsequent DELETE or REPLACE
  • REPLACE (REPL)
    ── Updates an existing segment occurrence in the database
  • INSERT (ISRT)
    ── Inserts a new segment occurrence in the database
  • DELETE (DLET)
    ── Deletes an existing segment occurrence and all of its dependents
Call Format
Syntax
Call-level DL/I has the following format:
CALL langDLI((#PARMS,)function,pcb-name,user-io-area,(ssa...))
Parameters
  • langDLI
    Specifies the language of the calling program (for example, PLITDLI for a PL/I program).
  • #PARMS
    Specifies the number of parameters for the call, not including the
    #parms
    parameter itself.
  • function
    Specifies one of the DL/I command codes (GU, GN, REPL, etc.).
  • pcb-name
    Specifies the PCB to be used with the call.
  • user-io-area
    Identifies the name of the I/O area. See Program Communication.
  • ssa
    Specifies one or more optional segment search arguments (SSAs). There can be from 0 to 15 SSAs.
Segment Search Arguments
A
segment search argument
(SSA) specifies criteria for selecting a segment occurrence along the hierarchical access path. SSAs take the following form:
Syntax
segment-name(field-name  operator  field-value)
Parameters
  • segment-name
    Identifies the name of the desired segment.
  • field-name
    Identifies the name of a field in the segment.
  • operator
    Specifies a standard relational operator (=, >=
    , <=
    , etc.).
  • field-value
    Specifies an actual value for
    field-name
    .
Call-level DL/I Example
The example below selects the EMPLOYEE segment occurrence whose ID field has the value 123456:
GU, EMP-PCB, IO-A, EMPLOYEE (ID = 123456)
DL/I searches the EMPLOYEE segment occurrences within the database identified by EMP-PCB (the PCB name) and returns the contents of the found occurrence to IO-A (the user I/O area). If duplicate values are allowed for the search field, DL/I returns the first qualifying occurrence into the I/O area.
You can construct more complex selection criteria by combining SSAs with logical operators (AND, OR, etc.). By combining SSAs, you can direct the search to any level in the hierarchy.
Command-level DL/I (EXEC DLI) Example
DL/I database access is also possible using EXEC DLI commands. These commands allow similar functionality and content as call-level DL/I. The example below selects the EMPLOYEE segment occurrence whose ID field has the value 123456 (assuming EMP-ID contains ‘123456’), and is equivalent to the call-level example above:
EXEC DLI GU USING PCB(EMP-PCB) SEGMENT(EMPLOYEE) WHERE(ID=EMPID) INTO(IO-A);
You can construct more complex selection criteria by combining multiple SEGMENT statements. By combining SEGMENT statements, you can direct the search to any level in the hierarchy.
Program Communication
The Program Communication Block (PCB)
When an application performs operations against a database, it always does so through a program communication block (PCB). The PCB restricts the application's access to specific segments selected from the definition of an underlying database.
Regardless of whether the definition is for a physical or a logical database, the database always appears to the application as hierarchical. This is an important point because the flow of the application's processing must always conform to a specific hierarchical path. In other words, application access to a database always starts at a root segment occurrence and proceeds downward through the hierarchy, moving from left to right among segment occurrences on the same level.
PCB Provides for Transfer and Control of Information
At program run time, DL/I maintains an I/O area for each PCB defined in the PSB. The PCB area provides for the transfer of data and control information between the application and DL/I. The PCB I/O area contains a control block with a number of fields. DL/I updates the control fields after each DL/I call. An application's access to these fields is established by declaring the fields as program variables. It is the application's responsibility to check the control fields, as appropriate, after each DL/I call.
Basic DL/I Control Fields
The basic DL/I control fields (with sample names) are:
  • DBD-NAME
    ── Name of the DBD referenced by the PCB. This DBD determines the access path available to the application.
  • SEG-LEVEL
    ── The current segment level in the hierarchy.
  • STATUS-CODE
    ── DL/I result status code.
  • PROCOPTS
    ── Processing options in effect, as specified in the PCB definition.
  • SEG-NAME
    ── Segment name for the segment occurrence last accessed.
  • KEY-LENGTH
    ── Length of the concatenated key for the segment occurrence last accessed.
  • SEN-SEGS
    ── Number of segments available to the application, as specified in SENSEG statements in the PCB.
  • KEY-AREA
    ── Key feedback area for the concatenated key of the segment occurrence last accessed.
Database Positioning
The SEG-LEVEL, SEG-NAME, and KEY-AREA fields in the PCB help the application to keep track of its current position in the database. The application can use the current contents of these fields to direct subsequent database navigation and/or retrieval operations.