How to make use of the batch "Transform" feature of the COBOL runtime

COBOL Batch Transform


The Common record editor allows the user to transform a file between various supported formats. (Refer to Common Record Editor ). As part of this process the user is allowed to save the transformation details to a .prof file. Using this file and the "Transform" program of the COBOL runtime the user can rerun the process from command line.

The command line is as follows:

java -cp <path to ecobol.jar>;<optional path to sql drivers>  com.heirloomcomputing.ecs.util.Transform [help] [quietmode] [warnxfdcharset] [norecvalidate] [badrecordexit] [key:value]

The location of ecobol.jar as well as the sql connection drivers can be set using CLASSPATH variable or using -cp option. 

The command line options are :-

help - Display help Information.
quietmode - Display only final count of records converted.
warnxfdcharset - If the XFD Charset does not match the load file charset, issue a warning but do not exit. Default behavior is to exit.
badrecordexit - If record length is shorter than the layout issue a warning and exit. Default behavior is to issue a warning and continue.
norecvalidate - Specifying this option prevents validation of the record length to the various fields in the record layout. Default behavior is to perform validation.

The [key:value] options allow the user to override or add to the settings in the .prof file. 

Add flag -Dsql.file.useEbcdicBinaryColumn=true, in order to enforce creation one extra column during the Transform that would make possible different EBCDIC ordering of the records. More information about EBCDIC order is available in the article.

The contents of the profile file are in the form of key=value typical of java properties file

Following are the properties that can be specified in the file:

sql.<conn-name>.user=<active sql connection user name>
sql.<conn-name>.password=<active sql connection password>
sql.<conn-name>.url=<active sql connection url>
sql.<conn-name>.driver=<active sql connection driver location>
sql.<conn-name>.autocommit=<active sql connection auto commit (true|false)>
sql.<conn-name>.isolation=<active sql connection isolation (repeatable|uncommitted|committed|serializable)>
sql.<conn-name>.catalog=<active sql connection catalog>
sql.<conn-name>.readonly=<active sql connection readonly (true|false)>
sql.file.useBatchInsert.batchSize=<batch size>

LOGFILE=path/to/logfile [On Windows use \\ as file path separator]
INFILE-DSNPATH=path/to/input/dataset [On Windows use \\ as file path separator]
CONVERTCOUNT=n (n is the number of records to be converted)
CONVERTRANGE=n-m (n-m is the range of records to be converted)
OUTFILE-APPEND=TRUE|FALSE Default behavior is to create new files. Set to TRUE to append.
OUTFILE-DSNPATH=path/to/output/dataset [On Windows use \\ as file path separator]
OUTFILE-PRIMARY-OFFSETS=[n, m, ....] (primary key offsets)
OUTFILE-PRIMARY-LENGTHS=[n, m, ....] (primary key lengths)
OUTFILE-RELKEY-LENGTH=n (relative key length)
OUTFILE-ALTKEY-OFFSETS=[n, m, ....] (alternate key offsets)
OUTFILE-ALTKEY-LENGTHS=[n, m, ....] (alternate key lengths)
OUTFILE-ALTKEY-DUPS=[true, false, ....] (alternate key duplicates allowed)

OUTFILE-ALTKEY-GROUPS=[n, m, ....] (alternate key groups)
OUTFILE-ALTKEY-GROUPS are used to identify split key groups. Non Split keys will have a
indicator value of -1. For e.g.:- [0,0,-1,2,2,2,-1,3,3] represents the following keys:
two field split key(0,0) , non split key(-1), 3 field split key(2,2,2) ,a non split key(-1)
and a two field split key(3,3)

OUTFILE-REC-MINIMUM=n (record minimum length)
OUTFILE-REC-MAXIMUM=n (record maximum length)
OUTFILE-REC-AVG=n (record average length)
OUTFILE-CHARSET= (Charset/Codepage)

VDB-IDXINFO-idxname=[n, m, ....][n1, m1, ....]
For each alternate key in a VDB output, an attrib 'VDB-IDXINFO-idxname' is created,
where idxname is replaced by the idx name that is specified
The value contains a combination of offset values[n, m, ....] and lengths[n1, m1, ....]

RFS-VERSION=1 XFD Record Format Structure
XFD[n]-NAME=value -name of xfd xml file created during compilation
XFD[n]-WHEN[n]-IDXDESC=value --
|-WHEN conditional information. These may be repeated multiple times for each xfd xml file
XFD[n]-WHEN[n]-INFO=value --
XFDVISIBILITY=value -XFD field visibility info. Occurs once

The following key=value properties are applied for the VDB output files when the input has multiple record layouts and/or redefines. These properties decide the the VDB views that get created for the output table

USE-VARCHAR=TRUE|FALSE Use VARCHAR declaration whereever CHAR PIC(X) is in use
MATERIALIZED-VIEW=TRUE|FALSE Create SQL for materialized View
INCLUDE-LAYOUTS=Layout1,Layout2,Layout3,..... Include layouts from a multi-layout XFD
EXCLUDE-LAYOUTS=Layout1,Layout2,Layout3,..... Exclude layouts from a multi-layout XFD
RENAME-LAYOUTS=Layout1:MyLayout,Layout2:UrLayout,Layout3:HisLayout,..... Override the layout field name during SQL generation
REDEFINES_USE= <Layout>.<RedefinedField1>:<RedefiningField1>,....... 

where <layout> is the name of the top 01 level record field

<RedefinedField1> is the name of the base field that is being redefined
<RedefiningField1> is the name of the redefining field to be used when creating the view

The <layout> qualifier is required when multiple layouts (01 levels) are present If the <layout> qualifier is not present, the field is processed for every layout encountered.
For e.g.

The default behavior when REDEFINES_USE is not specified is to use the base field being redefined to create the view
Specifying * as the redefining field will create a view consisting of the base redefined field and also views for each of
redefining fields of that base redefined field
For e.g.
Note the * can be specified for only one redefining field. If multiple redefines are present, the others will all default to base redefined field unless specified otherwise.

01 L1.
05 A.
05 B.
05 B1 redefines B.
05 B2 redefines B.
05 B3 redefines B.
05 C.
05 D.
05 D1 redefines D.
05 D2 redefines D.
05 D3 redefines D.
05 E.
05 F.
05 F1 redefines F.
05 F2 redefines F.
05 F3 redefines F.
05 G.

For the above layout consider the following scenarios
1) REDEFINES_USE not specified or default behavior
            View created = V(A,B,C,D,E,F,G)
            View created = V(A,B2,C,D,E,F3,G)
            View/s created = V(A,B2,C,D, E,F2,G)
4)REDEFINES_USE=* Same as (3) but applies the * to the first redefines within the layout
            View/s created = V(A,B, C,D,E,F,G)

As can be seen all of the settings that are provided in the .prof file can be provided as part of the command line options. One could effectively run the Transform utility without providing a .prof file and instead providing all the needed information using the key:value pairs.  


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk