DL/I Calls

Specifying Information in DL/I Calls

DL/I Call Functions

Program Communication Block

Database Position

Segment Search Arguments

The IMSWHST= Option for Qualified SSAs

Multiple SSAs in the DATA Step Interface

Command Codes

Specifying Information in DL/I Calls

The SAS/ACCESS interface to IMS accesses IMS database segments by issuing DL/I calls. A DL/I call is a request made by the interface to DL/I to access one or more segments of a database or message queue, or to perform some system function. Certain information must be specified in the DL/I call to communicate the SAS/ACCESS interface's request to DL/I. The normal information specified in a call is as follows:

a call function specifying the action DL/I is to perform (get, insert, replace, and so on)
a program view (PCB) in the PSB to use when performing the function. The PSB to be used has been specified earlier in your view descriptor or in your DL/I INFILE statement (for an IMS DATA step program).
an I/O area to use for transferring segment data between DL/I and the SAS/ACCESS interface to IMS.
up to 15 segment search arguments (SSAs). An SSA is a set of formatted search criteria that specifies the segment type or occurrence on which to perform the function.

Normally, a DL/I call accesses one segment at a time. However, by using a special command code in an SSA, the SAS/ACCESS interface to IMS can access multiple segments along a hierarchical path in the database. This type of call is a path call.

The following descriptions of the elements of a DL/I call do not need to be understood in detail by most users. They are included here for readers who want this additional information.

DL/I Call Functions

DL/I calls are categorized as Get calls or Update calls. A Get call is a call that retrieves (reads) a segment or segments. An Update call performs some type of write function, such as inserting a new segment or replacing or deleting an existing segment.

The basic DL/I database call functions are listed here. Some of the descriptions refer to SSAs (segment search arguments), qualified calls, and unqualified calls. These are described in Segment Search Arguments.

get-unique. If unqualified, this call retrieves (reads) the first segment in the PCB view (program view) of the database. If SSAs are specified, the call retrieves the first segment that satisfies qualifications specified by the SSAs.

get-next. If unqualified, this call retrieves the next segment in the hierarchical sequence of the database. If SSAs are specified, the call retrieves the next segment that satisfies qualifications specified by the SSAs.

GNP

get-next-within-parent. This call is like the GN call but is restricted to the subtree of the current parent. (The parent is described in the PCB.)

GHU

get-hold-unique. This call is like the GU call but also holds the segment for the next update call that uses the same PCB.

GHN

get-hold-next. This call is like the GN call but also holds the retrieved segment for the next update call that uses the same PCB.

GHNP

get-hold-next-within-parent. This call is like the GNP call but also holds the segment for the next update call that uses the same PCB.

DLET

delete. This call deletes the segment retrieved by the last get-hold call using the same PCB.

REPL

replace. This call replaces the segment held from the last get-hold call using the same PCB with an updated segment that you provide. The get-hold call must be the last DL/I call that used the same PCB.

ISRT

insert. This call adds new segments using the PCB specified.

Program Communication Block

The SAS/ACCESS interface to IMS consists of two distinct interfaces: the IMS engine interface and the DATA step interface. The IMS DATA step interface can use any PCB. You can use DL/I INFILE statement extensions to specify the PCB. The DATA step interface also offers limited support for TP PCBs and message queue processing.

The IMS engine interface (that is, where you use view descriptors) uses only two types of PCBs: the Database (DB) PCB and the Input/Output (I/O) PCB. The engine interface uses the first DB PCB that matches the database that you specify in the access descriptor, unless you specify otherwise in the PCB index field of the view descriptor. For updating, the engine interface to IMS uses the I/O PCB for checkpointing. The I/O PCB is also used if the type of DL/I processing environment, or region type, is BMP. An I/O PCB is created when you enter CMPAT=YES in the PSBGEN statement.

Using a program view of the database (that is, using the appropriate PCB), a call can selectively access only the segments that are required by the SAS/ACCESS interface. For example, you might need the interface to retrieve savings account data from the AcctDBD database without retrieving savings debit segments. The PCB defines as sensitive segments only those segments needed by the SAS/ACCESS interface.

A PCB to be used by the SAS/ACCESS interface that accumulates savings account credit information might use the program view shown in the following figure.

Program View of Savings Account Segments

In addition to defining a program view of the database by specifying sensitive segments, the PCB also accumulates information about the results of a call. This information, called the PCB mask data, includes the following elements:

segment level

is the hierarchical level of the last segment successfully retrieved or processed.

DL/Istatus code

is a return code that indicates whether the call was successful.

DL/I processing option

is a code that indicates what type of access to the database is used. The processing option might be one of the following:

for Get

for Delete, includes G

for Insert

for Replace, includes G

for All of the above

for Exclusive use, in conjunction with G,D,I,R,A

for Loading database, excludes HISAM

for Loading sequentially, required for HISAM

for inhibiting program isolation, must be used with G

for Path calls

for getting segments in ascending sequence

segment name

is the name of the last segment type successfully retrieved or processed by the call.

key feedback data

is the concatenated key (sequence) field values of all segments in the path between the root segment and the last segment that was successfully retrieved or processed.

The PCB mask data also contains other information not described here. (footnote 1)

Database Position

For each PCB, DL/I maintains a current position indicator. The position indicator points to the last segment accessed or to the top of the database, if no DL/I call has been issued or if the last call failed. The position determines which segment should be processed next, that is, by the current DL/I call.

Suppose your DATA step program uses a PCB that defines the CUSTOMER, CHCKACCT, and SAVEACCT segments as sensitive segments. The program is a read-only program and unqualified GN (get-next) calls are issued. Therefore, the program uses sequential processing. The program view is shown in the following figure.

Program View of Account Segments

When the first GN call is issued, DL/I is positioned at the front of the database and the call retrieves the first occurrence of a CUSTOMER segment. When the next call is issued, DL/I uses the current position to determine which segment is retrieved next. In this case, CHCKACCT is retrieved before SAVEACCT because the default search sequence for sequential access is top to bottom, left to right.

Note: The database position is influenced by considerations that are not described here, such as the type of call issued and certain command codes.

Segment Search Arguments

A DL/I call can be qualified or unqualified. A qualified call is one that specifies one or more SSAs (segment search arguments). An SSA provides additional information for the DL/I call. The simplest SSA identifies a segment type for the call to access. Other SSAs not only identify the segment type, but they also specify a value or a set of values to select a particular segment occurrence. An unqualified call does not have any SSAs and therefore does not specify a particular segment or set of segments.

If an SSA describes only the segment type to be accessed, it is an unqualified SSA. (The call is still a qualified call, but the SSA itself is unqualified.) In an unqualified SSA, you can also specify an optional command code, which might affect how the call function is performed or it might affect the qualification of a segment. See Command Codes for more information.

An unqualified SSA has the form

segment-name <command code>

where segment-name is an 8-byte field specifying the segment type, followed by a blank. A blank follows because the minimum SSA length for a DL/I call is 9 bytes. Command codes consist of an asterisk (*) followed by a letter, such as *U or *D.

If an SSA provides a field name and specific value for that field, it is a qualified SSA. A qualified SSA has the form

segment-name <command code> (field-name operator value . . .)

where segment-name is the 8-byte segment type, field-name is the 8-byte name of a sequence or search field for that segment as defined in the DBD, and operator is a 2-byte field that contains a comparison operator. Value is a value that is compared to the specified field in the segment. The values for each of the segment type, field name, operator, and value must be padded to represent the total number of bytes used by the particular field in the DBD. IMS requires the padding.

The first segment occurrence that satisfies the qualification or qualifications is retrieved.

For example, to retrieve a CUSTOMER segment for Hooper J. Walls, the Get (retrieve) call would be qualified with this qualified SSA:

CUSTOMER(CUSTNAME =WALLS, HOOPER J.         )

The comparison operators that IMS uses in a qualified SSA, along with their alternate forms, are listed in the following table.

Comparison Operators and Their Equivalents
Operator	Alternate Form
=1	= or EQ*
>1	> or GT
<1	< or LT
>=	=> or GE
<=	=< or LE
¬=	=¬ or NE
&	or AND (dependent AND)
\|	+ or OR (logical OR)
1Pad the =, >, and < operators with blanks on the right or left.

The IMSWHST= Option for Qualified SSAs

The SAS/ACCESS interface provides certain system and configuration options to use with IMS. One such configuration option, IMSWHST=, affects qualified SSAs and applies only to the IMS engine interface.

IMSWHST=Y makes sure that any specified WHERE criteria have been incorporated into the SSAs that are generated by the IMS engine. Doing so limits the amount of data that the database returns.

If qualified SSAs are not generated by the view descriptor's or application's WHERE statement (or there is no WHERE data set option), the software issues an error message, no IMS records are retrieved, and processing stops.

The default, IMSWHST=N, specifies that IMS records are retrieved for processing regardless of whether qualified SSAs are passed to IMS by a view descriptor's or application's WHERE statement.

Multiple SSAs in the DATA Step Interface

If you use the IMS DATA step interface and specify more than one SSA for a call, you must specify them in hierarchical order. You can specify as many as 15 SSAs. The segment specified in the last SSA, the target segment, is the segment accessed.

For example, if you want to issue a GN (get-next) call to retrieve a CHCKDEBT segment with a DEBTDATE of 28 March 1995 for banking customer Mary T. Summers, you would qualify the GN call with these SSAs:

CUSTOMER*U-(CUSTNAME =SUMMERS, MARY T.          )
CHCKDEBT(DEBTDATE =032895)

The target segment for the call is CHCKDEBT. It is the only segment returned.

To access more than one segment in one call, you must set up a path call, as explained in Command Codes.

Command Codes

Any SSA, qualified or unqualified, can include a command code. A command code provides still more information for the call. It might affect how the call function is performed, or it might affect the qualification of a segment. Command codes consist of an asterisk (*) followed by a letter.

One commonly used command code is *D, which signifies a path call. For a DL/I GET call, this means that the segment named in the SSA with the *D code is returned, even if it is not the target segment (the segment named in the last SSA). The segments retrieved with SSAs that specify *D are returned to the I/O area in hierarchical sequence. The target segment is placed in the I/O area behind the segments whose SSAs specified *D. (This has no effect on what is returned in the key feedback area; it affects only the I/O area.)

For example, one PCB defines CUSTOMER, CHCKACCT, and CHCKDEBT as sensitive segments. In the IMS DATA step interface, you specify these SSAs and a GU (get-unique) call function. Two segments are returned to the I/O area: CUSTOMER and CHCKDEBT.

CUSTOMER*D-(CUSTNAME =WALLS, HOOPER J.         )
CHCKACCT
CHCKDEBT(DEBTDATE =030594)

The PCB mask data contains CHCKDEBT as the name of the last segment successfully retrieved, and the key feedback data contains the concatenated key fields of the CUSTOMER and CHCKACCT segments. The CHCKDEBT segment has only a search field and no sequence field, and therefore no data for CHCKDEBT is in the key feedback area.

FOOTNOTE 1:The IMS DATA step programs can return PCB mask data, but the SAS/ACCESS engine interface cannot.[return]