j
Program Product
)
SH20-9026-8 File No. S370-50
IMS/VS Version 1
Application Programming=
Designing and Coding
Program Number 5740-XX2 Release 2
--..- -
- - - - - = - - ---- = - --- =----= ...
- - - - -
----_.-
. _ - - - -
- - - - _ ..._
..._-_._-_._
...__
.. _._--This publication was produced using the IBM Document Composition Facility
(program number 5748-XX9) and
the master was printed on the IBM 3800 Printing Subsystem.
Ninth Edition (March 1981)
This is a major revision of, and makes obsole~e, SH20-9026-7.
This edition,applies to Version 1, Release 2 of IMS/VS, Program Product 5740-XX2, and to any subsequent releases and
modifications until otherwise indicated in new editions or technical newsletters.
The changes for this edition are summarized under "Summary of Amendment s" fo 11 ow i ng the preface. Spec if; c changes are i nd i cated by a vertical bar to the left of the change. These bars will be deleted at any subsequent republication of the page affected.
Editorial changes that have no technical significance are not noted.
Changes are peri odi cally made to the i nformat i on here in; before using this publication in connection with the operation of IBM systems, consult the latest IBM System/370 and 4300'Processors Bibliography, GC20-0001, for the editions that are applicable and current.
It is possible that this material may contain reference to, or information about, IBM products (machines and programs),
programming, or services that are not announced in your country.
Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or
services in your country.
Pub I i cati ons are not stocked at the address gi ven below; requests for IBM publications should be made to your IBM representative or to the IBM branch office serving your locality.
A form for reader's comm9nts ;s provided at the back of this publication. If the form has been removed, comments may be addressed to IBM Corporation, P.O. Box 50020, Programming Publishing, S~n Jose, California, U.S.A. 95150.
IBM
may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation whatever.You may, of course, continue to use the information you supply.
(
(
)
)
PREFACE
'This retitled edition supersedes the seventh edition, called the IMS/VS Version 1 Application Programming Reference Manual. This manual contains the application programming information from the previous edition, and additional information on designing IMS/VS application programs. The application programming information from the previous edition has been separated into a guidance part and a reference part to better support application programming.
PREREQUISITE KNOWLEDGE
Before using this manual, you should understand basic IMS/VS concepts, the IMS/VS environment, and your installation's ,IMS/VS system. The IMS/VS concepts explained in this manual are limited to those concepts pertinent to developing and coding IMS/VS
application programs. You should also know how to use COBOL, PL/I, or assembler language.
HOW THIS BOOK IS ORGANIZED
The manual is divided into three parts. The first and second pa rt s, "Appl i cat i on Des i gn Gu i de" and "Appl i cat ion P rogramm i ng Guide," guide you in designing and coding IMS/VS application programs. The third part, "For Your Reference," contains
reference information about the parts of an IMS/VS application program. This part is for experienced programmers who understand IMS/VS application programming and need only to look up facts like a call format, a command code, or the meaning of a particular status code.
Part 1. Application Design Guide
This part contains the following five chapters:
• Chapter 1, "ConcG!pts and Terminology," describes the
characteristics of a hierarchic data base and explains the relationship between the programs you are designing and coding and the Dl/I data base. This chapter also introduces you to the tasks you will perform in developing online and batch application programs.
• Chapter 2, "Analyzing Application Requirements," gives an overview of application design and explains two of the subtasks of application design: defining application dat~
and designing local views.
• Chapter 3, "Understandi ng Onl i ne and Batch Processi ng,"
describes the types of processing available in IMS/VS in terms of the application requirements that each type answers.
This chapter will help you understand characteristics of each type of processing so you can decide which type will satisfy the requirements of the application.
• Chapter 4, "Gathering Requirements for Data Base Options,"
describes data base options in terms of the application requirements they satisfy and how each option affects the performance and efficiency of the program. This chapter describes the information about your application that you should supply to the data base administrator. This
information will be helpful to the DBA in choosing a data base design that will meet the requirements of all applications.
•
Chapter 5, "Gathering Requirements for Data Communications Options," describes data communications options in terms of the application requirements each satisfies. This information will help you understand these options and will enable you toPreface iii
- - - , , - - , - , - - - ' -
gather information that will be useful to the DB/DC system
administrator. (~
Part 2. Application programming Guide
This part contains the following seven chapters:
• Chapter 6, "Structuring the DL/! Portion of a Program,"
contains guidance information to help you structure programs using DL/! calls, SSAs, command codes, status codes, and other tools and techniques. Thi~ chapter and the next contain all the information you need to structure and code batch application programs. Chapters 8, 9, and 10 contain
addi ti onal i nformati on on structuri ng and codi ng MPPs, BMPs"
and Fast Path programs. . ,
• Chapter 7, "Coding the DL/! Portion of a Program," will guide you in coding batch programs and the DL/! portions of online programs, according to the design dacisions you have made.
• Chapter 8, "Structuring a Message Processing Program,"
explains what your program must do to -process messages. It tells how to structure an MPP using the tools and techniques described in Chapter 6 and those introduced in this chapter.
• Chapter 9, "Coding a Message Processing Program," explains how you code an MPP once you have a detailed design of it.
• Chapter 10, "Structurin~ and Coding a Batch Message Program,"
describes the types of BMPs that you can write, and tells what tools they can use.
•
Chapter 11, "Testing an Application Program," gives you guidance for testing OL/I call sequences, explains what you need to test a program, and describes the tools available to help you test. This chapter also describes the actions you can take in isolating a problem when your program does not execute correctly.• Chapter 12, "Documenting an Application Program," explains why you should document your programs and suggests parts of the application development process to document.
Part
3.For Your Reference
Thi-s part contains reference information about the parts of an IMS/VS a~plication program such as entry statements, DL/I calls, system service calls, SSAs, command code~, PCBs, and status codes, as they apply to COBOL, PL/I, and assembler language.
APpendixes
The appendixes contain the following:
• Appendix A is a sample batch application program. This
program 1S written in COBOL and accesses the sample data base that is part of the IMS/VS Primer function.
• Appendix B is a sample batch message (BMP) program. This program is written in COBOL-and accesses the sample data base that is part of the IMS/VS Primer function.
• Appendix C is a sample message processing program (MPP). Thts program is written in PL/! and accesses the sample data base that is part of th~ IMS/VS Primer function.
• Appendix 0 is a sample conversational,MPP program. This
program is written in COBOL and acce~ses the sample data base that is part of the IMSIVS Primer function.
•
Appendix E is a sample status code error routine. This program is wri tten in assembler language and accesses the sample database that is part of the IMS/VS Primer function.
(
)
)
•
Appendix F contains reference information on the formats and usage of the DL/I Test Program control statements.PREREQUISITE PUBLICATION
RELATED PUBLICATIONS
• The IMS/VS General Information Manual, GH20-1260 introduces IMS/VS. You can use this manual to acquaint yourself with IMS/VS functions, the hardware and software products
prerequisite to using IMS/VS, and the IMS/VS facilities that help satisfy application requirements.
• TheIMS/VS Data Base Administration Guide, SH20-9025, contains guidance information on planning, designing,
implementing, monitoring and tuning, and controlling a data base in an IMS/VS system. It gives the characteristics of the various kinds of IMS/VS data bases' and the design
considerations of each.
• TheIMS/VS System Administration Guide, SH20-9178, contains guidance information on establishing a data base/data
communication (DB/DC) system. This book explains how to control the content of the IMS/VS system definition and establish operating proc~dures. This manual also has information on monitoring the performance of the IMS/VS System, coding IMS/VS execution JCL, and preparing IMS/VS system definition macros for application and tuning
requirements.
•
•
IMS/VS Utilities Reference Manual, SH20-9029, describes the function and use of IMS/VS utilities. It contains reference information necessary for those installing an application system and planning operational procedures.
IMS/VS Installation Guide, SH20-9081, cont~;ns IMS/VS
reference information for all aspects of IMS/VS installation and system definition.
• IMS/VS System Programming Reference Manual, SH20-9027,
contains reference information useful when tuning the IMS/VS system or for coding exit routines.
• IMS/VS Message Format Service User's Guide, SH20-9053,
contains both design and reference information for formatting messages to and from terminals.
• IMS/VS Fast Path General Information Manual,GH20-9069, describes the IMS/VS Fast Path feature and provides information for evaluating the use of this feature.
• IMS/VS Primer, SH20-9145, describes the subset of IMS/VS functions available under the IMS/VS Primer function. The Primer function enables a first-time IMS/VS user. to design and install an application within a simpler system.
• DB/DC Data Dictionary General Information Manusl, GH20-9104, contains introductory information on the DB/DC Data
Dictionary and the hardware and software products prerequisite to using it.
• DB/DC Data Dictionary Applications Guide, SH20-9173, explains how you define subjects to the Data Dictionary.
• BTSII Batch Terminal Simulator II Program
Description/Operations Manual, SH20-1844, tells you how to use BTS II to test application programs.
Preface v
For installations with IMS/VS DB and CICS/OS/VS:
•
CICS/VS General Information Manual, GC33-0066, contains a general introduction to CICS/VS, sample applications, and machine and program requirements.• CICS/VS Application Programmer's Reference Manual, SC33-0079, contains information about requesting Data Language I (DL/I) services from a CICS/VS application program.
( I
(
)
~ /
/
)
SUMMARY OF AMENDMENTS
VERSION 1, RELEASE 2, MARCH 1981
NEW PROGRAMMING FACILITIES
• Data sharing provides control for application programs in two or more IMS/VS systems to access IMS/VS data basa~
concurrently. The IMS/VS systems can be in one processor, or they can be in separate processors. Application pr~grams that share data bases with application programs in other IMS/VS systems should issue checkpoint calls frequently; if they.
don't, they can ti~ up portions of the data base, preventing other application programs from accessing some data.
• There are two new processing options that can be used with the GO processing option for application programs: T and H. If an application program with the processing option GO tries to retrieve a segment containing an invalid pointer, IMS/VS terminates the program abnormally.
If
the application program uses the T or H option with GO (GOT or GOH), IMS/VS returns control to the application program and returns a GG status code. In addition, the T processing option causes IMS/VS to retry the call before returning control to the program.VERSION 1, RELEASE 1.6, JULY 1980
NEW PROGRAMMING FACILITIES
• Intersystem Communication, or ISC, is a part of Multiple Systems Coupling (MSC) that makes communication sessions between IMS/VS and other subsystems (such as CICS/VS, a user-written system, or another IMS/VS system) possible.
• MSC directed routing makes it possible for an application program to specify the multiple system name (MSHAME) and destination within that system for a message in another
system. The application program can receive the MSHAME of the system that originally scheduled it.
• Application programs may bypass-MFS editing or basic editing when communicating via 3270 or SLU 2 devices. This bypass makes it possible to leave the screen in an unprotected mode
so that IMS/VS can send output to the device without requiring input from the device. The application program can also
control the locking and unlocking of the keyboard.
MAJOR EDITORIAL CHANGES
This book is a complete reorganization of the IMS/VS Version 1 Application Programming Reference Manual. The revised book contains information on application design that is, for the most part, new to IMS/VS publications, and it contains information on application programming from the APRM.
Part 1 is a guide to designing IMS/VS applications. This new information has been added to help you in designing IMS/VS applications.
Parts 2 and 3 contain information on application programming from the APRM. This information has been separated into guide and
Summary of Amendments vii
reference information. Part 2 is a guide to application
programmi ng; it expla ins the steps of structuri ng and codi ng /~
IMS/VS appl i cat 1 on programs. Part 2 is for those who are not ( thoroughly familiar with IMS/VS, particularly people who have
little or no experience with IMS/VS. Part 3 contains reference information concerning application programming. This information is intended for experienced IMS/VS application programmers who understand the concepts of HIS/VS appl i cat i on programmi ng, and need only to look up a specific piece of information.
For a chapter by chapter description of the revised book, see the Preface at the beginning of this book.
VERSION I. RELEASE 1.5, DECEMBER 1978
FIELD LEVEL SENSITIVITY
Changes have been made to reflect the use of field level sensitivity.
VERSION I. RELEASE 1.5, SEPTEMBER 1978
NEW PROGRAMMING FACILITIES
OTHER CHANGES
service
changes·• An application program can issue IMS/VS operator commands, and a user-written exit routine can monitor resource
activity, by using the Automated Operator Interface (AOI).
•
•
Expanded security facilities, including the presence of the user identification in the I/O PCB.
Access to Fast Path and IMS/VS data bases from both Fast Path and IMS/VS application programs and other enhancements for
integrated support.
• Support for direct dependent segment types for DEDBs.
• An IMS/VS Primer function which makes it easier for new IMS/VS users to get IMS/VS and their initial applications up
running. This function runs under OS/VSl and OS/VS2 MVS.
• The rollback (ROlB) call can be issued by IMS/VS application programs to undo data base changes without subsequent
abnormal termination.
• Further system service call clarification.
• Correction to Pl/I" conversational program example.
RELEASE 1.4. FEBRUARY 1978
TECHNICAL CHANGES
•
The Dl/I call trace facility has been added to the book. This facility traces and records all Dl/I calls issued by anapplication program, making it possible to duplicate the conditions that caused a program failure. The trace output can be used as _inPut to the Dl/I test prgram, DFSDDlTO.
(
OTHER CHANGES )
Serv
ice
changes- - - ----
• COBOL and PL/I examples have been updated.
• The explanations of the OL/! system service checkpoint, restart, log, and statistics calls have been clarified.
• The example of the independent ANO Boolean operator has been expanded.
• A single use of the MFS MOD parameter is allowed for data communication insert and purge calls. Clarification in the use of the data communication change call has been added.
• OL/I test program changes:
The DATA statement maximum segment size has been' corrected.
The operation of the SNAP call has been clarified.
• OL/! status code changes:
The detailed descriptions of status codes AM, OJ, and IX were expanded.
A description for status code XX was added.
• The majority of the Boolean operator information given in Chapter 2 has been moved to the end of Chapter 3.
) VERSION 1, RELEASE 1.4
)
NEW PROGRAMMING FEATURE
OTHER CHANGES
The Fast Path feature provides data base and data communication facilities for applications requiring high transaction rates but needing only simple data base structures. The Fast Path feature uses functions of the Oata Communication feature and operates with existing telecommunication networks.
Fast Path provides two new types of data bases that are accessed with standard OL/! calls and, optionally, with Fast Path OL/I calls. The feature includes a message-handling facility to expedite the processing of Fast Path messages.
Four new OL/I calls exist for use in Fast Path applications: the field (FLO), rollback (ROLB), synchronize (SYNC), and position (POS) calls. These calls and all status codes associated with them have been added to the manual. Also added are notes on the use of those IMS/VS OL/I calls applicable in the Fast Path environments.
• Fast Path application programming is addressed in a new Chapter 6.
• A section on determining data base position after a GE status code has been added to the manual.
Summary of Amendments ix
- - - , - - - , - , - , , - - - - , , - -
----
VERSION 1. RELEASE 1.2
TECHNICAL CHANGES
OTHER CHANGES
This release reflects technical changes to this publication in support of the following new feature and devices:
• Multiple Systems Coupling Feature
• 3767 Communication Terminal
• 3779 Data Coummunication System
• A symbolic all interface for the.extended checkpoint/restart facility has been added. With this facility, ANS COBOL and PL/I application programs can now jssue extended CHKP and XRST DL/I calls and also CHKP DL~I calls that specify OS checkpoints.
• Updates have been made to PL/I information, and a revised example is included for the Pl/I Optimizing Compiler.
• Chapter 7 of this edition describes the "DL/I Test Program"
and flMessage Processing Region Simulation." This information was formerly in Appendix C of the IMS/VS Utilities Reference Manual and Appendix B of the IMS/VS System/Application Design Guide, respectively.
VERSION 1. MODIFICATION LEVEL 1.1.
•
Support has been added for the 3740 Data Entry System. IMS/VS supports the 3741 Data Station, Model 2, and the 3741Programmable Work Station, Model 4, attached on a switched line using BTAM.
• The restriction against the Utility Control Facility (UCF) has been lifted.
VERSION I. MODIFICATION LEVEL 1
The following new and/or enhanced IMS/VS functions have been added:
• Generalized Sequential Access Method (G~AM)
• Expanded restart (restart call)" get System Contents Directory Call, and statistics call
• Response alternate PCBs
• Fixed-length SPAs
• Program isolation
• Application program output limits
• Message Format Service (MFS) support for ad~itional terminals
Note:
Information in this manual about. the Utility ControlFacility (UCF) is for planning purposes only until that facility becomes available.
,r
\,.,
c
)
)
VERSION 1, MODIFICATION LEVEL 0.1
• Support for the IBM 2260 Display Station, Model 1 and 1, and for t~e IBM 2265 Display Station, Model 1
Summary of Amendments xi
I /'
( r
"
(
CONTENTS
)./
)
)
- - - - - - - -
Part 1. APplication Design Guide Chapter 1. concepts and Terminology
Processing Information in a Data BaseComparing Ways to store Data Storing Data in Separate Files Storing Data in a Combined File
Stor i ng Data ina Data Base . • . . . What the Data Looks Like When It's Stored What the Data Looks Like to Your Program How You Process a Data Base Record
A Look at the Tasks Ahead of You . . .
Chapter 2. Analyzing Application Requirements
An Overview of Application Design • . . . .The Tasks of Application Design . . . . Documenting the Application Design Process Converting an Existing Application
Identyfying Application Data Listing Data Elements
Naming Data Elements . . . .
Documenting Application Data . . . . Designing a Local View . . . . . . • . .
Analyzi ng Data Relati onshi ps . . . . Grouping Data Elements into Hierarchies
Determining Mappings . . . • • . . . . Local View Examples . . . . . . . . . Schedule of Courses . . . • • Instructor Skills-Report
Instructor Schedules
Chapter 3. Understanding Online and Batch processing
Analyzi ng Processi ng Requi rements . . • .Online Processing . . . • . . . Message Processing . . . • . . • .
How H15/VS Identifies Terminals . . . . How IMS/VS Protects Online Data: Sync Points MPPs . . . ~ . . . . Message-Driven Fast Path Programs
Transacti on-Ori ented BMPs . . . • . •
Batch Processi ng Onl i ne . . . . . . . Batch-Ori ented B~lPs . . : . . . . Nonmessage-Driven Fast Path Programs
Mixing Fast Path and IMS/VS Processing Batch Processing . . . • . . .
Sync Points in a Batch Program . . . . . . . .
Recovery ina Batch Program . . . . Summarizing IMS/VS Application Program Characteristics
Chapter 4. Gathering Requirements for Data Base Options
Analyzing Data Access . . . • . .Di rect Access . . . • . . . Primari ly Di rect Processing: HDAM . • . . Direct and Sequential Processing: HIDAM
Sequent i a 1 Access . . . . .. . . • . . . • • . Sequential Processing Only: HSAM . . . .
Primarily Sequential Processing: HISAM
Accessi ng OS/VS Fi les through H1S/VS: GSAM . . . , Accessing IMS/VS Data through OS/VS: SHSAM and SHISAM
Understanding How Data Structure Conflicts Are Resolved Using Different Fields: Field Level Sensitivity . Resolving Processing Conflicts in a Hierarchy: Secondary
Indexing . . . • . . . Using a Different Key . . . . Retrieving Segments Based on a Dependent's Qualification Creating a New Hierarchy: Logical Relationships . . • . .
Accessing a Segment through Different Paths . . . .
1 2 2 2 2 3 4 4 5 7 7 10 10 10 12 12 12 13 15 16 17 17 18 21 22 23 24 25 28 28 30 32 32 33 33 35 36
37 37 38 38 39 39 39 40
41 41 42 43 44 45 45 46 46 47 47 47 48 49 52 52 52
Contents xiii
Inverting a Parent/Child Relationship Identifying Security Requirements 0 0 • 0 0
Keeping a Program from Accessing the Data: Data Sensitivity 0 0 0 0 0 0 0
Segment Sensitivity . . • 0 0 • 0 • 0 0 0 0 0 Field Level Sensitivity •• 0 • 0 • • • • • 0
Key Sensitivity • . 0 0 • 0 0 • 0 • • • 0 • 0 0 •
Preven~ing a Program from Updating Data: Processing Options . . 0 • • • 0 0 0 • •
Identifying Recovery Requirements
. .
Choosing a Checkpoint Call 0 . , 0
How Often to Use Checkpoints
Checkpo i nts in Batch Programs . .
Checkpoi nts in Batch-Ori ented BMPs • 0 • • 0 • 0 0 Checkpoints in MPPs and Transaction-Oriented BMPs Checkpoints with Data Sharing o. 0 0 0 • • 0 • 0 •
Chapter s. Gathering Requirements for Data Communications
options • • • • • • • • • • • • • • • • • • • . • • • • • •
Identifying Online Security Requirements o . 0 0 0 0 • 0Limiting Access to Specific Individuals: Sign-on Security Limiting Access to Specific Terminals: Terminal Security Limiting Access to the Program: Password Security
Supplying Security Information 0 • 0 0 0 0 • 0
Analyzing Screen and Message Formats
An Overview of MFS 0 " 0 0 0 0 0 • • • 0 An Overview of Basic Edit •• 0 0 0
Editing Considerations in Your Application . 0 0 0 0 Gathering Requirements for Conversational Processing
What Happens ina Conversati on •• 0 • • Des i gn i ng a Conversat ion . . • 0 0 0 • •
Things You Need to Know about the SPA
Recovery Considerations in Conversations
Identifying Output Message Destinations • • • • • The Originating Terminal . • • • • • • • 0 • •
To Other Programs and Terminals
Part 2. Application programming Guide '. . . . . . .
Chapter 6. structuring the DL/I portion of a Program
How You Read and Update a DL/I Data Base: An OverviewDL/I Calls
SSA s . 0 • 0 • • 0 • • • Command Codes . . • • 0 • • • DB PCB Ma sks . • 0 • • Fo r Exampl e o . • . 0 • 0 • •
The Medical Hierarchy . . • • •
Medi cal Data Base Segment Formats . • • 0 • 0 What Happens When You Issue a Call
Retrieving, Information • • . ' . . . Retrieving Segments Directly: GU
How You Use GU . . • . 0 • • • 0 • 0 GU Examples 0 . . . 0 • 0 • • 0
Using SSAs with GU . . • 0 • 0 • • • Using Command Codes with GU . • • 0 GU and Parentage o. 0 0 0 0 0 • 0 GU Status Codes . . 0 • 0 0 0 0 • • 0 Retrieving Segments SequentiallY: GN
How You Use GN . 0 • • • • • • • • • • •
Using SSAs with GN . • . . • • 0 0 • 0 0 Usi ng Command Codes wi th GN o. 0 0
GN and Parentage o. 0 0 0 0 0 • 0 • GN Status Codes . . . 0 0 0 0 •
Retrieving Dependents Sequentially: GNP How You Use GNP . 0 0 • • 0 0
Usi ng SSAs wi th GNP 0 0 • 0 Using Command Codes with GNP GNP and Parentage . . . 0 0 GNP Status Codes • . . . • • . Using the Right Retrieval Call Updating Information . . • . • •
Before You Update: Get Hold Calls Replaci ng Segments: REPl . . 0 • •
..
,0
-54 55 55 56 56 56 58 59 60 61 61 61 62 63
64
64 65 65 65 65 66 66 67 67 68 68 69 70 71 72 72 737S
76 77 80 81 83 85 88 88 88 90 91 91 92 92 92 93 93 93 94 9S 96 96 97 97 97 97 98, 99 99 99 100 100 100 101/ ' (
,-
(
)
)
How You Use REPL . . . . • . . REPL Examples . . . • Usi ng SSAs wi th REPL . . . . Using Command Codes with REPL REP L and Parentage . . . . REPL status Codes
Deleting Segments: OLET How You Use OLET
OLET Examples
Using SSAs with DLET . . . Using Command Codes with OLET OL ET and Parentage . . . . . .
OLET status Codes . . . . . . . . . Inserting Information . . . .
Adding Information to an Existing Oata Base How You Use ISRT to Add Segments
ISRT (add) Example Using SSAs with ISRT
ISRT and Command Codes . . . . ISRT and Parentage . . . . ISRT Status Codes . . . . Initially Loading a Data Base Using SSAs in a Load Program Loading a Sequence of Segments Load Command Codes . . . .
status Codes for Load Programs . . . Determining Your Position in the Data Base
When Position Is Important . . . Current Position after Successful Calls
Position after Retrieval Calls . . . . Position after DLET . . . .
Position after REPL . . . . Posi ti on after ISRT . . . .
Current Position after Unsuccessful Calls
Techni ques to Make Programmi ng Easi er . . . . Usi ng SSAs . . . .
Guidelines on Using SSAs . . . . . . Using Multiple Qualification Statements
Us i ng Command Co des . . . . • . • Retrieving and Inserting a Sequence of Segments: D
Retrieving and Inserting the First Occurrence: F Retrieving and Inserting the Last Occurrence! L Using Concatenated Keys inSSAs: C . . . Setting Parentage Where You Want It: P
Using OL/I's Positions as Qualifications! U Qualifying the Search on the Current Path: V Preventing a Segment from Being Replaced! N Reserving a Place for Command Codes: Null Us; ng Parallel Process; ng . . . . . . . .
Using Multiple OB PCBs Using Multiple Positioning Programming Guidelines
Check i ng Status Codes . . • . . . Exceptional Conditions
Error Rout i nes . . . . •
Taking Checkpoints . . . • . . Checkpo i nt lOs . . . .
Where to Use Checkpoints . How Often to Use Checkpoints Symbolic CHKP . • • . .
Usi ng XRST . . . • • . . . • . . • . . . . . . Basi c CHKP . . . • • . . . • . • . . . . • . Using Secondary Indeiing and Logical Relationships
How Secondary Indexing Affects Your Program . . • . Usi ng SSAs wi th Secondary Indexes • . . • • . •
What DL/I Return~ with a Secondary Index . • . . . • . • Processi ng Segments in Log; cal Relati onshi ps ••
How Logical Relationships Affect Your Programming Status Codes for Logical Relationships • • • . Planning Ahead for Batch-to-BMP Conversion . • . •
The Compatibility Option . . . • • . • . . Checkpoint Frequency . . . .
Designing a Program that Uses GSAM
101 101 102 103 103 103 103 103 103 104 104 104 104 104 104 104 105 105 106 106 106 107 107 108 108 108 108 109 111 111 I I I 113 113 115 118 119 119 120 121 121 122 123 123 124 124 125 125 126 126 126 126 127 128 129 129 130 131 131 131 132 132 133 134 134 135 135 136 137 138 138 140 140 140
Contents xv
Access i ng GSAM Data Ba ses . . 0 0 0 0 0 0 0
PCB Masks for GSAM Data Bases 0 0 0 0 0 0 0 0 0 0 Retrieving and Inserting GSAM Records 0 • • • • Explicitly Opening and Closing a GSAM Data Base GSAM Record Formats . 0 • • • 0
GSA~l Status Codes . . 0 • • 0 0 Using Symbolic CHKP and XRST with GSAM Processing Fast Path Data Bases
Processing MSDBs . . . 0 0 0
T~/pes of MSDBs 0 0 0 0 • • 0 0
Reading Segments in an MSDB: GU and GN . . . . Updating Segments in an MSDB: REPL, DLET, ISRT, and FLD Sync Point Processing in an MSDB
Process'i ng DEDBs o. 0 0 • 0 0 0 Using DL/I Calls with DEDBs
The POS Call . . . . 0 • 0 • 0 0 0 Sync Point Processing in a DEDB
Chapter 7. coding the DL/I Portion of a Program
Before You Code . 0 0 • 0 0 • 0 0Parts of a DL/I Program . 0 0 • 0 0 • 0 • • 0 0 0 0 0 • 0 0 COBOL DL/I Program Structure o. 0 0 • •
PL/I DL/I Program Structure . 0 • • • • 0 Assembler Language DL/I Program Structure
Your Input . . . 0 • • • • • • • • 0 • •
Information You Need about the Program's Design Information You Need about Checkpoints . 0 • • Information You Need about Each Segment . . Information You Need about the Program's Hierarchies Coding the Program Logic . 0 • • • • • • 0 • • • 0 •
Codi ng an Entry Statement . • 0 • • • • Coding DL/I Calls . . . . Coding System Service Calls for'Recovery . • . . Coding System Service Calls for Monitoring
Check i ng Status Codes . . . . Codi ng the Data Area . • . . . . . . .
Codi ng the Parmcount . . 0 0 • • • . 0 • • Cadi ng DL/I Funct i on Codes 0 • • 0 • • • •
GU Functi on Code for COBOL . . . . 0 • • ISRT Function Code for PL/I 0 • • • • •
REPL Function Code for Assembler Language Coding DB PCB Masks
Coding the I/O,Area Codi ng SSAs . . . .
Cod i ng Checl<po in t IDs . . . . GSAM Coding Considerations . . . Coding Fast Path Data Base Calls
Chapter 8. structuring a Message processing Program • • • •
How You Send and Receive Messages: An Overview . • • .DC Calls . . . . . . 0 0 I/O PCB Masks . . . I . 0 • 0 Al ternate PCB Masks 0 0 • • • 0 0 Messages . . 0 0 0 • 0 • 0 • • 0 • 0 What Happens When You Process a Message What Input Messages Look Like
What Output Messages Look Like How You Edit Your Messages
Using Message Format Services Terminals and MFS . . 0 • •
An MFS Example . . 0 • 0 0 0 • • • • MFS Input Message Formats . 0 • • MFS Output Message Formats
Usi ng Basi cEdi t o . 0 0 0 Editing Input Messages
Ed it i ng Output Messages . • . . • . . . Retrieving Messages 0 • 0 0 • 0 0 •
Retrieving the First Segment: GU Retrieving Subsequent Segments: GN Send; ng Messages: ISRT, CHNG, and PURG
Replying to the Sender . . . . • • '
Sendi ng Messages to Other Termi nals . . . • • To One Alternate Terminal
140 141 143 143 144 144 145 145 146 146 148 148 152 152 153 153 154 155 155 155 156 159 162 165 165 166 166 166 166 167 167 167 167 168 168 168 168 169 169 169 169 169 170 170 170 171 172 173 175 176 178 179 180 182 182 183 183 184 184 186 191 192 192 192 192 193 193 193 193 194 194
c:,
)
)
'"
,)
To Several Alternate Terminals . • . . • . Sending Messages to Other Application Programs Communicating with Other IMS/VS Systems
Receiving Messages from Other IMS/VS Systems . . . . Sending Messages to Alternate Destinations in Other
IMS/VS Systems . . . . . Conversations . . . .
A Conversational Example
Conversational Structure . • • .
l~hat the SPA Conta; ns . . . . • • . . . . • • . What Messages look like in a Conversation . . . . • Saving Information in the SPA . . . • • . . . Replying to the Terminal . . . • . . . • . . . Passing the Conversation to Another Conversational
Program . . . . . . • • Conversational Processing and MSC . . . • Ending the Conversation . . . • . . . • . I ssu i ng Commands . . • . . . . • • .
194 195 196 197 19.8 199 199 201 203 204 204 204 205 205 206 Reserv i ng and Releasi ng Segments . • • . 207
Program Isolation Enqueues • • . . The Q Command Code . . . . .
Backing out Data Base Updates: ROLB and ROLE Usi ng ROLB . . . . • . . . • . . • • • • Using ROLL . . . . • • . Us; ng ROLB and ROLL in Conversati ons . .
. . . . 207 207 208 209 210 211 211 Considerations for Message-Driven Fast Path Programs
Retrieving and Sending Messages in Fast Path . . • • • Usi ng ROLB in Fast Path . . . . • • . . .
211 212 Usi ng CHKP in Fast Path . . . . • . . • . . . . • • . 213 213
Chapter 9. coding a Message processing Program
Before You Code . . . .Parts of an MPP . . . . • . . . . • . • • • • • . COBOL NPP Structure • . . • . • • . • . • Pl/! MPP Structure . • . . • • • •
Assembler Language MPP Structure
Your Input . . . . • . . . . • . • • • . . . • • . Information You Need about Your MPP's Design
Information You Need about Input Messages . • • • • Information You Need about Output Messages • • • Information You Need for a Conversational Program Codi ng the Program Log; c • • . • • • • . •
Coding DC Calls . . • • • Coding DC System Service Calls Check i ng Status Codes . . . • • Coding the Data Area
Codi ng I/O Areas. • • • • • • . • . Codi ng I/O PCB f1asks • • • •
Coding Alternate PCB Masks . . • • • • • • • • Codi ng SPAs . • . • • . . • . • • • • • •
Coding a Message-Driven Fast Path Program
Chapter
10.structuring and Coding a
Batc~Message Program
Process; ng Onl; ne Data Bases . • • • •Tools Avai lable to BMPs . • . • • • Sync Po i nts . . . • . . . . • .
Designing Transaction-Oriented BMPs . . • •
Processi ng Messages • . . • • • • . • • • . • Sync Points and Checkpoints in Transaction-Oriented BMPs
Single-Mode Bf1Ps • . . • • .
Multiple-Mode BMPs . . . • • . • • Designing Batch-Oriented BMPs . • • • • •
Chapter 11. Testing an APplication Program
What You Need to Test a ProgramTesti ng DL/I Call Sequences . . • • •
. . . .
Usi ng BTS II to Test Your Program • . What to Do When Your Program Terminates Abnormally
When You Fi nd You Have a Problem • . . • • Finding the Problem • • • • • • • • • • • •
Initialization Errors • • • • • . • • • • •
Execution Errors • • • • . . • • • . • • • • • • • • • Calls You Use for Monitoring and Debugging
.214
214 214 215 216 218 218 218 218 218 219 219 219 219 220 220 220 220 220 220 220
222
222 223 223 224 224 224 224 225 225
227
227 228 229 229 229 230 230 230 231
Contents xvii
xviii
Retrieving IMS/VS System Statistics: STAT Writing Information to the System log: lOG Retr i ev i ng System Addresses: GSCD . • • .
Chapter 12. Documsnting an APplication Program
Documentat i on for Other Programmers • • • • . Documentation for Users . • . • . • • .Part 3. For Your Reference
IHS/VS Entry and Return Conventions
COBOL . . • . • .P l/ I • . . . • • . . Assembler language
DL/I Calls
Dl/I Call Formats COBOL . . . . . PL/I . . . . Assembler language Dl/I Call Parameters
DB PCB
Masks • • • •
COBOL DB PCB Mask . . • . PL/I DB PCB Mask . . . . Assembler Language DB PCB Mask
I/O Area • • • •
COBOL I/O Area . • ..
PL/I I/O Area
Assembler Language I/O Area
Segment Search Arguments • • • •
SSA Coding RulesSSA Codi ng Formats . . . . COBOL SSA Definition Examples PL/I SSA Definition Examples .
Assembler Language SSA Definition
DC Calls . • • • • • •
DC Call Formats COBOL . • . . . PLI I . . . .
Assembler Language DC Call Parameters Summary of DC Calls
System Service Calls • • • • • • •
Symbolic CHKP and XRST Call FormatsCOBOL . . . • P L/ I • • • • • • • • • • • • • Assembler Language
Symbolic CHKP and XRST Parameters Basic CHKP Call Format
COBOL . • . . . • . P LI I • • • • • • •
Assembler Language Basic CHKP Parameters GSCD Call Formats
COBOL . . . • . . •
·PL/I . . . • . . . Assembler Language GSCD Parameters LOG Call Formats
COBOL . . • . . . . PL/ I . . . .
Assembler Language
lOG Parameters . . . • . Restrictions on lOG I/O Area STAT Call Formats
COBOL . • . . . • PL/ I . • . • • • . Assembler Language IMS/VS Application Programming
. . . . .
Examples
.~
... .
231 232 232
234
234 235
237
238 238 238 238 239 239 239 239 239 239
241
241 242 242
243
243 243 243
244
244 245 245 246 247
248
248 248 248 248 248 249 250 251 251 251 251 251 252 252 252 252 252 253 253 253 253 253 254 254 254 254 254 255 255 255 255 255
(
(
)
)
)
STAT Parameters . . . • Status Code Error Routlne Call Format
COBO l . . . • . • • . . . . P l/ I . . . . Assembler language . . . . • . • . . . Status Code Error Routlne Call Parameters
Suggestl0ns . • • .
OEQ Call Formats COBOL . . . .
P l / I • • . . • • • • • • • t
. . . .
,.
Assembler language DEQ Call Parameters ROlB Call Formats
COBOL . . . • • . . Pl/ I . . . . Assembler language ROlB Call Parameters ROll Call Formats
COBOL . . . . P l/ I . . . .
Ass~mbler language ROll Call Parameters
GSAM Reference
GSAM Call Formats COBOL . • . . . P l/ I . . . . Assembler language GSAM Call Parameters GSAM Data Areas
GSAM DB PCB Masks GSAM I/O Areas
GSA~l RSAs . . . . GSAM JCl Restrictions
Fast Path Reference • • • • • • •
Fast Path Data Base Calls . . . .FLO Call Format . . . . COBO l . . . . . . . Pl/! . . . .
Assembler language
. .
,.
.. ,. ,
FLO Call Parameters
pas Ca'l I Format
. . . . . . ...
COBOL . . . . P l/ I . • . . . .
Assembler language . . . . • . POS Call Parameters
Fast Path Data Areas FSAs . . . . POS I/O Area
Fast Path Message Calls . . Fast Path System Service Calls
SYNC Call Format
COBOL . . • . . • • .
P l/I . . . • . .
. .
,. . .
,. .
Assembler language
. . . .
,.
SYNC Call Parameters
IMS/VS status Codes • • • • • • • • •
IMS/VS Status Codes Quick Reference IMS/VS Status Codes ExplanationsAppendixes
APpendix A. Sample Batch Program
Appendix B. Sample Batch Message Program APpendix c. Sample Message Processing Program APpendix D. sample conversational MPP
. . . .
.
,. . , .
255 256 256 256 256 256 257 257 257 257 257 257 258 258 258 258 258 258 258 258 258 258 259 259 259 259 259 259 260 260 261 261 262
263
263 263 263 263 263 264 264 264 264 264 264 265 265 266 266 267 267 267 267 267 267 268 268 272286 287 293
299 302
APpendix E. Sample Status Code Error Routine (DFSOAER) 307
Contents xixAPpendix F. using the DL/I Test Program (DFSDDLTO)
Control Statements . . • •STATUS Statement COMMENTS Statement
Unconditional Conditional
CALL Statement . . .
DATA statement . . . • • . . • • • • Parameter Length, SNAP Calls
Parameter Length, LOG Call • . • . . Segment Length and Checking, All Calls COMPARE statement for PCB Comparisons . COMPARE statement for I/O Area Comparisons OPTION Statement . • . • . . • • Special Control Statements
PUNCH Statement . . . . PUNCH DO Statement
SYSIN2 DO Statement . • • • • Other Control statements . . . . • Speci al CAL L Statements . • . . • •
Execution in Different Regions . • • • . • • • . Suggestions on Using the DL/I Test Program
DL/I Test Program JCL Requirements Sample JCL for the Dl/I Test Program
. . .
. . . .
Index . . . . . . . . . . . . . .
,.... . . . . . . .
316:
ll6 - 3i6 318 318 318 318 320 320 321 321 322 323 324 325 325 326 326 327 327 328 329 330 331 333
(
'\
"-
(
)
)
)
FIGURES
1.
2.
3.
4.
5.
6.
7 • 8.
9.
10.
11.
12. 13.
14.
15. 16.
17.
18.
19.
20. 21.
22.
23.
24.
25. 26.
27.
28.
29.
30. 31.
32.
33.
34.
35.
36.
37 • 38.
39.
40.
41.
42.
43. 44.
45. 46.
47.
48.
49.
50.
51.
52.
53.
54. 55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
Medical Data Base Hierarchy . . . . Accounting Program's View of the Data Base . Patient Illness Program's View of the Data Base Entities and Data Elements . . . • .
Current Roster . . . • . • . .
Example of Data Elements Information Form Single Occurrence of Class Aggregate
Current Roster' Step 1 . . . • • • Multiple Occurrences of Class Aggregate Current Roster Step 2 . . . Current Roster Step 3 . . .
Schedule of Classes . . . Class Schedule Data Elements Class Schedule step 1 . . Instructor 51< i 11 s Report . . Instructor Skills Data Elements Instructor Ski lIs Step 1
Instructor Schedules . .
Instructor Schedules Data Elements . • • . . .
Instructor Schedules Step 1 . • . .
Instructor Schedules Step 2 . • . . . . • Current Roster Task Descri pti on . . . . .
·Summary of IMS/VS Application Program Characteristics Physi cal Employee Segment. . . .
Employee Segment with Field level Sensitivity Patient Hierarchy . . • .
Index i ng a Root Segment . . • • Indexing a Dependent Segment
Patient and Inventory Hierarchies Logical Relationships Example
Supplies and Purchasing Hierarchies Program B ~nd Program C Hierarchies Medical Data Base Hierarchy
Sample Hi erarchy . . • . . . . . Summary tif Symbolic and Basic Checkpoint Calls
Example of SPA Storage DL/I Program Structure
DL/I· Cal,l Parameters. . . • . Unqualified SSA Structure . . . . Qual i fi ed SSA Structure . . .
Unqualified SSA with Command Code Qualified SSA with Command Code D Command Code Example
DB PCB Nask
Medical Hierarchy PATIENT Segment ILLNESS Segment TREATMNT Segment BILLING Segment PAYMEtH Segment
HnUSHOLD Segment . . . •
Hi era rch i c Sequence 0 0 0 0 Cur r en t Po sit ion. Hie r arc h y . o. • • • Hierarchy after Deleting a Segment . . . . . Hierarchy after Deleting a Segment and Dependents Hierarchy after Adding New Segments and Dependents
Position after Not Found Calls . 0 • • • U Command Code Example • . .
Using an SSA with Secondary Indexing Patient and Item Hierarchies o . 0 •
GSAM DB PCB Mask . . . . . . Teller Segment in Fixed Related MSDB . Branch Summary Segment in Dynamic Related MSDB Account Segment in Nonrelated MSDB . . 0 0 •
FSA StructLlre . 0 • • •
COBOL DL/ I Skeleton Program o . • • • PL/I DL/I Skeleton Program . . . • •
4 6 6 13 13 17 18 19 20 20 21 23 23 23 24 24 25 25 26 26 26 29 40 48 48 49 50 51 53 53 54 55 56 58 60 71 78 80 82 82 83 83 84 85 88 89 89 89 90 90 90 94 109 112 112 114 115 125 135 137 141 146 147 147 157 149 160
Figures xxi
68.
69.
70. 71.
73. 72.
74.
75. 76.
77.
78. 79.
80.
81.
82.
83.
84.
85. 86.
87.
88.
89. 90.
91.
92.
93.
94. 95.
96.
97. 98.
99.
i 1 00.
101.
102.
103.
Assembler Language Skeleton Program Summmary of GSAM Calls . . • Basi c MPP Structure • . . I/O PCB Mask • . • Alternate PCB Mask . . . Message Segments . . • • Transaction Message Flow . . Inventory Inquiry MPP Example Input Message Format . . Output Message Format
Message Segment Formats • . . Terminal Screen for MFS Example Option 1 Message Format . .
Opt ion 2 Message Format . . . . . • •
Opti on 3 Message Format . . . . . . . • Message Format for Program-to-Program Message Switch MSC Example . . . . • . . .
Di rected Rout i ng Bit in I/O PCB • . . Directed Routing Output Message Format
SPA Format . .
Progra~ Isolation Example Q Command Code Example Comparison of ROlB and ROLL COBOL ~1PP Skeleton . . Pl/I MPP Skeleton . . . log Record Format . . DB PCB Mask • •
Relational Operators
Summary of DC Calls . Summary of System Service"Calls GSAM DB PCB Mask Format . . GSAM JCl Restrictions . . . .
Summary of Fast Path Data Base Calls
Fast Path Message Calls . • • . • . . Fast Path System Service Calls
IMS/VS Status Codes Quick Reference
163 170 174 177 179 180 181 182 182 183 187 188 188 189 191 196 197 198 198 203 208 208 210 215 216 232 241 244 249 250 260 262 263 266 269 267
(
(
) \
)
- - - - ---- - - -
PART 1. APPLICATION DESIGN GUIDE
This part of the book gives you an introduction to IMS/VS, and covers the decisions that you have to make when you are designing an IMS/VS application. The introductory material and the tasks that this part covers are:
• concepts
~ndTerminology
• Analyzing Application Requirements
• Understanding Online and Batch processing
• Gathering Requirements for Data Base options
• Gathering Requirements for Data communications options
Part 1. Application Design Guide 1
CHAPTER 1. CONCEPTS AND TERMINOLOGY
This chapter is an introduction to IMS/VS, and to designing and coding IMS/VS application programs. The first section explains some basic concepts about processing a data base, and the second section gives an overview of the tasks covered in this book:
• processing Information in a Data Base
This section explains the concepts and terms that you need to understand before reading the chapters that follow.
• A look at the Tasks Ahead of You
This section describes what you do to design and code IMS/VS application programs.
PROCESSING INFORMATION IN A DATA BASE
Before explaining what data base records look like and how you process them, this section describes what makes storing data in a data base different from other ways of storing data.
COMPARING WAYS TO STORE DATA
The advantage of storing and processing data in a data base is that all of the data appears only once, and that each program has to process only the data that it needs. One way to understand this is to compare three ways of stori ng data: in separate fi les, ina
I /
combined file, and in a data base. (
storing Data in separate Files
If you keep separate files of data for each part of your
organization, you can make sure that each program uses only the data it needs, but you have to store a lot of the data in several places at once. The problem with this is that redundant data takes up space that could be used for something else.
For example, suppose that a medical clinic keeps separate files for each of its departments, such as the clinic department, the accounting department, and the ophthalmology department.
• The clinic department kee.ps data about each patient that visits the clinic. For each patient, the clinic department needs to keep this information:
The patient's identification number The patient's name
The patient's address The patient's illnesses The date of each illness
The date that the patient came to the clinic for treatment The treatment that was given for each illness
The doctor that prescribed the treatment The charge for the treatment
\ ,
