Latest Version of Heirloom SDK
To have all the functionality described in this document, it’s required that you install latest version of the Heirloom SDK v21.2.12 or greater into your eclipse environment and latest Elastic Batch Platform environment v21.2.12 or greater.
Elastic Batch Platform can work in one of two modes, file or table based dcb (storage of file attributes)
File based DCB
Elastic Batch Platform (EBP) parses JCL to gather input (DISP=SHR/OLD/MOD) data control block information (DCB) to pass to underlaying COBOL or utility programs. New files (z/OS) which are being created usually supply DCB information about the file being created and EBP supplies java properties via the java -D parameter to the COBOL program.
Note: if MSGLEVEL=(4,4) is set on the job card, you’ll be able to see the java command line being passed.
File based DCB uses a simple line sequential file (.dcb) stored in the local data directory, which holds information about the Mainframe style dataset. . EBP can host different styles of Mainframe style datasets names i.e. AAAAAAAA.BBBBBBBB.CCCCCCCC.DDDDDDDD or AAAAAAAA\BBBBBBBB\CCCCCCCC\DDDDDDDD
With DSORG as PO or GDG having its own folder as the base name. For example, PO
AAAAAAAA.BBBBBBBB.CCCCCCCC.DDDDDDDD\MEMBER1 or AAAAAAAA\BBBBBBBB\CCCCCCCC\DDDDDDDD\MEMBER1
EBP places a separate. dcb into every folder and the .dcb information held in that folder only applies to that folder. For example, GDG folder will contain a .dcb but will only contain GOOVOO dcb info, nothing else.
Table based DCB
Table based DCB was created to avoid clashes between parallel jobs that required updating the same .dcb however Table based DCB shares the same functional characteristics as File based DCB except, all .dcb entries are loaded into a table including DSORG=PO/GDG.
Table DCB is totally optional and is controlled by a switch (ebp.dcb.dcb.mode.db=true/false) in the EBP properties file. You can switch back and forth between the 2 modes however, if you are in either mode and you create new files, you won’t see those changes reflected in the other environment.
Table based DCB will consolidate all. dcb information by fully qualifying each dataset regardless of the directory structure, much like the mainframe catalog. i.e.
Migrating File DCB to Table DCB
To migrate from File based DCB to Table based DCB, use the import facility shown below.
java -Ddcb.db.table=_TEST -Ddcb.db.driver=com.ibm.db2.jcc.DB2Driver -cp c:\ebp\class\ecobol.jar;c:\ebp\class\db2jcc4.jar com.heirloomcomputing.ecs.util.DCBDBUtils jdbc:db2://localhost:50000/MYDB:currentSchema=DCBDB; userid password c:\ebp\data
dcb.db.table= table name to be created (default DCBDB)*
dcb.db.driver=the DB driver for the database you are using (DB2 above)
-cp= classpath to your installed ecobol.jar and the database jar (DB2 above)
com.heirloomcomputing.ecs.util.DCBDBUtils=where the import facility resides
jdbc:db2://localhost:50000/MYDB:currentSchema=DCBDB; (jdbc connection string and the schema, in this case DCBDB is its own schema)
userid= userid to login to DB
password = password used to login to DB
c:\ebp\data = data directory to start the import, you may have multiple directories like the datalib in EBP.
Note: the import facility will search the entire folder(s) for files and relevant subfolders such as PO and GDG folders so you only need to specify the top level folder.
*: If a table does not exists, a table will be created before the import begins and if you don’t specify the dcb.db.table parameter, the table name will be DCBCB. Table DCB has support for multiple DCBDB instances to support multiple developers, for example, dcb.db.table=_JOHN would allow developer John to have his own set of DCB entries (DCBDB_JOHN) while dcb.db.table=_BETH would allow developer BETH (DCBDB_BETH) to have a totally independent set of DCBs. This concept is similar to File based DCBs when data folders are not shared.
Multiple imports are allowed, any duplicate DCB entries will display an error but will continue to load entries that are not duplicates. However, if there a more than 10 duplicate errors, we suggest dropping the DCBDB table and import again.
Self Healing Import
The import facility will try its best to self heal from bad directory folders but does not cover all cases. For example, if the GDG folder has a dcb entry, it will set the DSORG=GDG if not already set and import each GOOVOO into the catalog. The GDG folder should only contain GOOVOO entries and corresponding dcb entries. However in older version of the GDG processing, the fully qualified file name was stored in the DCB so you’ll get a -803 error on the insert. If that is the case, you may have to manually edit the .dcb in the GDG folder to remove the offending entries.
EBP and Table DCB
Once the import to Table DCB has been accomplished, EBP needs to know which table to use. Below are the java properties that must be set in ebp.properties (available in UI as of v21.4.19).
Important: You must also copy the appropriate Database driver to EBP's WEB-INF/lib folder
If manually adding to the ebp.properties (between v21.2.12 and v21.4.18), the properties are listed below.
*above ebp.dcb.dcb.mode.db turns on Table mode
The rest of the environment variables are associated to the connection info.
Note: for EBP, you must use the prefix ebp.dcb. If using from command line, remove the ebp.dcb like dcb.mode.db=true
Note2: Each developer can have their own local EBP and their own Table DCB as well as their own local Data folder. If each developer is using a shared DB instance, then setting up multiple instances of Table DCB might be useful. However, if all development is local including the DB, then setting up multiple instances is not necessary.
EBP and DB Driver for Table DCB
In order for EBP to read the table based DCB at initialization, you must include your DB driver into the EBP release WEB-INF/lib folder (i.e. C:\apache-tomcat-9.0.35\webapps\ebp##21.2.25\WEB-INF\lib). Failure to do so will result in unpredictable dcb behavior.
Copying Table DCB to a different instance
Define your table first, for example (DB2/UDB):
CREATE TABLE "DCBDB"."DCBDB_JOHN" (
"DSNAME" VARCHAR(50 OCTETS) NOT NULL,
"LRECL" VARCHAR(6 OCTETS),
"DSORG" VARCHAR(5 OCTETS),
"ORIENTATION" VARCHAR(50 OCTETS),
"PROTOTYPE" VARCHAR(6 OCTETS),
"RECFM" VARCHAR(5 OCTETS),
"RECMIN" VARCHAR(6 OCTETS),
"RECAVG" VARCHAR(6 OCTETS),
"CHARSET" VARCHAR(50 OCTETS),
"BLKSIZE" VARCHAR(7 OCTETS),
"GDG_LIMIT" VARCHAR(7 OCTETS),
"KEYLEN" VARCHAR(7 OCTETS),
"KEYOFF" VARCHAR(7 OCTETS),
"ALTKEYOFFS" VARCHAR(7 OCTETS),
"ALTKEYLENS" VARCHAR(7 OCTETS),
"ALTKEYDUPS" VARCHAR(7 OCTETS),
"ALTKEYGROUPS" VARCHAR(20 OCTETS),
"LABEL" VARCHAR(20 OCTETS),
"EXPDT" VARCHAR(26 OCTETS),
"REUSE" VARCHAR(20 OCTETS),
"RELATE" VARCHAR(50 OCTETS),
"ASSOCIATES" VARCHAR(50 OCTETS),
"PATH" VARCHAR(50 OCTETS),
"UPDATE_USER" VARCHAR(50 OCTETS),
ORGANIZE BY ROW
DATA CAPTURE NONE
Once a fully populated Table DCB is loaded, you can copy the Table DCB over to another Table DCB instance, for example:
INSERT INTO DCBDB.DCBDB_JOHN (DSNAME, LRECL, DSORG, ORIENTATION, PROTOTYPE, RECFM, RECMIN, RECAVG, CHARSET, BLKSIZE, GDG_LIMIT, KEYLEN, KEYOFF, ALTKEYOFFS, ALTKEYLENS, ALTKEYDUPS, ALTKEYGROUPS, LABEL, EXPDT, REUSE, RELATE, ASSOCIATES, PATH, UPDATE_USER, UPDATE_TS)
Select * from DCBDB.DCBDB;