idms batch cobol programming

7/14/2019 IDMS Batch COBOL Programming

http://slidepdf.com/reader/full/idms-batch-cobol-programming 1/52

IDMS BATCH COBOL PROGRAMMING

by Neal WaltersAmerisoft Inc. © 1998

Last Updated: November 17, 1998

This document is licensed for use by

customers of the IDMS Tutorial program

from Amerisoft Inc.

Intended Audiences:

1) Batch COBOL Programmers

2) Or CICS/PL1 programmers who need

an overview of Batch IDMS Programming

Major Topics:

1) Details on how to code and maintain Batch COBOL IDMS programs2) Brief overview of IDMS and DBMSs

3) How to compile programs

4) Testing and debugging techniques

5) Error Handling

6) DML Verbs

To be used in conjunction with IDMS FUNDAMENTALS

course book by Amerisoft Inc.

email: [email protected]

web site: http://www.amerisoftinc.com/mainframe.htm



IDMS COBOL Programming page ii

by Neal Walters, Amerisoft Inc. © 1998 Use by license agreement only.

Table of Contents

Overview of Network Databases .........................................................................................1

DBMS Overview............................................................................................................. 1

Why a DBMS? ................................................................................................................1

IDMS and SQL ...............................................................................................................2IDMS Overview ..............................................................................................................3

IDMS Schema or Bachman Diagram................................................................................4

DML - Data Manipulation Language ...............................................................................5

Two useful Tools.............................................................................................................6

CA/IDMS Manuals Relating to DML and COBOL:.........................................................6

The DML Precompiler.........................................................................................................6

Precompiler Options ........................................................................................................7

Precompiler Directives.....................................................................................................9

ENVIRONMENT DIVISION .....................................................................................9

DATA DIVISION: SCHEMA SECTION AND WORKING-STORAGE .................. 11

Figure 8 shows where the SCHEMA SECTION is added to the program, and how tocopy IDMS records into the program......................................................................... 11

PROCEDURE DIVISION DECLARATIVES........................................................... 12

ERROR HANDLING........................................................................................................14

Autostatus vs Non-Autostatus .......................................................................................14

IDMS-STATUS Routine ...............................................................................................17

MVS JOB LOG.............................................................................................................19

The Program’s SYSOUT............................................................................................... 20

IDMS Error Status ........................................................................................................20

IDMS RETRIEVAL COMMANDS ..................................................................................21

1) FIND/OBTAIN CALC/DUPLICATE........................................................................ 22

2) FIND/OBTAIN CURRENT and 6) FIND/OBTAIN NEXT WITHIN SET/AREA.... 24

3) FIND/OBTAIN DBKEY........................................................................................... 26

4) FIND/OBTAIN OWNER WITHIN set-name ............................................................ 27

5) FIND/OBTAIN WITHIN SET USING SORT KEY..................................................28

IDMS UPDATE COMMANDS ........................................................................................29

MODIFY EXAMPLE: ..................................................................................................30

STORE EXAMPLE: .....................................................................................................31

ERASE COMMAND:...................................................................................................32

ERASE EXAMPLE ......................................................................................................33

CONNECT AND DISCONNECT................................................................................. 34

CONNECT EXAMPLE:............................................................................................35DISCONNECT EXAMPLE: .....................................................................................35

OTHER REQUIRED COMMANDS:................................................................................36

The READY Command................................................................................................. 37



IDMS COBOL Programming page iii


The COMMIT Command ..............................................................................................38

The TWO BIND Commands..........................................................................................41

The FINISH and ROLLBACK Commands .................................................................... 42

IDMS Online Programming...............................................................................................43

IDMS Online Programming Overview ........................................................................... 43

Sample IDMS/DC Commands .......................................................................................44Overview of ADS ..........................................................................................................45

Overview of CICS .........................................................................................................46

Overview of IDMS/DC..................................................................................................46

Overview of Native VSAM............................................................................................ 46

Maintaining IDMS Programs............................................................................................. 47

Files on CD/ROM..............................................................................................................49



IDMS COBOL Programming page 1


Overview of Network Databases

DBMS Overview A DBMS (Database Management System) is an advanced method of maintaining data.

Many sites have left sequential and random files behind and develop all new systems under a

DBMS.

There are three types of DBMS:

1) relational (such as DB2/SQL or Oracle)

2) hierarchical (such as IMS)

3) network (such as IDMS)

Relational database deal with “tables” where the COBOL program can issue SQL commands to

select and join from various tables. Each table is similar to a flat file, and each “row” in the table is

the same as a record in the flat file.

A hierarchical database establishes a parent child relationship between records.

A netwhork database is similar to a hierarchical database, but is more flexible in that the

relationships can be more complex. For example, a child record can have more than one parent.

Many companies adopted IDMS as the Database of choice in the 80s. Although in the late 90s,

most companies are using relational databases, IDMS still has a strong foothold in major

corporations around the world. If often costs millions of dollars to convert a system from one

DBMS technology to another, so many companies continue to run older systems until they are

obsolete or can be re-written. Other companies still believe that IDMS is a better choice than

today’s relational alternatives. IDMS was originally marketed by a company called Cullinet, but is

now sold and supported by Computer Associates.

Why a DBMS?

A DBMS typically has the following benefits over sequential and VSAM files:

1) centralized control often with a data dictionary or repository for the meta-data (i.e. the

data about the data) and controlled by the database administration group

2) concurrent batch and online update and retrieval3) improved recovery (backout or rollback procedures)

4) improved record locking to prevent simultaneous update of same record(s) and to allow

programs to wait for a lock to be released - then continue execution.





I DM S and SQL

With release 12.0 of IDMS, an SQL option became available as an extra-cost product. Since

SQL is covered in another chapter of this book, IDMS/SQL will not be discussed in this chapter.

One of the unique aspects of the IDMS/SQL option is that SQL can be used against either an

IDMS/Relational database or an IDMS/Network database. Another advantage of the SQL option

is the ODBC capability to download data to PCs or to access IDMS mainframe data on clientserver platforms.





I DM S Overview

In IDMS terminology, a parent record is called an OWNER, and a child record is called a

MEMBER. Records are connected to each other via SETs. All database relationships are

predefined in a schema. A subschema is a smaller view of the schema that a COBOL program

uses to access the database. Some sites have one large global subschema, while other sites havemany small subschemas. When dealing with IDMS, there is usually a Database Administration

(DBA) group that is responsible for defining the databases (and for keeping the production

databases well organized).

IDMS records are stored in IDMS areas, each of which has a physical page range. The page

range and page size of each area determines how much space is available in any given area.

Usually, each area is mapped to one physical file (data set), but in the cases of large areas, one

area may be mapped to a series of data set names. It is also possible for one physical data set to

contain several areas. In IDMS 12.0 and after, several related areas are grouped together to form

a SEGMENT. Segments, buffering, and journalling all defined in a DMCL (Device Media

Control Language) created by the DBA.

Each IDMS record occurrence, when stored, is assigned a DBKEY, which consists of the page-

number and line-index (usually between 1 and 256). DBKEYs are referenced as an S9(8) COMP

field in COBOL. To convert this number to a page and line number, usually the dbkey is divided

by 256 to get the page number, and the remainder is the line number (see the sample IDMS

programs on the CD/ROM for a program that converts DBKEYs from one format to another and

gives full details.)

An IDMS system is called a Central Version, or CV for short. It is common to say that the test

CV will come down at 9 pm and back up at 6 am. When the IDMS CV is down, IDMS

programmer testing may be limited. Some sites have different CVs for different applications, for

instance a development CV, a maintenance CV, a Y2K Conversion CV, and a production CV.

IDMS programs can run in local-mode or “under the CV.” When running “under the CV,” all

database I/O is done by by the Central Version (one task running on the computer). Usually, for

the sake of speed, retrieval only jobs run in local-mode, and update jobs run “under the CV” to

allow for concurrent update and record locking. While update jobs can be run in local mode, this

feature is seldom used because the areas must be varied out of update mode - thus preventing

online and other batch jobs from concurrent update. This is sometimes done on weekends to

speed up long running batch jobs. Running “under the CV” incurs typical DBMS overhead such

as journalling, buffering, and record-locking. All online programs always run “under the CV.”

Most sites use the presence of a //SYSCTL JCL statement to indicate that the job is running

“under the CV”.





I DM S Schema or Bachman Diagram

Most IDMS sites publish a book or chart of schema diagrams, also called “Bachman”

diagrams (after Charles Bachman, one of the pioneers in database technology). Each IDMS

record-type is illustrated by a box. A set relationship is shown by connecting two records-

together. All sets represent a one-to-many relationship (where the point of the arrow indicatesthe child relationship).

IDMS records can be stored in three “location modes:”

1) CALC - a randomly assigned “hash” key, based on any logical key(s) in the record

2) VIA - records are physically stored near their owner record (this allows for extremely

rapid access)

3) DIRECT - this storage mode is most commonly used for audit trails (the record can be

stored with the highest dbkey in the area, or a specific dbkey can be provided and the record is

stored at that location)

???Editor: I have asked Computer Associates for permission toreprint this schema diagram - but have not yet received anything

from them in writing. They should be in contact with Tracy

Dunkelberger.

Figure 23.1. IDMS Schema Diagram (Employee Demo Database)

* * I ns er t f i gur e her e - I am s endi ng a phot oc opy of a di agr am f r om

a Comput e r As s oc i a t e s Ma nu al . I d o n ot h av e t h i s d i a gr am i n

c omput e r f or mat . ( Th i s i s t he onl y f i gur e i n t h i s doc ument - a l l

ot her ex ampl es ar e “ l i s t i ngs ” . ) * *





Each bachman record box consist of four lines:

line 1 contains the record-name

line 2 contains the record-id,

F,FC,V,VC for Fixed, Fixed Compressed, Variable, Variable Compressed

the record length (in bytes)the location mode (CALC, VIA, or DIRECT)

line 3 contains the CALC key or VIA SET-NAME,

followed by the duplicates option

(DN=Duplicates Not Allowed,

DF=Duplicates First, DL=Duplicates Last)

line 4 contains the physical AREA-NAME

Some sites add the approximate record occurrence count on the fourth line. This

sometimes helps the programmer to create a faster navigation path.

Usually, a copy of the IDMSRPTS utility is used with the schema diagram. This report

contain the same information that is on the diagram, along with a full listing of all the elements in

each record.A triangle symbol on a schema diagram represents an indexed set. This is a set that has a

pre-defined sort key assigned. Indexes are used 1) as a rapid access entry point into the database

based on a logical key value and 2) as a means of quickly displaying sorted data on an online

retrieval transaction.

DM L - Data Manipulation Language

IDMS databases are maintained by executing DML (Data Manipulation Language)

commands. The same commands can be used from COBOL, Assembler, PL/1 or even

FORTRAN. The DML commands allow the programmer to “navigate” the database (using

“OBTAIN” commmnds) and to make changes by issuing simple commands like “MODIFY”,

“STORE” and “ERASE.”

The differences between DML and SQL show that there are two primary differences

between an IDMS network database and a relational database:

1) With IDMS, all the set relationships are pre-defined, i.e. a program cannot issue a JOIN

between two record types. There must be a pre-defined set relationship between the two record

types (and this set relationship is drawn on the schema diagram).

2) With IDMS, the programmer chooses the his preferred database navigation strategy

(which hopefully is the fastest). With relational databases, the programmer just queries for the

desired data, and the DBMS chooses the access logic. Thus, as the metrics of an IDMS database

change, a program’s DML navigation may become slower. Sometimes, the program’s runtime can

be improved by changing the DML navigation path. For example, it might be better to walk an

index set when there are only 100 records in the database, but when there are one million records,

it might be faster to do an area sweep for the same records.





Two usefu l Tools

Computer Associates (CA) has an additional-cost product called “DMLO” which stands

for Data Manipulation Language Online. A competitor product called “DBOL” (Database

Online) is sold by Allen Systems Group. These two products allow programmers to issue and

practice DML commands online and interactively. A programmer often uses these products for

the following purposes:1) to test a DML navigation path before writing a COBOL program

2) to help debug a COBOL program by verifying DML navigation or values of fields in a database

CA/IDMS Manuals Relating to DM L and COBOL:

BooknameinIBM/READER

Order Number Manual Name

CAIDDMLC R005/&F0CBE CA-IDMS DML Reference -COBOL

CAIDNDML R005/&F0NPE CA-IDMS DML Navigational DMLProgramming

CAIDMSG R005/&F0M1ER005/&F0M2ER005/&F0M3ER005/&F0M4E

CA-IDMS Messages and Codes(Volumes 1 through 4)

CAIDQPRG RC05/&F0PQE CA-IDMS Programming QuickReference

Figure 1 -Recommended IDMS Manuals for COBOL Programmers

The DML Precompiler

The DML Precompiler, also called the DML pre-processor, converts

high-level DML (Data Manipulation Language) statements tostandard COBOL calls to the appropriate IDMS subroutine.

A sample JCL (Job Control Language) to execute the preprocessor,the COBOL compiler, and the linkage editor can be found in fileCOMPJCL on the CD/ROM that accompanies this book.

Figure 2 and Figure 3 show the DML code before and afterexpansion by the DML precompiler. Since “OBTAIN CALC” is notrecognized by COBOL, the DML Precompiler converts this statementto a “CALL ‘IDMS’” statement with the appropriate usingparameters. Most programmers to do not need to understand the

format of the “CALL ‘IDMS’”, because the code is maintained inthe high-level DML language.

Note two things about this example:





1) The “OBTAIN CALC” statement remains in the program, butis commented out

2) A unique DML-SEQUENCE number is assigned to each CALL toIDMS. This DML-SEQUENCE number is displayed in the IDMS ERROR-STATUS routine; thus, if the program fails with a bad IDMS

STATUS, the DML-SEQUENCE number is used to identify which IDMSDML VERB caused the problem.

028400 1000-OBTAIN-EMPLOYEE.028500 MOVE '123456789' TO EMPLOYEE-NUM

028600 OBTAIN CALC EMPLOYEE-REC

028800 IF DB-REC-NOT-FOUND028900 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT

029000 ELSE

029010 PERFORM IDMS-STATUS029100 PERFORM 1200-EMP-FOUND THRU 1200-EXIT

029200 END-IF

029300 .029400 1000-EXIT. EXIT.

Figure 2 - Code Submitted to DML Preprocessor

000332 1000-OBTAIN-EMPLOYEE.

000333 MOVE '123456789' TO EMPLOYEE-NUM000334 * OBTAIN CALC EMPLOYEE-REC

000335 MOVE 4 TO DML-SEQUENCE

000336 CALL 'IDMS' USING SUBSCHEMA-CTRL000337 IDBMSCOM (32)

000338 SR2001

000339 IDBMSCOM (43);000340 IF DB-REC-NOT-FOUND

000341 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT

000342 ELSE000343 PERFORM IDMS-STATUS

000344 PERFORM 1200-EMP-FOUND THRU 1200-EXIT

000345 END-IF000346 .

000347 1000-EXIT. EXIT.

Figure 3 - Code as Output from the DML Preprocessor

Precompil er Options

PRECOMPILER OPTIONS tell the precompiler how to do its work.

*RETRIEVAL

*DMLIST

*NODMLIST

NOTE: These three lines are standard COBOL comments (the asteriskshould begin in column 7).





A feature of the DML PRECOMPILER is that it can update the IDMSIntegrated Data Dictionary (IDD) each time the program iscompiled. This can be both a blessing and curse. The advantageis that detailed information about the program will beautomatically documented in the dictionary. The disadvantage isthat large programs can create a large number of record locks on

the dictionary, causing other IDD users and other programprecompiles to slow down or to ABEND with deadlocks.

Figure 4 shows a sample of program information that isautomatically stored in IDD by the precompiler. This informationis available within the online task “IDD” or by running a batchIDD job.DIS PROG DBATDEMO AS SYN.

ADDPROGRAM NAME IS DBATDEMO VERSION IS 1

*+ DATE CREATED IS 04/14/98

*+ DATE LAST COMPILED IS 04/14/98*+ NUMBER OF TIMES COMPILED IS 1

PUBLIC ACCESS IS ALLOWED FOR ALL

ESTIMATED LINES ARE 339PROGRAM CALLED IS IDMS VERSION IS 1

PROGRAM CALLED IS IDMSERR1 VERSION IS 1

PROGRAM CALLED IS ABORT VERSION IS 1MODULE USED IDMS-STATUS VERSION IS 11 LANGUAGE IS COBOL

RECORD COPIED SUBSCHEMA-CTRL VERSION IS 2

RECORD COPIED EMPLOYEE-REC VERSION IS 1RECORD COPIED DB-STATISTICS VERSION IS 1

SUBSCHEMA IS DBATSS01 OF SCHEMA DBATSC01 VERSION IS 1

AREA DBATEST1-AREA READIED FOR UPDATERECORD EMPLOYEE-REC BIND

RECORD EMPLOYEE-REC OBTAIN

MODE IS BATCHLANGUAGE IS COBOL

.

Figure 4 - IDD “Display Program”

Figure 5 shows how the IDD can also cross-references records backto programs:

DIS REC EMPLOYEE-REC WITH PROGRAMS AS SYN.

ADD

RECORD NAME IS EMPLOYEE-REC VERSION IS 1RECORD NAME SYNONYM IS EMPLOYEE-REC VERSION 1

*+ COPIED INTO PROGRAM DBATDEMO VERSION 1

.

Figure 5 - IDD “Display Record”

Most cross reference information can be also be obtained byscanning the source code (using TSO/ISPF 3.14, PANSCAN for

Panvalet, or a Librarian Scan for Librarian). Therefore, manysites disable the auto-update of the dictionary by including the“*RETRIEVAL” command at the top of each program. This is oftendone by your compile PROC which concatenates a one line member





that contains just the line “*RETRIEVAL”. An advantage ofrunning in RETRIEVAL mode is that the program can run in localmode rather than CV mode.

NOTE: The precompiler runs vary fast for small subschemas, butwhen a subschema contains 50 or 100 or 150 records, the

precompiler can run for several minutes.

The *DMLIST or *NODMLIST option specifies that the source listingit to be displayed as output from the preprocessor. The defaultis “*NODMLIST”. A listing of error messages is always produced.However, the errors typically point to the line number of theerror, and with *NODMLIST is can be difficult to find the error.

Precompiler D ir ectives

PRECOMPILER DIRECTIVES also affect the way the DML PRECOMPILERworks.

ENVIRONMENT DIVISION

The first required directive is the IDMS-CONTROL SECTION in theENVIRONMENT DIVISION and is shown in Figure 6.

008700 ENVIRONMENT DIVISION.008800 INPUT-OUTPUT SECTION.

009000 FILE-CONTROL.

009100 SELECT INPUT1-FILE ASSIGN TO INPUT1.009200

009300 IDMS-CONTROL SECTION.

009400 PROTOCOL. MODE IS BATCH DEBUG009500 IDMS-RECORDS MANUAL.

Figure 6 - Precompiler/Environment Division

In place of the word “BATCH” (in the above figure), specify IDMS-DC for online programs (programs that will use IDMS services suchas MAPIN/MAPOUT), or DC-BATCH for programs that run in batch butrequire DC services such as “GET QUEUE”, or CICS-AUTOSTATUS.





There are several common modes listed below. Check with the DBAor reference manual for a complete listing. Some sites may alsohave defined their own customized “modes.”

BATCH Typical batch program

BATCH-AUTOSTATUS Typical batch program with AUTOSTATUS on

CICS Typical CICS program

CICS-AUTOSTATUS Typical CICS program with AUTOSTATUS on

DC-BATCH For batch programs that need some typicallyonline services such as GET QUEUE or PUT QUEUE.

IDMS-DC For online IDMS programs that will use IDMSservices such as MAP IN, MAP OUT, READ TERMINAL,or GET QUEUE

Figure 7 - Common Modes

The word DEBUG is optional (but almost always used), and causesthe DML-SEQUENCE numbers to be generated for each DML VERB. TheAUTOSTATUS protocols are discussed in the next section on ERROR-HANDLING.

The “IDMS RECORDS MANUAL” clause specifies that the program willmanually include the required “COPY IDMS” statements in theWORKING-STORAGE or LINKAGE SECTION. Instead, if “IDMS RECORDS

WITHIN WORKING-STORAGE” is specified, then all records in theentire subschema will automatically be copied into the program.This works fine for small subschemas, but may be inappropriatefor larger subschemas.





DATA DIVISION: SCHEMA SECTION AND WORKING-STORAGE

Figure 8 shows where the SCHEMA SECTION is added to the program, and how to copy

IDMS records into the program.010000 DATA DIVISION

010100 FILE SECTION.

010200 FD INPUT1-FILE010300 LABEL RECORDS ARE STANDARD

010400 BLOCK CONTAINS 0 RECORDS.

010500 01 INPUT1-REC PIC X(80).010600

010700 SCHEMA SECTION.

011000 DB DBATSS01 WITHIN DBATSC01.011100

011200 WORKING-STORAGE SECTION.

011300011400 COPY IDMS SUBSCHEMA-CONTROL.

011500 COPY IDMS RECORD EMPLOYEE-REC.

011600 COPY IDMS DB-STATISTICS.

Figure 8 - Precompiler/Data Division

The SCHEMA SECTION simply identifies the name of the schema andsubschema. Each source program can only access one schema (acalled subroutine can be used to access data from a differentschema).

In the WORKING-STORAGE section, “COPY IDMS” statements are usedto build the required record layouts from the data dictionary(IDD). (If the “IDMS RECORDS WITHIN WORKING-TORAGE” clause wasused, then all subschema records are automatically copied, and“COPY IDMS record” statements do not need to be coded.

The “SUBSCHEMA-CONTROL” is actually a special code word for fourrecord-names: SUBSCHEMA-CTRL, SUBSCHEMA-RECNAMES, SUBSCHEMA-SETNAMES, and SUBSCHEMA-AREANAMES. Every program must includethese, as they are used in the “CALL ‘IDMS’” statements.

DB-STATISTICS is a optional record used with the “ACCEPTSTATISTICS” command. Many programs ACCEPT and display the IDMSstatistics at the end of the program. This information isextremely useful for debugging and/or improving performance of aprogram.





PROCEDURE DIVISION DECLARATIVES

Figure 9 and Figure 10 show how and where the “COPY IDMSSUBSCHEMA-BINDS” (the first listing is before the DMLprecompiler, the second listing is after the expansion by theprecompiler).

025800 0500-INITIALIZE.

025900026000 ACCEPT TODAYS-DATE FROM DATE.

026100 ACCEPT TODAYS-TIME FROM TIME.

026200 DISPLAY 'START: DBATDEMO - RELOAD AUDHST-RECS '026300 DISPLAY 'DATE = ' TODAYS-DATE

026400 ' TIME = ' TODAYS-TIME.

026700026710 COPY IDMS SUBSCHEMA-BINDS.

028000 0500-EXIT.

028100 EXIT.

Figure 9 - Precompiler Directives in the Procedure Division





0500-INITIALIZE.

ACCEPT TODAYS-DATE FROM DATE.

ACCEPT TODAYS-TIME FROM TIME.DISPLAY 'START: DBATDEMO - RELOAD AUDHST-RECS '

DISPLAY 'DATE = ' TODAYS-DATE

' TIME = ' TODAYS-TIME.

* COPY IDMS SUBSCHEMA-BINDS.

MOVE 'DBATDEMO' TO PROGRAM-NAME* BIND RUN-UNIT

MOVE 1 TO DML-SEQUENCE

CALL 'IDMS' USING SUBSCHEMA-CTRLIDBMSCOM (59)

SUBSCHEMA-CTRL

SUBSCHEMA-SSNAME;* BIND JOB-REC



SR2003

JOB-REC;* BIND EMPLOYEE-REC.


CALL 'IDMS' USING SUBSCHEMA-CTRL

IDBMSCOM (48)SR2001

EMPLOYEE-REC.

0500-EXIT.

EXIT.

Figure 10 - Same after Precompiler Expansion

The “COPY IDMS SUBSCHEMA-BINDS” accomplishes three things:

1) The program-name from the PROGRAM-ID statement is moved to afield called “PROGRAM-NAME”. This is useful to the DBA whenmonitoring the system.

2) The “BIND RUN UNIT” statement is generated

3) A “BIND RECORD” statement is generated for each databaserecord (either each record in the subschema or each recordincluded into the program with “COPY IDMS” statements).

This COPY statement does NOT generate a READY statement for eachdatabase area.

NOTE: Some sites make use of Logical Record Facility (LRF) whichresults in several changes to this information in this section.LRF allows the DBA or programmers to create logical records in

the subschema - where a logical record consists of one or morephysical records. Special processing logic is actually coded inthe subschema, special return-codes can be set, and much of thedatabase navigation is done by the subschema instead of the COBOL





program. Any site using LRF should have special instructionsavailable for its unique implementation.

ERROR HANDLING

Autostatus vs Non-Autostatus

Note that some modes (see Figure 7) contain the word“AUTOSTATUS.” This causes the precompiler to automaticallygenerate a “PERFORM IDMS-STATUS” statement after each DMLcommand. It is a matter of a site’s coding standards or aprogrammer’s own personal preference as to whether autostatus isused.

Some people prefer AUTOSTATUS, because if a programmer forgets tocheck the ERROR-STATUS and the program keeps running, then logicerrors occur which can be difficult to debug. Some people prefer

not using AUTOSTATUS because the code looks cleaner. Use ofAUTOSTATUS requires coding an “ON” statement for any “allowable”errors. For instance, an ERROR-STATUS of 0326 or DB-REC-NOT-FOUND is common when doing an OBTAIN CALC DML command. Thus,when using AUTOSTATUS, the programmer must code one “ON error”statement for each anticipated status.

Figure 11 shows a program coded to use AUTOSTATUS, and Figure 12shows the same code after it is expanded by the DML precompiler.

There are several COBOL 88-level working-storage variablesdefined for the most common IDMS error codes. The definition ofthese 88-levels is available in Figure 15.



028700 ON DB-REC-NOT-FOUND028800 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT

028900 .

029000 PERFORM 1200-EMP-FOUND THRU 1200-EXIT029100 .

029200 1000-EXIT. EXIT.

Figure 11 - Sample OBTAIN with AUTOSTATUS





The above code gets translated to the following000336 1000-OBTAIN-EMPLOYEE.

000337 MOVE '123456789' TO EMPLOYEE-NUM

000338 * OBTAIN CALC EMPLOYEE-REC000339 * ON DB-REC-NOT-FOUND

000340 MOVE 4 TO DML-SEQUENCE

000341 CALL 'IDMS' USING SUBSCHEMA-CTRL000342 IDBMSCOM (32)

000343 SR2001000344 IDBMSCOM (43)000345 IF NOT DB-REC-NOT-FOUND PERFORM IDMS-STATUS;

000346 ELSE

000347 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT000348 .

000349 PERFORM 1200-EMP-FOUND THRU 1200-EXIT

000350 .000351 1000-EXIT. EXIT.

Figure 12 - Same after precompiler expansion

Figure 13 shows the same code as Figure 12 when not usingAUTOSTATUS. The programmer should code the appropriate “PERFORMIDMS-STATUS” after each DML verb (after checking for any normallyexpected errors - such as the DB-REC-NOT-FOUND condition). Note

the addition of line 28950.



028700 IF DB-REC-NOT-FOUND028800 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT

028900 .

028950 PERFORM IDMS-STATUS029000 PERFORM 1200-EMP-FOUND THRU 1200-EXIT

029100 .

029200 1000-EXIT. EXIT.

Figure 13 - Obtain with NON-AUTOSTATUS

Some programmers will CODE a variation of the Figure 13 as shown

in Figure 14(note the addition of line 28910). This avoidsperforming the IDMS-STATUS paragraph unless needed but results intwo lines of code error-checking code instead of one.

028400 1000-OBTAIN-EMPLOYEE.

028500 MOVE '123456789' TO EMPLOYEE-NUM

028600 OBTAIN CALC EMPLOYEE-REC028700 IF DB-REC-NOT-FOUND

028800 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT

028900 .028910 IF DB-ANY-ERROR

028950 PERFORM IDMS-STATUS.

029000 PERFORM 1200-EMP-FOUND THRU 1200-EXIT029100 .

029200 1000-EXIT. EXIT.

Figure 14 - Alternative Coding





*COPY IDMS SUBSCHEMA-CONTROL.

01 SUBSCHEMA-CTRL.03 PROGRAM-NAME PIC X(8)

VALUE SPACES.

03 ERROR-STATUS PIC X(4)VALUE '1400'.

88 DB-STATUS-OK

VALUE '0000'.88 ANY-STATUS

VALUE ' ' THRU '9999'.

88 ANY-ERROR-STATUSVALUE '0001' THRU '9999'.

88 DB-END-OF-SET

VALUE '0307'.88 DB-REC-NOT-FOUND

VALUE '0326'.

03 DBKEY PIC S9(8) COMP SYNC.

Figure 15 - Error-Status and 88-levels





I DMS-STATUS Routine

Figure 16 shows the common code that is copied into all batchIDMS programs. Your site may have made minor modifications tothis code. The code itself is stored on the data dictionary(IDD) as a module with source code. The CALL ‘ABORT’ statementresults in the U2222 Abend as shown in Figure 16.

*COPY IDMS IDMS-STATUS.******************************************************************

IDMS-STATUS.

************************ V 33 BATCH-AUTOSTATUS ********************IDMS-STATUS-PARAGRAPH.

IF NOT DB-STATUS-OK

PERFORM IDMS-ABORTDISPLAY '**************************'

' ABORTING - ' PROGRAM-NAME

', ' ERROR-STATUS', ' ERROR-RECORD

' **** RECOVER IDMS ****'

UPON CONSOLEDISPLAY 'PROGRAM NAME ------ ' PROGRAM-NAME

DISPLAY 'ERROR STATUS ------ ' ERROR-STATUSDISPLAY 'ERROR RECORD ------ ' ERROR-RECORDDISPLAY 'ERROR SET --------- ' ERROR-SET

DISPLAY 'ERROR AREA -------- ' ERROR-AREA

DISPLAY 'LAST GOOD RECORD -- ' RRECORD-NAMEDISPLAY 'LAST GOOD AREA ---- ' AREA-NAME

DISPLAY 'DML SEQUENCE--------' DML-SEQUENCE

* IN-HOUSE CUSTOMIZATION - CHANGED "ROLLBACK"* TO A HARD-CODED CALL - TO AVOID "AUTOSTATUS"

* ADDING A "PERFORM IDMS-STATUS" AFTER THE ROLLBACK COMMAND

* AND THUS CREATING AN ENDLESS LOOP IN THIS PARAGRAPH* (WHICH WOULD NOW FLOOD THE CONSOLE WITH THE IDMSERR1 MESSAGES.

* ROLLBACK


IF ANY-ERROR-STATUS

DISPLAY 'ROLLBACK FAILED WITH STATUS='ERROR-STATUS

DISPLAY 'ROLLBACK FAILED WITH STATUS='ERROR-STATUS UPON CONSOLE

END-IF

CALL 'ABORT'

.IDMS-ABORT SECTION.

IDMS-ABORT-EXIT.

EXIT.

Figure 16 - IDMS-STATUS Paragraph

There are several versions of the IDMS-STATUS routine, and theappropriate one is copied from the IDD based on the “MODE IS”clause of the PROTOCOL statement. A site may have customtailored this routine to provide additional functionality.

The IDMS-STATUS routine should be performed after each DML Verbafter checking for anticipated errors. An example of ananticipated error is 0326 or DB-REC-NOT-FOUND. This occurs





frequently and the program should handle such an error. If thereis an unexpected error, the program will ABORT with a U2222 (alsocalled a USER 2222 ABEND). An example of an unexpected errormight be an 0069 or 1469 - which means that the IDMS/CentralVersion went down - and thus the program cannot continue. In thecase of an U2222 ABEND, the programmer must look at the DISPLAY

statements found in the //SYSOUT and the job log.





MVS JOB LOG

Figure 17 shows the MVS output of a batch job with a U2222 ABEND. The key error messages

are highlighted in bold.

The job log on MVS would look something like this:J E S 2 J O B L O G -- S Y S T E M G S L P -- N O D

10.15.37 JOB05801 IRR010I USERID USERID1 IS ASSIGNED TO THIS JOB.

10.15.38 JOB05801 ICH70001I USERID1 LAST ACCESS AT 10:13:47 ON WEDNESDAY, JULY

10.15.38 JOB05801 $HASP373 NRWDTSTE STARTED - INIT 12 - CLASS N - SYS ABCD10.15.38 JOB05801 IEF403I NRWDTSTE - STARTED - TIME=10.15.38

10.16.45 JOB05801 +IDMS DB347011 dbname XXXXXXXX invalid - binding subschema is

10.16.46 JOB05801 +************************** ABORTING - TESTERR1, 1477,

10.16.46 JOB05801 +IDMS RUN-UNIT CANCELLED DUE TO PROGRAM REQUEST

10.16.46 JOB05801 IEA995I SYMPTOM DUMP OUTPUT USER COMPLETION CODE=2222

TIME=10.16.45 SEQ=04261 CPU=0000 ASID=0031PSW AT TIME OF ERROR 078D1000 851000DE ILC 2 INTC 0D

ACTIVE LOAD MODULE ADDRESS=05100080 OFFSET=0000

NAME=IDMSCANCDATA AT PSW 051000D8 - 00181610 0A0D1814 0A0D0700

GPR 0-3 80000000 800008AE 0000CB08 00006D60

GPR 4-7 000008AE 0004B298 051000B4 851000A4GPR 8-11 80012BE0 0000A6A0 0004ACC0 851000A4GPR 12-15 80012662 0004AFE8 80012BDE 00000000

END OF SYMPTOM DUMP

10.16.46 JOB05801 IEC130I SYSABOUT DD STATEMENT MISSING10.16.46 JOB05801 +IGZ043I A 'SYSABOUT' error occurred. The ABEND information

10.16.46 JOB05801 + incomplete.

10.16.46 JOB05801 +IGZ057I An ABEND was intercepted by the COBOL run-time ABEN10.16.46 JOB05801 + It is described by a corresponding IEA995I message.

10.16.46 JOB05801 IEF450I NRWDTSTE STEP01 - ABEND=S000 U2222 REASON=00000000

TIME=10.16.46

10.16.46 JOB05801 *END STEP STEP01 OF NRWDTSTE TIME 10:16 **** ABEND U2222

10.16.46 JOB05801 IEF404I NRWDTSTE - ENDED - TIME=10.16.46

10.16.46 JOB05801 JOB NRWDTSTE END DATE 96.213 CPU 0.002 75085AA 8000XXXA TIM

10.16.46 JOB05801 $HASP395 NRWDTSTE ENDED------ JES2 JOB STATISTICS ------

31 JUL 1996 JOB EXECUTION DATE

379 CARDS READ

Figure 17 - Errors in MVS Job Log





The Program’ s SYSOUT

A sample listing of the //SYSOUT appears in Figure 18.

PROGRAM NAME ------ TESTERR1

ERROR STATUS ------ 0301

ERROR RECORD ------ EMPLOYEE-RECERROR SET --------- .

ERROR AREA -------- USER-AREA-NAME .

LAST GOOD RECORD --

LAST GOOD AREA ----DML SEQUENCE--------0000000008

Figure 18 - Errors in Program’s //SYSOUT

I DMS Error Status

The IDMS Error-Status is a four byte code. The first two bytesare the major code and the last two bytes are the minor code.The major code always indicates the verb number (for example03=OBTAIN, 09=READY). The minor code indicates the problem, suchas 26=RECORD NOT FOUND, 66=AREA NOT AVAILABLE). The IDMS manuals(seeFigure 1) should be consulted for a full explanation of eacherror code.





IDMS RETRIEVAL COMMANDS

There are three retrieval commands: FIND, GET, and OBTAIN. 95%of programmers use only the OBTAIN command, because an OBTAINdoes a FIND plus a GET. A FIND command sets database currency andretrieves the data, but does not put the data into the COBOL’sworking-storage records. A GET presumes that a FIND command hasalready been done, and simply moves the data from the IDMS bufferspace to the designated record-name in the COBOL’s working-storage. Occasionally, a programmer will just do a FIND in orderto save small amount of computer time.

A completed sample IDMS retrieval program can be found in fileEMPDEMO1 on the CD/ROM that accompanies this book.

There are six formats of the FIND/OBTAIN command:

1) FIND/OBTAIN CALC/DUPLICATE2) FIND/OBTAIN CURRENT3) FIND/OBTAIN DBKEY4) FIND/OBTAIN OWNER WITHIN set-name5) FIND/OBTAIN WITHIN SET USING SORT KEY6) FIND/OBTAIN WITHIN SET/AREA

Database currency refers to the where the program is positionedin the database. There are four types of currency:

1) Database Currency (one only)

2) Area Currency (one for each area)3) Record Currency (one for each record)4) Set Currency (one for each set)

When a command like “OBTAIN NEXT WITHIN ABC-AREA” is issued, thearea currency for area “ABC-AREA” is used to obtain the nextrecord in the area. Likewise, when a command like “OBTAIN NEXTWITHIN XYZ-SET” is issued, the set currency for the “XYZ-SET” isused to obtain the next record in the set. Beginning programmerscan easily get lost when navigating a database if they lack agood understanding of database currency. Unfortunately, this

topic deserves an entire chapter to itself.





1) FI ND/OBTAIN CALC/DUPLICATE

If a record is stored with location-mode of CALC, the fastest wayto retrieve that record is to OBTAIN it by using its CALC key. Atypical scenario would be an EMPLOYEE-RECORD where the CALC KEYmight be EMPLOYEE-NUM or EMP-SOCIAL-SECURITY-NUM. A record canhave only one CALC KEY - but it might consists of several non-contiguous field-names. Figure 19 shows a code fragment thatdemonstrates this command.

MOVE ‘123456789’ TO EMPLOYEE-NUM

OBTAIN CALC EMPLOYEE-REC

IF DB-REC-NOT-FOUNDDISPLAY ‘ EMPLOYEE-NUM=’ EMPLOYEE-NUM ‘ WAS NOT FOUND’

ELSE

PERFORM IDMS-STATUSDISPLAY ‘ EMPLOYEE-NUM=’ EMPLOYEE-NUM

‘ EMPLOYEE-NAME=’ EMPLOYEE-NAME

END-IF

Figure 19 - OBTAIN CALC Example

Duplicates are rare on CALC KEYS, but if the CALC record wasdefined as “DUPLICATES FIRST” or “DUPLICATES LAST” the programcan continue to get the remaining records with the same CALC KEYby performing a loop. Figure 20 shows a code fragment thatdemonstrates this command.

1000-GET-EMPLOYEE.

MOVE '123456789' TO EMPLOYEE-NUMOBTAIN CALC EMPLOYEE-REC

PERFORM IDMS-STATUS

PERFORM 2100-DISPLAY-RESULT THRU 2100-EXIT

PERFORM 2000-GET-DUP-EMPLOYEES THRU 2000-EXITUNTIL DB-REC-NOT-FOUND.

1000-EXIT. EXIT.

2000-GET-DUP-EMPLOYEES.

OBTAIN CALC EMPLOYEE-REC DUPLICATE.IF NOT DB-REC-NOT-FOUND

PERFORM IDMS-STATUS

PERFORM 2100-DISPLAY-RESULT THRU 2100-EXIT.

2000-EXIT. EXIT.

2100-DISPLAY-NAME.

IF DB-REC-NOT-FOUND

DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM‘WAS NOT FOUND’

ELSE

DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM‘ EMPLOYEE-NAME=‘ EMPLOYEE-NAME

END-IF.

2100-EXIT. EXIT.

Figure 20 - OBTAIN CALC DUPLICATE Example





2) FI ND/OBTAIN CURRENT and 6) FI ND/OBTAIN NEXT WITHI N SET/AREA

The FIND/OBTAIN NEXT command is used to get the first or nextrecord in the area or set. If the database area is over 50%full, the fastest way to retrieve all of a certain record typefrom the database is to do an “AREA SWEEP.” This process mightalso be called an extract job. This involves getting the FIRSTrecord in the area, and then performing the “OBTAIN NEXT” commanduntil the DB-END-OF-SET condition is reached.

The FIND/OBTAIN NEXT WITHIN SET is used to “walk a set.”Usually, the program is obtains the owner record and thenprocesses each member of the set.

The FIND/OBTAIN CURRENT is used to reposition database currencyback to a prior location. This is very common when sweeping a

database for record-1 while then walking a set for record-2. Ifthe program is not careful, it can “lose currency”. For example,the “OBTAIN NEXT EMPLOYEE-REC WITHIN AREA” statement will startfrom the currency of area, and go forward in the area, lookingfor the next EMPLOYEE-REC. If the current database position isnot on the last EMPLOYEE-REC, this could cause the program toomit records in an extract, or to go into a loop re-reading thesame series of records over-and-over.

The following code fragment demonstrates the following:

2) FIND/OBTAIN CURRENT

6) FIND/OBTAIN NEXT WITHIN SET and AREA





Figure 21 shows a code fragment that demonstrates these commands.

1000-GET-EMPLOYEE.MOVE ZERO TO RECORD-COUNT

PERFORM 2000-GET-NEXT-EMPLOYEE THRU 2000-EXIT

UNTIL DB-END-OF-SET.1000-EXIT. EXIT.

2000-GET-NEXT-EMPLOYEE.IF RECORD-COUNT = 0

OBTAIN FIRST EMPLOYEE-REC WITHIN EMPLOYEE-AREA

ELSE

OBTAIN NEXT EMPLOYEE-REC WITHIN EMPLOYEE-AREAEND-IF

IF DB-END-OF-SET

GO TO 2000-EXITEND-IF

PERFORM IDMS-STATUS

PERFORM 3000-GET-NEXT-JOBHIST THRU 3000-EXITUNTIL DB-ANY-ERROR.

*SET CURRENCY BACK TO LAST EMPLOYEE-REC

*THE “FIND” IS USED INSTEAD OF THE “OBTAIN” BECAUSE THE PROGRAM*IS NO LONGER INTERESTED IN THE DATA FROM THAT RECORD.

FIND CURRENT EMPLOYEE-REC

PERFORM IDMS-STATUS.

2000-EXIT. EXIT.

3000-GET-NEXT-JOBHIST.

OBTAIN NEXT JOBHIST WITHIN EMP-JOBHIST

IF NOT DB-END-OF-SETPERFORM 4000-WRITE-OUT-DATA THRU 4000-EXIT

END-IF

.3000-EXIT. EXIT.

Figure 21 - OBTAIN CURRENT & OBTAIN NEXT Example

Notes: With the OBTAIN WITHIN SET/AREA command, there are fiveoptions:

1) OBTAIN FIRST2) OBTAIN NEXT3) OBTAIN LAST4) OBTAIN PRIOR5) OBTAIN ws-number where ws-number is the Nth record

desired (this option is rarely used)





3) FIND/OBTAIN DBKEY

The FIND/OBTAIN DBKEY command is used to retrieve a record basedon a dbkey that was saved from a prior retrieval of that record.This is the fastest possible way to retrieve a record, becauseIDMS will only have to do one I/O. WARNING: If the databaseadministrator reorgs or re-sizes the physical database, then allthe dbkeys will change. Therefore it is unwise to save dbkeys insequential files for processing that will occur more than a fewhours later in the same day.

TIP: A DBKEY consists of a page-number and a line-number. InCOBOL it is defined as an S9(8) COMP field. DBKEYs can bedisplayed three different ways:

1) page:line-number - for example: 50,123:49

2) cobol number - for example: 12831537 (which equals

50,123 * 256 + 49)

3) hex - for example: 00C3CB31 (where X’00C3CB’ converts to50,123 and X’31’ converts to 49).

ADVANCED NOTES on DBKEYs:

1) large dbkeys over 8,388,608 will appear as negative numbersin an S9(8) COMP field, and require special processing to convertto page/line number

2) 99% of all databases are defined to allow 255records per page, and thus the number 256 is used in convertingdbkeys to page-line numbers. The database administrator has thepower to change the radix of the dbkey, and occasionally adifferent computation must be used.

3) There is a field called DBKEY in the SUBSCHEMA-CTRLrecord. This field always contains the value of the dbkey of thelast database record accessed, and thus can be used in a MOVEstatement in lieu of an “ACCEPT” command.





The FIND/OBTAIN DBKEY is almost useless without the ACCEPT DBKEYstatement, which saves the current DBKEY into a working-storagevariable. NOTE: The dbkey can also be saved by doing a move ofthe field “DBKEY” in the SUBSCHEMA-CTRL to a working-storage

variable. Figure 22 shows a code fragment that demonstrates thiscommand.

77 WS-SAVE-DBKEY PIC S9(8) COMP.

ACCEPT WS-SAVE-DBKEY FROM CURRENCY.

PERFORM IDMS-STATUS* (or ACCEPT WS-SAVE-DBKEY FROM EMPLOYEE-REC CURRENCY.)

* (or MOVE DBKEY TO WS-SAVE-DBKEY)

* . . . misc other processing here . . .OBTAIN EMPLOYEE-REC DBKEY IS WS-SAVE-DBKEY.


Figure 22 - OBTAIN DBKEY Example

4) F IND/OBTAIN OWNER WITH IN set-name

The FIND/OBTAIN OWNER command allows the programmer tonavigate up a hierarchy by moving from a member (child) record toits owner (or parent). Although an OBTAIN OWNER statement may becoded with checking for ownership first, this can cause badprogram logic and make debugging difficult. Thus, it should be astandard procedure to always use the “IF MEMBER” statement first.Technically, this is only needed for OPTIONAL sets, but by alwayscoding the “IF MEMBER”, this gives a site the flexibility tochange the set options without having to worry about having tore-code programs.

For the following example, the program has already obtained aJOBHIST record and needs to OBTAIN the owner EMPLOYEE-REC withinthe EMPLOYEE-JOBHIST set. Figure 23 shows a code fragment thatdemonstrates this command.

IF EMPLOYEE-JOBHIST MEMBER

OBTAIN OWNER WITHIN EMPLOYEE-JOBHIST

DISPLAY ‘OWNER-EMPLOYEE-NUM=‘ EMPLOYEE-NUMELSE

DISPLAY ‘WARNING: JOBHIST IS NOT A MEMBER OF EMPLOYEE-JOBHIST’

END-IF

Figure 23 - IF setname MEMBER Example





5) F IND/OBTAIN WITH IN SET USING SORT KEY

The FIND/OBTAIN WITHIN SET USING SORT KEY is used when a sorted-set is available, and the program is aware of the value of thesort-key of a desired member-record. For example, supposeEMPLOYEE-JOBHIST set is sorted by START-DATE. In other words,the START-DATE is the day that the employee began working on acertain job. Suppose the query is: “What job did employee123456789 start on the date of 19970501? Figure 24 shows a codefragment that demonstrates this command.

MOVE ‘123456789’ TO WS-SEARCH-EMP-NUM* NOTE: THE EMPLOYEE DEMO-DATABASE IS NOT Y2K COMPLIANT

MOVE ‘970501’ TO WS-SEARCH-DATE

MOVE WS-SEARCH-EMP-NUM TO EMPLOYEE-NUM


IF DB-REC-NOT-FOUNDDISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM ‘ WAS NOT FOUND’

ELSE

PERFORM IDMS-STATUS

DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM‘ EMPLOYEE-NAME=‘ EMPLOYEE-NAME

MOVE WS-SEARCH-DATE TO START-DATEOBTAIN JOBHIST WITHIN EMPLOYEE-JOBHIST USING START-DATE

IF DB-REC-NOT-FOUND

DISPLAY ‘NO JOBHIST FOUND FOR DATE=‘ START-DATEELSE

DISPLAY ‘START DATE=‘ START-DATE

‘ JOB-TITLE=‘ JOB-TITLEEND-IF

END-IF

Figure 24 - OBTAIN USING sortkey Example





IDMS UPDATE COMMANDS

Figure 25 shows the five simple commands used to update anIDMS database.

MODIFY After OBTAINING a record, the program can change thevalues of the fields in the record, and then use thiscommand to MODIFY (replace) the record in thedatabase

STORE After setting the working-storage values for arecord, the program can use this command to STORE(add) a new record to the database

ERASE After OBTAINING a record, the program can use thiscommand to ERASE (delete) the record from thedatabase

CONNECT Used to connect a database record to an optional set

DISCONNECT Used to disconnect a database record from an optionalset

Figure 25 - IDMS Update Commands





MODIF Y EXAMPLE:

Figure 26 shows a code fragment that demonstrates the MODIFYcommand.

MOVE ‘123456789’ TO WS-SEARCH-EMP-NUM

MOVE ‘JONES’ TO WS-NEW-LAST-NAME




ELSE

PERFORM IDMS-STATUSMOVE EMPLOYEE-LAST-NAME TO WS-OLD-LAST-NAME

MOVE WS-NEW-LAST-NAME TO EMPLOYEE-LAST-NAME

MODIFY EMPLOYEE-RECPERFORM IDMS-STATUS

DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM

‘ LAST-NAME CHANGED FROM: ‘‘ TO: ‘ EMPLOYEE-LAST-NAME

END-IF

Figure 26 - MODIFY Example





STORE EXAMPLE:

Figure 27 shows a code fragment that demonstrates the STOREcommand.

INITIALIZE EMPLOYEE-REC

MOVE ‘1231231234’ TO EMPLOYEE-NUMMOVE ‘JONES’ TO EMPLOYEE-LAST-NAMEMOVE ‘JOHN’ TO EMPLOYEE-FIRST-NAME

STORE EMPLOYEE-REC

PERFORM IDMS-STATUS

Figure 27 - STORE Example

Note: If you attempt to store a child record (into a MandatoryAutomatic set, see Figure 30 and Figure 31), then you must becurrent on the owner record in that set. IDMS will automaticallyconnect the member record to the current owner record. If norecord is current, you will get error-status 1225.





ERASE COMMAND:

The ERASE command has four options (shown in Figure 28). Theseoptions provide flexibility and safety for deleting OWNERrecords. When dealing with a record that is not the owner of anyset, the simplest option (#1 below) may be used.

1) ERASE record-name Erases only the specifiedrecord (but if record haschildren, ERASE will fail).

2) ERASE record-name PERMANENTMEMBERS

Erases the specified recordand all mandatory memberrecords

3) ERASE record-name SELECTIVEMEMBERS

Erases the specified recordand all optional memberrecords

4) ERASE record-name ALL MEMBERS Erases the specified recordand all mandatory andoptional member records

Figure 28 - Erase Sub-Options

NOTE: When dealing with a database that has a hierarchicalstructure (Record A owns B owns C owns D), when the top record inthe hierarchy is erased, all members records below (including Cand D) might also be erased, depending on the ERASE optionsspecified.

If the “ERASE EMPLOYEE-REC” command is used, and the EMPLOYEE-JOBHIST set is not empty, the program get an IDMS ERROR-STATUS=0230 (an attempt has been made to erase the owner recordof a non-empty set).

It is often practical to check for members, before attempting anERASE. This can be done with the “IF MEMBER” command. The “IFMEMBER” statement and the ERASE command are illustrated in Figure29.





ERASE EXAMPLE




ELSE

PERFORM IDMS-STATUSDISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM

IF EMPLOYEE-JOBHIST NOT EMPTY

DISPLAY ‘CANNOT ERASE UNTIL MEMBERS ARE DELETED’ELSE

ERASE EMPLOYEE-REC

PERFORM IDMS-STATUSEND-IF

END-IF

Figure 29 - ERASE Example





CONNECT AND DI SCONNECT

The CONNECT and DISCONNECT commands are used less frequently thanthe other IDMS update commands. The majority of IDMS sets are“MANDATORY AUTOMATIC”.

It is important to understand the meaning of these set options.These options always come in a pair, where there are two possiblevalues for the first of the pair, and two possible values for thesecond part of the pair. The four combinations of set optionsare usually abbreviated by their initials (MA, MM, OM, OA).These sets option are explained in the following in figures(Figure 30 and Figure 31).

MANDATORY The member record cannot bedisconnect from the set and thereforethe DISCONNECT command NOT allowed.

OPTIONAL The member record can be disconnectedfrom the set.

Figure 30 - First Set Option

AUTOMATIC The member record will automaticallybe connected to the set when themember record is stored.

MANUAL The member record will not be

connected to the set when the memberrecord is stored.

Figure 31 - Second Set Option

The CONNECT command can be executed on any record that is notconnected to its owner by the set relationship. This can eitherbe a record that was STORED and never connected (OM or MM setoptions), or a record that had been disconnected by theDISCONNECT command (OA or OM) set options. A program may neverdo a CONNECT or DISCONNECT on when the set options are Mandatory-Automatic (MA). An example of the CONNECT verb is shown in

Figure 32.





CONNECT EXAMPLE:

IF NOT EMPLOYEE-JOBHIST MEMBERCONNECT JOBHIST TO EMPLOYEE-JOBHIST

PERFORM IDMS-STATUS

END-IF

Figure 32 - CONNECT ExampleIt is common for a member record to be disconnect from one ownerand then reconnected immediately to another owner. A record thatis disconnected from one owner but not reconnected to anotherowner is sometimes called an ORPHAN record. An example of theDISCONNECT verb is shown in Figure 33.

DISCONNECT EXAMPLE:

DISCONNECT JOBHIST FROM EMPLOYEE-JOBHIST

PERFORM IDMS-STATUS

Figure 33 - DISCONNECT Example





OTHER REQUIRED COMMANDS:

A few other commands are important to COBOL programmers,although they neither retrieve data or store data. They are theREADY, BIND, FINISH, ROLLBACK and COMMIT commands. A briefsummary of each command is shown in Figure 34.

READY Used to READY IDMS-AREAs in retrieval or update mode.

BIND Two formats:

1) BIND RUN-UNIT - establishes a run-unit with IDMS

2) BIND RECORD - specifies an area of working storageto be used for retrieving and updating each databaserecord

FINISH Indicates that all database updates are final and ends

the run-unit

ROLLBACK Indicates that all database updates since the start ofthe program or the last commit (which ever is mostrecent) should be reversed or rolled-out and the run-unit is ended.

COMMIT Indicates that all database updates are final andreleases all update (exclusive) locks, but does NOT endthe run-unit.

Figure 34 - Other Required Commands





The READY Command

The READY command deals with the program’s intentions as to howan IDMS AREA is to be used. If area is readied in RETRIEVALmode, any updates against that area will fail. It is wise toREADY each area in the lowest possible READY mode. This reduceslocking and contention. The READY AREA statement is extremelyuseful in production job scheduling. Typically, the jobschedulers needs to know if two programs can run at the sametime, or if the Database Administrator can run a re-org jobagainst AREA-X while program B is running on a weekend. Thus, aSCAN utility is often run against the COBOL source code toidentify the how each program readies each IDMS-AREA.

The format of the READY statement is:

READY area-name USAGE-MODE IS PROTECTED/EXCLUSIVE RETRIEVAL/UPDATE.

Usually the PROTECTED and EXCLUSIVE options are omitted, becausethey limit the ability of other programs to run concurrentlyagainst the same IDMS AREAs. “PROTECTED UPDATE” indicates thatthis program will be the only program allowed to update the AREA.Once the program starts, any other program that attempts to READYthe same AREA in UPDATE mode will fail with an IDMS ERROR-STATUS= 0966.

PROTECTED UPDATE has one main advantage; it avoids deadlocks. Tounderstand deadlocks, IDMS locking must be understood. When anIDMS program readies an area in update mode, every recordretrieved has a SELECT lock (also called INQUIRE lock)turned on.

This lock is released when another record of the same record-nameis retrieved. Any record that is updated has an UPDATE lock(also called EXCLUSIVE lock) turned on. This lock is releasedwhen the program does a COMMIT or when the run unit terminates(via either a ROLLBACK or FINISH). When program-B requests arecord that program-A has locked, program-B will go into a DBKEYWAIT. If two programs access different data in the same areathere is no problem. But, when two programs tend to use the samedata records, performance usually decreases because one programwill go into WAIT until the lock is freed by the other program.When the condition arises that program-A needs a record locked byprogram-B, and program-B needs a record that is locked by

program-A a DEADLOCK occurs. IDMS will return the ‘xx29’ error-status causing one of the two programs to ABEND.





The COMM IT Command

Deadlocks can often be avoided by increasing the COMMITfrequency. A program typically has a record-update counter, andwhen that counter reaches a certain point, the program performs acommit.

Figure 35 shows how to code COMMIT frequency logic in an updateprogram:

*THIS PROGRAM READS A SEQUENTIAL FILE CONTAINING*AN EMPLOYEE-ID AND A CHANGE TO THE EMPLOYEE’S LAST-NAME.

03 WS-UPDATE-COUNTER PIC S9(4) COMP. VALUE ZERO.03 WS-COMMIT-COUNTER PIC S9(4) COMP VALUE ZERO.

03 WS-COMMIT-FREQ PIC S9(4) COMP VALUE +100.

PERFORM 1000-UPDATE-LOOP THRU 1000-EXIT

UNTIL WS-YN-INPUT1-EOF = ‘Y’

DISPLAY ‘NUMBER OF UPDATES=‘ WS-UPDATE-COUNTER.

1000-UPDATE-LOOP.READ INPUT1-FILEAT END MOVE ‘Y’ TO WS-YN-INPUT1-EOF

GO TO 1000-EXIT

END-READMOVE INPUT1-EMP-ID TO EMPLOYEE-EMP-ID


IF DB-REC-NOT-FOUNDDISPLAY ‘RECORD NOT FOUND EMP-ID=‘ INPUT1-EMP-ID

GO TO 1000-EXIT

END-IFPERFORM IDMS-STATUS

MOVE INPUT1-LAST-NAME TO EMPLOYEE-LAST-NAME

MODIFY EMPLOYEE-RECPERFORM IDMS-STATUS

ADD 1 TO WS-UPDATE-COUNTER

ADD 1 TO WS-COMMIT-COUNTERIF WS-COMMIT-COUNTER NOT < WS-COMMIT-FREQ

PERFORM 8000-COMMIT THRU 8000-EXITEND-IF.

1000-EXIT. EXIT.

8000-COMMIT.

COMMIT.


MOVE ZERO TO WS-COMMIT-COUNTER.8000-EXIT. EXIT.

Figure 35 - COMMIT Frequency Example

However, the above program is incomplete because it does nothandle the case of an ABEND and restart logic. Suppose there are500 records on the input file and that the program ABENDs when

processing record #325. What happens? Since the commit counteris set for every 100 records, then 300 records have been writtento the database. In the case of a simple MODIFY-only program asshown above, the program could be restarted and could simply





reprocess all 500 records. However, if the program was storingrecords instead of modifying them, then the restart logic becomesmore difficult. The program could be changed in two ways:

1) The program could check to see if each record existed andonly STORE new records

2) The program could “spin past” the first 300 records, andbegin it’s STORE logic right where it left off, at record #301(realizing that records #301 thru #325 were rolled-out when theprogram ABENDed).

The second approach is more elegant - but also is moredifficult to code. This means that the program must save thecurrent record counter each time it does a commit. This could bedone by adding logic as shown in Figure 36. A complete sampleIDMS update program with commit and restart logic can be found infile EMPDEMO2 on the CD/ROM that accompanies this book.

*THIS TECHNIQUE ASSUMES THAT THE COMMIT1-FILE EXISTS

*AND THAT DISP=SHR IS SPECIFIED IN THE MAINFRAME MVS

*JCL (JOB CONTROL LANGUAGE).8000-COMMIT.

COMMIT.

PERFORM IDMS-STATUS.MOVE ZERO TO WS-COMMIT-COUNTER.

OPEN OUTPUT COMMIT1-FILE.

MOVE WS-UPDATE-COUNTER TO COMMIT1-UPDATE-COUNTER.WRITE COMMIT1-REC

CLOSE COMMIT1-FILE.

8000-EXIT. EXIT.

Figure 36 - COMMIT Example (UPDATE-COUNTER is saved)





The program now writes the update-counter to a sequential file.By opening and closing the file each time, the last recordwritten is overlaid. Now that the program saves this counter, italso needs restart logic, which is shown in Figure 37.

0000-INIT.

OPEN INPUT INPUT1-FILEPERFORM 8500-CHECK-RESTART THRU 8500-EXIT.

PERFORM 1000-UPDATE-LOOP THRU 1000-EXIT

UNTIL WS-YN-INPUT1-EOF = ‘Y’DISPLAY ‘NUMBER OF UPDATES=‘ WS-UPDATE-COUNTER.

8500-CHECK-RESTART.OPEN INPUT COMMIT1-FILE.

READ COMMIT1-FILE

AT END MOVE ‘Y’ TO WS-YN-COMMIT1-EOFEND-READ

IF WS-YN-COMMIT1-EOF = ‘Y’

DISPLAY ‘8500 NO RESTART REQUIRED’ELSE

DISPLAY ‘8500 RESTARTING AT UPDATE-COUNTER=’

COMMIT1-UPDATE-COUNTERPERFORM 8510-SKIP-INPUT1-REC THRU 8510-EXIT

COMMIT1-UPDATE-COUNTER TIMES

MOVE COMMIT1-UPDATE-COUNTER TO WS-UPDATE-COUNTEREND-IF.

CLOSE COMMIT1-FILE.

8500-EXIT. EXIT.

8510-SKIP-INPUT1-REC.

READ INPUT1-FILEAT END MOVE ‘Y’ TO WS-YN-INPUT1-EOF

DISPLAY ‘8510: ERROR //INPUT1 EOF ON RESTART’

MOVE 16 TO RETURN-CODESTOP RUN

END-READ.

8510-EXIT. EXIT.

Figure 37 - COMMIT/Restart Example





The TWO BIND Commands

The BIND RUN-UNIT statement is used to establish a run-unit. Arun-unit is an IDMS term that describes a program that has issueda BIND but has not yet issued a FINISH or ROLLBACK. A run-unitestablishes communication with the IDMS database server andcreates all necessary control blocks to communicate with IDMS.

The following precompiler directive builds the ‘BIND RUN-UNIT’statement and a BIND for each record-type.

COPY IDMS SUBSCHEMA-BINDS.

This statement was previously discussed in the precompilerdirectives section (seeFigure 9). Prior to release 12.0 of IDMS,sites using multiple DBNAMEs would code the DBNAME on the BINDRUN-UNIT statement. But with 12.0, the DBNAME is usuallyspecified external to the program in the //SYSIDMS file.

(DBNAMEs allow the same program to run against different copiesof the same database. For example, a USA Payroll database and aCANADA Payroll database could be maintained by the same programs,although the data in each database would be entirely different.This is often called segmentation or segmented databases.)

There must be one BIND record statement issued for each recordthat the program will access. Each BIND record statementprovides addressability to the COBOL working-storage section foreach record-layout. If the precompiler directive “COPY SUBSCHEMABINDS” (Figure 8) is not used, your BINDs AND READYs could becoded as shown in Figure 38.

BIND RUN-UNIT

PERFORM IDMS-STATUSBIND JOB

PERFORM IDMS-STATUS

BIND EMPOSITIONPERFORM IDMS-STATUS

BIND EMPLOYEE

PERFORM IDMS-STATUSREADY EMP-DEMO-REGION USAGE-MODE RETRIEVAL.


READY ORG-DEMO-REGION USAGE-MODE RETRIEVAL.PERFORM IDMS-STATUS.

Figure 38 - BIND Example

NOTE: It is always wise to do the “PERFORM IDMS-STATUS” aftereach statement. This ensures that you get the proper error assoon as possible, rather than getting a misleading error later.





The F INI SH and ROLLBACK Commands

The FINISH command is used to complete the IDMS RUN-UNIT and tomake permanent all the changes to the database (since the lastCOMMIT). As IDMS updates are written to the actual databasefiles, before and after images are also written to the IDMSjournal files. If the program ABENDs or issues the ROLLBACKcommand, these journal images are used to reverse the changesmade to the actual database.

If the program fails to include either a FINISH or ROLLBACK, aROLLBACK is assumed (however, the DML Precompiler will issue awarning). Thus if a programmer runs a test program and thendiscovers that the updates did not happen, it is likely that theprogram did not include the FINISH statement.

After the program does a FINISH or ROLLBACK, the run-unit isterminated, and it cannot do any further DML commands (resulting

in a bad error-status such as nn77).





IDMS Online Programming

I DM S Onli ne Programming Overview

Online programming involves creating screens (called maps) that

allow COBOL programs to communicate with mainframe 3270 terminals(or PC programs that emulate 3270 terminals). Literals anddatabase variables are presented on the terminal and theapplication end-users use function keys, transaction codes,and/or menus to access the desired programs and data. Onlineprogramming involves skills above and beyond batch COBOLprogramming.

The four most common means of writing online programs forIDMS databases are:

1) ADS - IDMS Application Development System2) CICS - IBM’s Customer Information System

3) IDMS/DC - IDMS TP Commands4) TSO/ISPF Panels

IDMS also includes DC (Data Communications) or Teleprocessingcapabilities (sometimes called a TP/Monitor). This allows IDMSonline programs using interactive screens to access or update anIDMS database.

Online programming is usually done in full-screen (mapping) mode,but also can be done in line mode. IDMS full-screen maps arecreated in an IDMS task called MAPC (Mapping Compiler for IDMS12.0 and after) or OLM (Online Mapping - for IDMS pre 12.0releases). CICS Maps are created with a language called BMS -Basic Mapping Support.





Sample IDMS/DC Commands

Sample IDMS DC commands include:

FULL-SCREEN:

MAP INMAP OUTMAP OUTININQUIRE MAP

LINE-MODE:

WRITE LINE TO TERMINAL,READ LINE FROM TERMINALREAD TERMINAL

OTHER DC Commands:

SET TIMERSEND MESSAGESNAPSTARTPAGEWAITENQUEUE/DEQUEUEPOSTGET QUEUE/PUT QUEUEGET SCRATCH/PUT SCRATCH

These DC commands allows IDMS/DC programs to do most anything

that CICS programs can do. IDMS software called UniversalCommunication Facility (UCF) allows IDMS/DC programs to run underCICS, or a site might run IDMS/DC and not use CICS at all.





Overview of ADS

ADS is a separate product and an entire programming language butone that is totally integrated with IDMS. Many sites haveadopted it as their primary online development system. ADS isoften referred to as ADSO (ADS/Online), but ADS also has batchcapabilities (ADS/Batch). ADS is rarely used for batchreporting; most sites choose COBOL, Online Query (OLQ/BATCH),CULPRIT, or fourth generation language (4GL) report-writers suchas FOCUS, SAS, Data-Analyzer, or Easytrieve-Plus.

ADS programs are written as module text and stored on the IDMSIntegrated Data Dictionary (IDD). ADSO programmers usually haveaccess to create work records and elements on the IDD. ADSOprograms are typically built online using the ApplicationGeneration and Application Compiler. An ADSO program is called adialog, which usually consists of a map, a subschema, one premapprocess, and several response processes.





Overview of CICS

CICS programs using CICS command level language and go through aCICS precompiler in addition to the DML precompiler. A CICS/IDMSprogram is designed by specifying a proper mode statement in theENVIRONMENT DIVISION, as shown in Figure 39.

009200 ENVIRONMENT DIVISION.009300 IDMS-CONTROL SECTION.

009400 PROTOCOL. MODE IS CICS-AUTOSTATUS

009500 IDMS-RECORDS MANUAL.

Figure 39 - CICS “MODE IS” Example

Some sites use only CICS to create online programs (instead ofIDMS/DC or ADS) for the following reasons:

1) CICS programmers might be easier to find and/or thecompany has a larger base of CICS experience

2) Other in-house programs use CICS/VSAM or sophisticatedCICS menuing systems, and the end-users want a consistent methodof accessing data.

Overview of I DMS/DC

IDMS/DC programs use the same DML precompiler as batch programs.An online IDMS/DC program is designated by specifying a propermode statement in the ENVIRONMENT DIVISION as shown in Figure 40.

009200 ENVIRONMENT DIVISION.009300 IDMS-CONTROL SECTION.

009400 PROTOCOL. MODE IS IDMS-DC

009500 IDMS-RECORDS MANUAL.

Figure 40 - IDMS/DC “MODE IS” Example

Overview of Nati ve VSAM

Native VSAM files can be defined to IDMS schemas so that anIDMS/DC or IDMS/Batch program can read or update a VSAM fileusing DML commands.





Maintaining IDMS Programs

Once an IDMS system is implemented, IDMS has some uniqueaspects for maintaining the programs.

1) Management Issues

Management usually works with the customer to determine whatchanges must be made. Often there is a large list of changeswhich the customer must prioritize. It is not unusual to have aone to three year backlog of changes.

2) Program migration

Usually each site has a unique set of procedures formigrating programs from the test environment to the production

environment (often using an intermediate staging or qualityassurance environment). Most sites recompile the program at somepoint in this process. Some sites require change controlpaperwork or the approval of a Quality Control group. In somecases, getting the paperwork signed-off can be more challengingthan the COBOL program changes.

3) Coordinating Record Structure Changes and Schema Changes withthe DBA

Typically, when a database record must be changed, it is thejob of the DBA (database administrator) to run the appropriate

restructure utilities. Usually senior programmers work with theDBA to migrate programs from a test system to the productionsystem immediately after these changes are made.

Usually, months before such a change is made, theprogrammer/analysts do research to identify the amount of effortand the number of programs that must be changed. Suppose thechange is to add a PIC X(2) STATUS-CODE to the EMPLOYEE-REC.Someone must create a list of all the effected programs anddetermine if they need a simple recompile, or if the program codemust be changed.





4) Program Documentation

If a report or an online screen is changed, is there a manualthat must be changed? Are there any changes to the customerprocedures that will be required before the program is migrated?Is it appropriate to hold a training class before implementing

the change?

5) Performance and Tuning

Many program changes are made in an effort to make programsrun faster. Perhaps a batch program ran in one hour the firstsix months in the life of the system, but now it runs in fourhours, which no longer satisfactory for the nightly batch window.Perhaps an index can be added to the database to make the programrun faster. Perhaps the DML navigation path of program can bechanged to make the program run faster.

6) Preventative Maintenance

Frequently, the DBA will reorganize database for the sake ofefficiency. This is commonly done when database areas approach70% full, or upon areas where there are abnormally high number ofchanges. Index sets also need to be reorganized frequently.Since the DBA must take the databases offline when making hischanges, he usually performs them late nights or weekends, withthe coordination of the production job schedulers. The DBA willalso install maintenance and new releases of IDMS software andcoordinate the implementation with the programming staff.



Files on CD/ROM

1) EMPDEMO1 - COBOL SOURCE - Sample report program that readssequential file and creates detailed employee/job-history reportfor each employee-id specified

2) EMPDEMO2 - COBOL SOURCE - Sample update program, readssequential file containing OFFICE-CODE, DEPT-ID, EMP-ID, EMP-LAST-NAME, and EMP-FIRST-NAME and stores on database. Thisprogram has complete COMMIT and restart logic.

3) EMPDEMO3 - COBOL SOURCE - Sample update program that deletesall employees with EMP-ID between 1000 and 2000 (i.e. thoseemployees added by program EMPDEMO2). This is used to clean upthe database so that EMPDEMO2 can be run again without gettingduplicates. This program also write a zero counter to the COMMIT

file.

4) XMPDEMO1 - EXECUTION JCL - Job Control Language (JCL) andINPUT data to demonstrate report program EMPDEMO1

5) XMPDEMO2 - EXECUTION JCL - JCL and INPUT data to demonstrateEMPDEMO2. JCL comments explain what each step does. JCL is setup to cause an ABEND after x records are processed, so therestart logic can be demonstrated in the next step.

6) XMPDEMO3 - EXECUTION JCL - JCL demonstrate delete programEMPDEMO3

7) COMPJCL - EXECUTION JCL - Sample JCL for DML Preprocessor andCOBOL Compile and link. Check with your site for actual COBOLJCL or compile PROC to be used.

8) PMPDEMO1 - PRINTOUT OF EXECUTION - from EMPDEMO1

9) PMPDEMO2 - PRINTOUT OF EXECUTION - from EMPDEMO2

idms batch cobol programming

Documents