Introduction
Heirloom Computing, inc., provides support for the IMS DB compatible operations that store data in Elastic COBOL supported file formats. Both COBOL batch application (executed from within Elastic Batch Platform) or online transactions (invoked from within Elastic Transaction Platform) are supported. Elastic IMS DB is available on Windows, UNIX and Linux platforms where Elastic COBOL is supported.
Accessing ("real") IBM IMS DB from Elastic COBOL, whether running on System z CP, zIIP, zAAP, IFL CPUs or from within a Windows, UNIX or Linux environment is not supported directly through IMS Remote functions. See the IBM IMS DB Connect program product for use from within the Java environment for more information on how to invoke IMS from a Java program and use any of several mechanisms to invoke Java classes and methods from within Elastic COBOL applications.
The following utilities are available from Elastic Batch Platform on which to create databases and data structures and then run Elastic COBOL applications. These can take advantage of all of the Heirloom Computing technology when it comes to data storage: EC, MF, Acu ISAM file formats, ISAM file transparency (mapping) to relational database, and access by either DLI or SQL protocols.
Elastic IMS DB consists of the following built-in utilities available from the Elastic Batch Platform (EBP) environment:
- DBDGEN - Generate an Elastic IMS DB database from a DBD file and store a defininiton of that schema in a .DBD file
- PSBGEN - Generate a program status block defining the data structure access points a program may use to access an Elastic IMS DB in a .PSB file
- DFSRRC00 - The Elastic IMS DB main module (processor) that invokes customer applications
- IDCAMS - Extract, translate and/or load an Elastic IMS DB from another database or sequential file
Two new APIs are supplied with Elastic COBOL:
- DLITCBL - DFSRRC00 invokes this entry point defined in an Elastic COBOL program that will operate on an Elastic IMS DB
- CBLTDLI - Invoked by Elastic IMS DB COBOL programs to act on a database with retrieval (i.e., Get Unique) or update (Insert, Replace) processing requests.
The EXEC DLI ... END-EXEC (macro processor for DL/I) is not supported in Elastic COBOL, use the direct calling mechanism CALL CBLTDLI to invoke IMS DB operations from within ETP transactions or EBP batch programs.
Elastic IMS DB File Layout
An Elastic IMS DB database is stored in standard Elastic COBOL indexed sequential file formats, including those mapped to relational databases. ISAM files can also be created by COBOL File Section statements within a program and by the IDCAMS utility within EBP. To guarantee correct database definition, however, the DBDGEN utility should be used with a DBD (database definition) file.
The structure created by DBDGEN consists of keys which uniquely identify a particular segment (even if sequence fields are not defined or are multi-valued) and the segment dependent data. The number of keys depends upon the number of levels of the hierarchy defined in a DBD. Given the following IMS DB logical layout defining three segments (records) we see that a "Library" consists of both "Books" and "Magazines.":
Fig. 1. IMS DB logical layout
Each segment has identifying information, name or title, and dependent information such as location, author or publisher. The exact specification for this example might be given by the following DBD file:
*
* DBD contains 3 segments: LIBSEG, BOOKSEG, MAGSEG
*
DBD NAME=LIBRARY,ACCESS=HIDAM
DATASET DD1=LIB,DEVICE=3380
SEGM NAME=LIBSEG,PARENT=SYSTEM,BYTES=30
FIELD NAME=(LIBRARY,SEQ,U),BYTES=10,START=1,TYPE=C
FIELD NAME=ADDRESS,BYTES=20,START=11,TYPE=C
*
SEGM NAME=BOOKSEG,PARENT=LIBSEG,BYTES=50
FIELD NAME=(BOOK,SEQ,U),BYTES=20,START=1,TYPE=C
FIELD NAME=AUTHOR,BYTES=30,START=21,TYPE=C
*
SEGM NAME=MAGSEG,PARENT=LIBSEG,BYTES=35
FIELD NAME=(MAGAZINE,SEQ,U),BYTES=15,START=1,TYPE=C
FIELD NAME=PUBLISHR,BYTES=20,START=16,TYPE=C
*
DBDGEN
FINISH
END
Fig. 2. Elastic IMS Database Definition specification
In order to generate a ISAM file that follows the hierarchical retrival order stipulated by IMS DB "Get Next" operations, DBDGEN will create a key from the overlap of {LIBSEG.LIBRARY, BOOKSEG.BOOK} and {LIBSEG.LIBRARY, MAGSEG.MAGAZINE}. To distinguish between these overlapping keys the segment number of each segment is also included as part of the key.
DBDGEN numbers each SEGM it encounters from zero (root or first segment). IMS DB demands that a database contain at most 256 segments which DBDGEN represents by an additional byte within each segment key. When there are fewer than 62 segments defined these segment numbers may be represented in data as the printable characters '0'..'9','a'..'z','A'..'Z. If more than 62 segments are defined within a database the keys contain X'00' through X'FF'.
Another aspect of DBD key generation relies on whether the IMS DB sequence fields (SEQ) are unique (U) or multi-valued (M). Since ISAM files in Elastic COBOL must have unique primary keys, a uniqueness indicator of four bytes is also included in the key.
When loading an Elastic IMS DB database either through a COBOL program with COBOL file I/O, or running the IDCAMS utility the keys need to be specified with the segment I/O data. Thus, the concatenated segment numbers and their keys, and the uniqueness indicators should be included in the records. The following figures show three different cases: (3) when all segments contain unique SEQ fields, (4) when some sements contain multi-valued SEQ fields and (5) when no segments contain SEQ fields.
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8..
SKKKKKKKKKKSKKKKKKKKKKKKKKKKKKKKDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
0SF Main SF Main 100 Larkin St. 94102
0SF Mission SF Mission960 4th St. 94102
0SF Main 1Principia Principia Newton, Isaac
0SF Main 1Koran Koran Allah
0SF Mission1Cat in the Hat Cat in the Hat Dr. Seuss
0SF Main 2JAMA JAMA Amer. Med. Assoc.
0SF Main 2Nature Nature Nature Pub. Grp.
0SF Mission2Time Time Time, Inc.
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8..
SKKKKKKKKKKSKKKKKKKKKKKKKKKKKKKKDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
Record layout: S-seg #, K-key (1-32), D-dependent data (33-81)
Fig. 3. Record layout for loading an Elastic IMS DB from (raw) input records (unique SEGM SEQ fields)
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8....:.
SKKKKKKKKKKSKKKKKKKKKKKKKKKKKKKKUUUUDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
0SF Main 0000SF Main 100 Larkin St. 94102
0SF Mission 0000SF Mission960 4th St. 94102
0SF Main 1Principia 0000Principia Newton, Isaac
0SF Main 1Koran 0000Koran Allah
0SF Mission1Cat in the Hat 0000Cat in the Hat Dr. Seuss
0SF Mission1Cat in the Hat 0001Cat in the Hat Theordor Geisel
0SF Main 2JAMA 0000JAMA Amer. Med. Assoc.
0SF Main 2Nature 0000Nature Nature Pub. Grp.
0SF Mission2Time 0000Time Time, Inc.
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8....:
SKKKKKKKKKKSKKKKKKKKKKKKKKKKKKKKUUUUDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD.
Record layout: S-seg #, K-key (1-36), U-uniqueness ind, D-dependent data (37-86)
Fig. 4. Record layout for loading an Elastic IMS DB from (raw) input records (multi-valued SEGM SEQ fields)
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8....:
UUUUSSDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
00000 SF Main 100 Larkin St. 94102
001001Principia Newton, Isaac
002001Koran Allah
003002JAMA Amer. Med. Assoc.
004002Nature Nature Pub. Grp.
00500 SF Mission960 4th St. 94102
006001Cat in the Hat Dr. Seuss
006101Cat in the Hat Theordor Geisel
007002Time Time, Inc.
....:....1....:....2....:....3....:....4....:....5....:....6....:....7....:....8....:
UUUUSSDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
Record layout: S-seg, U-uniqueness ind, D-dependent data (7-56)
Fig. 5. Record layout for loading an Elastic IMS DB from (raw) input records (no SEQ fields)
Note that if there are no SEQ fields defined for the SEGM definitions the entire hierarchy must be maintained in the uniqueness fields. Elastic IMS DB does not care whether these fields are binary or printable characters as it will renumber the keys (and DLET and ISRT into the database accordingly) to maintain the parent/child and "get next" relationship between them as necessary.
When retrieved in hierarchical order with "get next" operations the segments are returned following this diagram:
Fig. 6. Retrieving the entire database using "Get Next" DL/I API calls.
Elastic IMS DB Operations
The following IMS DB operations are supported by Elastic IMS DB:
| Op ID | Operation | Function |
| GU | Get Unique | Get the unique segment based on Segment Search Area (SSA) criteria |
| GN | Get Next | Get the next segment following the one retrieved earlier GU or GN operation |
| GNP | Get Next Parent | Get the next segment within the same parent segment |
| GHU | Get Hold Unique | Get the unique segment based on the SSAs, holding the segment for DLET or REPL |
| GHN | Get Hold Next | Get the next segment, holding the segment for DLET or REPL |
| GHNP | Get Hold Next Parent | Get the next segment within the same parent,, holding the segment for DLET or REPL |
| ISRT | Insert | Insert the segment |
| DLET | Delete | Delete the segment most recently retrieved |
| REPL | Replace | Replace the segment most recently retrieved |
| PCB | Program Comm Block | Retrieve the Program Communication Block used within this application |
Elastic Transaction Platform
Elastic IMS DB is supported from within the Elastic Transaction Platform environment. The EXEC DLI ... END-EXEC (macro processor for DL/I) is not supported in Elastic COBOL, use the direct calling mechanism CALL CBLTDLI to invoke IMS DB operations from within ETP transactions.
Whereas IMS DB database files from EBP are supported with any supported Indexed Sequential file format (Elastic COBOL, Micro Focus IDX 3, 8, Acu, VDB, VSQL) support from within ETP require databases use the VDB protocol, which has the transactional VSAM capabilities required for transactional IMS DB.
Configure your IMS DB environment from the Elastic Transaction Deployment Wizard (Elastic COBOL Eclipse plug-in), the IMS DB tab.
Fig. 7. IMS DB Deploy Settings
Your ETP transactions should invoke the DL/I PCB function to get the PCB for use with other DL/I operations such as GU or GNP.
CALL 'CBLTDLI' USING 'PCB ' WS-PCB-MASK.
The CICS-to-IMS user information block is supported in Elastic COBOL/ETP. Use the copybook to include those definitions.
COPY DLIUIB.
Status of Elastic IMS DB operations within ETP transactions can be checked with constants defined within.
CALL 'CBLTDLI' USING 'GU ' WS-PCB-MASK WS-MAG-SEG WS-LIB-SSA WS-MAG-SSA.
IF NOT FCNORESP
IF FCNOTOPEN THEN
STRING 'GU - IMS DB NOT OPEN' into EIMSMSGO
END-IF
END-IF.
DBCTL and Transaction Management
The ability for the IMS-DB subsystem to run in a separate address space from the application and the associated control logic between them, DBCTL, is not supported in Elastic IMS DB. Elastic IMS DB runs in the same address space as the DL/I caller ... either the ETP "region" running within a Java Servlet Engine (e.g., Tomcat, Jetty) or Java Application Server (e.g., Weblogic, Websphere, Wildfly) or from within the application spawned by the EBP batch job running DFSRRC00 standard utility.
Two or more subsystems (regions or batch job steps) may run concurrently and the coordination among them, is performed by the underlying database management system (e.g., DB2, Oracle, Postgres, SQL Server, MySQL) that is serving the Elastic COBOL file protocol type VDB that houses the IMS DB. That database management system ensures transaction integrity as ETP processes implicit satisfactory transaction ends or explicit SYNCPOINTs or EBP processes batch job step completion (if autocommit is off or the VDB database) or DL/I operations (if autocommit is on for the VDB database).
XRF and Elastic IMS DB Recovery
IMS Extended Recovery Facility (XRF) functionality is provided by the underlying database management system, if such a system exists. See the database management system's documentation for setting up clustered systems, hot-standby environments or standard database recovery procedures in the event of a failure. With the correct configuration of those systems an XRF-like facility can be created in which an immediate fail-over to another ETP or EBP processing application workload is possible.
Examples
The attached EBP batch jobs demonstrate these utilities and the programming APIs. Also attached is the DBDGEN output report as it creates an Elastic IMS DB. One test (TEST96.JCL) shows the creation of an Elastic IMS DB in a standard Elastic COBOL ISAM file. This can only be used by a single process, single thread (i.e., EBP batch job step) at a time. Another test (TEST98.JCL) shows the same example as a VDB relational database management system managed Elastic IMS DB. This can be used by multiple batch job steps and/or multiple transactions in or more ETP regions (Java EE servers) at a time.
Note: Elastic IMS DB utility and API operations are contained in the etrans.jar distributed with the Elastic COBOL product. IMS DB framework utilities are delivered as part of the Elastic Batch Platform facility.
Also included are two files showing Elastic IMS DB access from within an Elastic Transaction Platform transaction and green screen. This test works with the Elastic IMS DB created from the TEST98.JCL VDB based database.
0 Comments