This document is licensed for use bycustomers of the IDMS Tutorial program
from Amerisoft Inc.
Intended Audiences:1) Batch COBOL Programmers2) 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 DBMSs3) How to compile programs4) Testing and debugging techniques5) Error Handling6) DML Verbs
To be used in conjunction with IDMS FUNDAMENTALScourse book by Amerisoft Inc.
Overview of Network Databases .........................................................................................1DBMS Overview.............................................................................................................1Why a DBMS? ................................................................................................................1IDMS and SQL ...............................................................................................................2IDMS Overview ..............................................................................................................3IDMS Schema or Bachman Diagram................................................................................4DML - Data Manipulation Language ...............................................................................5Two useful Tools.............................................................................................................6CA/IDMS Manuals Relating to DML and COBOL: .........................................................6
The DML Precompiler.........................................................................................................6Precompiler Options ........................................................................................................7Precompiler Directives.....................................................................................................9
ENVIRONMENT DIVISION .....................................................................................9DATA DIVISION: SCHEMA SECTION AND WORKING-STORAGE .................. 11Figure 8 shows where the SCHEMA SECTION is added to the program, and how tocopy IDMS records into the program......................................................................... 11PROCEDURE DIVISION DECLARATIVES........................................................... 12
ERROR HANDLING........................................................................................................ 14Autostatus vs Non-Autostatus ....................................................................................... 14IDMS-STATUS Routine ............................................................................................... 17MVS JOB LOG............................................................................................................. 19The Program’s SYSOUT............................................................................................... 20IDMS Error Status ........................................................................................................ 20
IDMS RETRIEVAL COMMANDS .................................................................................. 211) FIND/OBTAIN CALC/DUPLICATE........................................................................ 222) FIND/OBTAIN CURRENT and 6) FIND/OBTAIN NEXT WITHIN SET/AREA .... 243) FIND/OBTAIN DBKEY........................................................................................... 264) FIND/OBTAIN OWNER WITHIN set-name ............................................................ 275) FIND/OBTAIN WITHIN SET USING SORT KEY.................................................. 28
IDMS UPDATE COMMANDS ........................................................................................ 29MODIFY EXAMPLE: .................................................................................................. 30STORE EXAMPLE: ..................................................................................................... 31ERASE COMMAND: ................................................................................................... 32ERASE EXAMPLE ...................................................................................................... 33CONNECT AND DISCONNECT................................................................................. 34
The COMMIT Command .............................................................................................. 38The TWO BIND Commands.......................................................................................... 41The FINISH and ROLLBACK Commands .................................................................... 42
IDMS Online Programming ............................................................................................... 43IDMS Online Programming Overview ........................................................................... 43Sample IDMS/DC Commands ....................................................................................... 44Overview of ADS .......................................................................................................... 45Overview of CICS ......................................................................................................... 46Overview of IDMS/DC.................................................................................................. 46Overview of Native VSAM............................................................................................ 46
Maintaining IDMS Programs ............................................................................................. 47Files on CD/ROM.............................................................................................................. 49
DBMS OverviewA 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 aDBMS.
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 toselect and join from various tables. Each table is similar to a flat file, and each “row” in the table isthe 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 therelationships 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 majorcorporations around the world. If often costs millions of dollars to convert a system from oneDBMS technology to another, so many companies continue to run older systems until they areobsolete or can be re-written. Other companies still believe that IDMS is a better choice thantoday’s relational alternatives. IDMS was originally marketed by a company called Cullinet, but isnow 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 group2) 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.
IDMS and SQLWith release 12.0 of IDMS, an SQL option became available as an extra-cost product. SinceSQL 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 anIDMS/Relational database or an IDMS/Network database. Another advantage of the SQL optionis the ODBC capability to download data to PCs or to access IDMS mainframe data on clientserver platforms.
IDMS OverviewIn IDMS terminology, a parent record is called an OWNER, and a child record is called aMEMBER. Records are connected to each other via SETs. All database relationships arepredefined in a schema. A subschema is a smaller view of the schema that a COBOL programuses 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 productiondatabases well organized).
IDMS records are stored in IDMS areas, each of which has a physical page range. The pagerange 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, onearea may be mapped to a series of data set names. It is also possible for one physical data set tocontain several areas. In IDMS 12.0 and after, several related areas are grouped together to forma SEGMENT. Segments, buffering, and journalling all defined in a DMCL (Device MediaControl 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) COMPfield in COBOL. To convert this number to a page and line number, usually the dbkey is dividedby 256 to get the page number, and the remainder is the line number (see the sample IDMSprograms on the CD/ROM for a program that converts DBKEYs from one format to another andgives full details.)
An IDMS system is called a Central Version, or CV for short. It is common to say that the testCV will come down at 9 pm and back up at 6 am. When the IDMS CV is down, IDMSprogrammer testing may be limited. Some sites have different CVs for different applications, forinstance 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,” alldatabase I/O is done by by the Central Version (one task running on the computer). Usually, forthe sake of speed, retrieval only jobs run in local-mode, and update jobs run “under the CV” toallow for concurrent update and record locking. While update jobs can be run in local mode, thisfeature is seldom used because the areas must be varied out of update mode - thus preventingonline and other batch jobs from concurrent update. This is sometimes done on weekends tospeed up long running batch jobs. Running “under the CV” incurs typical DBMS overhead suchas 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”.
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 IDMSrecord-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 record2) 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 isstored at that location)
???Editor: I have asked Computer Associates for permission toreprint this schema diagram - but have not yet received anythingfrom them in writing. They should be in contact with TracyDunkelberger.
**Insert figure here - I am sending a photocopy of a diagram froma Computer Associates Manual. I do not have this diagram incomputer format. (This is the only figure in this document - allother examples are “listings”.) **
Each bachman record box consist of four lines:line 1 contains the record-nameline 2 contains the record-id,
F,FC,V,VC for Fixed, Fixed Compressed, Variable, Variable Compressedthe 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-NAMESome 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 ineach record.
A triangle symbol on a schema diagram represents an indexed set. This is a set that has apre-defined sort key assigned. Indexes are used 1) as a rapid access entry point into the databasebased on a logical key value and 2) as a means of quickly displaying sorted data on an onlineretrieval transaction.
DML - Data Manipulation LanguageIDMS databases are maintained by executing DML (Data Manipulation Language)
commands. The same commands can be used from COBOL, Assembler, PL/1 or evenFORTRAN. 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 differencesbetween 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 JOINbetween two record types. There must be a pre-defined set relationship between the two recordtypes (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 thedesired data, and the DBMS chooses the access logic. Thus, as the metrics of an IDMS databasechange, a program’s DML navigation may become slower. Sometimes, the program’s runtime canbe improved by changing the DML navigation path. For example, it might be better to walk anindex 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 useful ToolsComputer Associates (CA) has an additional-cost product called “DMLO” which stands
for Data Manipulation Language Online. A competitor product called “DBOL” (DatabaseOnline) is sold by Allen Systems Group. These two products allow programmers to issue andpractice DML commands online and interactively. A programmer often uses these products forthe following purposes:1) to test a DML navigation path before writing a COBOL program2) to help debug a COBOL program by verifying DML navigation or values of fields in a database
Figure 1 -Recommended IDMS Manuals for COBOL Programmers
The DML PrecompilerThe DML Precompiler, also called the DML pre-processor, convertshigh-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 theformat of the “CALL ‘IDMS’”, because the code is maintained inthe high-level DML language.
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 IDMSSTATUS, the DML-SEQUENCE number is used to identify which IDMSDML VERB caused the problem.
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 onthe 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. ADD PROGRAM 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 339 PROGRAM CALLED IS IDMS VERSION IS 1 PROGRAM CALLED IS IDMSERR1 VERSION IS 1 PROGRAM CALLED IS ABORT VERSION IS 1 MODULE USED IDMS-STATUS VERSION IS 11 LANGUAGE IS COBOL RECORD COPIED SUBSCHEMA-CTRL VERSION IS 2 RECORD COPIED EMPLOYEE-REC VERSION IS 1 RECORD COPIED DB-STATISTICS VERSION IS 1 SUBSCHEMA IS DBATSS01 OF SCHEMA DBATSC01 VERSION IS 1 AREA DBATEST1-AREA READIED FOR UPDATE RECORD EMPLOYEE-REC BIND RECORD EMPLOYEE-REC OBTAIN MODE IS BATCH LANGUAGE 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 1 RECORD 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 forPanvalet, 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, theprecompiler 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 DirectivesPRECOMPILER DIRECTIVES also affect the way the DML PRECOMPILERworks.
ENVIRONMENT DIVISIONThe 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.009200009300 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 RECORDSWITHIN 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.
Figure 8 shows where the SCHEMA SECTION is added to the program, and how to copyIDMS records into the program.010000 DATA DIVISION010100 FILE SECTION.010200 FD INPUT1-FILE010300 LABEL RECORDS ARE STANDARD010400 BLOCK CONTAINS 0 RECORDS.010500 01 INPUT1-REC PIC X(80).010600010700 SCHEMA SECTION.011000 DB DBATSS01 WITHIN DBATSC01.011100011200 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 DECLARATIVESFigure 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).
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-CTRL IDBMSCOM (59) SUBSCHEMA-CTRL SUBSCHEMA-SSNAME; * BIND JOB-REC MOVE 2 TO DML-SEQUENCE CALL 'IDMS' USING SUBSCHEMA-CTRL IDBMSCOM (48) SR2003 JOB-REC; * BIND EMPLOYEE-REC. MOVE 3 TO DML-SEQUENCE 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 inthe 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-AutostatusNote 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 prefernot 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.
The above code gets translated to the following000336 1000-OBTAIN-EMPLOYEE.000337 MOVE '123456789' TO EMPLOYEE-NUM000338 * OBTAIN CALC EMPLOYEE-REC000339 * ON DB-REC-NOT-FOUND000340 MOVE 4 TO DML-SEQUENCE000341 CALL 'IDMS' USING SUBSCHEMA-CTRL000342 IDBMSCOM (32)000343 SR2001000344 IDBMSCOM (43)000345 IF NOT DB-REC-NOT-FOUND PERFORM IDMS-STATUS;000346 ELSE000347 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT000348 .000349 PERFORM 1200-EMP-FOUND THRU 1200-EXIT000350 .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). Notethe addition of line 28950.
Some programmers will CODE a variation of the Figure 13 as shownin 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-NUM028600 OBTAIN CALC EMPLOYEE-REC028700 IF DB-REC-NOT-FOUND028800 PERFORM 1100-EMP-NOT-FOUND THRU 1100-EXIT028900 .028910 IF DB-ANY-ERROR028950 PERFORM IDMS-STATUS.029000 PERFORM 1200-EMP-FOUND THRU 1200-EXIT029100 .029200 1000-EXIT. EXIT.
IDMS-STATUS RoutineFigure 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-ABORT DISPLAY '**************************' ' ABORTING - ' PROGRAM-NAME ', ' ERROR-STATUS ', ' ERROR-RECORD ' **** RECOVER IDMS ****' UPON CONSOLE DISPLAY 'PROGRAM NAME ------ ' PROGRAM-NAME DISPLAY 'ERROR STATUS ------ ' ERROR-STATUS DISPLAY 'ERROR RECORD ------ ' ERROR-RECORD DISPLAY 'ERROR SET --------- ' ERROR-SET DISPLAY 'ERROR AREA -------- ' ERROR-AREA DISPLAY 'LAST GOOD RECORD -- ' RRECORD-NAME DISPLAY '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 CALL 'IDMS' USING SUBSCHEMA-CTRL IDBMSCOM (67) 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 DISPLAYstatements found in the //SYSOUT and the job log.
The Program’s SYSOUTA sample listing of the //SYSOUT appears in Figure 18.
PROGRAM NAME ------ TESTERR1 ERROR STATUS ------ 0301 ERROR RECORD ------ EMPLOYEE-REC ERROR SET --------- . ERROR AREA -------- USER-AREA-NAME . LAST GOOD RECORD -- LAST GOOD AREA ---- DML SEQUENCE--------0000000008
Figure 18 - Errors in Program’s //SYSOUT
IDMS Error StatusThe 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.
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, thistopic deserves an entire chapter to itself.
1) FIND/OBTAIN CALC/DUPLICATEIf 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-FOUND DISPLAY ‘ EMPLOYEE-NUM=’ EMPLOYEE-NUM ‘ WAS NOT FOUND’ ELSE PERFORM IDMS-STATUS DISPLAY ‘ 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.
2) FIND/OBTAIN CURRENT and 6) FIND/OBTAIN NEXT WITHIN 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 adatabase 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:
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-AREA END-IF IF DB-END-OF-SET GO TO 2000-EXIT END-IF PERFORM IDMS-STATUS PERFORM 3000-GET-NEXT-JOBHIST THRU 3000-EXIT UNTIL 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-SET PERFORM 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
3) FIND/OBTAIN DBKEYThe 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 equals50,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-storagevariable. 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. PERFORM IDMS-STATUS.
Figure 22 - OBTAIN DBKEY Example
4) FIND/OBTAIN OWNER WITHIN set-nameThe FIND/OBTAIN OWNER command allows the programmer to
navigate 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-NUM ELSE DISPLAY ‘WARNING: JOBHIST IS NOT A MEMBER OF EMPLOYEE-JOBHIST’ END-IF
5) FIND/OBTAIN WITHIN SET USING SORT KEYThe 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 OBTAIN CALC EMPLOYEE-REC IF DB-REC-NOT-FOUND DISPLAY ‘ 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-DATE OBTAIN JOBHIST WITHIN EMPLOYEE-JOBHIST USING START-DATE IF DB-REC-NOT-FOUND DISPLAY ‘NO JOBHIST FOUND FOR DATE=‘ START-DATE ELSE DISPLAY ‘START DATE=‘ START-DATE ‘ JOB-TITLE=‘ JOB-TITLE END-IF END-IF
IDMS UPDATE COMMANDSFigure 25 shows the five simple commands used to update an
IDMS 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
STORE EXAMPLE:Figure 27 shows a code fragment that demonstrates the STOREcommand.
INITIALIZE EMPLOYEE-REC MOVE ‘1231231234’ TO EMPLOYEE-NUM MOVE ‘JONES’ TO EMPLOYEE-LAST-NAME MOVE ‘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 EXAMPLEMOVE WS-SEARCH-EMP-NUM TO EMPLOYEE-NUM OBTAIN CALC EMPLOYEE-REC IF DB-REC-NOT-FOUND DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM ‘ WAS NOT FOUND’ ELSE PERFORM IDMS-STATUS DISPLAY ‘ EMPLOYEE-NUM=‘ EMPLOYEE-NUM IF EMPLOYEE-JOBHIST NOT EMPTY DISPLAY ‘CANNOT ERASE UNTIL MEMBERS ARE DELETED’ ELSE ERASE EMPLOYEE-REC PERFORM IDMS-STATUS END-IF END-IF
CONNECT AND DISCONNECTThe 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 beconnected 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 inFigure 32.
CONNECT EXAMPLE: IF NOT EMPLOYEE-JOBHIST MEMBER CONNECT JOBHIST TO EMPLOYEE-JOBHIST PERFORM IDMS-STATUS END-IF
Figure 32 - CONNECT Example
It 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
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 endsthe 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.
The READY CommandThe 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 byprogram-A a DEADLOCK occurs. IDMS will return the ‘xx29’ error-status causing one of the two programs to ABEND.
The COMMIT CommandDeadlocks 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-FILE AT END MOVE ‘Y’ TO WS-YN-INPUT1-EOF GO TO 1000-EXIT END-READ MOVE INPUT1-EMP-ID TO EMPLOYEE-EMP-ID OBTAIN CALC EMPLOYEE-REC IF DB-REC-NOT-FOUND DISPLAY ‘RECORD NOT FOUND EMP-ID=‘ INPUT1-EMP-ID GO TO 1000-EXIT END-IF PERFORM IDMS-STATUS MOVE INPUT1-LAST-NAME TO EMPLOYEE-LAST-NAME MODIFY EMPLOYEE-REC PERFORM IDMS-STATUS ADD 1 TO WS-UPDATE-COUNTER ADD 1 TO WS-COMMIT-COUNTER IF WS-COMMIT-COUNTER NOT < WS-COMMIT-FREQ PERFORM 8000-COMMIT THRU 8000-EXIT END-IF . 1000-EXIT. EXIT.
8000-COMMIT. COMMIT. PERFORM IDMS-STATUS. 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 whenprocessing 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-FILE PERFORM 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-EOF END-READ IF WS-YN-COMMIT1-EOF = ‘Y’ DISPLAY ‘8500 NO RESTART REQUIRED’ ELSE DISPLAY ‘8500 RESTARTING AT UPDATE-COUNTER=’ COMMIT1-UPDATE-COUNTER PERFORM 8510-SKIP-INPUT1-REC THRU 8510-EXIT COMMIT1-UPDATE-COUNTER TIMES MOVE COMMIT1-UPDATE-COUNTER TO WS-UPDATE-COUNTER END-IF. CLOSE COMMIT1-FILE. 8500-EXIT. EXIT.
8510-SKIP-INPUT1-REC. READ INPUT1-FILE AT END MOVE ‘Y’ TO WS-YN-INPUT1-EOF DISPLAY ‘8510: ERROR //INPUT1 EOF ON RESTART’ MOVE 16 TO RETURN-CODE STOP RUN END-READ. 8510-EXIT. EXIT.
The TWO BIND CommandsThe 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.
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 FINISH and ROLLBACK CommandsThe 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 (resultingin a bad error-status such as nn77).
IDMS Online Programming OverviewOnline programming involves creating screens (called maps) thatallow 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 System3) 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 CommandsSample 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 anythingthat 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 ADSADS 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 CICSCICS 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.
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 IDMS/DCIDMS/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.
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 productionenvironment (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 appropriaterestructure 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.
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 implementingthe 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.
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 COMMITfile.
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.
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
