D command code

You can use the D command code to retrieve or insert a sequence of segments in a hierarchic path with one call rather than retrieving or inserting each segment with a separate call. A call that uses the D command code is called a path call.

For your program to use the D command code, the P processing option must be specified in the PCB, unless your program uses command code D when processing DEDBs.

Related reading: For more information on using the P processing option, see the description of PSB generation in IMS Version 15.4 System Utilities.

Retrieving a sequence of segments

When you use the D command code with retrieval calls, IMS places the segments in your I/O area. The segments in the I/O area are placed one after the other, left to right, starting with the first SSA you supplied. To have IMS return each segment in the path, you must include the D command code in each SSA. You can, however, include an intervening SSA without the D command code. You do not need to include the D command code on the last segment in the path, because IMS always returns the last segment in the path to your I/O area.

The D command code has no effect on the IMS retrieval logic. The only thing it does is cause each segment to be moved to your I/O area. The segment name in the PCB is the lowest-level segment that is retrieved or the last level that is satisfied in the call in the case of a GE (not-found) status code. Higher-level segments with the D command code are placed in the I/O area.

If IMS is unable to find the lowest segment your program has requested, it returns a GE (not-found) status code, just as it does if your program does not use the D command code and IMS is unable to find the segment your program has requested. This is true even if IMS reaches the end of the database before finding the lowest segment your program requested. If IMS reaches the end of the database without satisfying any levels of a path call, it returns a GB (end of database) status code. However, if IMS returns one or more segments to your I/O area (new segments for which there was no current position at the start of the current call), and if IMS is unable to find the lowest requested segment, IMS returns a GE status code, even if it has reached the end of the database.

The advantages of using the D command code are significant even if your program is not sure that it will need the dependent segment returned by D. For example, suppose that after examining the dependent segment, your program still needs to use it. Using the D command, your program has the segment if you need it, and your program is not required to issue another call for the segment.

For an example of the D command code, suppose your program has this request:

Compute the balance due for each of the clinic's patients by subtracting the payments received from the amount billed; print bills to be mailed to each patient.

To process this request for each patient, your program needs to know the patient's name and address, what the charges are for the patient, and the amount of payment the patient has made. Issue this call until your program receives a GE status code indicating that no more patient segments exist:

GN    PATIENTb*Db
      BILLINGb*Db
      PAYMENTbb

Each time you issue this call, your I/O area contains the patient segment, the billing segment, and the payment segment for a particular person.

Inserting a sequence of segments

With ISRT calls, your program can use the D command code to insert a path of segments simultaneously. Your program need not include D for each SSA in the path. Your program just specifies D on the first segment that you want IMS to insert. IMS inserts the segments in the path that follow.

For example, suppose your program has this request:

Judy Jennison visited the clinic for the first time. Add a record that includes PATIENT, ILLNESS, and TREATMNT segments.

After building the segments in your I/O area, issue an ISRT call with the following SSA:

ISRT    PATIENTb*Db
        ILLNESSbb
        TREATMNTb

Not only is the PATIENT segment added, but the segments following the PATIENT segment, ILLNESS and TREATMNT, are also added to the database.

You cannot use the D command code to insert segments if a logical child segment in the path exists.