Escolar Documentos
Profissional Documentos
Cultura Documentos
SC26-9424-01
IMS Version 7
SC26-9424-01
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on
page xiii.
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Programming Interface Information. . . . . . . . . . . . . . . . . . xv
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Product Names. . . . . . . . . . . . . . . . . . . . . . . . . xvi
Preface . . . . . . . . . . . . . . . . .xvii. . . . . . . . . .
Summary of Contents . . . . . . . . . . . .
xvii . . . . . . . . . .
Prerequisite Knowledge . . . . . . . . . . .
xvii . . . . . . . . . .
Syntax Diagrams. . . . . . . . . . . . . . .
xviii . . . . . . . . .
How to Send Your Comments . . . . . . . . . . . . . . . . . . . xx
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7
Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7
A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8
Contents v
STAT Command . . . . . . . . . . . . . . . . . . . . . . . . 60
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 61
SYMCHKP Command . . . . . . . . . . . . . . . . . . . . . . 61
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63
XRST Command . . . . . . . . . . . . . . . . . . . . . . . . 63
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 65
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 153
IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 153
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Contents vii
viii Application Programming: EXEC DLI Commands for CICS and IMS
Figures
1. The Structure of a Command-Level Batch or BMP Program . . . . . . . . . . . . . . . 7
2. Medical Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. PATIENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. ILLNESS Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. TREATMNT Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. BILLING Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. PAYMENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. HOUSHOLD Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
9. General Format of a PSB. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
10. Processing a Long Chain of Segment Occurrences with Subset Pointers . . . . . . . . . . 93
11. Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . . . 94
12. More Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . 94
13. How Subset Pointers Divide a Chain into Subsets . . . . . . . . . . . . . . . . . . 94
14. Processing Performed for the Sample Passbook Example. . . . . . . . . . . . . . . . 96
15. Retrieving the First Segment in a Chain of Segments . . . . . . . . . . . . . . . . . 97
16. Moving the Subset Pointer to the Next Segment after Your Current Position . . . . . . . . . 98
17. Unconditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . . . . 99
18. Conditionally Setting the Subset Pointer to Your Current Position. . . . . . . . . . . . . 100
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to
you.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
xiv Application Programming: EXEC DLI Commands for CICS and IMS
these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to
IBM’s application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or
other countries or both:
C/370 IBM
CICS IMS
CICS/ESA IMS/ESA
CICS/MVS MVS
DATABASE 2 MVS/ESA
DB2 RACF
Notices xv
BookManager
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
Product Names
In this book, the licensed programs have shortened names:
v “COBOL for MVS & VM” is referred to as “COBOL”.
v “DB2 for MVS” is referred to as “DB2”.
v “CICS for MVS” is referred to as “CICS”.
v “CICS Transaction Server for OS/390” is referred to as “CICS”.
xvi Application Programming: EXEC DLI Commands for CICS and IMS
Preface
This book is for CICS application programmers whose programs use EXEC DLI
commands in an IMS environment. This book lists and describes the EXEC DLI
commands, and explains the procedures for writing application programs. For
information on using databases (such as, position in the database, using multiple
positioning, and using secondary indexing and logical relationships), see IMS
Version 7 Application Programming: Database Manager.
| This edition is available only in PDF and BookManager formats. This book is
| available on the IMS Version 7 Licensed Product Kit (LK3T-2326). You can also get
| the most current versions of the PDF and BookManager formats by going to the
| IMS Web site at www.ibm.com/ims and linking to the Library page.
Summary of Contents
This book has two parts:
Part 1 (“Chapter 1. How Your EXEC DLI Application Program Works with IMS” on
page 7through “Chapter 7. Using Data Availability Enhancements” on page 109)
explains the basics of writing the DL/I part of your application program with EXEC
DLI commands.
“Part 2. For Your Reference” on page 111 contains reference information about the
parts of an IMS command-level application program such as EXEC DLI commands,
system service calls, qualification statements, EXEC DLI options, the DIB (DL/I
Interface Block), I/O areas, and status codes. These chapters are for experienced
programmers who understand IMS application programming and need only to look
up a fact such as the meaning of a particular status code. If you are one of those
programmers, you may also want to have on hand IMS/ESA Application
Programming: EXEC DLI Commands for CICS and IMS Summary.
“Bibliography” on page 153 lists all the non-IMS publications referred to in this book.
Prerequisite Knowledge
| IBM offers a wide variety of classroom and self-study courses to help you learn
| IMS. For a complete list, see the IMS home page on the World Wide Web at:
| www.ibm.com/ims
| This book assumes you are a CICS programmer familiar with the functions,
| facilities, hardware, and software described in CICS/ESA CICS Family General
| Information and from the Library page of the IMS home page on the Web:
| www.ibm.com/ims.
This book also assumes that, if you plan to write a CICS program, you are familiar
with the principles covered in CICS/ESA Application Programming Guide and in
other CICS documentation.
Before using this book, you should understand the concepts of application design
presented in IMS Version 7 Application Programming: Design Guide.
Syntax Diagrams
The following rules apply to the syntax diagrams used in this book:
Arrow symbols
Read the syntax diagrams from left to right, from top to bottom, following
the path of the line.
─── Indicates the beginning of a statement.
─── Indicates that the statement syntax is continued on the next line.
─── Indicates that a statement is continued from the previous line.
─── Indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the
─── symbol and end with the ─── symbol.
Conventions
v Keywords, their allowable synonyms, and reserved parameters, appear in
uppercase for MVS and OS/2 operating systems, and lowercase for
UNIX operating systems. These items must be entered exactly as shown.
v Variables appear in lowercase italics (for example, column-name). They
represent user-defined parameters or suboptions.
v When entering commands, separate parameters and keywords by at
least one blank if there is no intervening punctuation.
v Enter punctuation marks (slashes, commas, periods, parentheses,
quotation marks, equal signs) and numbers exactly as given.
v Footnotes are shown by a number in parentheses, for example, (1).
v A symbol indicates one blank position.
Required items
Required items appear on the horizontal line (the main path).
REQUIRED_ITEM
Optional Items
Optional items appear below the main path.
REQUIRED_ITEM
optional_item
If an optional item appears above the main path, that item has no effect on
the execution of the statement and is used only for readability.
optional_item
REQUIRED_ITEM
xviii Application Programming: EXEC DLI Commands for CICS and IMS
Multiple required or optional items
If you can choose from two or more items, they appear vertically in a stack.
If you must choose one of the items, one item of the stack appears on the
main path.
REQUIRED_ITEM required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the
main path.
REQUIRED_ITEM
optional_choice1
optional_choice2
Repeatable items
An arrow returning to the left above the main line indicates that an item can
be repeated.
REQUIRED_ITEM repeatable_item
If the repeat arrow contains a comma, you must separate repeated items
with a comma.
REQUIRED_ITEM repeatable_item
A repeat arrow above a stack indicates that you can specify more than one
of the choices in the stack.
Default keywords
IBM-supplied default keywords appear above the main path, and the
remaining choices are shown below the main path. In the parameter list
following the syntax diagram, the default choices are underlined.
default_choice
REQUIRED_ITEM
optional_choice
optional_choice
Preface xix
STATEMENT item 1 item 2 A
A:
item 3 KEYWORD
item 4 item 5
item 6
Substitution-block
Sometimes a set of several parameters is represented by a
substitution-block such as <A>. For example, in the imaginary
/VERB command you could enter /VERB LINE 1, /VERB EITHER
LINE 1, or /VERB OR LINE 1.
EITHER
OR
Parameter endings
Parameters with number values end with the symbol '#', parameters
that are names end with 'name', and parameters that can be
generic end with '*'.
xxii Application Programming: EXEC DLI Commands for CICS and IMS
Part 1. Writing Application Programs
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7
Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7
A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8
Your EXEC DLI application uses EXEC DLI commands to read and update DL/I
databases. These applications can execute as pure batch, as a BMP running with
DBCTL or DB/DC, or as an online CICS program using DBCTL. Your EXEC DLI
program can also issue system service commands when using DBCTL.
Notes to Figure 1:
1I/O areas. DL/I passes segments to and from the program in the I/O areas.
You may use a separate I/O area for each segment.
2Key feedback area. DL/I passes, on request, the concatenated key of the
lowest-level segment retrieved to the key feedback area.
Requirement: CICS/ESA Version 4, or later, and CICS Transaction Server run with
this version of IMS. Unless a distinction needs to made, all supported versions are
referred to as CICS.
A Sample Hierarchy
Many of the examples in this book use the medical hierarchy shown in the following
graphic. The database contains information that a medical clinic might keep about
its patients. To understand the examples, you should be familiar with the hierarchy
and the segments it contains.
The figures that follow show the layouts of the segments in the hierarchy. The
number below each field is the length in bytes that has been defined for that field.
v PATIENT Segment
The following graphic shows the PATIENT segment. It has three fields: patient
number (PATNO), patient name (NAME), and the patient’s address (ADDR).
PATIENT has a unique key field: PATNO. PATIENT segments are stored in
ascending order of their patient numbers. The lowest patient number in the
database is 00001 and the highest is 10500.
v ILLNESS Segment
v TREATMNT Segment
The following graphic shows the TREATMNT segment.
It contains four fields:
– The date of the treatment (DATE)
– The medicine that was given to the patient (MEDICINE)
– The quantity of the medicine that the patient was given (QUANTITY)
– The name of the doctor who prescribed the treatment (DOCTOR)
The key field of the TREATMNT segment is DATE. Because a patient may
receive more than one treatment on the same date, DATE is a nonunique key
field. TREATMNT, like ILLNESS, has been specified as having RULES=LAST.
TREATMNT segments are also stored on a first-in-first-out basis. DATE is
specified in the same format as ILLDATE—YYYYMMDD.
v BILLING Segment
The following graphic shows the BILLING segment. It has only one field—the
amount of the current bill. BILLING has no key field.
v PAYMENT Segment
Chapter 1. How Your EXEC DLI Application Program Works with IMS 9
A Sample Hierarchy
The following graphic shows the PAYMENT segment. It also has only one
field—the amount of each payment remitted. The PAYMENT segment has no key
field.
v HOUSHOLD Segment
The following graphic shows the HOUSHOLD segment. It contains the names of
the members of the patient’s household, and how each is related to the patient.
RELNAME is the key field.
I/O PCB
In a DBCTL environment, an I/O PCB is needed to issue DBCTL service requests.
Unlike the other types of PCB, it is not defined with PSB generation, but if the
application program is using an I/O PCB, this has to be indicated in the PSB
scheduling request.
Alternate PCB
An alternate PCB defines a logical terminal and can be used instead of the I/O PCB
when it is necessary to direct a response to a terminal. Alternate PCBs appear in
PSBs used in a CICS-DBCTL environment, but are used only in an IMS DC
environment. CICS applications using DBCTL cannot successfully issue commands
that specify an alternate PCB, an MSDB PCB, or a GSAM PCB. However, a PSB
that contains PCBs of these types can be scheduled successfully in a CICS-DBCTL
environment.
Alternate PCBs are included in the PCB address list returned to a call level
application program. In an EXEC DLI application program, the existence of alternate
PCBs in the PSB affects the PCB number used in the PCB keyword.
DB PCB
A database PCB (DB PCB) is the PCB that defines an application program’s
interface to a database. One DB PCB is needed for each database view used by
the application program. It can be a full-function PCB, a DEDB PCB, or an MSDB
PCB.
GSAM PCB
A GSAM PCB defines an application program’s interface for GSAM operations.
When using DBCTL, a CICS program receives, by default, a DB PCB as the first
PCB in the parameter list passed to it after scheduling. However, when your
application program can handle an I/O PCB, you indicate this using the SYSSERVE
keyword on the SCHD command. The I/O PCB is then the first PCB in the parameter
address list passed back to your application program.
[IOPCB]
[Alternate PCB ... Alternate PCB]
[DBPCB ... DBPCB]
[GSAMPCB ... GSAMPCB]
Each PSB must contain at least one PCB. The I/O PCB must be addressable in
order to issue a system service command. An alternate PCB is used only for IMS
online programs, which can run only with the Transaction Manager. Alternate PCBs
can be present even though your program does not run under the Transaction
Manager. A DB PCB can be a full-function PCB, a DEDB PCB, or an MSDB PCB.
PCB Summary
The following section summarizes the information concerning I/O PCBs and
alternate PCBs in various types of application programs.
Recommendation: You should read the following section if you intend to issue
system service requests.
DB Batch Programs
Alternate PCBs are always included in the list of PCBs supplied to the program by
DL/I irrespective of whether you have specified CMPAT=Y. The I/O PCB is returned
depending on the CMPAT option.
If you specify CMPAT=Y, the PCB list contains the address of the I/O PCB, followed
by the addresses of any alternate PCBs, followed by the addresses of any DB
PCBs.
If you do not specify CMPAT=Y, the PCB list contains the addresses of any
alternate PCBs followed by the addresses of the DB PCBs.
The PCB list contains the address of the I/O PCB, followed by the addresses of any
alternate PCBs, followed by the addresses of the DB PCBs.
Code the commands in free form: Where keywords, operands, and parameters are
shown separated by commas, no blanks can appear immediately before or after the
comma. Where keywords, operands, and parameters are shown separated by
blanks, you can include as many blanks as you wish.
The format of the commands is the same for users of COBOL, PL/I, assembler
language, C/370 and C++/370.
The EXEC DLI commands and the pages they are found on are as follows:
v “DLET Command” on page 15
v “GN Command” on page 17
v “GNP Command” on page 22
v “GU Command” on page 28
v “ISRT Command” on page 33
v “POS Command” on page 39
v “REPL Command” on page 40
v “RETRIEVE Command” on page 44
The examples included with each command refer to the “A Sample Hierarchy” on
page 8.
DLET Command
The Delete (DLET) command is used to remove a segment and its dependents from
the database.
Format
EXEC DLI DLET
USING PCB(expression) VARIABLE
SEGMENT(name) FROM(area)
SEGMENT((area)) SEGLENGTH(expression)
SETZERO(data_value)
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
VARIABLE
Indicates that a segment is variable-length.
SEGMENT(name)
Qualifies the command, specifying the name of the segment type you want to
retrieve, insert, delete, or replace.
Usage
You use the DLET command to delete a segment and its dependents from the
database. You must first retrieve segments you want to delete, just as if you were
replacing segments, The DLET command deletes the retrieved segment and its
dependents, if any, from the database.
Example
“Evelyn Parker has moved away from this area. Her patient number is 10450.
Delete her record from the database.”
Explanation
You want to delete all the information about Evelyn Parker from the database. To do
this, you must delete the PATIENT segment. When you do this, DL/I deletes all the
dependents of that segment. This is exactly what you want DL/I to do—there is no
reason to keep such segments as ILLNESS and TREATMNT for Evelyn Parker if
she is no longer one of the clinic’s patients.
Before you can delete the patient segment, you have to retrieve it:
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);
To delete this patient’s database record, you issue a DLET command and use the
FROM option to give the name of the I/O area that contains the segment you want
deleted:
EXEC DLI DLET SEGMENT(PATIENT) FROM(PATAREA);
When you issue this command, the PATIENT segment, and its dependents—the
ILLNESS, TREATMNT, BILLING, PAYMENT, and HOUSHOLD segments—are
deleted.
Restrictions
You cannot issue any commands using the same PCB between the retrieval
command and the DLET command, and you can issue only one DLET command for
each GET command.
GN Command
The GN command is used to retrieve segments sequentially.
Format
EXEC DLI GET NEXT
GN USING PCB(expression)
(1)
INTO(area)
KEYFEEDBACK(area)
FEEDBACKLEN(expression)
<A> <B>
VARIABLE FIRST SEGMENT(name) SEGLENGTH(expression)
LAST SEGMENT((area))
CURRENT
OFFSET(expression) (2) LOCKED
INTO(area) LOCKCLASS(class)
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value) SETPARENT
WHERE(qualification statement)
(3)
FIELDLENGTH(expression)
KEYS(area)
(4)
KEYLENGTH(expression)
VARIABLE FIRST SEGMENT(name) SEGLENGTH(expression)
LAST SEGMENT((area))
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value)
WHERE(qualification statement)
(3)
FIELDLENGTH(expression)
KEYS(area)
(4)
KEYLENGTH(expression)
Notes:
1 If you leave out the SEGMENT option, specify the INTO option as shown.
2 Specify INTO on parent segments for a path command.
3 If you use multiple qualification statements, specify a length for each, using
FIELDLENGTH. For example: FIELDLENGTH(24,8)
4 You can use either the KEYS option or the WHERE option, but not both on
one segment level.
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (It is required in COBOL
programs and optional in PL/I and assembler language programs.)
INTO(area)
Specifies an area into which the segment is read.
VARIABLE
Indicates that a segment is variable-length.
Usage
Use the GN command to sequentially retrieve segments from the database. Each
time you issue a GN command, IMS DB retrieves the next segment, as described by
the options you include in the command. Before issuing a GN command, you should
establish position in the database record by issuing a GU command.
You do not have to use a segment option with a GN command. However, you should
qualify your GN commands as much as possible with the KEYS or WHERE options
after the SEGMENT option.
Examples
Example 1
“We need a list of all patients who have been to this clinic.”
Each time your program issued this command, the current position moves forward
to the next database record.
Example 2
“What are the names of the patients we have seen since the beginning of this
month?”
Example 3
EXEC DLI GN INTO(PATAREA);
Restrictions
With an unqualified GN command, the retrieved segment type might not be the one
expected. Therefore, specify an I/O area large enough to contain the largest
segment accessible to your program.
Use either the KEYS option or the WHERE option, but not both on one segment
level.
GNP Command
The Get Next in Parent (GNP) command is used to retrieve dependent segments
sequentially.
Format
EXEC DLI GET NEXT IN PARENT
GNP USING PCB(expression)
(1)
INTO(area)
KEYFEEDBACK(area)
FEEDBACKLEN(expression)
<A> <B>
VARIABLE FIRST SEGMENT(name) SEGLENGTH(expression)
LAST SEGMENT((area))
CURRENT
OFFSET(expression) (2) LOCKED
INTO(area) LOCKCLASS(class)
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value) SETPARENT
KEYS(area)
(4)
KEYLENGTH(expression)
VARIABLE FIRST SEGMENT(name) SEGLENGTH(expression)
LAST SEGMENT((area))
OFFSET(expression) INTO(area) LOCKED
LOCKCLASS(class)
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value)
WHERE(qualification statement)
(3)
FIELDLENGTH(expression)
KEYS(area)
(4)
KEYLENGTH(expression)
Notes:
1 If you leave out the SEGMENT option, specify the INTO option as shown.
2 Specify INTO on parent segments for a path command.
3 If you use multiple qualification statements, specify a length for each, using
FIELDLENGTH. For example: FIELDLENGTH(24,8)
4 You can use either the KEYS option or the WHERE option, but not both on
one segment level.
Options
You can qualify your GNP command by using SEGMENT and WHERE options.
You can have as many levels of qualification for a GNP command as there are levels
in the database’s hierarchy. However, you should not qualify your command in a
way that causes DL/I to move off of the segment type you have established as a
parent for the command.
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated. Use this to retrieve a
segment’s concatenated key.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (It is required in COBOL
programs and optional in PL/I and assembler language programs.)
INTO(area)
Specifies an area into which the segment is read. Use this to retrieve one or
more segments with one command.
VARIABLE
Indicates that a segment is variable-length.
FIRST
Specifies that you want to retrieve the first segment occurrence of a segment
type, or that you want to insert a segment as the first occurrence. Use this to
retrieve the first segment occurrence of a segment type.
LAST
Specifies that you want to retrieve the last segment occurrence of a segment
type, or that you want to insert a segment as the last segment occurrence. Use
this to retrieve the last segment occurrence of a segment type.
CURRENT
Qualifies the command, and specifies that you want to use your current position
at this level and above as qualification for this segment. Use this to retrieve a
segment based on your current position.
SEGLENGTH(expression)
Specifies the length of the I/O area into which the segment is retrieved. Its
argument can be any expression that converts to the integer data type; you can
specify either a number or a reference to a halfword in your program containing
a number. (SEGLENGTH is required in COBOL programs for any SEGMENT
level that specifies the INTO or FROM option.)
Requirement: The value specified for SEGLENGTH must be greater than or
equal to the length of the longest segment that can be processed by this call.
OFFSET(expression)
Specifies the offset to the destination parent. The argument can be any
Usage
The Get Next in Parent (GNP) command makes it possible to limit the search for a
segment; you can retrieve only the dependents of a particular parent. You must
have established parentage before issuing a GNP command. IMS Version 7
Application Programming: Database Manager explains how to establish parentage.
Explanation: To satisfy this request, you want only to retrieve the dependent
segments of the patient whose patient number is 09080; you do not want to retrieve
all the dependents of each patient. To do this, use the GU command to establish
your position and parentage on the PATIENT segment for Kate Bailey. Then
continue to issue a GNP without SEGMENT or WHERE options until DL/I returns all
the dependents of that PATIENT segment. (A GE status code indicates that you
have retrieved all the dependent segments.) To answer the request above, your
program could issue these commands:
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA)
WHERE (PATNO=PATNO1);
EXEC DLI GNP
INTO(ILLAREA);
A GNP command without SEGMENT or WHERE options retrieves the first dependent
segment occurrence under the current parent. If your current position is already on
a dependent of the current parent, the above command retrieves the next segment
occurrence under the parent.
With an unqualified GNP command, the segment type you retrieve might not be the
one you expected, so you should specify an I/O area large enough to contain the
largest segment your program has access to. (After successfully issuing a GNP
command, you can find out from the DIB the segment type retrieved.)
Example 2
“Which doctors have been prescribing acetaminophen for headaches?”
To process this, your program continues issuing the GNP command until DL/I
returned a GE (not found) status code, then your program retrieves the next
headache segment and retrieves the TREATMNT segments for it. Your program
does this until there were no more ILLNESS segments where the ILLNAME was
headache.
Restrictions
The GNP command has the following restrictions:
v You must have established parentage before issuing this command.
v You cannot qualify your GNP command in a way that causes DL/I to move off of
the segment type you have established as the parent for the command.
GU Command
The Get Unique (GU) command is used to directly retrieve specific segments, and to
establish a starting position in the database for sequential processing.
Format
EXEC DLI GET UNIQUE
GU USING PCB(expression)
INTO(area)
KEYFEEDBACK(area)
FEEDBACKLEN(expression)
<A> <B>
<A>:
SEGMENT(name)
VARIABLE LAST SEGMENT((area)) SEGLENGTH(expression)
OFFSET(expression) (1) LOCKED
INTO(area) LOCKCLASS(class)
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value) SETPARENT
WHERE(qualification statement)
(2)
FIELDLENGTH(expression)
KEYS(area)
(3)
KEYLENGTH(expression)
<B>:
SEGMENT(name)
VARIABLE LAST SEGMENT((area)) SEGLENGTH(expression)
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SETCOND(data_value) SETZERO(data_value)
WHERE(qualification statement)
(2)
FIELDLENGTH(expression)
KEYS(area)
(3)
KEYLENGTH(expression)
Notes:
1 Specify INTO on parent segments for a path command.
2 If you use multiple qualification statements, specify a length for each, using
FIELDLENGTH. For example: FIELDLENGTH(24,8)
3 You can use either the KEYS option or the WHERE option, but not both on
one segment level.
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (It is required in COBOL
programs and optional in PL/I and assembler language programs.)
INTO(area)
Specifies an area into which the segment is read.
VARIABLE
Indicates that a segment is variable-length.
LAST
Specifies that you want to retrieve the last segment occurrence of a segment
type, or that you want to insert a segment as the last segment occurrence.
Usage
Use the GU command to retrieve specific segments from the database, or to
establish a position in the database for sequential processing.
You must at least specify the SEGMENT option with a GU command to indicate the
segment type you want to retrieve. (IMS DB retrieves the first occurrence of the
segment you named in the SEGMENT argument.)
When you need to retrieve a specific occurrence of a segment type, you can further
qualify the command by using the WHERE or KEYS option after the SEGMENT
option.
You probably want to further qualify your GU commands with the WHERE or KEYS
option, and specify a specific occurrence of a segment type. If you fully qualify a GU
command, you can retrieve a segment regardless of your position in the database
record.
Examples
Example 1
“What illness was Robert James here for most recently? Was he given any
medication on that day for that illness? His patient number is 05136.”
Once you had retrieved the ILLNESS segment with the date of the patient’s most
recent visit to the clinic, you could issue another command to find out whether he
was treated during that visit. If the date of his most recent visit was January 5,
1988, you could issue the command below to find out whether or not he was
treated on that day for that illness (assuming PATNO1 contains 05163, and DATE1
contains 19880105):
EXEC DLI GU
SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
SEGMENT(ILLNESS) WHERE(ILLDATE=DATE1)
SEGMENT(TREATMNT) INTO(TRTAREA) WHERE(DATE=DATE1);
Example 2
“What is Joan Carter currently being treated for? Her patient number is 10320.”
EXEC DLI GU
SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
SEGMENT(ILLNESS) INTO(ILLAREA);
Explanation: In this example you want the ILLNESS segment for the patient
whose patient number is 10320.
Example 3
EXEC DLI GU
SEGMENT(PATIENT)
SEGMENT(ILLNESS)
SEGMENT(TREATMNT) INTO(AREA);
Explanation: This example retrieves the first TREATMNT segment and specifies
the three levels of qualification.
Restriction
You must at least specify the SEGMENT option to indicate the segment type you
want to retrieve.
ISRT Command
The Insert (ISRT) command is used to add one or more segments to the database.
SEGMENT(name)
VARIABLE FIRST SEGMENT((area)) SEGLENGTH(expression)
LAST
CURRENT
(1) MOVENEXT(data_value) GETFIRST(data_value)
FROM(area)
SET(data_value) SETCOND(data_value) SETZERO(data_value)
WHERE(qualification statement)
(2)
FIELDLENGTH(expression)
KEYS(area)
(3)
KEYLENGTH(expression)
VARIABLE FIRST SEGLENGTH(expression) OFFSET(expression)
LAST
MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)
SEGMENT(name)
SETCOND(data_value) SETZERO(data_value) SEGMENT((area))
FROM(area)
Notes:
1 Specify FROM on parent segments for a path command.
2 If you use multiple qualification statements, specify a length for each, using
FIELDLENGTH. For example: FIELDLENGTH(24,8)
3 You can use either the Keys option or the Where option, but not both on one
segment level.
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
If you are inserting a root segment, you need only specify a SEGMENT option.
DL/I determines the correct place for its insertion in the database by the key
taken from the I/O area. If the segment you are inserting is not a root segment,
When you specify multiple parent segments, you can mix segments with and
without the WHERE option. If you include only SEGMENT options on parent
segments, DL/I uses the first occurrence of each segment type to satisfy the
command.
SEGLENGTH(expression)
Specifies the length of the I/O area from which the segment is obtained. Its
argument can be any expression that converts to the integer data type; you can
specify either a number or a reference to a halfword in your program containing
a number. (It is required in COBOL programs for any SEGMENT level that
specifies the INTO or FROM option.)
Requirement: The value specified for SEGLENGTH must be greater than or
equal to the length of the longest segment that can be processed by this call.
FROM(area)
Specifies an area containing the segment to be added, replaced, or deleted.
Use FROM to insert one or more segments with one command.
MOVENEXT(data_value)
Specifies a subset pointer to be moved to the next segment occurrence after
your current segment.
GETFIRST(data_value)
Specifies that you want the search to start with the first segment occurrence in
a subset.
SET(data_value)
Specifies unconditionally setting a subset pointer to the current segment.
SETCOND(data_value)
Specifies conditionally setting a subset pointer to the current segment.
SETZERO(data_value)
Specifies setting a subset pointer to zero.
WHERE(qualification statement)
Qualifies the command, specifying the segment occurrence. Its argument is one
or more qualification statements, each of which compares the value of a field in
a segment to a value you supply. Each qualification statement consists of:
v The name of a field in a segment
v The relational operator, which indicates how you want the two values
compared
v The name of a data area in your program containing the value that is
compared against the value of the field
When you specify multiple parent segments, you can mix segments with and
without the WHERE option. If you include only SEGMENT options on parent
segments, DL/I uses the first occurrence of each segment type to satisfy the
command.
Usage
To add new segments to an existing database, use the ISRT command. When you
issue the ISRT command, DL/I takes the data from the I/O area you have named in
the FROM option and adds the segment to the database. (The initial loading of a
database requires using the LOAD command, instead of the ISRT command.)
You can use ISRT to add new occurrences of an existing segment type to a HIDAM,
HISAM, or HDAM database. For an HSAM database, you can add new segments
only by reprocessing the whole database or by adding the new segments to the end
of the database.
Before you can issue the ISRT command to add a segment to the database, your
program must build the segment to be inserted in an I/O area. If the segment has a
key, you must place the correct key in the correct location in the I/O area. If field
sensitivity is used, the fields must be in the order defined by the PSB for the
application’s view of the segment.
If you are adding a root segment occurrence, DL/I places it in the correct sequence
in the database by using the key you supply in the I/O area. If the segment you are
inserting is not a root, but you have just inserted its parent, you can insert the child
segment by issuing an insert request qualified with only the segment name. You
must build the new segment in your I/O area before you issue the ISRT request.
You also qualify insert requests with the segment name when you add a new root
segment occurrence. When you are adding new segment occurrences to an
existing database, the segment type must have been defined in the DBD. You can
add new segment occurrences directly or sequentially after you have built them in
the program’s I/O area.
If the segment type you are inserting has a unique key field, the location where DL/I
adds the new segment occurrence depends on the value of its key field. If the
Examples
Example 1
“Add information to the record for Chris Edwards about his visit to the clinic on
February 1, 1993. His patient number is 02345. He had a sore throat.”
Explanation: First, build the ILLNESS segment in your program’s I/O area. Your
I/O area for the ILLNESS segment looks like this:
19930201SORETHROAT
Use the command to add this new segment occurrence to the database is:
EXEC DLI ISRT
SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) FROM(ILLAREA);
Example 2
“Add information about the treatment to the record for Chris Edwards, and add
information about the illness.”
Explanation: You build the TREATMNT segment in a segment I/O area. The
TREATMNT segment includes the date, the medication, amount of medication, and
the doctor’s name:
19930201MYOCINbbb0001TRIEBbbbbb&b
The following command adds both the ILLNESS segment and the TREATMNT
segment to the database:
EXEC DLI ISRT
SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) FROM(ILLAREA)
SEGMENT(TREATMNT) FROM(TRETAREA);
Example 3
EXEC DLI ISRT
SEGMENT(ILLNESS) KEYS(CONKEY)
SEGMENT(TREATMNT) FROM(TRETAREA);
Restrictions
The following restrictions apply to the ISRT command:
v You cannot issue the ISRT command until you have built a new segment in the
I/O area.
v You must specify at least one SEGMENT option for each segment being added
to the database.
v When inserting a segment, you must have position established on the parents of
the segment.
POS Command
The Position (POS) command retrieves the location of either a dependent or the last
inserted sequential dependent segment.
Format
EXEC DLI POSITION USING PCB(n) INTO(data_area)
POS
KEYFEEDBACK(area) SEGMENT(name)
FEEDBACKLEN(expression) SEGMENT((area))
WHERE(qualification_statement)
FIELDLENGTH(expression)
Options
USING PCB(n)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
INTO(data_area)
Specifies an area into which the segment is read.
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (FEEDBACKLEN is required in
COBOL programs and optional in PL/I and assembler language programs.)
Usage
Use the POS command to:
v Retrieve the location of a specific sequential dependent segment, including the
last one inserted
v Determine the amount of unused space within each DEDB area
If the area specified by the POS command is unavailable, the I/O area is unchanged
and an FH status code is returned.
Restriction
The POS command is for DEDBs only.
REPL Command
The Replace (REPL) command is used to replace a segment, usually to change the
values of one or more of its fields.
SEGMENT(name)
VARIABLE SEGMENT((area)) SEGLENGTH(expression)
FROM(area)
OFFSET(expression) MOVENEXT(data_value)
SET(data_value) SETCOND(data_value) SETZERO(data_value)
SEGMENT(name)
VARIABLE SEGMENT((area)) SEGLENGTH(expression)
FROM(area)
OFFSET(expression) MOVENEXT(data_value)
SET(data_value) SETCOND(data_value) SETZERO(data_value)
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
VARIABLE
Indicates that a segment is variable-length.
SEGMENT(name)
Qualifies the command, specifying the name of the segment type you want to
retrieve, insert, delete, or replace.
SEGMENT((area))
Is a reference to an area in your program containing the name of the segment
type. You can specify an area instead of specifying the name of the segment in
the command.
SEGLENGTH(expression)
Specifies the length of the I/O area from which the segment is obtained. Its
argument can be any expression that converts to the integer data type; you can
specify either a number or a reference to a halfword in your program containing
a number. (It is required in COBOL programs for any SEGMENT level that
specifies the INTO or FROM option.)
Requirement: The value specified for SEGLENGTH must be greater than or
equal to the length of the longest segment that can be processed by this call.
Usage
You must qualify the REPL command with at least one SEGMENT and FROM option,
which together indicate the retrieved segments you want replaced.
If the Get command that preceded the REPL command was a path command, and
you do not want to replace all of the retrieved segments or the PSB does not have
replace sensitivity for all of the retrieved segments, you can indicate which of the
segments are not to be replaced by omitting the SEGMENT option.
If your program attempts to do a path replace of a segment where it does not have
replace sensitivity, the data for the segment in the I/O area for the REPL command
must be the same as the segment returned on the preceding GET command. If the
data changes in this situation, the transaction is abended and no data is changed
as a result of the Replace command.
Notice that the rules for a REPL path command differ from the rules for an ISRT path
command. You cannot skip segment levels to be inserted with an ISRT command,
as you can with a REPL command.
To update information in a segment, you can use the REPL command. The REPL
command replaces data in a segment with data you supply in your application
program. First, you must retrieve the segment into an I/O area. You then modify the
information in the I/O area and replace the segment with the REPL command. For
your program to successfully replace a segment, that segment must already have
been defined as replace-sensitive in the PCB by specifying PROCOPT=A or
PROCOPT=R on the SENSEG statement in the PCB.
You cannot issue any commands using the same PCB between a Get command
and the REPL command, and you can issue only one REPL command for each Get
command.
Examples
Example 1
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA);
Explanation: This example shows that you cannot issue any commands using the
same PCB between the Get command and the REPL command, and you can issue
only one REPL command for each Get command. If you issue the above commands
and wanted to modify information in the segment again, you must first reissue the
GU command, before reissuing the REPL command.
Example 2
“We have received a payment for $65.00 from a patient whose ID is 08642. Update
the patient’s billing record and payment record with this information, and print a
current bill for the patient.”
After you have calculated the current bill and payment, you can print the bill, then
replace the billing and payment segments in the database. Before issuing the REPL
command, you must change the segments in the I/O area.
Because you have not changed the PATIENT segment, you do not need to replace
it when you replace the BILLING and PAYMENT segments. To indicate to DL/I that
you do not want to replace the PATIENT segment, you do not specify the
SEGMENT option for the PATIENT segment in the REPL command.
EXEC DLI REPL
SEGMENT(BILLING) FROM(BILLAREA)
SEGMENT(PAYMENT) FROM(PAYAREA);
These two examples are called path commands. You use a path REPL command to
replace more than one segment with one command.
Example 3
“Steve Arons, patient number 10250, has moved to a new address in this town. His
new address is 4638 Brooks Drive, Lakeside, California. Update the database with
his new address.”
Explanation: You need to retrieve the PATIENT segment for Steve Arons and
replace the address portion of the segment. To retrieve the PATIENT segment, you
can use this GU command (assuming PATNO1 contains 10250):
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);
Since you are not replacing the first two fields of the PATIENT segment (PATNO
and NAME), you do not have to change them in the I/O area. Place the new
address in the I/O area following the PATNO and NAME fields. Then you issue the
following REPL command:
EXEC DLI REPL
SEGMENT(PATIENT) FROM(PATAREA);
Example 4
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA)
WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) INTO(ILLAREA)
SEGMENT(TREATMNT) INTO(TRETAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA)
SEGMENT(TREATMNT) FROM(TRETAREA);
Explanation: This example assumes that you want to replace the PATIENT and
TREATMNT segments for patient number 10401, but you do not want to change the
ILLNESS segment. To do this issue the above command (assuming PATNO1
contains 10401).
Restrictions
The following restrictions apply to the REPL command:
v You cannot issue any commands using the same PCB between the Get
command and the REPL command.
v You can issue only one REPL command for each Get command.
v To modify information in a segment, you must first reissue the GU command
before reissuing the REPL command.
v You must qualify the REPL command with at least one SEGMENT option and one
FROM option.
v If you use a FROM option for a segment, you cannot qualify the segment by
using the WHERE or KEYS option; DL/I uses the key field value specified in the
I/O area as qualification.
RETRIEVE Command
Use the RETRIEVE command to determine current position in the database in batch
and BMP programs.
FEEDBACKLEN(expression)
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
expression specifies the PCB for which you want to retrieve the concatenated
key. It can be any expression in the host language that converts to the integer
data type. You can specify either a number or a reference to a halfword
containing a number. The value must be a positive integer not greater than the
number of PCBs generated for the PSB. The first PCB in the list, the I/O PCB,
is 1. The first DB PCB in the list is 2, the second is 3, and so forth.
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated.
FEEDBACKLEN(expression)
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (It is required in COBOL
programs and optional in PL/I and assembler language programs.)
expression is the length of the key feedback I/O area. It can be any expression
in the host language that converts to integer data type; you can specify either a
number or a reference to a halfword containing a number. For IBM COBOL for
MVS & VM (or VS COBOL II), PL/I, or assembler language, FEEDBACKLEN is
optional. For COBOL programs that are not compiled with the IBM COBOL for
MVS & VM (or VS COBOL II) compiler, you must specify FEEDBACKLEN with
the KEYFEEDBACK option.
Usage
If your program issues symbolic checkpoint commands it must also issue the
extended RESTART (XRST) command or the RETRIEVE command. The RETRIEVE
command is issued once, at the start of your program. You can use the RETRIEVE
command to start your program normally, or to restart it in case of an abnormal
termination.
You can use the RETRIEVE command from a specific checkpoint id or a time/date
stamp. Because the RETRIEVE command attempts to reposition the database, your
program also needs to check for correct position.
After issuing the RETRIEVE command, the segment type and level on which the
position is established is returned to the DIBSEGM and DIBSEGLV fields in the
DIB. The value in DIBKFBL is set to the actual length of the concatenated key. The
DIBSTAT field contains the value returned from the GU repositioning, not the XRST
command.
Examples
EXEC DLI RETRIEVE USING PCB(2) KEYFEEDBACK(KEYAREA);
EXEC DLI RETRIEVE USING PCB(5) KEYFEEDBACK(KEYAREA);
Explanation
These RETRIEVE commands retrieve the concatenated key for the first and fourth DB
PCBs. (The first PCB in the list is the I/O PCB, so the first DB PCB is the second
one in the list.) After issuing the first RETRIEVE command, you can determine your
position in the first DB PCB by examining the concatenated key in KEYAREA, and
the values returned in the DIBSEGM and DIBSEGLV fields in the DIB. After issuing
the second RETRIEVE command, you can determine your position in the fourth DB
PCB by examining the same fields.
Restrictions
The following restrictions apply to the RETRIEVE command:
v You cannot use this command in a CICS program.
v To use this command, you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v You cannot use this command unless the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
SCHD Command
The Schedule (SCHD) command is used to schedule a PSB in a CICS online
program. For information on the I/O PCB, see “Using the I/O PCB, PSB, and PCB”
on page 11.
Format
EXEC DLI SCHEDULE PSB(name)
SCHD PSB((area)) SYSSERVE NODHABEND
Options
PSB(name)
Specifies the name of the PSB available to your application program that you
want to schedule with the SCHD command.
PSB((area))
Specifies an 8-byte data area in your program that contains the name of the
PSB available to your program that you want to schedule with the SCHD
command.
Usage
Before you can access DL/I databases from a CICS program, you must notify DL/I
that your program will be accessing a database by scheduling a PSB. Do this by
issuing the SCHD command. When you no longer plan to use a PSB, or you want to
schedule a subsequent PSB (one or more), you must terminate the previous PSB
with the TERM command. (For more information on the I/O PCB and PSB, see
“Using the I/O PCB, PSB, and PCB” on page 11)
The SCHD command can be specified two ways (see the examples below).
Examples
EXEC DLI SCHD PSB(psbname)SYSSERVE;
EXEC DLI SCHD PSB((AREA));
Explanation
These examples show two ways to schedule a PSB in a CICS program.
TERM Command
The Terminate (TERM) command is used to terminate a PSB, in a CICS online
program.
Format
EXEC DLI TERMINATE
TERM
Options
No options are allowed with the TERM command.
Usage
If you want to use a PSB other than the one already scheduled, use the TERM
command to release the PSB.
When you issue the TERM command, all database changes are committed and
cannot be backed out. Because returning to CICS also terminates the PSB and
commits changes, you need not use the TERM command unless you want to
schedule another PSB, or commit database changes before returning to CICS.
Example
EXEC DLI TERM
Explanation
This example shows how to terminate a PSB with the TERM command.
The following system service commands are valid in batch or BMP without first
issuing the SCHD command with the SYSSERVE keyword:
v “CHKP Command” on page 49
v “ROLB Command” on page 55
v “ROLL Command” on page 56
v “SYMCHKP Command” on page 61
v “XRST Command” on page 63
The following system service commands are valid in an online CICS program using
DBCTL:
v ACCEPT
v DEQ
v LOG
v QUERY
v REFRESH
v ROLS
v SETS
v STAT
To issue system service commands, the input/output PCB (I/O PCB) is required. For
detailed information on the I/O PCB, as well as the PSB, and PCB, see “Using the
I/O PCB, PSB, and PCB” on page 11.
ACCEPT Command
The Accept (ACCEPT) command is used to tell IMS to return a status code to your
program, rather than abend the transaction.
Format
EXEC DLI ACCEPT STATUSGROUP('A')
Options
STATUSGROUP('A')
Informs IMS that the application is prepared to accept status codes regarding
unavailability. IMS then returns a status code instead of pseudoabending if a
call issued later requires access to unavailable data.
This is a required option.
Usage
Use the ACCEPT command to tell IMS to return a status code instead of abending
the program. These status codes result because PSB scheduling completed without
all of the referenced databases being available.
Example
EXEC DLI ACCEPT STATUSGROUP('A');
CHKP Command
The Checkpoint (CHKP) command is used to issue a basic checkpoint and to end a
logical unit of work. You cannot use this command in a CICS program.
Format
EXEC DLI CHECKPOINT ID(area)
CHKP ID(’literal’)
Options
ID(area)
Contains the checkpoint ID. Specifies the name of an area in your program
containing the checkpoint ID. The area pointed to is eight bytes. If you are
using PL/I, specify this option as a pointer to a major structure, an array, or a
character string.
ID('literal')
'literal' is an 8-byte checkpoint ID, enclosed in quotation marks. In CHKP
commands the area pointed to is 8 bytes long.
Usage
The two kinds of commands that allow you to make checkpoints are: the CHKP, or
basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Both checkpoint commands make it possible for you to commit your program’s
changes to the database and to establish places from which the program can be
restarted, should it terminate abnormally.
You must not use the CHKPT=EOV parameter on any DD statement to take an IMS
checkpoint.
You can issue the basic CHKP command to commit your program’s changes to the
database and establish places from which your program can be restarted. When
you issue a basic CHKP command, you must provide the code for restarting your
program.
When you issue a CHKP command, you specify the ID for the checkpoint. You can
supply either the name of a data area in your program that contains the ID, or you
can supply the actual ID, enclosed in single quotes. See the examples below.
Examples
EXEC DLI CHKP ID(chkpid);
EXEC DLI CHKP ID('CHKP0007');
Explanation
These examples show how to specify the CHKP command.
Restrictions
The following restrictions apply to the CHKP command:
v You cannot use this command in a CICS program, as was stated above.
v You must first define an I/O PCB for your program before you can use the CHKP
command.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
DEQ Command
The Dequeue (DEQ) command is used to release a segment that is retrieved with
the LOCKCLASS option.
Format
EXEC DLI DEQ LOCKCLASS(data_value)
Usage
Use the DEQ command to release locks on segments that were retrieved using the
LOCKCLASS option. Using LOCKCLASS on Get commands allows you to reserve
segments for exclusive use by your transaction. No other transaction is allowed to
update these reserved segments until either your transaction reaches a sync point
or the DEQ command has been issued, thereby releasing the locks on these
reserved segments. The LOCKCLASS option lets your application program leave
these segments and retrieve them later without any changes having been added.
Example
Your program can use the LOCKCLASS option as follows:
EXEC DLI DEQ LOCKCLASS(data_value)
EXEC DLI GU SEGMENT(PARTX)
SEGMENT(ITEM1) LOCKCLASS('B') INTO(PTAREA1);
EXEC DLI GU SEGMENT(PARTX)
SEGMENT(ITEM2) LOCKCLASS('C') INTO(PTAREA2);
EXEC DLI DEQ LOCKCLASS('B');
Explanation
This example shows the format of the DEQ command, where data_value is a 1-byte
alphabetic character in the range B to J. The DEQ command releases the lock that
was gotten and held with a LOCKCLASS of ’B’ for the PARTX segment as a result
of the first GU. The lock that was gotten with a LOCKCLASS of ’C’ on the PARTX
segment during the second GU remains held.
Restriction
The following restriction applies to the DEQ command:
v To use this command you must first define an I/O PCB for your program.
LOAD Command
The Load (LOAD) command is used to add a segment sequentially while loading the
database.
SEGMENT(name) FROM(area)
SEGMENT((area)) SEGLENGTH(expression)
Options
USING PCB(expression)
Specifies the DB PCB you want to use. Its argument can be any expression
that converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number.
VARIABLE
Indicates that a segment is variable-length.
SEGMENT(name)
Specifies the name of the segment type you want to retrieve, insert, delete, or
replace.
SEGMENT((area))
A reference to an area in your program containing the name of the segment
type. You can specify an area instead of the name of the segment in the
command.
SEGLENGTH(expression)
Specifies the length of the I/O area from which the segment is obtained. Its
argument can be any expression that converts to the integer data type; you can
specify either a number or a reference to a halfword in your program containing
a number. ( SEGLENGTH is required in COBOL programs for any SEGMENT
level that specifies the INTO or FROM option.)
Requirement: The value specified for SEGLENGTH must be greater than or
equal to the length of the longest segment that can be processed by this call.
FROM(area)
Specifies an area containing the segment to be added, replaced, or deleted.
Usage
The LOAD command is used for database load programs, which are described in
IMS Version 7 Administration Guide: Database Manager.
Example
EXEC DLI LOAD
SEGMENT(ILLNESS) FROM(ILLAREA);
LOG Command
The Log (LOG) command is used to write information to the system log.
Options
FROM(area)
Specifies an area containing the segment to be added, replaced, or deleted.
LENGTH(expression)
Specifies the length of an area.
Usage
You use the LOG command to write information to the system log. For detailed
information on this command, see IMS Version 7 Application Programming: Design
Guide.
Example
EXEC DLI LOG
FROM(ILLAREA) LENGTH(18);
Restriction
The following restriction applies to the LOG command:
v To use this command you must first define an I/O PCB for your program.
QUERY Command
The Query (QUERY) command obtains status code and other information in the DL/I
interface block (DIB), which is a subset of the IMS PCB.
Format
EXEC DLI QUERY USING PCB(expression)
Options
USING PCB(expression) is required. No other options are allowed with the QUERY
command.
Usage
For full-function databases, the DIB should contain NA, NU, TH or blanks. For an
explanation of the codes, see “Status Code Explanations” on page 127.
Use the QUERY command after scheduling the PSB but before making the database
call. If the program has already issued a call using the DB PCB, you then use the
REFRESH command to update the information in the DIB.
Explanation: This example shows how to specify the QUERY command. In this
example, (n) specifies the PCB.
Example 2
EXEC DLI REFRESH DBQUERY;
Explanation: If your program has already issued a call using the DB PCB name,
use the REFRESH command to update the information in the DIB. The REFRESH
command updates all DB PCBs. You can issue it only one time.
Restrictions
The following restrictions apply to the QUERY command:
v To use this command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
REFRESH Command
The Refresh (REFRESH) command is used to obtain the most recent information from
the DIB for the most recently issued command.
Format
EXEC DLI REFRESH DBQUERY
Options
DBQUERY is required. Other options are not allowed with the REFRESH command.
Usage
The REFRESH command is used with the QUERY command.
The QUERY command is used after scheduling the PSB but before making the first
database call. If the program has already issued a call using the DB PCB, use the
REFRESH command to update the information in the DIB.
The REFRESH command updates all DB PCBs. It can be issued only once.
Example
EXEC DLI REFRESH DBQUERY;
Explanation
This example shows how to specify the REFRESH command.
ROLB Command
The Roll Back (ROLB) command is used to dynamically back out changes and return
control to your program. You cannot use this command in a CICS program.
Format
EXEC DLI ROLB
Options
No options are allowed with the ROLB command.
Usage
When a batch or BMP program determines that some of its processing is invalid,
two commands make it possible for the program to remove the effects of its
inaccurate processing. These are the rollback commands, ROLL (see “ROLL
Command” on page 56) and ROLB.
The ROLB command is valid in batch programs when the system log is stored on
direct access storage and dynamic backout has been specified through the use of
the BKO execution parameter.
Issuing the ROLB causes IMS DB to back out any changes your program has made
to the database since its last checkpoint, or since the beginning of the program if
your program has not issued a checkpoint. When you issue a ROLB command, IMS
DB returns control to your program after backing out the changes, so that your
program can continue processing with the next statement after the ROLB command.
Example
EXEC DLI ROLB;
Explanation
This example shows how to dynamically back out changes and return control to
your program with the ROLB command.
Restrictions
The following restrictions apply to the ROLB command:
v You cannot use this command in a CICS program, as was stated above.
v You must first define an I/O PCB for your program before you can use this
command.
ROLL Command
The Roll (ROLL) command is used to dynamically back out changes. You cannot use
this command in a CICS program
Format
EXEC DLI ROLL
Options
No options are allowed with the ROLL command.
Usage
When a batch program determines that some of its processing is invalid, two
commands make it possible for the program to remove the effects of its inaccurate
processing. These are the rollback commands, ROLL and ROLB (see “ROLB
Command” on page 55).
Issuing the ROLL causes CICS and DL/I to back out any changes your program has
made to the database since its last checkpoint, or since the beginning of the
program provided your program has not issued a checkpoint. When you issue a
ROLL command, DL/I terminates your program after backing out the updates.
Example
EXEC DLI ROLL;
Explanation
This example shows how to dynamically back out changes with the ROLL command.
If you use the ROLL command, IMS terminates the program with user abend code
U0778. This type of abnormal termination does not produce a storage dump.
Restrictions
The following restrictions apply to the ROLL command:
v You cannot use this command in a CICS program, as was stated above.
v You must first define an I/O PCB for your program before you can use this
command.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v You cannot use this command when the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
ROLS Command
The Roll Back to SETS or SETU (ROLS) command is used to back out to a
processing point set by an earlier SETS command.
Format
EXEC DLI ROLS USING PCB(expression)
TOKEN(token) AREA(data_area)
Options
USING PCB(expression)
Specifies the DB PCB you want to use. Its argument can be any expression
that converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number.
TOKEN(token)
A 4-byte token associated with the current processing point. If you specify both
TOKEN and AREA, the ROLS command backs out to the SETS or SETU you
specified.
AREA(data_area)
The name of the area to be restored to the program when a ROLS command is
issued. The first 2 bytes of the data-area field contain the length of the
data-area, including the length itself. The second 2 bytes must be set to
X'0000'. If you specify both TOKEN and AREA, the ROLS command backs out to
the SETS you specified.
The ROLS call has two formats: with TOKEN and AREA (for IOPCB only) and without
TOKEN and AREA (for IOPCB or DBPCB).
Usage
Use the SETS and ROLS commands to define multiple points at which to preserve the
state of DL/I full-function databases and to return to these points later. (For
example, you can use them so your program can handle situations that can occur
when PSB scheduling completes without all of the referenced DL/I databases being
available.)
Use of the SETS and ROLS commands apply only to DL/I full-function databases. This
means that if a logical unit of work (LUW) is updating types of recoverable
resources other than full-function databases, for example, VSAM files, the SETS and
ROLS requests have no effect on the non-DL/I resources. The backout points are not
CICS commit points; they are intermediate backout points that apply only to DBCTL
resources. It is up to you to ensure the consistency of all the resources involved.
You can use the ROLS command to backout to the state all full-function databases
were in before either a specific SETS or SETU request or the most recent commit
point.
Examples
Example 1
EXEC DLI ROLS TOKEN(token1) AREA(data_area)
Example 2
EXEC DLI ROLS USING PCB(PCB5)
Explanation: In this example, for IOPCB or DBPCB, backout takes place to the
prior sync point and the application is pseudo-abended with a U3033, status code.
Control does not return to the application.
In this example, PCB5 is the number of a DB PCB that has received a 'data
unavailable' status code. This command results in the same action that would have
occurred had the program not issued an ACCEPT STATUSGROUPA command.
(See “Chapter 7. Using Data Availability Enhancements” on page 109.)
Example 3
EXEC DLI ROLS
Explanation: In this example, for IOPCB or DBPCB, backout takes place to the
prior sync point and the application is pseudo-abended with a U3033, provided the
previous reference to that PCB gave an unavailable status code. Control does not
return to the application.
Restrictions
The following restrictions apply to the ROLS command:
v To use this command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v You cannot use this command when the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
SETS Command
The Set a Backout Point (SETS) command is used to define points in your
application at which to preserve the state of the DL/I databases before initiating a
set of DL/I requests to perform a function. Your application can issue a ROLS
command later if it cannot complete the function.
Format
EXEC DLI SETS
TOKEN(mytoken) AREA(data_area)
Options
TOKEN(mytoken)
A 4-byte token associated with the current processing point.
AREA(data_area)
The name of the area to be restored to the program when a SETS command is
Usage
You can use the SETS command to define multiple points at which to preserve the
state of the DL/I databases and to return to these points later. For example, you
can use the SETS command to allow your program to handle situations that can
occur when PSB scheduling completed without all of the referenced DL/I databases
being available.
The SETS command applies only to DL/I full-function databases. If a logical unit of
work (LUW) is updating types of recoverable resources other than full-function
databases, for example VSAM files, the SETS command has no effect on the
non-DL/I resources. The backout points are not CICS commit points; they are
intermediate backout points that apply only to DBCTL resources. It is up to you to
ensure the consistency of all the resources involved.
Example
EXEC DLI SETS TOKEN(mytoken) AREA(data_area)
Explanation
This example shows how to specify the SETS command.
Restrictions
The following restrictions apply to the SETS command:
v To use this command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v In batch, you can only use this command when the system log is stored on direct
access storage and dynamic backout has been specified. You must also specify
BKO=Y in the parm field of your JCL when you execute the program.
v It is rejected when the PSB contains a DEDB or MSDB PCB, or when the call is
made to a DB2 database.
v It is valid, but not functional, if unsupported PCBs exist in the PSB or if the
program uses an external subsystem.
SETU Command
The Set a Backout Point Unconditionally (SETU) command is identical to the SETS
command except that it does not get rejected if unsupported PCBs are in the PSB
or if the program uses an external subsystem.
Format
EXEC DLI SETU
TOKEN(mytoken) AREA(data_area)
Usage
You can use the SETU command to define multiple points at which to preserve the
state of the DL/I databases and to return to these points later. For example, you
can use the SETU command to allow your program to handle situations that can
occur when PSB scheduling completed without all of the referenced DL/I databases
being available.
The SETU command applies only to DL/I full-function data bases. If a logical unit of
work (LUW) is updating types of recoverable resources other than full-function
databases, such as VSAM files, the SETU command has no effect on the non-DL/I
resources. The backout points are not CICS commit points; they are intermediate
backout points that apply only to DBCTL resources. It is up to you to ensure the
consistency of all the resources involved.
Example
EXEC DLI SETU TOKEN(mytoken) AREA(data_area)
Explanation
This example shows how to specify the SETU command.
Restrictions
The following restrictions apply to the SETU command:
v You cannot use this command in a CICS program.
v To use this command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v You cannot use this command when the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
STAT Command
This section contains programming interface information.
The Statistics (STAT) command is used to obtain IMS database statistics that you
can use in debugging your program.
VSAM FORMATTED
LENGTH(expression) NONVSAM UNFORMATTED
SUMMARY
Options
USING PCB(expression)
Specifies the DB PCB you want to use. Its argument can be any expression
that converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number.
INTO(area)
Specifies an area into which the data is read.
LENGTH(expression)
Specifies the length of an area.
VSAM/NONVSAM
Specifies database type.
FORMATTED/UNFORMATTED/SUMMARY
Specifies type of output.
Usage
The STAT command is described in IMS Version 7 Application Programming: Design
Guide.
Examples
For examples of the STAT command, see IMS Version 7 Application Programming:
Database Manager.
SYMCHKP Command
The Symbolic Checkpoint (SYMCHKP) command is used to issue a symbolic
checkpoint and to end a logical unit of work.
Format
EXEC DLI SYMCHKP ID(chkpid)
ID('literal')
AREA#(area#)LENGTH#(expression#)
Usage
The two kinds of commands that allow you to make checkpoints are: the CHKP, or
basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Batch programs can use either the symbolic or the basic command.
Both checkpoint commands make it possible for you to commit your program’s
changes to the database and to establish places from which the program can be
restarted, should it terminate abnormally. You must not use the CHKPT=EOV
parameter on any DD statement to take an IMS checkpoint.
Explanation
This example shows how to issue a symbolic checkpoint and to end a logical unit of
work with a SYMPCHKP command.
Restrictions
The following restrictions apply to the SYMCHKP command:
v If you issue this command, you must also issue the XRST command.
v You cannot use this command in a CICS program.
v To use the SYMCHKP command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v The areas you specify using the SYMCHKP command must be the same, and in the
same order, as the areas specified in the XRST command.
v If you specify more than one area, you must specify all intervening areas. For
example, if you specify AREA3, you must also specify AREA1 and AREA2.
v When specifying expression1 with a COBOL program that is not compiled with
the IBM COBOL for MVS & VM (or the VS COBOL II) compiler, LENGTHx
(where x is 1 to 7) is required for each AREAx (where x is 1 to 7) that you
specify.
XRST Command
The Extended Restart (XRST) command is used to issue an extended restart, and to
perform a normal start or an extended restart from a checkpoint ID or time/date
stamp. If you use Symbolic Checkpoint commands in your program, you must use
the XRST command.
Format
EXEC DLI XRST
MAXLENGTH(expression) ID(chkpid)
ID('literal')
AREA#(area#)LENGTH#(expression#)
Options
MAXLENGTH(expression)
Specifies the length of an area from which a program is restarted. This
parameter is the longest segment in the PSB, or of all the segments in a path, if
you use path commands in your program. It can be any expression in the host
Usage
If your programs issues Symbolic Checkpoint commands it must also issue the
Extended Restart (XRST) command. The XRST is issued once, at the start of your
program. You can use the XRST command to start your program normally, or to
extend restart it in case of an abnormal termination.
After issuing the XRST command, you should test the DIBSEGM field in the DIB.
After a normal start, the DIBSEGM field should contain blanks. At the completion of
an Extended Restart, the DIBSEGM field will contain a checkpoint ID. Normally,
XRST will return the 8-byte symbolic checkpoint ID, followed by 4 blanks. If the
8-byte ID consists of all blanks, then XRST will return the 14-byte timestamp ID. The
only successful status code for an XRST command is a blank status code. If DL/I
detects any error while processing the XRST command, your program abends.
Example
EXEC DLI XRST MAXLENGTH(expression)
ID(chkpid)
AREA1(area1) LENGTH1(expression1)
...
AREA7(area7) LENGTH7(expression7)
Explanation
This example shows how to specify the XRST command.
Restrictions
The following restrictions apply to the XRST command:
v You cannot use this command in a CICS program.
v To use this command you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of nonunique keys or nonkeyed
segments.
v You cannot use this command unless the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
With CICS Transaction Server 1.1 or later, the following EXEC DLI commands are
supported in the AIB format (as well as the PCB format):
v GU
v GN
v GNP
v ISRT
v DLET
v REPL
v STAT
v POS
v QUERY
v REFRESH
v ACCEPT
v LOG
v DEQ
v SETS
v ROLS
With CICS Transaction Server 1.1 or later, and IMS/ESA Version 5, the following
AIB-only commands are supported via the EXEC DLI interface: ICMD, RCMD and
GMSG.
The CICS EDF debugging transaction supports AIB EXEC DLI requests, just as it
handles PCB type requests.
AIB Mask
The AIB mask must be supplied by the application and referenced in the EXEC call
instead of the PCB number (for example, EXEC DLI GU AIB(aib)).
The DIBSTAT field is set with a valid STATUS code when AIBRETRN =
X’00000000’ or x’00000900’. Applications should test AIBRETRN for any other
values and respond accordingly.
Each program’s working storage contains its own DIB. The contents of the DIB
reflect the status of the last DL/I command executed in that program. If the
information in your program’s DIB is required by another program used by your
transaction, you must pass the information to that program.
To access fields in the DIB, use labels that are automatically generated in your
program by the translator.
Requirement: These labels are reserved; you must not redefine them.
In your COBOL, PL/I, assembler, and C programs, some variable names are
mandatory.
For a C program:
unsigned char dibver {2} ;
unsigned char dibstat {2} ;
unsigned char dibsegm {8} ;
unsigned char dibfic01 ;
unsigned char dibfic02 ;
The following notes explain the contents of each variable name. The name in
parenthesis is the label used to access the contents.
1. Translator Version (DIBVER)
This is the version of the DIB format your program is using. (DIBVER is used for
documentation and problem determination.)
2. Status Code (DIBSTAT)
DL/I places a 2-character status code in this field after executing each DL/I
command. This code describes the results of the command.
After processing a DL/I command, DL/I returns control to your program at the
next sequential instruction following the command. The first thing your program
should do after each command is to test the status code field and take
appropriate action. If the command was completely successful, this field
contains blanks.
Following are the status codes that could be returned to this field (they are the
only status codes returned to your program):
bb (Blanks) The command was completely successful.
BA For GU, GN, GNP, DLET, REPL, and ISRT commands. Data was unavailable.
FH For GU, GN, GNP, DLET, REPL, ISRT, POS, CHKP, and SYMCHKP commands.
The DEDB was inaccessible.
FW For GU, GN, GNP, DLET, REPL, ISRT, and POS commands. More buffer space
is required than normally allowed.
GA For unqualified GN and GNP commands. DL/I returned a segment, but the
segment is at a higher level in the hierarchy than the last segment that
was returned.
GB For GN commands. DL/I reached the end of the database trying to
satisfy your GN command and did not return a segment to your
program’s I/O area.
GD For ISRT commands. The program issued an ISRT command that did
not have SEGMENT options for all levels above that of the segment
being inserted.
GE For GU, GN, GNP, ISRT, and STAT commands. DL/I was unable to find the
segment you requested, or one or more of the parents of the segment
you are trying to insert.
GG For Get commands. DL/I returns a GG status code to a program with a
processing option of GOT or GON when the segment that the program
is trying to retrieve contains an invalid pointer.
GK For unqualified GN and GNP commands. DL/I returned a segment that
satisfies an unqualified GN or GNP request, but the segment is of a
different segment type (but at the same level) than the last segment
returned.
II For ISRT commands. The segment you are trying to insert already exists
in the database. This code can also be returned if you have not
established a path for the segment before trying to insert it. The
The status codes listed above indicate exceptional conditions, and are the only
status codes returned to your program. All other status codes indicate error
conditions and cause your transaction or batch program to abnormally
terminate. If you want to pass control to an error routine from your CICS
program, you can use the CICS HANDLE ABEND command; the last 2 bytes of the
abend code are the IMS status code that caused the abnormal termination. For
more information on the HANDLE ABEND command, see the application
programming reference manual for your version of CICS. Batch BMP programs
abend with abend 1041.
3. Segment Name (DIBSEGM)
This is the name of the lowest-level segment successfully accessed. When a
retrieval is successful, this field contains the name of the retrieved segment. If
the retrieval is unsuccessful, this field contains the last segment, along the path
to the requested segment, that satisfies the command.
After issuing an XRST command, this field is either set to blanks (indicating a
successful normal start), or a checkpoint ID (indicating the checkpoint ID from
which the program was restarted).
You should test this field after issuing any of the following commands:
v GN
v GNP
v GU
v ISRT
v LOAD
v RETRIEVE
v XRST
4. Segment Level Number (DIBSEGLV)
This is the hierarchic level of the lowest-level segment retrieved. When IMS DB
retrieves the segment you have requested, IMS DB places, in character format,
the level number of that segment in this field. If you are issuing a path
command, IMS DB places the number of the lowest-level segment retrieved. If
IMS DB is unable to find the segment you have requested, it gives the level
number of the last segment it encountered that satisfied your command. This is
the lowest segment on the last path that IMS DB encountered while searching
for the segment you requested.
You should test this field after issuing any of the following commands:
v GN
Specify the name of the area using the KEYFEEDBACK option on a GET
command.
A concatenated key is made up of the key of a segment, plus the keys for all of its
parents. For example, say you requested the concatenated key of the ILLNESS
segment for January 2, 1988, for patient number 05142. The following would be
returned to your key feedback field:
0514219880102
This number includes the key field of the ILLNESS segment, ILLDATE,
concatenated to the key field of the PATIENT segment, PATNO.
If you define an area that is not long enough to contain the entire concatenated key,
the key is truncated.
As an example of what a segment looks like in your I/O area, say that you retrieved
the ILLNESS segment for Robert James, who came to the clinic on March 3, 1988.
He was treated for strep throat. The data returned to your I/O area would look like
this:
19880303STREPTHROA
DATA DIVISION.
WORKING-STORAGE SECTION.
01INPUT-AREA.
02 KEY PICTURE X(6).
02 FIELD PICTURE X(84).
Your program should define the I/O area as a fixed-length character string and pass
the name of that string, or define it in one of the other ways mentioned above and
then pass the pointer variable that points to that definition. If you want to use
substructures or elements of an array, use the DEFINED or BASED attribute.
DECLARE 1 INPUT_AREA,
2 KEY CHAR(6),
2 FIELD CHAR(84);
IOAREA DS 0CL90
KEY DS CL6
FIELD DS CL84
Programming Guidelines
This description provides some guidelines for writing efficient and error-free
programs
The number, type, and sequence of the DL/I requests your program issues affect
the efficiency of your program. A program that is poorly designed runs if it is coded
correctly. The suggestions that follow can help you develop the most efficient design
possible for your application program. Inefficiently designed programs can adversely
affect performance and are hard to change. Being aware of how certain
combinations of commands or calls affects performance helps you to avoid these
problems and design a more efficient program.
Once you have a general sequence of calls mapped out for your program, look over
the guidelines on sequence below to see if you can improve the sequence. Usually
an efficient sequence of requests causes efficient internal DL/I processing.
v Use the simplest call. Qualify your requests to narrow the search for DL/I, but do
not use more qualification than required.
v Use the request or sequence of requests that gives DL/I the shortest path to the
segment you want.
v Use the fewest number of requests possible in your program. Each DL/I request
your program issues uses system time and resources. You may be able to
eliminate unnecessary calls by:
– Using path requests if you are replacing, retrieving, or inserting more than one
segment in the same path. If you are using more than one request to do this,
you are issuing unnecessary requests.
– Changing the sequence so that your program saves the segment in a
separate I/O area, and then gets it from that I/O area the second time it needs
the segment. If your program retrieves the same segment more than once
during program execution, you are issuing an unnecessary request.
– Anticipating and eliminating needless and nonproductive requests, such as
requests that result in GB, GE, and II status codes. For example, if you are
issuing GNs for a particular segment type and you know how many
occurrences of that segment type exist, do not issue the GN that results in a
GE status code. You can keep track of the number of occurrences your
program retrieves, and then continue with other processing when you know
you have retrieved all the occurrences of that segment type.
– Issuing an insert request with a qualification for each parent instead of issuing
Get requests for the parents to make sure that they exist. When you are
inserting segments, you cannot insert dependents unless the parents exist. If
DL/I returns a GE status code, at least one of the parents does not exist.
v Keep the main section of the program logic together. For example, branch to
conditional routines, such as error and print routines, in other parts of the
program, instead of having to branch around them to continue normal
processing.
Except for a few commands, the program shown below applies to batch, BMP, and
CICS programs. Differences are highlighted in the notes that follow. The numbers to
the right of the sample code refer to those notes.
Except for a few commands, the program shown below applies to batch, BMP, and
CICS programs. Differences are highlighted in the notes that follow. The numbers to
the right of the sample code refer to those notes.
Except for a few commands, the program shown below applies to batch, BMP, and
CICS programs. Differences are highlighted in the notes that follow. The numbers to
the right of the program refer to those notes.
/* ************************************************************* */
/* RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS */
/* ************************************************************* */
/* */
SEGKEYA = 'A300';
EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA)
WHERE(KEYA=SEGKEYA); 6
CALL TEST_DIB;
GNPLOOP:
EXEC DLI GNP USING PCB(1) INTO(AREAG); 7
IF DIBSTAT = 'GE' THEN GO TO LOOPDONE;
CALL TEST_DIB;
GO TO GNPLOOP;
LOOPDONE:
/* */
/* ************************************************************ */
/* INSERT NEW ROOT SEGMENT */
/* ************************************************************ */
/* */
AREAA = 'DATA FOR NEW SEGMENT INCLUDING KEY';
EXEC DLI ISRT USING PCB(1) SEGMENT(SEGA) FROM(AREAA);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* RETRIEVE 3 SEGMENTS IN PATH AND REPLACE THEM */
/* ************************************************************* */
/* */
SEGKEYA = 'A200';
SEGKEYB = 'B240';
SEGKEYC = 'C241';
EXEC DLI GU USING PCB(1)
/* */
/* ************************************************************* */
/* SEND OUTPUT MESSAGE */
/* ************************************************************* */
/* */
EXEC CICS SEND MAP('SAMPMAP') MAPSET('MAPSET'); 4
EXEC CICS WAIT TERMINAL;
/* */
/* ************************************************************* */
/* COMPLETE TRANSACTION AND RETURN TO CICS */
/* ************************************************************* */
/* */
EXEC CICS RETURN; 4
/* */
/* ************************************************************ */
/* CHECK STATUS IN DIB */
/* ************************************************************ */
/* */
TEST_DIB: PROCEDURE;
IF DIBSTAT = ' ' RETURN; 10
Coding a Program in C
The following is a sample program written in C. It shows you how the different parts
of a command-level program fit together, and how the EXEC DLI commands are
coded.
Except for a few commands, the program shown below applies to batch, BMP, and
CICS programs. Differences are highlighted in the notes that follow. The numbers to
the right of the program refer to those notes.
char NEWSEGC[54];
} NEWSEG;
char OUTLINE[120]; 4
struct {
main()
{
EXEC CICS ADDRESS EIB(dfheiptr); 5
strcpy(OUTLINE,DIVIDER);
SENDLINE();
strcpy(OUTLINE,START);
SENDLINE();
/* */
/* SCHEDULE PSB */
/* */
strcpy(OUTLINE,SCHED);
SENDLINE();
EXEC DLI SCHEDULE PSB(PC3COCHD); 6
SENDSTAT();
TESTDIB();
/* */
/* ISSUE GU REQUEST */
/* */
strcpy(OUTLINE,GU1);
SENDLINE();
EXEC DLI GET UNIQUE USING PCB(2) 7
SEGMENT(SE2ORDER)
WHERE(FE2OGREF>="000000")
INTO(&GUIOA) SEGLENGTH(60);
strcpy(OUTLIN2.OUTLINA,"SE2ORDER=");
strcpy(OUTLIN2.OUTLINB,GUIOA);
SENDLIN2();
SENDSTAT();
TESTDIB();
/* */
/* ISSUE GNP REQUEST */
/* */
do {
strcpy(OUTLINE,GNP1);
SENDLINE();
SENDLIN2()
{
EXEC CICS SEND FROM(OUTLIN2) LENGTH(120);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN2) LENGTH(TLINE);
strcpy(OUTLIN2.OUTLINA,BLANK,9);
strcpy(OUTLIN2.OUTLINB,BLANK,111);
return;
}
SENDLIN3()
{
EXEC CICS SEND FROM(OUTLIN3) LENGTH(120);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN3) LENGTH(TLINE);
strcpy(OUTLIN3.OUTLINX,BLANK,9);
strcpy(OUTLIN3.OUTLINY,BLANK,6);
strcpy(OUTLIN3.OUTLINZ,BLANK,105);
return;
}
SENDSTAT()
{
strncpy(OUTLIN2.OUTLINA,BLANK,9);
strncpy(OUTLIN2.OUTLINB,BLAN2,110);
strcpy(OUTLIN2.OUTLINA," DIBSTAT=");
strcpy(OUTLIN2.OUTLINB,dibptr->dibstat);
EXEC CICS SEND FROM(OUTLIN2) LENGTH(11);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN2) LENGTH(L11);
strcpy(OUTLINE,DIVIDER);
SENDLINE();
return;
}
SENDSTT2()
{
SENDOK()
{
EXEC CICS SEND FROM(OKMSG) LENGTH(120);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OKMSG) LENGTH(TLINE);
return;
}
TESTDIB() 21
{
if (strncmp(dibptr->dibstat," ",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GK",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GB",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GE",2) == 0)
return;
else
{
EXEC CICS ABEND ABCODE("PETE"); 22
EXEC CICS RETURN;
}
return;
}
You can use CICS-supplied procedures to translate, compile, and link-edit your
program. The procedure you use depends on the type of program (batch, BMP, or
CICS online) and the language it is written in (COBOL, PL/I, or assembler
language).
For a CICS online program containing EXEC DLI commands, you must specify the
DLI and CICS options. For a batch or BMP program containing EXEC DLI
commands, you must specify the DLI option.
You can also specify the options on the EXEC job control statement that invokes
the translator; if you use both methods, the CBL and *PROCESS statement
overrides those in the EXEC statement. For more information on the translator
options, see CICS/ESA Application Programming Guide.
You must ensure that the translator options you use in a COBOL program do not
conflict with the COBOL compiler options. When you translate an IBM COBOL for
MVS & VM program, you must use the COBOL for MVS & VM translator option.
Similarly, when you translate a VS COBOL II program, you must use the COBOL II
translator option.
DEDBs provide high data availability. Each DEDB can be partitioned, or divided into
multiple “areas.” Each area contains a different set of database records. In addition,
you can make up to seven copies of each area data set. If an error exists in one
copy of an area, application programs can access the data by using another copy
of that area. This is transparent to the application program. When an error occurs to
data in a DEDB, IMS does not stop the database. It makes the data in error
unavailable, but continues to schedule and process application programs. Programs
that do not need the data in error are unaffected.
Related Reading: For more information on DEDB data sharing, see the description
of administering IMS systems that share data in IMS Version 7 Administration
Guide: System.
Figure 10. Processing a Long Chain of Segment Occurrences with Subset Pointers
Figure 11 and Figure 12 show some of the ways you can set subset pointers.
Subset pointers are independent of one another, which means that you can set one
or more pointers to any segment in the chain. For example, you could set more
than one subset pointer to a segment, as shown in Figure 11.
Alternatively, you could define a one-to-one relationship between the pointers and
the segments, as shown in Figure 12.
Figure 13 on page 94 shows how the use of subset pointers divides a chain of
segment occurrences under the same parent into subsets. Each subset ends with
the last segment in the entire chain. For example, the last segment in the subset
defined by subset pointer 1 is B7.
After the pointers are defined in the DBD and the PSB, an application program can
set the pointers to segments in a chain. When an application program finishes
executing, the subset pointers used by that program remain as they were set by the
program and are not reset.
Using the passbook account example described earlier, say that Bob Emery visits
the bank, bringing his passbook, and you want to post all the unposted
transactions. Because subset pointer 1 was previously set to the first unposted
transaction, your program could use the following command to retrieve that
transaction:
EXEC DLI GU SEGMENT(A) WHERE(AKEY = 'A1')
SEGMENT(B) INTO(BAREA) GETFIRST('1');
If the subset does not exist (subset pointer 1 has been set to zero), IMS returns a
GE status code, and your position in the database immediately follows the last
segment in the chain. Using the passbook example, the GE status code indicates
that no unposted transactions exist.
You can specify only one GETFIRST option per qualification statement; if you use
more than one GETFIRST in a qualification statement, IMS returns an AJ status
code to your program. The rules for using the GETFIRST option are:
1. You can use GETFIRST with all options except:
v FIRST
v LOCKCLASS
v LOCKED
2. Other options take effect after the GETFIRST option has, and position has been
established on the first segment in the subset.
3. If you use GETFIRST with LAST, the last segment in the segment chain is
retrieved.
4. If the subset pointer specified with GETFIRST is not set, IMS returns a GE
status code, not the last segment in the segment chain. See “Setting the Subset
Pointers with the SETZERO, MOVENEXT, SET, and SETCOND Options”
5. Do not use GETFIRST with FIRST. This causes you to receive an AJ status
code.
6. GETFIRST overrides all insert rules, including LAST.
If the current segment is the last in the chain, and you use a MOVENEXT option,
IMS sets the pointer to zero.
Figure 16. Moving the Subset Pointer to the Next Segment after Your Current Position
Figure 17. Unconditionally Setting the Subset Pointer to Your Current Position
Figure 18. Conditionally Setting the Subset Pointer to Your Current Position
100 Application Programming: EXEC DLI Commands for CICS and IMS
Processing DEDBs with Subset Pointers
Inserting Segments in a Subset
When you use the GETFIRST option to insert an unkeyed segment in a subset, the
new segment is inserted before the first segment occurrence in the subset.
However, the subset pointer is not automatically set to the new segment
occurrence. For example, the following command inserts a new B segment
occurrence in front of segment B5, but does not set subset pointer 1 to point to the
new B segment occurrence:
EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1')
SEGMENT(B) FROM(BAREA) GETFIRST('1');
To set subset pointer 1 to the new segment, you use the SET option along with the
GETFIRST option, as shown in the following example:
EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1')
SEGMENT(B) FROM(BAREA) GETFIRST('1') SET ('1');
If the subset does not exist (subset pointer 1 has been set to zero), the segment is
added to the end of the segment chain.
Combining Options
You can use the SET, MOVENEXT, and SETCOND options with other options, and
you can combine subset pointer options with each other, provided they do not
conflict. For example, you can use GETFIRST and SET together, but you cannot
use SET and SETZERO together because their functions conflict. If you combine
options that conflict, IMS returns an AJ status code to your program.
You can use one GETFIRST option per qualification statement, and one update
option (SETZERO, MOVENEXT, SET, or SETCOND) for each subset pointer.
If the area the POS command specifies is unavailable, the I/O area is unchanged
and the status code FH is returned.
To retrieve this information, you issue a POS command with a qualification statement
containing the segment name of the sequential dependent. The current position
after this kind of POS command is in the same place that it is after a GNP command.
102 Application Programming: EXEC DLI Commands for CICS and IMS
The POS Command
command with a qualification statement containing the root segment as the
segment name. The current position after this type of command follows the same
rules as position after a GU.
After a successful unqualified POS command, the I/O area contains the length (LL),
followed by as many entries as there are areas within the database. Each entry
contains the second through the fifth fields shown below:
LL A 2-byte field containing the total length of the data in the I/O area,
in binary. The length includes the 2 bytes for the LL field, plus 24
bytes for each entry.
Area Name An 8-byte field giving the ddname from the AREA statement.
Position An 8-byte field giving the next available position within the
sequential dependent part.
Unused CIs A 4-byte field containing the number of unused CIs in the sequential
dependent part.
Unused CIs A 4-byte field containing the number of unused CIs in the
independent overflow part.
104 Application Programming: EXEC DLI Commands for CICS and IMS
Chapter 6. Recovering Databases and Maintaining Database
Integrity
This chapter describes the commands you can use to help recover data accessed
by your program and maintain data integrity:
v The Basic Checkpoint command, CHKP, which you can use to issue checkpoints
from a batch or BMP program
v The Symbolic Checkpoint command, SYMCHKP, which you can use to issue
checkpoints from a batch or BMP program and to specify data areas that can be
restored when you restart your program
v The Extended Restart command, XRST, which you can use along with symbolic
checkpoints to start or restart your batch or BMP program
v The rollback commands, ROLL and ROLB, which you can use to dynamically back
out database changes from a batch or BMP program
v The managing-backout-points commands, SETS and ROLS, which you can use to
set multiple backout points and then return to these points later
v The Dequeue command, DEQ, which releases previously reserved segments
To use any of the commands, you must have defined an I/O PCB for your program,
except for the DEDB DEQ calls, which are issued against a DEDB PCB.
Related Reading: For more information on checkpoint and rollback commands, see
the description “Using the I/O PCB, PSB, and PCB” on page 11, and the manuals
IMS Version 7 Utilities Reference: System and IMS Version 7 Application
Programming: Design Guide.
Batch programs can use either the Symbolic Checkpoint or the Basic Checkpoint
command.
Both checkpoint commands make it possible for you to commit your program’s
changes to the database and to establish places from which the batch or BMP
program can be restarted, in cases of abnormal termination.
Requirement: You must not use the CHKPT=EOV parameter on any DD statement
to take an IMS checkpoint.
For examples of how to specify the SYMCHKP command, see “SYMCHKP Command”
on page 61.
Because the XRST command attempts to reposition the database, your program also
needs to check for correct position.
You can use both ROLL and ROLB in batch programs. You can only use the ROLB
command in batch programs if the system log is stored on direct access storage
and if you have specified BKO=Y in the parm field of your JCL.
Issuing either of these commands causes DL/I to back out any changes your
program has made to the database since its last checkpoint, or since the beginning
of the program if your program has not issued a checkpoint.
The SETS and ROLS commands apply only to DL/I full-function databases. Therefore,
if a logical unit of work (LUW) is updating recoverable resources other than
full-function databases (VSAM files, for example), the SETS and ROLS requests have
106 Application Programming: EXEC DLI Commands for CICS and IMS
Intermediate Backout Points
no effect on the non-DL/I resources. The backout points are not CICS commit
points; they are intermediate backout points that apply only to DBCTL resources.
Your program must ensure the consistency of all the resources involved.
SETS Command
Before initiating a set of DL/I requests to perform a function, you can use a SETS
command to define points in your application at which to preserve the state of DL/I
databases. Your application can issue a ROLS command later if it cannot complete
the function.
ROLS Command
You can use the ROLS command to back out to the state all full-function databases
were in before either a specific SETS request or the most recent commit point.
108 Application Programming: EXEC DLI Commands for CICS and IMS
Chapter 7. Using Data Availability Enhancements
Your program might fail when it receives a status code indicating that a DL/I
full-function database is unavailable. To avoid this, you can use data availability
enhancements. After a PSB has been scheduled in DBCTL, your application
program can issue requests to indicate to IMS that the program can handle data
availability status codes and to obtain information about the availability of each
database.
You can obtain the data availability status codes within the DL/I interface block
(DIB) by using the following QUERY command:
EXEC DLI QUERY USING PCB(n);
The QUERY command is used after scheduling the PSB but before making the first
database call. If the program has already issued a call using a DB PCB, then the
QUERY command must follow the REFRESH command:
EXEC DLI REFRESH DBQUERY
The REFRESH command updates the information in the DIB. You can only issue this
command one time.
For full-function databases, the DIBSTAT should contain NA, NU, TH, or blanks. For
MSDBs and DEDBs, the DIBSTAT always contains blanks.
If a CICS command language translator has been used to translate the EXEC DLI
commands, then, in addition to data availability status, the DBDNAME will be
returned in the DIB field DIBDBDNM. Also, the name of the database organization
will be returned in the DIB field DIBDBORG.
For an explanation of the codes, see “Status Code Explanations” on page 127.
Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options
Call- Level Command-Level Allows You to...
C KEYS option Use the concatenated key of a segment to identify the segment.
D INTO or FROM specified on Retrieve or insert a sequence of segments in a hierarchic path using
segment level to be only one request, instead of having to use a separate request for each
retrieved or inserted. segment. (Path call or command).
114 Application Programming: EXEC DLI Commands for CICS and IMS
Comparing Command-Level and Call-Level Programs
Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options (continued)
Call- Level Command-Level Allows You to...
F FIRST option Back up to the first occurrence of a segment under its parent when
searching for a particular segment occurrence. Disregarded for a root
segment.
L LAST option Retrieve the last occurrence of a segment under its parent.
M MOVENEXT option Set a subset pointer to the segment following the current segment.
N Leave out the SEGMENT Designate segments you do not want replaced, when replacing
option for segments you do segments after a get hold request. Usually used when replacing a path
not want replaced. of segments.
P SETPARENT Set parentage at a higher level than what it usually is (the lowest
hierarchic level of the request).
Q LOCKCLASS, LOCKED Reserve a segment so that other programs are not able to update it
until you have finished processing it.
R GETFIRST option Retrieve the first segment in a subset.
S SET option Unconditionally set a subset pointer to the current segment.
U No equivalent for command Limit the search for a segment to the dependents of the segment
level programs. occurrence on which position is established.
V CURRENT option Use the current position at this hierarchic level and above as
qualification for the segment.
W SETCOND option Conditionally set a subset pointer to the current segment.
Z SETZERO option Set a subset pointer to zero.
– No command-level Null. Use an SSA in command code format without specifying the
equivalent. command code. Can be replaced during execution with the command
codes you want.
116 Application Programming: EXEC DLI Commands for CICS and IMS
Chapter 9. DL/I Status Codes
This section contains reference information on all IMS status codes. The information
is divided into two parts:
v Status code tables
– Database Calls
– Message Calls
– System Service Calls
v Status code explanations
For information about each of the status codes, see Table 6, Table 7 on page 122,
and Table 8 on page 124.
Exception: Although the calls APSB, DPSB, and ROLL are included in Table 8 on
page 124, they do not receive status codes.
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
TERM
(ADD)
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
AB X X X X X X X X X X 4 Segment I/O area required;
none specified in call. Only
applies to full-function DEQ
calls.
AC X X X X X X 4 Hierarchic error in SSAs.
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
AD X X X X X X X X X X 4 Function parameter
incorrect. Only applies to
full-function DEQ calls.
AF X X 4 GSAM detected invalid
variable-length record.
AH X X 4 Required SSA missing.
Options list not specified in
SETO call.
AI X X X X X X 5 Data management OPEN
error.
AJ X X X X X X X X 4 Incorrect parameter format in
I/O area; incorrect SSA
format; incorrect command
used to insert a logical child
segment. I/O area length in
AIB is invalid; incorrect class
parameter specified in Fast
Path Q command code.
AK X X X X X X X 4 Invalid SSA field name.
AM X X X X X X X X 4 Call function not compatible
with processing option,
segment sensitivity,
transaction code, definition,
or program type.
AO X X X X X X X 5 I/O error: OSAM, BSAM, or
VSAM.
AT X X X 4 User I/O area too long.
AU X X X X X X 4 SSAs too long.
BA X X X X X 6 Call could not be completed
because data was
unavailable.
BB X X X X X 6 Call could not be completed
because data was
unavailable and updates are
backed out only since the
last commit point.
BC X 6 Call could not be completed
because of a deadlock
occurrence; updates are
backed out only since the
last commit point.
DA X X 4 Segment key field or
nonreplaceable field has
been changed.
DJ X 4 No preceding successful
GHU or GHN call or an SSA
supplied at a level not
retrieved.
118 Application Programming: EXEC DLI Commands for CICS and IMS
Status Code Tables
Table 6. Database Calls (continued)
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
DX X 4 Violated delete rule.
EM X Normally for a utility.
FA X X 4 MSDB arithmetic overflow
error occurred.
FC X 4 POS call for direct
dependent segments only.
FD X X X X X X X 2 Deadlock occurred.
FE X 4 FSA error, not field name.
FF X 3 No space in MSDB.
FG X 4 Combination of FE and FW
codes.
FH X X X X X X X 3 DEDB inaccessible.
FI X X X X X X X 4 I/O area not in user’s
dependent region.
FM X X X X X X 4 Randomizing routine return
code = 4.
FN X 4 FSA error, field name.
FP X X X 4 Invalid hexadecimal or
decimal data.
FR X X X X X X X X 5 Total buffer allocation
exceeded.
FS X 3 DEDB areas are full.
FT X X X X X X 4 Too many SSAs on call.
FV X 3 MSDB verify condition failed.
FW X X X X X X X X X 2 More resources needed than
normally allowed. For the
DEQ call, Fast Path was not
able to release any buffers.
FY X X X X X X X X 4 Attempt to read sequential
data preceding the current
position.
GA X X 2 Crossing hierarchical
boundary.
GB X 1 End of database.
GC X X X X 3 Crossing unit of work (UOW)
boundary.
GD X 1 Call did not have SSAs for
all levels above insert and
has lost segment position.
GE X X X X 1 Segment not found.
GG X X X 5 Segment contains invalid
pointer.
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
GK X X 2 Crossing segment
boundaries on same level.
GL X 4 Invalid user log code. Only
applies to full-function DEQ
calls.
GP X X X 4 No parentage established.
HT X Normally for a utility.
II X 3 Segment already exists.
IX X 4 Violated insert rule.
L2 X 1 The area lock failed.
LB X 1 Segment being loaded
already exists in database.
LC X 4 Key field of segments out of
sequence.
LD X 4 No parent for this segment
has been loaded.
LE X 4 Sequence of sibling
segments not the same as
DBD sequence.
LF X 4 An attempt was made to
load a logical child segment
in either a HALDB PHDAM
or PHIDAM database.
| LS X 1 Work may be backed out
| because sufficient CI space
| was not preallocated for the
| area, or the SDEP CI lock
| failed.
NA X X 6 A database was unavailable.
NE X 3 DL/I call issued by index
maintenance cannot find
segment.
NI X X X 1 Index maintenance found
duplicate segment in index.
NO X X X 5 I/O error: OSAM, BSAM, or
VSAM.
NU X X 6 A database was unavailable
for update.
OS X Normally for a utility.
RX X 4 Violated replace rule.
TH X 4 No PSB was scheduled
(command-level only).
TI X 4 Invalid path to segment
(command-level only).
120 Application Programming: EXEC DLI Commands for CICS and IMS
Status Code Tables
Table 6. Database Calls (continued)
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
X X X X X X 5 DL/I not active
(command-level only).
X X X X X X 5 Invalid system DIB
(command-level only).
TO X 4 Path replace error
(command-level only).
TP X X X X X X 4 Invalid number for PCB or
invalid processing option
(command-level only).
TR X X X X X X X X 4 CICS XDLIPRE user exit
determined the preceding
request should not be
executed.
TY X X X X X X 5 Database not open
(command-level only).
TZ X X X X X X 5 Length of segment greater
than 64 KB.
UC X 1 Checkpoint taken (Utility
Control Facility (UCF) status
code).
US X 1 Stop (UCF status code).
UX X 1 Checkpoint and stop (UCF
status code).
V1 X X X 4 Segment length not within
limits of DBDGEN.
V2 X X X X X X X X 4 Segment length invalid
(command-level only).
V3 X X X X 4 Field length missing or
invalid (command-level only).
V4 X X X X X X 4 Length of variable-length
segment invalid
(command-level only).
V5 X X X X X 4 Offset if invalid
(command-level only).
V6 X X X X X 4 Concatenated key length
invalid (command-level only).
XX X X X X 5 Internal GSAM error.
1
bb X X X X X X X X X X X X X X 1 No status code returned.
Proceed.
Note:
1. bb indicates blank.
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
AA X X 4 CHNG call for alternate response PCB can specify only
logical terminal destination; transaction code destination
specified.
AB X X X X X X X 4 Segment I/O area required; none specified in call.
AD X X X X X X X X 4 Function parameter invalid.
AH X 4 Required SSA missing. Options list not specified in SETO
call.
AJ X 4 Invalid parameter format in I/O area; invalid SSA format;
invalid command used to insert a logical child segment. I/O
area length in AIB is invalid.
AL X X X X X X X X 4 Call using I/O PCB in batch program.
AP X X X X X X X X 4 Specifying more than four user call parameters for a TP PCB
is not valid.
AR X X 4 Error in option list related to IMS option keyword.
AS X X 4 The PRTO= option contained invalid data set processing
options.
AT X X X 4 User I/O area too long.
AX X X X X 5 System error. Call not completed successfully.
AY X 4 Alternate response PCB referenced by ISRT call has more
than one physical terminal assigned for input purposes. Notify
master terminal operator.
AZ X 4 The conversational program has issued a PURG call to PCB
that cannot be purged.
A1 X X X 4 AUTH call attempted with invalid generic class name or error
occurred during attempt to set destination name specified in
the CHNG or ISRT call.
A2 X 4 Call attempted with invalid PCB (PCB not modifiable or ISRT
operation already done).
A3 X X 4 Call attempted to a modifiable TP PCB with no destination
set.
A4 X X X 4 Security violation detected during processing of either an
AUTH call, a CHNG call, or an ISRT on a conversational
response.
A5 X X 4 Format name specified on second or subsequent message
ISRT or PURG.
A6 X 4 Output segment size limit exceeded on call.
A7 X 4 Number of output segments inserted exceeded the limit by
one. Any further queue manager calls are prohibited to
prevent message queue overflow.
A8 X 4 ISRT to alternate response PCB followed ISRT to I/O PCB or
vice versa.
A9 X 4 Alternate response PCB referenced by call requires that the
source physical terminal receive the output response.
CA X 4 No such command. No command responses produced.
122 Application Programming: EXEC DLI Commands for CICS and IMS
Status Code Tables
Table 7. Message Calls (continued)
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
CB X 4 Command, as entered, not allowed for AOI. No command
responses produced.
CC X 2 Command executed. One or more command responses
produced.
CD X 4 Entered command violates security. No command responses
produced.
CE X 2 Transaction rescheduled after CMD call. Commit point had
not been reached.
CF X 2 Message on queue before IMS was last started.
CG X 2 Transaction originated from AOI exit routine.
CH X 5 AOI detected system error; CMD request not processed.
Reissue CMD call.
CI X 2 Transaction on queue before IMS last started. Transaction
rescheduled. Commit point not reached.
CJ X 2 Transaction from AOI exit routine. Message rescheduled.
Commit point not reached.
CK X 2 Transaction from AOI exit routine. Message on queue before
IMS last started.
CL X 2 Transaction from AOI exit routine. Message on queue before
IMS last started. Message rescheduled. Commit point had not
been reached.
CM X 3 Command executed. No command response produced.
CN X 4 IOASIZE= parameter on PSBGEN macro does not meet
minimum requirement for CMD call.
E1 X X 4 The DFSMSCE0 user routing exit rejected the CHNG or ISRT
call.
E2 X X 4 The DFSMSCE0 user routing exit rejected the CHNG or ISRT
call.
E3 X X 4 The DFSMSCE0 user routing exit rejected the CHNG or ISRT
call.
FF X 3 No space in MSDB.
FH X 3 DEDB inaccessible.
FI X X X 4 I/O area not in user’s dependent region.
FS X 3 DEDB areas are full.
FV X 3 MSDB verify condition failed.
MR X – Reserved
QC X 3 No more input messages exist.
QD X X 3 No more segments exist for this message.
QE X X 4 GN request before GU. GCMD request before CMD.
QF X X X X 4 Segment less than five characters (segment length is
message text length plus four control characters).
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
QH X X X X 4 Terminal symbolic error; output designation unknown to IMS
(logical terminals or transaction code). Either the message
segment LL is not at least 5 bytes or the destination name in
I/O area is blank or invalid.
TG X 4 No PSB was scheduled (command-level only).
X 5 Invalid system DIB (command-level only).
TP X 4 Invalid number for PCB or invalid processing option
(command-level only).
TY X 5 Database not open (command-level only).
TZ X 5 Length of segment greater than 64 KB.
XA X 4 Attempt to continue processing the conversation by passing
SPA by a program-to-program switch after answering
terminal.
XB X 4 Program passed SPA to other program, but trying to respond.
XC X 4 Program inserted message with Z1 field bits set. These bits
are reserved for system use.
XE X 4 Tried to ISRT SPA to express PCB.
XF X X 4 Alternate PCB specified in ISRT call for SPA had destination
set to a logical terminal, but was not defined as
ALTRESP=YES. MSC direct routing does not support
program-to-program switch between conversational
transactions.
XG X 4 Current conversation requires fixed-length SPAs. Attempt was
made to insert SPA to transaction with a different or nonfixed-
length SPA.
X2 X X 4 First insert to transaction code PCB that is conversational is
not a SPA.
X3 X 4 Invalid SPA.
X4 X 4 Insert to a transaction code PCB that is not conversational
and the segment is a SPA.
X5 X 4 Insert of multiple SPAs to transaction code PCB.
X6 X 4 Invalid transaction code name inserted into SPA.
X7 X 4 Length of SPA is incorrect (user modified first 6 bytes).
1
bb X X X X X X X X X 1 No status code returned. Proceed.
Note:
1. bb indicates blank.
PCB
CHKP
ROLB
SYNC
ROLS
SNAP
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
1
124 Application Programming: EXEC DLI Commands for CICS and IMS
Status Code Tables
Table 8. System Service Calls (continued)
Category
PCB
CHKP
ROLB
SYNC
ROLS
SNAP
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
AC X 4 Hierarchic error in SSAs.
AD X X X X X X X X X X X 4 Function parameter invalid.
AG X 4 Partial data return. I/O area too small.
AJ X X X 4 Invalid parameter format in I/O area;
invalid SSA format; invalid command
used to insert a logical child segment.
I/O area length in AIB is invalid.
AL X X X 4 Call using I/O PCB in batch program.
AP X 4 More than 4 user call parameters for a
TP PCB are invalid.
AQ X 4 Invalid subfunction code.
AT X 4 User I/O area too long.
BJ X 6 All of the databases included in the
PSB are unavailable or no database
PCBs are in the PSB.
BK X 6 At least one of the databases included
in the PSB is unavailable or has
limited availability, or at least one PCB
received an NA or NU status code.
FA X X 4 MSDB arithmetic overflow error
occurred.
FD X X 3 Deadlock occurred.
FF X 3 No space in MSDB.
FH X X 3 DEDB inaccessible.
FI X X 4 I/O area not in user’s dependent
region.
FS X X 3 DEDB areas are full.
FV X X 3 MSDB verify condition failed.
GA X 2 Crossing hierarchic boundary.
GE X X X 1 Segment not found.
GL X 4 Invalid user log code.
NA X 6 A database was unavailable.
NL X 4 XEFRDER card not provided. Please
supply one.
NU X 6 A database was unavailable for
update.
QC X 3 No more input messages exist.
QE X X 4 GN request before GU. GCMD request
before CMD.
QF X 4 Segment less than five characters
(segment length is message text
length plus four control characters).
Category
PCB
CHKP
ROLB
SYNC
ROLS
SNAP
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
RA X 4 Token does not match one for a SETS,
or the PCB did not get BA or BB on
last call.
RC X 4 ROLS call issued with unsupported
PCBs in the PSB, or the program is
using an attached subsystem.
SA X 5 Insufficient space.
SB X 4 Would exceed maximum number of
levels allowed.
SC X X 5 A SETS/SETU call was issued with
unsupported PCBs in the PSB, or the
program is using an attached
subsystem.
SY X 5 Internal error during sync-point
processing for an IMS/Java
application.
TA X 5 PSB not in PSB directory
(command-level only).
TC X 4 PSB already scheduled
(command-level only).
TE X 5 PSB initialization failed
(command-level only).
TJ X 5 DL/I not active (command-level only).
TL X 4 Conflict in scheduling intent
(command-level only).
TN X X X X X X X 5 Invalid system DIB (command-level
only).
TP X X 4 Invalid number for PCB or invalid
processing option (command-level
only).
TR X X X X 4 CICS XDLIPRE user exit determined
the preceding request should not be
executed.
TY X X 5 Database not open (command-level
only).
TZ X X 5 Length of segment greater than 64 KB.
V2 X 4 Segment length invalid
(command-level only).
V7 X 4 Statistics area length invalid
(command-level only).
XD X X 1 IMS terminating. Further DL/I calls
must not be issued. No message
returned.
bb3 X X X X X X X X X X X X X 1 Good. No status code returned.
Proceed.
126 Application Programming: EXEC DLI Commands for CICS and IMS
AA • AD
Table 8. System Service Calls (continued)
Category
PCB
CHKP
ROLB
SYNC
ROLS
SNAP
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
Notes:
1. SNAP is a Product-sensitive programming interface.
2. STAT is a Product-sensitive programming interface.
3. bb indicates blank.
All explanations apply to both DL/I call (call-level) programs and EXEC DLI
(command-level) programs except where split. The term “request” means call,
command, or both.
AC AD
Explanation: Explanation:
For call-level programs: For call-level programs:
An error is in an SSA for a DLET, Get, ISRT, or REPL call Either the function parameter on the call is invalid or the
for one of these reasons: function is not supported for the type of PCB specified
v DL/I could not find a segment in the DB PCB in the call. Only applies to full-function DEQ calls. Some
specified in the call that has the segment name given possible reasons are:
in the SSA. v The function parameter is invalid.
v The segment name is in the DB PCB, but the SSA v A system service call used a PCB that is not the I/O
specifying that segment name is not in its correct PCB.
hierarchic sequence.
v The call specifies two SSAs for the same hierarchic
level. 1. STAT is a Product-sensitive programming interface.
v Referencing an I/O PCB for a database command, or v The data set OPEN request did not specify load
not defining an I/O PCB before issuing system mode, but the data set was empty. An empty data set
service commands. requires the load option in the PCB.
v A command issued in a DCCTL environment referred v The buffer is too small to hold a record that was read
to an unsupported database or DB PCB. at open time.
v No DD statements or DFSMDA members were
Programmer Response: Be sure that the specified supplied for logically related databases.
function is valid for the PCB specified by the request.
v For an OSAM data set, the DSORG field of the
OSAM DCB, DSCB, or JFCB does not specify PS or
AF DA.
Explanation: GSAM detected a variable-length record v For an old OSAM data set, the BUFL or BLKSIZE
whose length is invalid on a GU, GHU, GN, or GHN call. field in the DSCB is 0.
v The data set is being opened for load, and the
Programmer Response: Correct the program.
processing option for one or more segments is other
than L or LS.
AG v The allocation of the OSAM data set is invalid. The
Explanation: During INQY call processing, the I/O area allocation is probably (1,1), rather than (1,1) and this
was not large enough to contain all the output data. The causes the DSORG to be P0.
I/O area was filled with partial data, as much as would v The processing option is L, the OSAM data set is old,
fit in the area provided. AIBOALEN contains the actual and the DSCB LRECL, BLKSIZE, or both, does not
length of the data returned to the application and match the DBD LRECL, BLKSIZE, or both.
AIBOAUSE contains the output area length that is v Incorrect or missing information prevented IMS from
required for the application program to receive all the determining the block size or the logical record
data. length.
Programmer Response: Correct the application v A catalog was not available for accessing a VSAM
program by using a larger I/O area. The minimum size database that was requested.
of the I/O area is the value contained in the AIBOAUSE v OS could not perform an OPEN, but the I/O request
field. is valid. Either the data definition information is
incorrect, or information is missing.
v RACF was used to protect the OSAM data set, and
the control region has no update authorization.
128 Application Programming: EXEC DLI Commands for CICS and IMS
AJ • AK
If IMS returns message DFS0730I, you can determine number, or you included an invalid character. The
the cause of the OPEN failure from this message in the number following the command code must be
job log. For more information, see the description of this between 1 and 8, inclusive.
message in IMS Version 7 Messages and Codes, v The SSA included more than one R command code.
Volume 2. An SSA can include only one R command code.
Programmer Response: These kinds of problems v The specified size for the SSA is too small. After this
often require the help of a system programmer or status code is returned, your position in the database
system administrator. But before you go to one of these is unchanged.
specialists, some things you can do are: v In response to a SETS or ROLS call, the length of the
v Check the DD statements. Make sure that the I/O area is 0, the LL field is less than 4, or the ZZ
ddname is the same as the name specified on the field is not 0.
DATASET statement of the DBD. The segment name v In response to an INIT call, the format of the I/O area
area in the DB PCB (call level), or in the DIB is incorrect.
(command level) has the ddname of the data set that
v For calls that provide the length of the I/O area in the
could not be opened.
AIB, such as INQY, the I/O area length is invalid.
v Check the PSB and make sure that the appropriate
v For SETO, I/O area length is less than 4096 or less
processing options have been specified for each of
than the minimum.
the DB PCBs that your program uses.
v For the Q command code, the specified lock class is
not a letter (A-J).
AJ
Explanation: For call-level programs: For command-level programs:
For calls that provide parameters in the I/O area, such An ISRT command attempted to insert a logical child
as SETS, ROLS, and INIT, the format of the parameters segment using a path command. ISRT commands for
in the I/O area is invalid. logical child segments cannot be path commands.
For database calls that include SSAs, such as Get, Programmer Response:
DLET, REPL, and ISRT, the format of one of the SSAs is
invalid. The number in the segment level number field of If you receive this status code on a SETS, ROLS, or INIT
the DB PCB is the level number of the SSA that is request, correct the parameters provided in the I/O
invalid. Some possible reasons for the invalid SSA area.
format are:
If you receive this status code on a Get, DLET, REPL, or
v The SSA contains a command code that is invalid for ISRT request, correct the invalid portion of the SSA. If
that call. you receive this status code on a GSAM call, correct
v The relational operator in the qualification statement the RSA.
is invalid.
v A qualification statement is missing a right AK
parenthesis or a Boolean connector.
Explanation: For call-level programs:
v A DLET call has multiple or qualified SSAs.
v A REPL call has qualified SSAs. An SSA contains an invalid field name, or the field
name is not defined in the DBD. The number in the
v An ISRT call has the last qualified SSA.
segment level number field of the DB PCB is the level
v An ISRT call that inserts a logical child segment into number of the SSA that contains the invalid name.
an existing database includes the D command code.
ISRT calls for logical child segments cannot be path You can also receive this status code if the program is
calls. accessing a logical child through the logical parent. DL/I
returns AK if the field specified in the qualification has
v The RSA parameter on a GSAM call is invalid.
been defined for the logical child segment, and it
v The SSA used an R, S, Z, W, or M command code includes (at least partially) the portion of the logical child
for a segment for which no subset pointers are that contains the concatenated key of the logical parent.
defined in the DBD.
When you are using field-level sensitivity, a field you
v The subset command codes included in the SSA are
specified in the SSA has not been defined in the PSB.
in conflict; for example, if one SSA contained an S
After this status code is returned, your position in the
status code and a Z status code, Fast Path would
database is unchanged.
return an AJ status code. S means to set the pointer
to current position; Z means to set the pointer to 0. For command-level programs:
You could not use these status codes in one SSA.
A WHERE option contains an invalid field name. (The
v The pointer number following a subset pointer field name is not defined in the DBD.) The number in
command code is invalid. Either you did not include a the DIBSEGLV field of the DIB is the level number of
130 Application Programming: EXEC DLI Commands for CICS and IMS
AO • AX
v If you issue a DLET, REPL, or ISRT command for a
AQ
segment to which the program is not sensitive.
v If you issue a CHKP command if a GSAM or VSAM Explanation: The AIB contains an invalid subfunction,
data set is open for output. or the INQY call specifies an invalid function.
v If you issue a GSAM call with an invalid call function Programmer Response: Specify a valid subfunction.
code. Valid INQY call subfunctions are null, DBQUERY,
v If you issue an ISRT or DLET command for the index ENVIRON, FIND, or PROGRAM.
target segment, or a segment in the physical
database on which the index target is dependent, AR
while using an alternate processing sequence.
Explanation: The options list contains an error that is
v If you issue a path replace where the program does
related to a keyword. The feedback area, if one is
not have replace sensitivity, command code N is not
provided, will contain additional error information.
specified, and the data for the segment is changed in
the I/O area. Programmer Response: Correct the request.
v If you issue a call to a GSAM dummy data set. Any
call to a GSAM dummy data set is invalid. AS
Programmer Response: Correct the request, or make Explanation: An IAFP specific processing error has
the necessary changes in the PCB. occurred. The PRTO= option contained invalid data set
processing options. The feedback area, if provided, will
AO contain additional error information.
Explanation: A BSAM, GSAM, VSAM, or OSAM Programmer Response: Correct the request.
physical I/O error occurred. When issued from GSAM,
this status code means that the error occurred when: AT
v A data set was accessed.
Explanation: The length of the data in the program’s
v The CLOSE SYNAD routine was entered. The error I/O area is greater than the area reserved for it in the
occurred when the last block of records was written control region. The length of the area reserved is
prior to the closing of the data set. defined by the ACB utility program, DFSUACB0, and is
printed as part of its output.
IMS does not return an AO status code for write errors
with BSAM, VSAM, and OSAM. Programmer Response: If the program is in error,
correct the program. If the program is correct, reserve a
If your program receives this status code after issuing a larger control region by specifying parameters on the
call, this call does not cause the database to be PSBGEN statement of PSBGEN.
stopped.
Programmer Response: Determine whether the error AU
occurred during input or output, and correct the Explanation: The total length of the SSAs in the
problem. These problems usually require the help of a database call is greater than the area reserved for them
system programmer or system administrator. in the control region. The length of the area reserved is
defined by the ACB utility program, DFSUACB0, and
AP printed as part of its output. After this status code is
returned, your position in the database is unchanged.
Explanation: A message or CHKP call is invalid
because more than four parameters (or five if a Programmer Response: If the program is in error,
parameter count is specified) are in a message call or a correct the program. If the program is correct, increase
CHKP call issued in a transaction-oriented BMP. The the PSB SSA space defined in the PSBGEN.
following exceptions apply:
v A batch-oriented BMP can issue a CHKP call with AX
more than 4 (or 5) parameters.
Explanation: A failure to get CSA storage, a failure of
v One parameter after the I/O area parameter is the DFSLUMIF call, or a processing error with the IAFP
allowed in order for the application program to specify Spool API occurred. When this code is returned,
a MOD name in an ISRT call. It is counted towards diagnostic information is written to the log in a '67D0'
the maximum of four (or five) parameters. log record. Spool API processing errors return a
Programmer Response: Correct the call. DFS0013E message.
A RACROUTE REQUEST=VERIFY,EVIRON=CREATE
Programmer Response: Correct the PURG or ISRT call. Explanation: The program issued a CHNG call
against an invalid PCB. The PCB was invalid for one of
these reasons:
A1 v It was not an alternate PCB.
Explanation: IMS returns the A1 status code for one v It was an alternate PCB, but it was not modifiable.
of the following reasons: v It was being used to process a message and had not
v AUTH call for LU 6.2 input did not find a PST LU 6.2 completed processing it.
extension block or did not find a UTOKEN.
Programmer Response: Check the PCB that was
v CHNG call against alternate response PCB when the used by the CHNG call and determine which PCB should
application program has not yet issued a GU. have been used for the call.
v The MSC program routing exit routine (DFSCMPR0)
was called while processing a CHNG call and one of
the following occurred: A3
– The exit routine rejected the call by returning with Explanation: The program issued an ISRT or PURG call
return code 8 (A1 status code). that referenced a modifiable alternate PCB that did not
– The exit routine returned with a RC=4 to route the have its destination set. IMS returns this status code to
message back to the originating system; however, PURG calls only when the PURG call specified an I/O area
as one of the parameters.
132 Application Programming: EXEC DLI Commands for CICS and IMS
A4 • BA
Programmer Response: Issue a CHNG call to set the | prohibited the insert to prevent the message queue
destination of the modifiable alternate PCB, and then | data sets from overflowing. However, the ISRT is not
reissue the ISRT or PURG call. | ignored for the message in progress when the
| DFSQSPC0 threshold is exceeded. The in-progress
| message will be processed. Any subsequent ISRTs
A4
| are ignored.
Explanation: A security violation was detected during v The IMS queue manager or user Queue Manager
processing of an AUTH, CHNG, or ISRT call of a SPA on a Space Notification exit routine (DFSQSPC0)
conversational response. Some of the reasons for this prohibited the insert because the destination
status code are: TRANSACTION or LTERM was stopped.
v Transaction authorization is active and either RACF
Programmer Response: Check the output messages
or a transaction authorization exit routine returned a
and correct them. Use ROLB or another method to free
nonzero return code.
buffer space.
v The user is not authorized for access to the
RESOURCE name in the class requested in the
AUTH call. No installation data is returned. A8
v No source CNT is available, which might be caused Explanation: IMS ignored an ISRT call because:
by the application program not having issued a GU. v An ISRT call to an alternate response PCB must not
v A program-to-program message switch is being done. follow an ISRT call to the I/O PCB.
In this case, the applicable authorization LTERM is v An ISRT call to the I/O PCB must not follow an ISRT
based on the original message, and this authorization call to an alternate response PCB.
does not allow this function to be performed.
Programmer Response: Correct the ISRT call.
Programmer Response: Check the transaction code
to make sure it was entered correctly. If it was, check
with the person who handles security at your A9
installation. Explanation: IMS ignored the ISRT call because:
v The ISRT call referenced an alternate response PCB
A5 defined as SAMETRM=YES, but the PCB
represented a logical terminal that is not part of the
Explanation: An ISRT or PURG call supplied an invalid
originating physical terminal. An alternate response
parameter list. The call supplied the fourth parameter
PCB defined as SAMETRM=YES must represent the
(the MOD name), but the ISRT or PURG being issued was
same physical terminal as the physical terminal
not for the first segment of an output message.
associated with the originating logical terminal.
Programmer Response: Correct the ISRT or PURG call. v The originating terminal is in response mode, and the
alternate response PCB is not associated with that
A6 logical terminal.
Explanation: For a message processing program IMS does not return this status code if the program
(MPP or BMP), IMS ignored a message ISRT call makes either of these errors while communicating with a
because the length of the message segment being terminal in a remote IMS system through MSC.
inserted exceeds the size specified in the SEGSIZE
keyword of the TRANSACT macro. For a Fast Path Programmer Response: Determine whether the
program (IFP), the length of the output message to a application program is in error, the output logical
Fast Path terminal exceeds the size specified in the terminal has been incorrectly reassigned (using the
FPBUF parm of the TERMINAL macro. /ASSIGN command), or if SAMETRM=YES should not
have been specified for the alternate response PCB.
Programmer Response: Correct the output message
segment.
BA
All database resources that were allotted up to the last Explanation: The command that was entered on the
commit point are backed out, with the exception of CMD call violates security, or the application program is
GSAM and DB2. All output messages are backed out to not authorized to issue CMD calls. IMS does not execute
the last commit point. Input messages are requeued. the command or return any command responses.
134 Application Programming: EXEC DLI Commands for CICS and IMS
CE • DJ
CE CK
Explanation: IMS rescheduled the message that this Explanation: CK is a combination of CF and CG. The
GU call retrieved since the last CMD call. The program message retrieved with this GU originated from an AOI
had not reached a commit point when the message was user exit. The message was scheduled for transmission
rescheduled. before IMS was last started.
Programmer Response: This is an information-only Programmer Response: This is an information-only
status code. status code.
CF CL
Explanation: The message being returned on the GU Explanation: CL is a combination of CE, CF, and CG.
call was received by IMS before the start of this IMS Please see the explanations of those codes.
execution. CF can be received on a CHKP call when an
Programmer Response: This is an information-only
I/O area is specified for an MPP or message-oriented
status code.
BMP. This occurs when a CHKP call issues an internal GU
call.
CM
Programmer Response: This is an information-only
status code. Explanation: The command that was entered on the
CMD call has been executed and completed, but it
resulted in an exception response that could not be built
CG
because of an insufficient amount of general work area
Explanation: The message retrieved by this GU (WKAP).
originated from an AOI exit routine.
Programmer Response: Increase WKAP if you want
Programmer Response: This is an information-only retrieval of the response.
status code.
CN
CH
Explanation: The IOASIZE= parameter that was
Explanation: IMS ignored the CMD call just issued specified on the PSBGEN macro is defined for less than
because the AOI command interface detected a system the required minimum for CMD calls (132 bytes).
error and was unable to process the command. IMS
Programmer Response: Redefine IOASIZE=
processing continues.
parameter on the PSBGEN for a minimum of 132 bytes.
Programmer Response: Reissue the command.
DA
CI
Explanation: The program issued a DLET or REPL that
Explanation: CI is a combination of CE and CF. The tried to modify the key field in the segment or, when
message retrieved by this GU was scheduled for using field-level sensitivity, a REPL call tried to modify a
transmission before IMS was last started. The message field that had REPL=NO specified on the SENFLD
was rescheduled, but the program had not reached a STMT in the PSB. You cannot change a segment’s key
commit point. field.
Programmer Response: This is an information-only Programmer Response: Correct the request.
status code.
DJ
CJ
Explanation: The program issued a DLET or REPL call
Explanation: CJ is a combination of CE and CG. The that was rejected because the segment was not
message retrieved by this GU was scheduled for currently in hold status. Some possible reasons for this
transmission before IMS was last started. The message status code are:
originated from an AOI exit routine. v The segment had not been previously retrieved with
Programmer Response: This is an information-only a Get Hold call.
status code. v The segment was already deleted using this PCB.
After one Get Hold call, multiple REPL calls or a DLET
call following a REPL call are valid, but multiple DLET
calls are not.
136 Application Programming: EXEC DLI Commands for CICS and IMS
FE • FN
Your position in the database is before the first root in
FE
the next area. A GN will get the next available record
Explanation: IMS returns this status code any time a (unless that one is also inaccessible).
program issues a FLD call that receives a nonblank
If a program has access to an area through a PCB with
status code in the FSA.
PROCOPT=H and another PCB without PROCOPT=H,
Programmer Response: See “Fast Path Databases” it is possible that only calls to the PCB with
in IMS Version 7 Application Programming: Database PROCOPT=H will receive the FH status code. This is
Manager for an explanation of FSA status codes and because the area is accessible to IMS, but the required
correct the FLD call. HSSP (high-speed sequential processing) setup could
not be established. Message DFS0533A explains the
reason for this occurrence and is sent to the job log.
FF
This status code is also returned if the PROCOPT for
Explanation: A program issued an ISRT call against one PCB is more restrictive than the PROCOPT of a
an MSDB that has no free space. If IMS determines that different PCB in the same PSB. Position is set to the
there is no free space when the program issues the beginning of the next accessible area.
ISRT call, the program receives the FF status code for
Rather than having an abnormal termination occur, this
that call. IMS might not determine this until the program
status code is returned to the application program that
reaches the next commit point. In this case, IMS returns
issued the EXEC DLI command.
FF when the program issues a GU call to the message
queue, a SYNC call, or a CHKP call, depending on which Programmer Response: If the data in the area is
call caused the commit point. important, contact the DBA. If the data in the area is
unimportant, the program should roll back the changes.
Programmer Response: To avoid this situation,
Your program can continue processing with the next
specify more space for the MSDB at the next system
available area.
start (cold start or normal restart).
If the status code is related to an HSSP setup problem,
fix the error as described in the message DFS0533A in
FG
the job log.
Explanation: FG is a combination of FE and FW. A
batch-oriented BMP issued a FLD call that received a
FI
nonblank status code in the FSA, and the program has
depleted its normal buffer allocation. Explanation: The program’s I/O area is not at a
storage address that the program can access.
Programmer Response: Check the FSA status code
and correct the FLD call, and then issue SYNC or CHKP Programmer Response: Correct the program.
calls in the program more frequently. One way to handle
this status code is to branch to an error routine that
FM
causes the program to issue SYNC or CHKP calls more
frequently when it receives this status code. Explanation: The application program issued a
request for which the randomizing routine returned a
return code of 4.
FH
| The key supplied on a DL/I call to a HALDB was greater
Explanation: A DEDB area was inaccessible to the
| than the high key value for the last partition. Or the
requested service when the program issued a database
request or when the program reached a commit point.
| user’s partition selection exit returned with RC=04 after
The AREA was stopped or the DEDB randomizing
| having been passed a key value with which to select a
routine was not loaded into storage. A /START
| partition.
DATABASE dedbname command will cause the DEDB Rather than having an abnormal termination occur, this
randomizing routine to be reloaded. status code is returned to the application program that
issued the EXEC DLI command.
If IMS returns this status code on a call that caused a
commit point to occur (a SYNC call, a message GU, a Programmer Response: The database position has
CHKP request, or a SYMCHKP command), IMS issues not changed. The application program must determine
an internal ROLB call to eliminate the program’s database subsequent processing.
updates and message output created since the last
commit point.
FN
If your program is accessing a DEDB in a data-sharing
environment, and if the authorization fails when your Explanation: The program issued a FLD call that
program issues its first DL/I call to the DEDB, Fast Path contains a field name in the FSA that is not defined in
returned this status code. Fast Path also notified the the DBD. IMS does not continue processing the FLD call
master terminal operator of the authorization failure. or any of the FSAs in the FLD call. IMS returns an FN
FS
FW
Explanation: For a root segment or direct dependent
Explanation: A BMP has used all buffers that are
segment, this status code is returned only to BMPs. For
allocated for normal use, or all buffers have been
a sequential dependent segment, this status code can
modified. IMS returns this status code to warn you that
be returned to either a BMP or a message-driven
you might be running out of buffer space. An FR status
program:
code might be imminent.
v A BMP issued an ISRT request for a root segment, a
direct dependent segment, or a sequential dependent If you have been processing a DEDB, you get FW for
segment, but IMS could not get enough space in requests that change data.
either the root-addressable or sequential dependent If you have been processing an MSDB, you get FW for
part of the DEDB area to insert the new segment: all calls that change data and for GH calls.
138 Application Programming: EXEC DLI Commands for CICS and IMS
FY • GD
With a DEQ call, you receive this code if no buffers can v An unqualified GN call
be released. v A qualified GN call without a maximum key (if no data
Rather than having an abnormal termination occur, this is returned to the I/O area)
status code is returned to the application program that
issued the EXEC DLI command. In contrast, a GE status code, instead of a GB status
code, can be returned for:
Programmer Response: You can supply an
v A GU call
error-handling routine, triggered by the FW status code,
that will cause your program to issue SYNC calls, CHKP v A qualified GN call without a maximum key (if data is
requests, or SYMCHKP commands as soon as an FW returned to the I/O area)
status code is returned to your program. This reduces v A qualified GN call with a maximum key
the total buffer requirement. To avoid receiving the FW
status code, issue SYNC or CHKP calls more frequently. IMS also returns this status code when it has closed a
GSAM data set. The assumed position for a subsequent
FY request for a GSAM or full-function database is the
beginning of the database, or if a SETR statement was
Explanation: PROCOPT=H PCBs process segments used for a DEDB database, the beginning of the current
sequentially in the forward direction. Position is range.
established on a UOW and is moved forward only.
Attempts to retrieve segments prior to the current UOW Rather than having an abnormal termination occur, this
position are not allowed for HSSP application programs status code is returned to the application program that
and will not be processed; they receive this status code. issued the EXEC DLI command.
Programmer Response: Change the application Programmer Response: User determined.
program to retrieve segments in a forward direction
only; use a PCB with a PROCOPT value other than H
to access the segments in the backward direction. GC
Explanation: An attempt was made to cross a
GA unit-of-work (UOW) boundary, or an area boundary in
the case of PROCOPT=H. For a batch-oriented BMP
Explanation: In trying to satisfy an unqualified GN or PCB with PROCOPT=H or PROCOPT=P, at least one
GNP call, IMS crossed a hierarchic boundary into a call on the referenced PCB changed position in the
higher level. database since the last commit process or after the
If IMS returns GA after a STAT2 request, it means that program began executing. IMS did not retrieve or insert
the request that was just issued retrieved the total a segment. Position is before the first segment of the
statistics for all the VSAM buffer subpools. following UOW.
Rather than having an abnormal termination occur, this Rather than having an abnormal termination occur, this
status code is returned to the application program that status code is returned to the application program that
issued the EXEC DLI command. This call results in a issued the EXEC DLI command.
return code of 0. Programmer Response: User determined. However, if
Programmer Response: This status code is an the GC status code results from a call that referred to a
information-only status code. PCB with PROCOPT=H, the program must cause a
commit process before any other call can be issued for
that PCB. Failure to do so results in an FR status code.
GB
Explanation: In trying to satisfy a GN call, DL/I reached GD
the end of the database or, if you used a SETR
statement, the end of the current range. In this situation, Explanation: The program issued an ISRT call that
the SSA for the call or qualification for the command was not qualified for all levels above the level of the
specified data beyond the last occurrence, and the segment being inserted. For at least one of the levels
search was not limited to the presence of a known or for which no qualification was specified, a prior request
expected segment occurrence. using this PCB established valid position on a segment.
That position is no longer valid for one of these
For example, a GN call was specified for a key greater reasons:
than a particular value, rather than a GU call specifying a v The segment has been deleted by a DLET call using a
key value beyond the highest value. different DB PCB.
A GB status code can be returned for:
v A nonmessage driven BMP issued a FLD call to an Programmer Response: Continue processing with
MSDB segment. After the FLD call but before a another segment or terminate the program. The request
commit point, the MSDB segment was deleted. GE that resulted in the GG status code might be successful
can be returned for this reason after either a SYNC or if you issue it again.
a CHKP call.
GK
For command-level programs:
v DL/I is unable to find a segment that satisfies the Explanation: DL/I has returned a different segment
segment described in a Get command. type at the same hierarchic level for an unqualified GN or
GNP call.
v For an ISRT command, DL/I cannot find one of the
parents of the segment you’re inserting. Rather than having an abnormal termination occur, this
v The program issued a STAT command for ISAM or
3 status code is returned to the application program that
OSAM buffer pool statistics, but the buffer pool does issued the EXEC DLI command. This call results in a
not exist. return and reason code of 0.
v The program issued a STAT call for 3 VSAM buffer Programmer Response: This is an information-only
subpool statistics, but the subpools do not exist. status code.
140 Application Programming: EXEC DLI Commands for CICS and IMS
GP • L2
For command-level programs: the second segment of this type for that parent, or it
is the second HDAM or PHDAM root for one anchor
EXECDLI returns a GL status for either a GN, GNP, GU, or
point.
DEQ command when the alphabetic character coded on
the LOCKCLASS option is not within the range of B to v The segment being inserted is in an inverted
J. An ABENDU1041 is then issued. structure. (The immediate parent of this segment in
the logical structure is actually its physical child in the
Programmer Response: Correct the log code, which physical structure.)
is the first byte of the log message.
v A physically paired logical child segment already
For call-level programs: exists with a sequence field equal to that of the
segment you’re inserting. For example, the segment
If the program received this status code for a DEQ could have been inserted with no duplication, but
request, check the DEQ class code in the I/O area. when an attempt was made to position for the insert
For command-level programs: of its physical pair, the segment had a duplicate key
to an existing twin segment.
Check the alphabetic character coded for class on the
v An application program inserted a key of X'X’FF...FF’'
LOCKCLASS option to ensure that it is in the range
into a HISAM, HIDAM, or PHIDAM database.
from B to J.
Rather than having an abnormal termination occur, this
GP status code is returned to the application program that
issued the EXEC DLI command.
Explanation: The program issued a GNP when there is
no parentage established, or the segment level Programmer Response: User determined.
specified in the GNP is not lower than the level of the
established parent.
IX
Programmer Response: Make sure you have
established parentage before issuing GNP, and check Explanation: The program issued an ISRT call that
the segment level specified by the GNP. violated the insert rule for that segment. Some of the
reasons that IMS returns this status code are:
v The program tried to insert the logical child and
HT logical parent, and the insert rule for the logical
Explanation: The HT status indicates that the parent is physical and the logical parent does not
High-Water-Mark time stamp (HWM TS) is less than the exist.
Logical Begin time stamp (LB TS). v The program tried to insert the logical child and the
logical parent, and the insert rule is logical or virtual
Programmer Response: The time stamp in the
and the logical parent does not exist. In the I/O area,
High-Water-Mark segment was not updated on the area
the key of the logical parent does not match the
data set during utility setup and partner notification.
corresponding key in the concatenated key in the
Check whether the data-sharing partner is still running.
logical child.
The RLM may have a lock for the sequential dependent
CI. v The program tried to insert a logical child, and the
insert rule of the logical parent is virtual and the
logical parent exists. In the I/O area, the key in the
II logical parent segment does not match the
Explanation: The program issued an ISRT call that corresponding key in the concatenated key in the
tried to insert a segment that already exists in the logical child.
database. Current position after an II status code is just v The program tried to insert a physically paired
before the duplicate of the segment you tried to insert. segment, where both sides of the physical pair are
Some of the reasons for receiving this status code are: the same segment type and the physical and logical
v A segment with an equal physical twin sequence field parent are the same occurrence.
already exists for the parent. v The program issued an ISRT call to a GSAM
v A segment with an equal logical twin sequence database after receiving an AI or AO status code.
already exists for the parent. Programmer Response: Correct the ISRT or the
v The logical parent has a logical child pointer, the program.
logical child does not have a logical twin pointer, and
the segment being inserted is the second logical child
| L2
for that logical parent.
v The segment type does not have physical twin | Explanation: The application program needed to
forward pointers and the segment being inserted is | allocate SDEP CI RBAs to contain the application
| programs’ insert activity for a particular AREA in the
| DEDB, but the request to acquire the AREA lock failed.
Explanation: The key field of the segment being A request made using this PCB will probably result in a
loaded is out of sequence. BA status code if the INIT STATUS GROUPA has been
issued or in a DFS3303I message and 3303 pseudo
Programmer Response: Check the segment and abend if it has not. An exception is when the database
determine where it should be loaded. is not available because dynamic allocation failed. In
this case, a request results in an AI (unable to open)
LD status code.
Explanation: No parent has been loaded for the Programmer Response: This is an information-only
segment being loaded. status code.
142 Application Programming: EXEC DLI Commands for CICS and IMS
NI • QC
message was deleted. If this is not the case, check the issued or in a DFS3303I message or 3303 pseudo
cause for the index inconsistency with the database and abend if it has not. If the unavailable database is only
correct it. required for delete processing, it is possible that the
ISRT and REPL requests can be processed.
NI Programmer Response: This is an information-only
status code.
Explanation: There is a duplicate segment in a unique
secondary index. While IMS was inserting or replacing a
source segment for a secondary index defined with a OS
unique sequence field, the insertion of the secondary
Explanation: The OS status indicates that the
index segment was attempted but was unsuccessful
STOPRBA parameter value given for the DEDB
because an index segment with the same key was
Sequential Dependent Scan Utility is too large for the
found. One possible cause for a duplicate segment in
current sequential dependent CI set.
the index is that the index DBD incorrectly specified a
unique key value—secondary index only. Programmer Response: Check the parameter value
for validity and use a correct value or use the utilities
In an online application program, the call is backed out
default value for the scan end.
and the program receives an NI status code.
For a batch program that does not log to the IMS DASD
QC
log, IMS abnormally terminates the program with a
U0828 abend. You should run batch backout. Explanation: There are no more messages in the
queue for the program. The reasons that IMS returns
Programmer Response: The response is determined
this status code are:
by the user. If duplicate secondary index entries occur,
specify the index as non unique, and provide an v An application program issued a successful CHKP call,
overflow entry-sequenced data set. but the message GU call issued internally by the CHKP
call was unsuccessful (that is, it did not return a
message).
NL
v An application program processing APPC
Explanation: The application program issued an synchronous messages that does not set sync points
extended checkpoint call. Checkpoint information is for each message GU call (that is, mode=MULT on the
written to the log data set, but there is no DD statement TRANSACT macro) is returned a QC status code to
in the batch step for the log, so no checkpoint was force a sync point after each GU call.
written. The DD name for the log data set is IEFRDER. For more information regarding the TRANSACT
Although no checkpoint information was written, normal macro, refer to IMS Version 7 Installation Volume 2:
commit processing was performed. System Definition and Tailoring.
Programmer Response: Provide an IEFRDER DD v An MPP or transaction-oriented BMP issued a GU call
statement. No status is returned for a DD DUMMY to retrieve another message, but either there are no
statement. more messages or the processing limit (that is,
PROCLIM=parm on the TRANSACT macro) has
been reached.
NO
v IMS is shutting down or:
Explanation: A BSAM or VSAM physical I/O error
– A /PSTOP REGION command has been issued for
occurred during a database request that is issued by
the dependent region in which the application
the index maintenance function.
program is processing.
For an online program, all updates made for the call are – A database dump (/DBD) command has been
backed out and the application program receives the issued.
NO status code. For a batch program that does not log
– A database recovery (/DBR) command is in
to the IMS DASD log, IMS abnormally terminates the
operation.
program with an 826 abend.
– A stop subsystem (/STOP SUBSYS) command
Programmer Response: See accompanying has been issued.
messages giving details of the error. In a batch
For more information regarding these commands,
environment, run batch backout.
refer to IMS Version 7 Command Reference.
v IMS wants to reschedule the region (quick
NU reschedule). For more information regarding quick
Explanation: An ISRT, DLET, or REPL request using reschedule, refer to IMS Version 7 Administration
this PCB might result in a BA status code if the INIT Guide: System.
STATUS GROUPA call or QUERY command has been Programmer Response: This is an information-only
| Programmer Response: Correct the segment. Issue a Programmer Response: User determined.
| ROLB to back out any incomplete data. Explanation: The ROLS request was rejected because
the PSB contains access to a DEDB, MSDB, or GSAM
QH organization or has access to an attached subsystem.
Explanation: There has been a terminal symbolic Programmer Response: The ROLS request is invalid in
error. The output logical terminal name or transaction this environment. The program must either remove the
code is unknown to IMS. Some reasons for receiving use of the database organization that is preventing the
this status code are: use of the ROLS call or not use the ROLS call.
v The program tried to insert an alternate response
PCB receiving a QC status code for a GU call. RX
v The program tried to insert to an I/O PCB that has a Explanation: The program issued a REPL that violated
logical terminal name of blanks. This could occur the replace rule for that segment.
after the program issued a GU call for a message that
originated either from a batch-oriented BMP or a CPI Programmer Response: Correct the REPL call, or
Communications driven program. check with the DBA or the equivalent specialist at your
installation.
144 Application Programming: EXEC DLI Commands for CICS and IMS
SA • TJ
SA TE
Explanation: On a SETS request, IMS was not able to Explanation: This status code applies to CICS online
obtain the storage space for the data in the I/O area. command-level programs only, and it is returned
following a scheduling request. The PSB could not be
Programmer Response: Use a larger region size for
scheduled because an initialization error occurred.
the job step.
Programmer Response: See your system
programmer or DBA. For information on possible
SB
causes for the PSB initialization error, see IMS Version
Explanation: The maximum number of levels, nine, of 7 Application Programming: Database Manager.
SETS requests were already specified, and this request
is attempting to set the tenth.
TG
Programmer Response: Correct the program.
Explanation: This status code applies to CICS online
command-level programs only, and it is returned
SC following a terminate request. The program issued a
terminate request when there was no PSB scheduled.
Explanation: A SETS or SETU call was issued with
unsupported PCBs (DEDB, MSDB, or GSAM) in the Programmer Response: This is an information-only
PSB, or the program is using an attached subsystem. status code. If you only wanted to terminate a PSB,
continue with processing. If you also wanted to cause a
Programmer Response: For a SETS call, the request sync point, issue a SYNCPOINT command. (No sync
is rejected. Remove the unsupported PCBs or use the point was caused by the unsuccessful terminate
SETU call. For a SETU call, the program can proceed with request.)
the knowledge that a ROLS call will not back out changes
for the unsupported PCBs. The other option is to not Rather than having an abnormal termination occur, this
use the SETS or ROLS function. status code is returned to the application program that
issued the EXEC DLI command.
SY
TH
Explanation: IMS incurred an internal error during
Syncpoint processing for an IMS/JAVA SYNC request Explanation: This status code applies to CICS online
call. command-level programs only, and it is returned
following a database request or a statistics request. The
Programmer Response: Contact your IMS system program attempted to access the database before
programmer. scheduling a PSB.
Programmer Response: Correct your program, and
TA schedule a PSB before accessing the database.
Explanation: This status code applies to CICS online
command-level programs only, and it is returned TI
following a scheduling request. The PSB named in the
request is not in the PSB directory. Explanation: This status code applies to
command-level programs only, and it is returned after
Programmer Response: Correct the name of the PSB an ISRT command. The ISRT command defined an
in the scheduling request, or add the PSB name to the invalid path to the segment. Data must be transferred
PSB directory. for all segments between the first named segment and
the last named segment.
TC Programmer Response: Correct the ISRT command,
Explanation: This status code applies to CICS online specifying a FROM option for each segment to be
command-level programs only, and it is returned transferred.
following a scheduling request. It means that you have
already scheduled a PSB. TJ
Programmer Response: Correct your program so that Explanation: This status code applies to CICS online
you terminate a PSB before scheduling another. If you command-level programs only, and it can be returned
want to reschedule a PSB, you must have already after any command that a CICS online program uses.
terminated the PSB. DL/I is not active.
Programmer Response: Contact your DBA. CICS
TL TR
Explanation: This status code applies to CICS online Explanation: This status code means that the CICS
command-level programs only, and it is returned after a XDLIPRE exit routine returned X'04' in register 15
scheduling request. A conflict in scheduling intent because the routine determined that the immediately
occurred. (This cannot occur if program isolation has preceding DL/I request should not be executed.
been specified.)
Programmer Response: Contact the CICS system
Programmer Response: Specify program isolation in programmer.
the SIT. If program isolation has not been specified, wait
until the PSB is no longer in use, and reschedule it.
TY
Explanation: This status code applies to CICS online
TN
command-level programs only, and it is returned
Explanation: This status code applies to following a database or statistics request. The database
command-level programs only, and it can be returned was not open when the request was issued.
after any of the commands. An invalid SDIB exists. An
Programmer Response: Contact your DBA or system
initialization call was not made, or the system’s DIB (not
programmer. The database can be checked and opened
the application program’s DIB) was overlaid.
by using operator commands.
Programmer Response: Check your program to
make sure that you did not use an entry statement, as
TZ
you would in a call-level batch program. Also make sure
that no addressing errors are in your program that Explanation: This status code applies to CICS online
would cause an overlay. command-level programs only, and it is returned
following a database or statistics request. The length of
the retrieved segment is greater than 64 KB.
TO
Programmer Response: Contact your DBA or system
Explanation: This status code applies to
programmer; the database definition might require
command-level programs only, and it is returned
modification.
following a REPL command. A path-replace error
occurred. The segments to be replaced are compared
to the previous Get command and one of the following UB
situations occurred:
Explanation: This status code is returned when IMS is
v A segment is named to be replaced that was not unable to obtain private buffer pool.
retrieved by the Get command.
v Data had not been transferred (no INTO option) for Programmer Response: No DFS0535I message is
this segment on the Get command. issued if the High Speed Reorganized Utility (HSRE) is
being used when this status code is received. See the
v The attributes of the data to be transferred do not DFS2712I messages issued at utility termination for the
match the data in the database. name of the module, abend subcode, Utility High Speed
Programmer Response: Correct the program. Workarea (UHSW) storage area dump, IOAR (DEDB
I/O), and register contents.
146 Application Programming: EXEC DLI Commands for CICS and IMS
UP • V1
Version 7 Administration Guide: Database Manager
UW
and IMS Version 7 Utilities Reference: Database and
Transaction Manager. Explanation: This status code is returned when IMS is
During the processing of an HD reorganization, a unable to obtain a work area.
reload, or an initial load program under the Programmer Response: Increase the REGION size
supervision of the Utility Control Facility (UCF), a and run the job again.
checkpoint record was written to the UCF journal
data set. IMS returns this status code to indicate that
the last ISRT call was correct and the initial load UX
program might continue or it might perform a Explanation: This status code is returned for batch
checkpoint procedure before continuing. programs only. A checkpoint record was written, and
v When a connect failed. processing stopped. This is a combination of UC and
US status codes.
Programmer Response: This is an information-only
status code for the first status code reason above. Programmer Response: See the descriptions of UC
and US status codes.
When this status code is issued for a connect failure,
see message DFS0535I for more information on how to
correct the error. U1
Explanation: This status code is returned when the
UP area name specified is not valid.
Explanation: This status code is returned when the Programmer Response: Correct the error and run the
UOW requested is greater than the UOW range. utility job again.
Programmer Response: Correct the error and run the
job again. U9
Explanation: This status code is returned when the
UR area access intent is read or read only. Access intent
must be UP or EX.
Explanation: This status code is returned for batch
programs only. Your initial load program is being Programmer Response: Use the /STA DB ACCESS
restarted under UCF. For information about the Utility command to set the access intent to UP or EX and run
Control Facility (UCF), see IMS Version 7 Administration the job again.
Guide: Database Manager and IMS Version 7 Utilities
Reference: Database and Transaction Manager. The
program terminated while executing under UCF. The job V1
was resubmitted with a restart request. Explanation: The program tried to insert or replace a
Programmer Response: Ensure that the program is variable-length segment that is too long. The length of
in proper sequence with database loading. The program the segment must be equal to or less than the
uses the I/O area and the DB PCB key feedback area maximum length specified in the DBD. IMS also returns
to do this. status code V1 when the specified minimum length
cannot hold the complete sequence field of the segment
type. In this situation, status code V1 results from one
US of three instances: processing without an
edit/compression routine; processing with an
Explanation: This status code is returned for batch
edit/compression routine, but not specifying the key
programs only. The initial load program is about to stop
compression option; or coding a length field (LL) that is
processing. While processing an HD reorganization
less than the specified minimum length. The length
reload or user initial load program under the supervision
must be long enough to include the entire reference
of UCF, the operator replied to the WTOR from UCB
field; if the segment is a logical child, it must include the
and requested the current function to terminate. For
entire concatenated key of the logical parent and all
information about the Utility Control Facility (UCF), see
sequence fields for the paired segment. The program
IMS Version 7 Administration Guide: Database Manager
tried to delete a variable-length segment. The copy of
and IMS Version 7 Utilities Reference: Database and
this segment in the user’s I/O area contains an invalid
Transaction Manager. The last ISRT call was processed.
length field.
Programmer Response: Ensure that the initial load
IMS also returns this status code when an invalid record
program performs a checkpoint procedure of its data
length is specified in a GSAM call.
sets and returns with a nonzero value in register 15.
Programmer Response: Correct the program.
V2 V7
Explanation: This status code applies to Explanation: This status code applies to
command-level programs only, and it is returned command-level programs only, and is returned following
following a database or LOAD command. The segment a STAT command. It means that the statistics area
length is missing or invalid. The segment length must length is either too small or invalid. The length must be
be a positive integer. For variable-length segments, it is a positive integer, and it must be at least 72 bytes for
the maximum size acceptable to the program’s I/O area. unformatted statistics, 120 bytes for summary statistics,
and 360 bytes for formatted statistics.
Programmer Response: Check that the program
translated and compiled correctly. The value of any Programmer Response: Correct the program.
segment length in a path command should not exceed
32 KB, and the sum of the lengths should not exceed
XA
64 KB.
Explanation: The program tried to continue
processing the conversation by passing the SPA to
V3
another program through a program-to-program
Explanation: This status code applies to message switch after already responding to the
command-level programs only, and it is returned terminal.
following a Get or ISRT command. The field length is
Programmer Response: If a response has been sent,
missing or invalid. The field length must be a positive
the SPA should be returned to IMS. Correct the
integer, and it must be specified for each field in a
program.
WHERE option.
Programmer Response: Correct the program.
XB
Explanation: The program has passed the SPA to
V4
another program but is trying to respond to the
Explanation: This status code applies to originating terminal.
command-level programs only, and it is returned
Programmer Response: No response is allowed by a
following any of the database commands or a LOAD
program that is passed control of the program through a
command. The length of a variable-length segment is
program-to-program message switch.
invalid. The LL field as provided by the program on an
ISRT or REPL command, or as received in the I/O area
on a Get command, exceeds the value of XC
SEGLENGTH.
Explanation: The program inserted a message that
Programmer Response: Correct the program. has some bits in the Z1 field set. The Z1 field is
reserved for IMS.
V5 Programmer Response: Correct the program to
prevent it from setting those bits.
Explanation: This status code applies to
command-level programs only, and is returned following
a Get, REPL, or ISRT command. The offset is invalid. The XD
offset must be a positive integer and not greater than
the segment length. Explanation: IMS is terminating by a CHECKPOINT
FREEZE or DUMPQ. IMS returns this code to a BMP
Programmer Response: Correct the program. that has issued a CHKP or SYNC call. If it is a
transaction-oriented BMP, IMS does not return a
message.
V6
IMS also returns XD when a batch program issues a
Explanation: This status code applies to
SYNC call.
command-level programs only, and it is returned
following a Get or ISRT command using the KEYS Programmer Response: Terminate the program
option. The concatenated key length is missing or immediately. IMS will terminate the program abnormally
invalid. The length of the concatenated key must be a if the program issues another call.
positive integer.
Programmer Response: Correct the program.
148 Application Programming: EXEC DLI Commands for CICS and IMS
XE • X7
XE X2
Explanation: A program tried to insert a SPA to an Explanation: The first ISRT call to an alternate PCB
alternate express PCB. whose destination is a conversational transaction code
is not for the SPA. The SPA must be inserted with the
Programmer Response: Regenerate the PSB and
first ISRT call.
remove the EXPRESS=YES option from the PCB, or
define another non-express PCB to be used in the ISRT Programmer Response: Insert the SPA, and then
call. reinsert the message segment.
XF X3
Explanation: IMS is ignoring the ISRT call for the SPA, Explanation: The program modified the first 6 bytes of
because the specified alternate PCB had its destination the SPA; the SPA is now invalid.
set to a logical terminal but was not defined as
Programmer Response: Correct the program and
ALTRESP=YES during PSB generation.
restore the original bytes.
MSC directed routing does not support a
program-to-program switch between conversational
X4
transactions.
Explanation: The program issued an ISRT call to pass
Programmer Response: Correct the application
the SPA to a nonconversational transaction code. It did
program or change the PSB generation for that
this by referencing a PCB whose destination was set for
alternate PCB to specify ALTRESP=YES.
the nonconversational transaction code. You can send
the SPA only to transaction codes that are defined as
XG conversational.
Explanation: IMS ignored the ISRT call because the Programmer Response: Correct the ISRT call. Send
current conversation requires a fixed-length SPA, and only data segments.
the ISRT call was to a program with a different length or
variable-length SPA, while the source IMS system was
X5
earlier than IMS 6.1. If the SPA ISRT on a remote
system is not going back to the input terminal (IOPCB), Explanation: The program issued more than one ISRT
the SPA size must be the same as the size of the call to send the SPA to a PCB whose destination is a
current one, if the source IMS system is earlier than transaction code. Only one SPA is allowed per
IMS 6.1. message.
Programmer Response: Correct the program or the Programmer Response: Correct the program.
SPA definitions.
X6
XX
Explanation: An invalid transaction code name was
Explanation: An error occurred during GSAM inserted into the SPA. This will occur if the input is from
initialization or during GSAM call processing. If this LU 6.2 (APPC) or OTMA and if a dynamic control block
status code is in the GSAM PCB before the application was built for the transaction code.
program issued the first call, the error was detected
during initialization. Possible causes are: Programmer Response: Correct the program to set
the proper transaction code name.
v Insufficient space
v Invalid DBD
v Invalid block size
v Invalid option X7
v Internal GSAM error
Explanation: The length of the SPA is incorrect. The
Programmer Response: A subsequent GSAM call will program modified the first 6 bytes.
result in an abnormal termination of the program. The
Programmer Response: Correct the SPA and the
program should terminate.
program.
blanks (bb)
Explanation: The call was completed.
Programmer Response: Proceed with processing.
150 Application Programming: EXEC DLI Commands for CICS and IMS
Part 3. Appendixes
156 Application Programming: EXEC DLI Commands for CICS and IMS
GNP (GET NEXT in Parent) command (continued) locating
restrictions 27 a specific sequential dependent 102
usage 26 last inserted sequential dependent 102
GSAM PCB 11 LOG command
GU (GET UNIQUE) command description 52
description 28 examples 53
examples 32 format 53
format 28 options 53
options 29 restrictions 53
restrictions 33 usage 53
usage 32
guidelines, general programming 73
M
medical database example
H description 8
HERE insert rule 37 segments 8
hierarchical database example, medical 8 MOVENEXT option
HOUSHOLD segment 10 examples 98
use when moving subset pointer forward 98
moving subset pointer forward 98
I
I/O area
assembler language 72 O
COBOL 72 online programs, command-level samples
coding 72 assembler 74
command-level program 71 C 85
PL/I 72 COBOL 78
symbolic CHKP 106 PL/I 81
XRST 106 options for subset pointers
I/O PCB (input/output PCB) 11 GETFIRST 96
ILLNESS segment 8 MOVENEXT 98
intermediate backout points 106 SET 98
ISRT (insert) command SETCOND 99
insert rules 37 SETZERO 97
ISRT (Insert) command
description 33
examples 38 P
format 34 P processing option 103
options 34 path command 44
restrictions 38 PATIENT segment 8
usage 37 PAYMENT segment 9
issue checkpoints in batch or BMP programs 105 PCB (program communication block)
in application programs, summary 12
types 11
K PL/I
key feedback area DL/I command-level sample 81
command-level program 71 I/O area 72
length field in DIB 71 pointers, subset
DBD, defining 95
description 93
L GETFIRST option 96
LAST insert rule 37 MOVENEXT option 98
level number field in DIB 70 preparation for using 94
link editing, EXEC DLI 92 PSB, defining 95
linkage editor options with EXEC DLI 92 sample application 95
LOAD (Load) command SET option 98
description 51 SETCOND option 99
examples 52 SETZERO option 97
format 52 status codes 101
options 52 POS command
usage 52 description 39
Index 157
POS command (continued) ROLB (Rollback) command (continued)
EXEC DLI command format 39 restrictions 55
format 39 usage 55
free space, identifying 103 ROLL command
locating a specific sequential dependent 102 description 56
locating the last inserted sequential dependent 102 examples 56
options 39 format 56
usage 40 options 56
using with DEDBs 102 restrictions 56
processing usage 56
DEDBs 93 ROLS command 107
Fast Path, P (position) option 103 description 57
programming guidelines, general 73 examples 57
PSB (program specification block), format 12 format 57
options 57
Q restrictions 58
QUERY command usage 57
description 53 RULES=FIRST 37
example 53 RULES=HERE 37
format 53 RULES=LAST 37
options 53
restrictions 54 S
usage 53 sample programs
command-level assembler language
batch 74
R online 74
randomizing routine, FM status code 137 command-level C
recovering databases 105 batch 85
recovery EXEC DLI commands online 85
basic CHKP 105 command-level COBOL
SYMCHKP 106 batch 78
XRST 106 online 78
REFRESH command 109 command-level PL/I
description 54 batch 81
example 54 online 81
format 54 SCHD (Schedule) command
options 54 description 46
restrictions 55 examples 47
usage 54 format 46
REPL (Replace) command options 46
description 40 usage 47
examples 43, 44 segment level number field 70
format 41 segment name field, DIB (DL/I interface block) 70
options 41 segments in medical database example 8
restrictions 44 sequential dependent segments
usage 42 free space, identifying 103
resetting a subset pointer 98 in DEDBs 93
restarting your program, with EXEC DLI XRST locating a specific dependent 102
command 106 locating the last inserted dependent 102
RETRIEVE command POS command 102
description 44 SET option
examples 46 examples 98
format 45 resetting a subset pointer 98
options 45 SETCOND option
restrictions 46 examples 99
usage 45 setting a subset pointer conditionally 99
ROLB (Rollback) command SETS command
description 55 description 58
examples 55 example 59
format 55 format 58
options 55 options 58
158 Application Programming: EXEC DLI Commands for CICS and IMS
SETS command (continued) System Service (continued)
restrictions 59 REFRESH 54
usage 59 ROLB 55
setting a subset pointer ROLL 56
conditionally 99 ROLS 57
to zero 97 SETS 58
SETU command SETU 59
description 59 STAT 60
example 60 SYMCHKP 61
format 59 XRST 63
options 60
restrictions 60
usage 60 T
SETZERO option TERM (Terminate) command
examples 97 description 47
setting a subset pointer to zero 97 examples 48
STAT command format 47
description 60 options 47
examples 61 usage 47
format 61 translating, EXEC DLI program 91
options 61 translator options required for EXEC DLI 91
usage 61 translator version, DIB (DL/I interface block) 69
status code, field in DIB 69 TREATMNT segment 9
status codes
categories 117
checking in a command-level program 69 U
database calls 122 Utility Control Facility (UCF) 147
database calls, table 117
message calls, table 122, 124
processing option P 103 V
subset pointers 101 variable names, mandatory 68
subset pointers
DBD, defining 95
description 93
GETFIRST option 96
X
XRST (Extended Restart) command
MOVENEXT option 98
description 63
preparation for using 94
examples 65
PSB, defining 95
format 63
sample application 95
options 63
SET option 98
restrictions 65
SETCOND option 99
usage 64
SETZERO option 97
status codes 101
symbolic checkpoint
restart 106
XRST 106
SYMCHKP (Symbolic Checkpoint) command
current position 62
description 61, 106
examples 63
format 61
options 62
restrictions 63
usage 62
System Service
ACCEPT 49
CHKP 49
DEQ 50
LOAD 51
LOG 52
QUERY 53
Index 159
160 Application Programming: EXEC DLI Commands for CICS and IMS
Readers’ Comments — We’d Like to Hear from You
IMS Version 7
Application Programming: EXEC DLI Commands for CICS and IMS
Overall, how satisfied are you with the information in this book?
How satisfied are you that the information in this book is:
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you.
Name Address
Company or Organization
Phone No.
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
SC26-9424-01 Along Line
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC26-9424-01 Along Line
SC26-9424-01
Spine information: