Elastic COBOL supports a number of compile-time options and runtime-options. Runtime options affect the behavior of a program while it is running, either in a stand-alone (command-line) environment, under control of the Elastic Batch Platform (batch) environment, or within the Elastic Transaction Platform (online) environment. Other configurations and settings also affect the operation of programs. Different file protocols affect the way COBOL files are stored and accessed and SQL properties affect database interactions. Also, when calling subprograms other than those written in COBOL or Java calling convention settings may be required.
Compile-time options are those passed to the ecobol command invokes the compiler from a command-line environment. It accepts the same options that may be set in the Elastic COBOL Eclipse IDE under COBOL Compiler Settings. Compiler directives can be set on the compiler command line, in the Additional Parameters field of the COBOL Compile Settings for the project or within the program itself with the "$SET DIRECTIVE" or "$SET PGM-DIRECTIVE" statements ('$' in column 7 on fixed-format source files). Run-time option name can be specified with a value as environment variables set before the program starts, as a Java property (-Dname=value in a VM argument to the Java command), as command-line options (name=value after the class name) or set programmatically with the SET CONFIGURATION COBOL statement. Run-time options may also be compiled into the generated Java program with the "-run name=value" compiler directive, the "$SET RUNTIME 'name=value'" statement or $SET DIRECTIVE '-run name=value'" statement.
A variation of "$SET DIRECTIVE" is "$SET PGM-DIRECTIVE myprog.cbl directive". This is best used in an ecobol.dir file as an alternative to inserting directives into the application source. In this case, the "directive" is only applied to "myprog.cbl" - it will not be applied to any other source files.
See EBP Configuration options or ETP Configuration options for information on runtime options of those systems.
Elastic COBOL Compiler Options
The compiler options are available by typing:
ecobol -?
The ecobol.exe compiler executable and its support files (etrans.jar, ecobol.jar, ECERR.txt) are distributed with the Elastic COBOL IDE. They are contained in the Eclipse installation directory in the following subdirectories
You may copy all of these files to another location, such as your home directory's "bin" directory (xx.yy.zz is the ECOBOL version) or create symbolic links on Linux in a well -known directory to them:
- ./com.heirloomcomputing.ecd.core_xx.yy.zz/elastic_cobol/bin/win64/x86_64/ecobol.exe or
- ./com.heirloomcomputing.ecd.core_xx.yy.zz/elastic_cobol/bin/linux/x86_64/ecobol
- ./com.heirloomcomputing.ecd.core_xx.yy.zz/elastic_cobol/etrans.jar
- ./com.heirloomcomputing.ecd.core_xx.yy.zz/elastic_cobol/ecobol.jar
- ./com.heirloomcomputing.ecd.core_xx.yy.zz/elastic_cobol/ECERR.txt
Elastic COBOL uses runtime Gnu C and C++ libraries that should already be installed on your system. If you experience errors (e.g., "Missing GLIB 2.14") you need to install these dependent libraries before running. On Linux, install with these commands
sudo yum install libglib2.0-0 libstdc++
or
sudo apt-get install libglib2.0-0 libstdc++
Option |
Description/Option Value |
-? |
Help on Elastic COBOL Options |
-help |
Help on Elastic COBOL Options |
-help:old |
Help on Elastic COBOL Deprecated Options |
-help:acu |
Help on Elastic COBOL Acu-Style Options |
-h |
Help on Elastic COBOL Simple-Style Options |
-cc |
Transpile COBOL to Java |
-ccj |
Transpile COBOL to Java, then compile Java to class files (default) |
-ccjx |
Transpile COBOL to Java, then compile Java to class files, then execute the main class |
-dt n |
Data type compatibility with various environments (n: 0=EC, 2=Acu, 4=MPE, 5=MF, 6=RM, 7=IBMA, 8=IBME) IBMA = IBM ASCII (e.g., IBM Power Series, AIX) IBME = IBM EBCDIC (e.g., IBM Z, z/OS) |
-dt:ec |
Datatype Compatible with Elastic COBOL (default) |
-dt:ibma |
Datatype Compatible with IBM ASCII |
-dt:ibm -dt:ibme |
Datatype and file storage Compatible with IBM Enterprise COBOL ("native EBCDIC" mode) |
-dt:mf |
Datatype Compatible with Micro Focus |
-dt:acu |
Datatype Compatible with AcuCOBOL |
-dt:mpe |
Datatype Compatible with HP MPE/iX COBOL-II |
-dt:rm |
Datatype Compatible with Liant RM/COBOL 7 |
-dt:bin |
BINARY is BINARY-REV |
-dt:truncbin |
BINARY byte truncation rather than PIC truncation |
-dt:compbin |
COMPUTATIONAL is BINARY |
-dt:aix |
Datatypes Compatible with IBM AIX |
-dt:os2 |
Datatypes Compatible with IBM OS/2 |
-source:auto |
Auto-detect source format (default) |
-source:free |
Free-form source code |
-source:fixed |
Fixed-form source code |
-source:variable |
Variable-form source code |
-source:utf8 |
UTF-8 encoding |
-source:copypath pathname |
Set COPY library path to parameter pathname |
-source:suppress name |
Suppress parameter name from being reserved word |
-source:ignore name |
Ignore parameter name as a reserved word |
-source:wordlist filename |
File filename contains reserved word suppress list |
-source:ansikey |
Use only ANSI keywords |
-source:basednumeric |
Based Literals are Numeric (Hex,Decimal,Octal,Binary) |
-source:hp |
Prefer HP semantics when in conflict. |
-source:path pathname |
Add parameter to front of PATH |
-source:tabsize |
Set tab size in spaces |
-source:pause |
Pause after compilation |
-source:dbcs |
Activate SHIFT-IN/SHIFT-OUT DBCS 0x0e, 0x0f |
-source:dbcsso char |
Activate parameter char as DBCS SHIFT-OUT |
-source:dbcssi char |
Activate parameter char as DBCS SHIFT-IN |
-source:obsx |
Flag Syntax Obsolete in COBOL 2002 or X/Open |
-source:archaic |
Flag Syntax Archaic in COBOL 2002 |
-source:assignenv |
ASSIGN TO name is environment, not variable |
-source:assignvar |
ASSIGN TO name is variable, not environment |
-out:ecoboldir pathname |
pathname to directory containing ecobol.dir |
-out:java |
Generate .java files from COBOL source, but do not generate .class files afterwards |
-out:javaversion n |
Compile COBOL to specified Java version and use javac -source 1.n and -target 1.n options (also see -script:javac option) |
-out:class |
Compile COBOL to .java, then executable .class (default) |
-out:execute |
Compile COBOL to .java, .class, then execute |
-out:cobolinjava |
Include COBOL statements in .java |
-out:nocobolinjava |
Do not include COBOL statements in .java (default) |
-out:manyfields |
Each 01 level in own constructor in .java |
-out:name name |
Use parameter as name for applet/application |
-out:subprogram |
Designate as subprogram |
-out:package name |
Use parameter as generate Java package name causing Java output to contain the package statement and be placed in a corresponding directory hierarchy |
-out:html |
Generate template HTML file |
-out:nohtml |
Do not generate template HTML file |
-out:bean |
Create CobolBean interface |
-out:servlet |
Create Servlet interface |
-out:nobean |
Do not create CobolBean interface |
-out:nothreadlock |
Disable ThreadQueue suspension |
-out:dir dirname |
Set output directory to parameter |
-out:omapdir dirname |
Set output directory of .omap files used by Eclipse Elastic COBOL IDE to parameter |
-out:japplet |
Inherit from JApplet by default |
-out:applet |
Inherit from Applet by default |
-out:suppress |
Suppress generated output (check only) |
-out:filter n |
Set output filter (n: 0=native, 1=EBC-to-ASC, 2=ASC-to-EBC, 3=breakup large classes) |
-out:noarrayprops |
No Array GET|SET Properties |
-out:assert |
Enable ASSERT functionality |
-out:staticinvoke |
Statically bind OO invokes where possible |
-out:notransient |
Do not produce transient modifiers |
-out:smap |
Generate .smap file |
-out:nopretty |
Do not create pretty java code |
-out:transaction |
Allow EXEC TRANSACTION capabilities |
-out:importjava name |
Generate a Java import statement with the given parameter class specification (e.g., javax.servlet.*). |
-out:indexcheck |
Check table indexes against table bounds |
-out:noindexcheck |
Do not check table indexes against table bounds |
-out:indexsize |
Set INDEX byte size to param |
-out:cicsmsg |
Set transaction message level |
-out:transactionmsg |
Set transaction message level |
-out:odoslide |
Generate OCCURS arrays exactly the size specifies in the DEPENDING ON variable within enclosing groups |
-out:noodoslide |
Generate OCCURS arrays such that they allocate the maximum size within enclosing groups (default) |
-out:translate |
Generate shorter Java names for groups and elements, do not generate shared string constants, implies -out:cobolinjava |
-out:linkage |
DFHEIBLK and DFHCOMMAREA variables creation (NO or YES 'default') |
-out:mergeduplicateconditions |
Merge the values of duplicate Level 88 conditions into a single condition |
-out:nomergeduplicateconditions |
Generate an "ambiguous identifier" error when duplicate Level 88 condition names are referenced (default) |
-out:[no]converthex |
Convert the value of hex strings "in the wild" from EBCDIC to ASCII. |
-err:file filename |
Set error filename to parameter |
-err:none |
No error output |
-err:stdout |
Send errors to stdout |
-err:stderr |
Send errors to stderr |
-err:max n |
Set maximum reported errors to parameter |
-err:level |
Minimum error Level (0=All, 1=Warning, 2=Error) |
-err:pedantic |
Pedantic error messages |
-err:optinfo |
Generate informational messages for optimizations |
-err:nooptinfo |
Do not generate informational messages for optimizations (default) |
-script:execute |
Execute scriptfile upon completion |
-script:append parameter |
Append parameter to end of scriptfile |
-script:format |
Format each line of scriptfile according to parameter |
-script:javac javaccommand |
Use parameter as Java Compiler string |
-script:java javacommand |
Use parameter as Java Runtime string |
-run:defaultbyte |
Fill initial memory with byte number or 'space' |
-run:noprogressbar |
Do not generate runtime progress bar during download |
-run:nocheckversion |
Do not generate runtime code to verify Java version |
-run:performrecurse |
Use MF style perform |
-run:noperformrecurse |
Use ANSI style perform |
-run:novisiblecallfail |
Disable Visible Call Failure |
-run:console |
ACCEPT and DISPLAY statements (without an explicit UPON clause) default to CONSOLE ( graphical user interface window or ASCII terminal) rather than SYSIN/SYSOUT (standard in / standard out). The default is -run:system |
-run:system |
ACCEPT and DISPLAY statements (without an explicit UPON clause) default to SYSIN/SYSOUT (standard in / standard out) rather than |
-run:visiblecallfail |
Enable Visible Call Failure |
-run:dynvisiblecallfail |
Allow runtime to enable/disable Visible Call Failure |
-run:novisibleopenfail |
Disable Visible Open Failure |
-run:visibleopenfail |
Enable Visible Open Failure |
-run:dynvisibleopenfail |
Allow runtime to enable/disable Visible Open Failure |
-run:redefinesinfo |
Preserve REDEFINES info at runtime for Datatype |
-run:trace |
Produce tracing messages for PARAGRAPH/SECTION, CALL, GOTO, PERFORM, FILE I/O operations & SQL I/O operations |
-run:tracecall |
Produce tracing messages for each CALL. |
-run:tracegoto |
Product tracing messages for each GOTO. |
-run:traceio |
Produce tracing messages for each FILE I/O operation. |
-run:tracepara |
Produce tracing messages for each PARAGRAPH/SECTION. |
-run:traceperf |
Produce tracing messages for each PERFORM. |
-run:tracesql |
Produce tracing messages for each SQL I/O operation. |
-run:tracestack |
Produce a COBOL stack trace if exception occurs. |
-run:tracefullsrcpath |
Emit full source path for program source location in trace output (not default). |
-run:notrace |
Turn off all tracing messages. |
-run:notracecall |
Turn off tracing messages for each CALL. |
-run:notracegoto |
Turn off tracing messages for each GOTO. |
-run:notraceio |
Turn off tracing messages for each FILE I/O operation. |
-run:notracepara |
Turn off tracing messages for each PARAGRAPH/SECTION. |
-run:notraceperf |
Turn off tracing messages for each PERFORM. |
-run:notracesql |
Turn off tracing messages for each SQL I/O operation. |
-run:wdm |
Enable WITH DEBUGGING MODE, allowing lines with 'D' in the indicator column to be executed. |
-run:nowdm |
Disable WITH DEBUGGING MODE, preventing lines with 'D' in the indicator column to be executed. |
-run name=value |
Generate code that sets the run-time option name to value as if -Dname=value was specified on the Java command line, as an environment variable, or in the cblconfig or etp_deploy_settings.properties run-time configurations files. |
-run ebcdic_codepage=<number> |
Adds a run-time parameter for the EBCDIC codepage that will be used if the 'collateAsEBCDIC' flag (can be seen below) is up. <number> can be either 037 or 277. These numbers match exactly collation sequences:
If a different codepage number is provided, 037 will be used as default. Note that there is a slight difference between Codepage037 and SQL_EBCDIC037_CP1_CS_AS. This is true for codepage 277 as well. |
-file:shareallothers |
Default share: SHARING ALL OTHER |
-file:sharenoother |
Default share: SHARING NO OTHER |
-file:sharereadonly |
Default share: SHARING READ ONLY |
-file:sharenone |
Default share: no default/explicit sharing |
-file:$infilename |
dollar symbol ($) may be part of file name |
-cache:auto | enable | disable | forbid | smart | external -cache:0 | 1 | 2 | 3 | 4 | 5 -cache:external:section-type |
Enable or disable various forms of group and element value caching. Disable cache is the default which means element values are fetched from the COBOL section memory (e.g., working storage, linkage section, etc.) when referenced and saved when changed. Other settings will cache those values in Java objects and invalidate/flush the values when necessary. Based on the usage and frequency of REDEFINES, OCCURS, OCCURS DEPENDING ON and access/modification of groups and elements within groups you may find that different caching algorithms (enable 1, forbid 3, smart 4) may perform better in certain instances. Using external 5 will cause memory allocation to be performed outside the Java heap. This has two effects, larger programs may benefit by having their working-storage and other sections allocated in the non-JVM garbage-collected heap usually reserved for OS malloc() and free() memory allocation and, when used with UNSAFE calling convention, it allows for persistent (non changing) pointers to COBOL variables to be passed to C-libraries invoked from COBOL. Setting auto attempts to determine the best for your program. Indicating a :section-name will enable that cache setting only for that section-type (wrk, lnk, fil, etc.). |
-sql:off |
Disable SQL Support. Abends on SQL statements |
-sql:len |
Set SQL VARYING stub len to param (len) |
-sql:txt |
Set SQL VARYING stub txt to param (arr) |
-sql:next |
SQL JDBC/DB2 next() workaround |
-sql:db2 |
SQL IBM JDBC/DB2 workarounds |
-sql:mssql |
SQL workarounds for Microsoft SQL Server, specifically define cursors as scroll type SENSITIVE if they are also UPDATABLE because MS SQL Server disallows the combination of INSENSITIVE and UPDATABLE. |
-sql:cro |
Use JDBC CONCUR_READ_ONLY for the concurrency setting when defining cursors (default UPDATABLE cursors) |
-sql:ta |
SQL Transaction Adjust |
-sql:sc |
SQL Server handles Concat (||) |
-sql:it |
SQL Ignore Right Truncation |
-sql:jdbc level |
JDBC level to which to generate JDBC API methods (level: 1, 2, 3, 4) |
-sql:sp name |
Generate SQL Stored Procedure of type name. db2 only supported at this time. |
-sql:spschema name |
Schema of the stored procedure. Used at compile time stored procedure validation against the database. This parameter is optional, as the -sql:user will be used as the default. |
-sql:spname name |
Name of the stored procedure. Used at compile time stored procedure validation against the database. This parameter is required for COBOL stored procedure compiles. |
-sql:logmode NO|YES |
SQL Logging (NO, YES) |
-sql:groupmode |
SQL group items treated as single item |
-sql:nogroupmode |
SQL group items treated as multiple items |
-sql:nowarn |
SQL Warning not obtained from JDBC |
-sql:declarestatic |
SQL DECLARE CURSOR always static |
-sql:declaredynamic |
SQL DECLARE CURSOR dynamic when possible (default) |
-sql:opt |
Pass SQL option, -sql:opt ? for dump |
-sql:mode ANSI|ORACLE|DB2 |
SQL Process statements and return results in given parameter mode (ANSI, ORACLE, DB2). DB2 mode simulates DB2 for z/OS on other databases such that error DB2 SQLCODEs are translated from SQLSTATEs and SAVEPOINT-protected INSERT/UPDATE/DELETE statements do not abort transactions upon error |
-sql:cc NO|YES |
SQL Close on Commit to parameter (YES, NO) |
-sql:eof |
SQL END OF FETCH value (100,1403) |
-sql:unsafenull NO|YES |
SQL Unsafe Null (NO,YES) |
-sql:picx |
SQL PICX type (CHARF,VARCHAR2) |
-sql:url |
Check SQL syntax against database URL (e.g., jdbc:postgresql://localhost/mydb) |
-sql:user |
Check SQL syntax against database USER (e.g., postgres) |
-sql:password |
Check SQL syntax against database PASSWORD (e.g., mypw) |
-sql:driver |
Check SQL syntax against database DRIVER (e.g., org.postgresql.Driver) |
-listing:xml |
Listing file XML form to programid.xml |
-listing:body |
Listing file XML includes source body |
-listing:define |
Listing file XML includes 'define' tag |
-listing:file |
Listing file set to mainfile.list |
-listing:cross |
Listing file includes cross-reference |
-listing:vbref |
Listing file cross-reference includes verbs |
-listing:info |
Listing file cross-reference includes info lines |
-listing:all |
Listing file cross-reference includes all options |
-listing:dir |
Listing files output directory |
-cp pathlist |
Use parameter as classpath during Java compile |
-opt:large |
Optimize for extremely large (> 100KLOC) input files |
-opt:break n |
Implies -opt:large. Break up output Java classes every n lines instead of the default 10000 |
-opt:break para |
Implies -opt:large. Break up output Java classes every COBOL paragraph. Output classes are also named after the paragraph name. |
-opt:break section |
Implies -opt:large. Break up output Java classes every COBOL procedure division section. Output classes are also named after the section name. |
-opt:initialize |
(Default) Generates a optimized version of the initialize statement. A single java initialize statement is created corresponding to each COBOL initialize statement for group fields |
-opt:noinitialize |
Generates a non optimized version of the initialize statement. Multiple java initialize statements is created corresponding to each COBOL initialize statement for group fields |
-opt:occurs |
Optimize OCCURS arrays (tables) such that no Java array is actually generated, but simulated as an object with getters and setters. This is faster for sparse arrays, i.e., large OCCURS x TIMES where x is large but only a few of the elements are actually used. Also required when redefining a table and subsequent indexes are out-of-bounds. |
-opt:nooccurs |
Generate COBOL OCCURS arrays (tables) as Java arrays (default). |
-opt:keepunusedvars |
Do generate unused group and element variables in the Java output |
-opt:deleteunusedvars |
Do not generate unused group and element variables in the Java source code (default) |
-collateAsEBCDIC
|
By default COBOL programs use the ASCII collating sequence to do string comparisons, in this mode "1" < "a". This flag sets the compiled program to use the EBCDIC collating sequence which means that "1" > "a". Alternatively it is possible to use the COBOL configuration section to set this collating sequence, this also gives more options to provide custom collating sequences. configuration section. |
Elastic COBOL Runtime Options
Elastic COBOL runtime options are applied as Java defined arguments (i.e. with -D) to the JVM.
java –Dname=value –jar myproj.jar
Application arguments are passed as named pairs (e.g. name=value).
java –jar myproj.jar name=value
These named pairs can also be included as part of an Elastic COBOL configuration file in the current working directory or /etc directory named cblconfig, cblconfi, cobopt.cfg or any other filename as set with the CBLCONFIG property (e.g. –DCBLCONFIG=/tmp/my-ec.conf).
name=value
Option |
Value |
Description |
BE |
ISO-8859-1, Cp1047 |
Overall Byte Encoding for storage of bytes in the COBOL memory array. Java strings are in UTF-8, but COBOL memory must fit in 8-bit bytes. For most datatype settings this is ISO-8859-1 (ASCII) but for -dt:ibm operating in EBCDIC mode, this is Cp1047 by default. Can be explicitly overridden at runtime. See ibm.encoding, sql.encoding, file.encoding |
BUFFER-OVERRUN |
Yes/1/On/True/Relax, No/0/Off/False/Strict, Extreme |
Yes/Relax: Allow buffer overrun during MOVEs in certain situations (Enterprise COBOL for zOS compatibility). No/Strict: Prevent buffer overrun in all cases (cannot overwrite beyond the size of an element to a subprogram, i.e., safest). Extreme: Allow buffer overruns up to the size of memory. |
CHECKINDEX |
True/1/on/yes, False/0/off/no |
Used along with compiler option -out:indexcheck. Its value determines what happens when an index out of bounds situation is detected. When set to true, it causes the runtime to throw an IndexOutofBounds CobolException and terminate the program.When set to false(default), it causes the runtime to return an ArrayIndexOutOfBoundsVariable object as the referenced item. |
CHECKNUM |
True/1/on/yes, False/0/off/no |
Check packed decimal (COMP-3) for valid characters before arithmetic or display operations |
CODE-CASE |
0, 1, 2 |
Forces uppercase or lowercase program names for all CALL statements. 0 = No force (default), 1 = Force lowercase, 2 = Force uppercase. |
CODE-MAPPING |
True, False |
Enables program name mapping for CALL statements. At the time of a CALL, if CODE-MAPPING is enabled and a configuration parameter matching the CALL statement's program name is set to a value, the value of the parameter is used in place of the program name. |
CODE-SUFFIX |
none |
Appends a string to the end of program names for all CALL statements. |
COLUMNS |
80 |
Changes the default number of screen columns for the console. |
CONSOLE |
default |
List of console font settings, separated by commas, in this order: CONSOLE-CELL, CONSOLE-WIDTH, CONSOLE-WIDTH-MIN, CONSOLE-WIDTH-MAX, CONSOLE-WIDTH-MULT, CONSOLE-FONT. |
CONSOLE-CELL |
default |
Overrides the console's font width setting. |
CONSOLE-FONT |
default |
Override the default console font where applicable. |
CONSOLE-FONT-SIZE |
default |
Override the default console font size where applicable. |
CONSOLE-WIDTH-MAX |
default |
Sets the maximum width of font allowed. |
CONSOLE-WIDTH-MIN |
default |
Sets the minimum width of font allowed. |
CONSOLE-WIDTH-MULT |
default |
Sets a multiplier for the font width heuristic. |
CONSOLEBG |
BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, BROWN, WHITE, BRIGHT-BLACK, BRIGHT-BLUE, BRIGHT- GREEN, BRIGHT-CYAN, BRIGHT-RED, BRIGHT- MAGENTA, BRIGHT- YELLOW, BRIGHT- BROWN, BRIGHT-WHITE |
Background color used by default in the graphically emulated text console. |
CONSOLEFG |
GREEN CYAN, RED, MAGENTA, YELLOW, BROWN, WHITE, BRIGHT-BLACK, BRIGHT-BLUE, BRIGHT- GREEN, BRIGHT-CYAN, BRIGHT-RED, BRIGHT- MAGENTA, BRIGHT- YELLOW, BRIGHT- BROWN, BRIGHT-WHITE |
Foreground color used by default in the graphically emulated text console. |
CONVERT-NUMERIC |
True/1/on/yes/False/0/off/no |
By default, when passing numerics such as COMP-3 to native (C) methods, convert them to the most appropriate data type (int, long) ignoring precision and scale. Set to NO to pass numerics as their internal byte (e.g., packed decimal) representation. |
CURSOR-MODE |
1, 2, 3 |
Determines when the cursor should be visible: 1=Always, 2=Never, and 3=Only during ACCEPT. |
DDNAME |
DATASETNAME |
When -source:assignenv compiler option is specified, associate DDNAMEs from HCI Batch Platform (JES/JCL) referenced in COBOL programs to DATASET (file) names on disk. |
DDNAME.DISP |
SHR, OLD, MOD |
When -source:assignenv compiler option is specified, set the disposition of the COBOL connection for the SELECT statement. By default, INPUT is shared (SHR) disposition and OUTPUT and I O are exclusive (OLD) disposition. Applications running in HCI Batch Platform (JES/JCL) with DISP=MOD set the equivalent of EXTEND mode although the program opens for OUTPUT. |
DDNAME.encoding |
Cp1047, ISO-8859-1, not set |
When different files within the same program are encoded with different code sets (e.g., ASCII and EBCDIC), this will specify the encoding of a particular file when it is different from the default operations (file.encoding, ibm.encoding). Most useful when running programs in "EBCDIC mode" (-dt:ibm compiler option) where some input files are in ASCII or UTF-8. Or, when operating programs in "ASCII mode" (-dt:ec or -dt:mf compiler options) with some files brought down from the mainframe (EBCDIC data). Note that Java Charset encoding / decoding is performed on entire records such that a record containing "a" (EBCDIC 0x81) is translated to "a" (ISO-8859-1 0x61) allowing a program to compare the PIC X(1) element to the literal constant 'a'. However, an EBCDIC half-word binary number 64 (EBCDIC null+space, 0x0040) would also be translated (ASCII null+space 0x0020) ... and not conform with the expected little-endian binary representation of the number 64 (0x4000) representing a PIC S9(4) BINARY element with default compiler settings. |
DEBUGMODE |
True, False |
Execute in debugger if debug information present. This debug information must have been compiled into the program by setting the debug flag before compilation. |
DEFSYS |
True, False |
Default to SYSIN/SYSOUT rather than CONSOLE or other runtime default. This may also be specified at compilation time. |
DLL-LINK |
dll-or-so-library,... |
List of dynamic linked libraries or shared object libraries (i.e., libmyso.so, my.dll) that should be pre-loaded before COBOL calls reference C functions within them. If no preloading is done, you must explicitly CALL "libmyso.so". prior to invoking functions within it. The library must be in the LD_LIBRARY_PATH (Linux), PATH (Windows) or LIBPATH (AIX) environment variable paths in order to be found or a program-not-found error will occur. Default is to not load any libraries. |
DLL-CONVENTION |
0 (CDECL) | |
The default calling convention to use for C libraries. The default is determined by the libraries accessed (if possible) or 0 (CDECL) on Linux/UNIX or 1 (STDCALL) on Windows. To protect Java memory transient variables are created and passed to C-libraries with CDECL and STDCALL, even with BY REFERENCE parameters. However, UNSAFE uses the Java Unsafe API to obtain actual pointers to the Java objects and pass them directly to called C routines. This may result in increased performance, but more risk should buffer overruns occur within called routines. However, pointers to the same COBOL variable may change from call-to-call because of Java Garbage Collection. To prevent this (COBOL variable addresses retain their static nature), allocate outside the Java heap with compiler option -cache:external. |
EXTERNALS |
SESSIONSAFE|ON|1| GLOBAL|OFF|0 |
The treatment of COBOL EXTERNAL variables is either SESSIONSAFE (default) or GLOBAL. With SESSIONSAFE, variables marked EXTERNAL are private within a JEE "session" (e.g., ETP/CICS logged on user session) and COBOL program Java objects instantiated by Java programs. With GLOBAL, external variables are shared across all sessions and program instances. Java programs that instantiate COBOL programs objects and manage them separately may want to share all EXTERNALs and use GLOBAL. |
file.encoding |
Cp1252 |
Encoding for all I/O (file and display statements). |
FILESYSTEM |
ECOBOL, MICROFOCUS, MF, MF3, MF8 ACUCOBOL, ACUCONNECT, ISAM, OS400, SYNCSORT, IBMV, IBMVB |
Changes the default filesystem used by Elastic COBOL If a protocol is not specified in an ASSIGN TO, the default filesystem is used where applicable. MF3 is IDX3 support, MF8 is IDX8 support (MF on read will iterpret correct encoding). |
FILESYSTEMIDX |
ECOBOL, MICROFOCUS, MF, MF3, MF8, ACUCOBOL, ACUCONNECT, ISAM, OS400 |
Changes the default filesystem for indexed files. If a protocol is not specified in an ASSIGN TO, the default filesystem is used where applicable. MF3 is IDX3 support, MF8 is IDX8 support (MF on read will iterpret correct encoding). |
FILESYSTEMREL |
ECOBOL, MICROFOCUS, ACUCOBOL, ACUCONNECT, ISAM, OS400 |
Changes the default filesystem for relative files. If a protocol is not specified in an ASSIGN TO, the default filesystem is used where applicable. |
FILESYSTEMSEQ |
ECOBOL, MICROFOCUS, MF ACUCOBOL, ACUCONNECT, ISAM, OS400, SYNCSORT, IBMV, IBMVB |
Changes the default filesystem for sequential files. If a protocol is not specified in an ASSIGN TO, the default filesystem is used where applicable. |
FILESYSTEMCOMPRESSION |
off | false | no | 0on | true | yes | 1 |
Turn on or off MF style data compression (CBLDC001 compatible) or specify user-defined compression algorithm(s) with number and class. Number is between 128 and 255 and class represents a class name (e.g., "com.example.mycomp") which implements the Java interface com.heirloomcomputing.ecd.MFFile$Compression defined by two methods, public byte[] compress(byte[] buf, int start, int len); public byte[] decompress(byte[] buf, int start, int len); |
GARBAGE |
DEFAULT VERBOSE QUIET |
Used to determine the actions associated with the creation and interaction with ArrayIndexOutOfBoundsVariable object. Default behavior is to return 0/null when accessed and throw a CobolException if an attempt is made to move a value to it.VERBOSE is similar to DEFAULT but also logs a message if Logging is set to true. The messages get logged when an IndexOutofBounds error occurs and also when the ArrayIndexOutOfBoundsVariable throws an exception. QUIET is same as DEFAULT but does not throw an exception when a value is moved to the object. |
ibm.encoding |
Cp1047 |
File encoding for IBM EBCDIC files when -dt:ibm compile time option has been specified. |
HANDLE-ERROR |
DEFAULT ( TRUE | ON ) FALSE | OFF |
Allows the catch all error handler to be explicitly disabled/ignored. By default the handler will be on whenever the application program specifies the HANDLE CONDITION ERROR() and setting the parameter to FALSE or OFF disables it. |
IDXCACHE |
default |
Changes the indexed file cache size percentage setting. To double the cache size use 200.0, to halve it use 50.0. This setting enables fine tuning of indexed file performance in some cases. |
IDXCACHEMODE |
READONLY, READWRITE |
Changes the default indexed file cache mode setting. Read only caching is slower, but also safer. NOTE: If this value is not set and the indexed file is open for MASS UPDATE, then read-write caching is used. |
DB-BUFFER-SIZE |
Numeric value |
Turns on I/O buffering capabilities. Issues commit every numeric-value number of operations for database-based file protocls (VDB: and VSQL: file formats). Specifying a value of 0 instructs the COBOL run time to "autocommit" the database. Specifying a negative or non-numeric value has the same effect as omitting the parameter; I/O buffering is off. |
DB-ROWS-TO-FETCH |
Numeric value |
When jdbc autocommit is OFF this controls the number of rows returned in any resultsets for the database-based file protocols (VDB: and VSQL: file formats). The default for this parameter is 1000. Use smaller values if you typically use START GE (COBOL I/O) or STARTBR GE (ETP I/O) followed by only a few READs. Special case for MySQL use -2147483648 to restrict computation of result to 1 row. When used in combination with -Ddisable_sqlcursors=true, -DbatchUpdateThreshold=100 and -DDB-ROWS-TO-FETCH=1000, VDB will construct a query select top 1000 and |
disable_sqlcursors |
True, False |
Disable usage of SQL cursors When used in combination with -Ddisable_sqlcursors=true, -DbatchUpdateThreshold=100 and -DDB-ROWS-TO-FETCH=1000, VDB will construct a query select top 1000 and |
batchUpdateThreshold
|
Numeric value |
Set batch mode threshold for When used in combination with -Ddisable_sqlcursors=true, -DbatchUpdateThreshold=100 and -DDB-ROWS-TO-FETCH=1000, VDB will construct a query select top 1000 and |
IO-BUFFER-SIZE |
Numeric value |
Turns on I/O buffering capabilities. Creates a buffer size in bytes for file-based protocols with the numeric value provided. Specifying a value of 0 instructs the COBOL run time to use the default buffer size. Specifying a negative or non-numeric value has the same effect as omitting the parameter; I/O buffering is off. |
KEYCODESTYLE |
ACU, MF, CHAR, JAVA |
Controls which raw key codes are returned in CRT-STATUS. For example, JAVA will return VK_KeyEvent codes, CHAR will return ASCII codes, MF returns Micro Focus style codes, ACU returns AcuCOBOL style codes. |
LINES |
25 |
Changes the default number of screen lines for the console. |
LOG |
True, False, SEVERE, ERROR, WARNING, INFO |
Enable general runtime logging or tracing at various levels, default no logging (False). True is same as INFO level (all I/O operations), WARNING (file open conditions that result in non 00 file status such as mismatched COBOL FD specification and file headers like key or record sizes), ERROR (error conditions), SEVERE (catastrophic conditions). |
LOG_SQL |
True, False |
Enable verbose logging of runtime SQL activity; this is useful for tracking down lower-level activities of the SQL/JDBC access. |
MQ_CHANNEL |
default |
Assigns MQSeries channel setting. |
MQ_HOSTNAME |
localhost |
Assigns MQSeries client hostname or IP address. |
MQ_PASSWORD |
none |
Assigns MQSeries user password. |
MQ_PORT |
default |
Assigns MQSeries port number. |
MQ_USER_ID |
none |
Assigns MQSeries user identification. |
MQSERVER |
localhost |
Assigns MQSeries server hostname or IP address. |
NULL-POINTER-DEREFERENCE |
No/0/Off/False, Yes/1/On/True |
Allows variables that have their address set as NULL POINTERs to be dereferenced. Such pointers reference page zero of virtual memory, which contains LOW-VALUES. By default a NULL dereference will cause a program to fail with a Java NullPointerException. |
NUMPROC |
PFD, NOPFD, MIG, BULL, NCR |
Interpret Packed Decimal sign digits. Similar to IBM Enterprise COBOL NUMPROCsuch that PFD: preferred sign digits X'C' (credit, +), X'D' (debit, -), X'F' (unsigned); NOPFD: not preferred accepts allX'A'..'F' digits, 'B' and 'D' being debit (-); MIG: migrated OS/VS cobol; BULL: Bull all X'A'..'F' digits,X'B' also indicates credit (+), NCR: NCR X'B' (credit, +), X'D' (debit, -), X'F' (unsigned). |
PFTERMS |
default |
Controls function key terminator assignments. Forexample: 4-6,!9,10 will assign F4,F5,F6 and F10 tobe user defined function key terminators. F9 willbe disabled as a terminator, and the function keysthat are not in the list will be assigned as systemdefined function key terminators. |
RUN_TRACE |
1 (on),0 (off) |
If application has been compiled with -run:trace[para|call|io|sql], then all trace information can be suppressed by setting to 0. |
RUN_TRACECALL |
1 (on), 0 (off) |
If application has been compiled with -run:trace or -run:tracecall, then all CALL trace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
RUN_TRACEGOTO |
1 (on) 0 (off) |
If application has been compiled with -run:trace or -run:tracegoto, then all GOTOtrace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
RUN_TRACEIO |
1 (on), 0 (off) |
If application has been compiled with -run:trace or -run:traceio, then all FILE I/O trace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
RUN_TRACEPARA |
1 (on), 0 (off) |
If application has been compiled with -run:trace or -run:tracepara, then all SECTION & PARAGRAPH trace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
RUN_TRACEPERF |
1 (on), 0 (off) |
If application has been compiled with -run:trace or -run:traceperf, then all PERFORM trace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
RUN_TRACESQL |
1 (on), 0 (off) |
If application has been compiled with -run:trace or -run:tracesql, then all SQL I/O trace information can be suppressed by setting to 0. If RUN_TRACE=0, then this setting is ignored. |
S1,S2,S3,S4, S5,S6,S7,S8, S9,S10,S11, S12,S13,S14, S15,S16,S17, S18,S19,S20, S21,S22,S23, S24,S25,S26 |
True, False |
COBOL Switch values |
SECURE-CHAR |
* |
This character is used in password fields as a substitute for sensitive information. |
SHOWNUMERICERROR |
True, False |
Certain numeric errors may be detected at runtime that have an automatically corrected default behavior, bringing the numeric to zero. This condition may be made visible in certain cases by setting this flag. |
sql.encoding |
ISO-8859-1, Cp1047 |
Encoding of SQL host variables to be converted to UTF-8 before being passed to JDBC drivers. Set as a default to be the same as BE (overall byte encoding). For -dt:ibm this is Cp1047 (EBCDIC) for other datatypes this is ISO-8859-1 (ASCII). |
TERMINATE |
ENTER, ESCAPE, CONTROL-x |
Controls normal terminator assignments. For example: ESCAPE, ENTER, CONTROL-G will allow the escape, enter, and control-G keys to terminate an ACCEPT. |
TRUNC |
NOTRUNC, BINARY |
Truncation of binary numbers based on their storage size instead of their PIC definition. With -dt:mf, TRUNC=BINARY is the default with -dt:ec TRUNC=NOTRUNC is the default. -dt:truncbin will also set TRUNC=BINARY. Note in the (default) -dt:ec mode -dt:compbin should be set with -dt:truncbin to achieve the desired effect on COMP variables. |
USECURSES |
true|false |
When both a GUI terminal is available, use character mode for screen by default (default false, use GUI if available, otherwise use character mode) |
USEGFX |
true|false |
Attempt to use a GUI terminal (windowing controls) to display screens defined in the COBOL language extensions, fall back to character mode if not (default true) |
USER-GRAY |
default |
Used to override color number 7, low intensity white. This value should be a decimal, octal, or hexadecimal 24-bit integer (RGB). |
USER-WHITE |
default |
Used to override color number 15, high intensity white. This value should be a decimal, octal, or hexadecimal 24-bit integer (RGB). |
RUN_SHOW-SQL-EXCEPTION |
true, false |
Cobol Runtime Option argument RUN_SHOW-SQL-EXCEPTION=true would enable logging of extra SQL related information in case SQLException is thrown in the code - Program Id, SQLCODE, SQLSTATE and SQLERRM. This information won't be available in the console log if:
EBP property value showsqlexceptionincobol with value true add this argument as Cobol Runtime Option. |
SMART_HEAP_IMPL |
Qualified classname |
Cobol Runtime Option argument SMART_HEAP_IMPL is used to specify the implementation of the com.heirloomcomputing.ecs.exec.smartheap.SmartHeap that we want to use. Currently there are two implementations available: com.heirloomcomputing.ecs.exec.smartheap.SmartHeapVector The first one always increases the vector size when new element is allocated, where the VectorOptimized will first search for available free cells within the Vector and only if everything is occupied then will increase the vector size +1. If not specified, the default value is: com.heirloomcomputing.ecs.exec.smartheap.SmartHeapVectorOptimized |
Elastic COBOL File Protocols
You can prefix file names in the value of the ASSIGN TO clause to indicate the internal file format. The global "-DFILESYSTEM=xxx" runtime setting overrides the protocol of individual files. The protocol is specified as "protocol:file" as in "mf:/data/mf-idx3.dat". Different protocols may be available for different file system types. IBMVB (in which Block Descriptor Words and Record Descriptor Words accompany the data) is available for ORGANIZATION SEQUENTIAL but not LINE SEQUENTIAL, which always use native operating system line-ending characters.
Protocol |
Runtime Option |
Description |
none |
ECOBOL |
Use Elastic COBOL Fixed record (data only), Variable record (4-byte little-endian length followed by data of that length) and Indexed Sequential file formats. |
mf: |
MICROFOCUS |
Use Micro Focus formatted files all types (sepcialized headers begin each file). |
mf3: |
MICROFOCUS |
Use Micro Focus IDX 3 file format |
mf8: |
MICROFOCUS |
Use Micro Focus IDX 8 file format |
acu: |
ACUCOBOL |
Use AcuCOBOL Fixed record (data only), Variable record (2-byte big-endian length followed by data of that length) and ISAM file formats |
ibmv: |
IBMV |
Use IBM RECFM=V format for SEQUENTIAL variable length record datasets, 2-byte big-endian length plus 2-bytes of zeros precede the data. Length includes the 4-bytes for this Record Descriptor Word. |
ibmvb: |
IBMVB |
Use IBM RECFM=VB format for SEQUENTIAL variable length record datasets, 4-byte big-endian block size followed by records in IBMV format. The Block Descriptor Word length includes the size of the BDW itself. |
ZOS |
Use zos: or vsam: when running Elastic COBOL applications on z/OS under the JZOS environment. Use the z/OS dataset name after the qualifier to allow IBM's zFile class to open VSAM files, Physical Sequential, or member PDSs directly. Either datasets (with embedded '.' separators) or DDnames (no '.') may be specified as in "zos:SYS1.AAA.DAT" or "zos:MYDD". |
|
sync: |
SYNCSORT |
Use SyncSort Variable length data format (2-byte big-endian length followed by data of that length). |
VSAM-SQL Transparency Mode (columnar). Perform CICS and Cobol files as JDBC SQL calls against tables made up of columns corresponding to the elements within an FD structure. |
||
VSAM-SQL Transparency Mode (record). Perform CICS and Cobol files as JDBC SQL calls against tables made up of a BLOB column corresponding to the entire record and other columns for each alternate index. |
For VDB, dataset names are mapped to JDBC data source names, catalogs (if supported by the database), schema and table names. Dataset DSN1.CAT1.USR1.TAB1.DAT will be created in the datasource name DSN1 (given by -Dsql.dsn1.url=jdbc...),
schema USR1 and table TAB1 in PostgreSQL and MySQL where the schema USR1 exists.
Elastic COBOL SQL Properties
SQL settings allow you to change the default interaction with databases on a per connection basis as well as supply connection information for COBOL programs and EBP job steps (whether run under IKJEFTxx or PGM=xx). Similar properties influence ETP operation, see the SQL tab on the ETP Deployment Properties. Set properties with -Dprop=value on the command line or PARM field of JCL or within the IKJEFT.properties file when starting programs with IKJEFTxx.
If the order the files are read from the database need to be changed to EBCDIC, please check here
Property |
Values |
Default |
Description |
sql.connection.url |
jdbc://... |
none |
Use the JDBC connection URL when connecting to a database connection. |
sql.connection.user |
any |
none |
Use the JDBC connection user when connecting to a database connection. |
sql.connection.password |
any |
none |
Use the JDBC connection password when connecting to a database connection. |
sql.connection.driver |
any |
discovered automatically in JDBC4 |
Use the JDBC connection driver name when connecting to a database connection. |
sql.connection.autocommit |
0 | 1 | yes | no | on | off | true | false |
false |
Set the JDBC connection to setAutoCommit(true) when true, yes, 1, on. |
sql.connection.isolation |
read | uncommitted | committed | repeat | serial |
read |
Set the JDBC connection setIsiolationLevel(x) transaction isolation level property to read only committed data, read for committed data, read for uncommitted (dirty read) data, repeatable read data, or serialized read |
sql.connection.implicit |
0 | 1 | yes | no | on | off | true | false |
true |
Commit implicit transactions (autocommit is false) upon successful program exit, rollback upon ABEND |
sql.file.useBatchInsert |
true | false |
false |
Flag for using bulk insert when inserting data to DB. |
sql.file.useBatchInsert.batchSize |
number > 0 |
0 |
Works in combination with sql.file.useBatchInsert and specifies the batch size that is going to be inserted at once. |
Elastic COBOL C/C++ Library Calling Conventions
Elastic COBOL can invoke C functions or C++ methods through the Java Native Interface (JNI) capability. You must notify Elastic COBOL that some functions mentioned in COBOL CALL statements may be found in a library by "loading" that library first. Load a library by making an explicity call to it (e.g., CALL "libmyso.os".) or by specifying them with the DLL-LINK runtime parameter (e.g., -DDLL-LINK=libmyso.so,my.dll).
You also specify the calling convention, or let Elastic COBOL set the convention. On most UNIX and Linux systems, this is CDECL and on Windows it is STDCALL. You can define SPECIAL NAMES in the ENVIRONMENT DIVISION of your program and reference them in call statements (e.g., CALL CDECL "mysofunc". or CALL STDCALL "mydllfunc".) Alternatively, you can specify the default calling convention to use (if not overridden on the CALL statement) with a runtime parameter (e.g., -DDLL-CONVENTION=1).
environment division.
special-names.
call-convention 0 is DEFAULTCALL
call-convention 1 is BACKWARDS
call-convention 2 is CDECL
call-convention 64 is STDCALL
call-convention 128 is UNSAFE.
When Elastic COBOL passes parameters to C/C++ they are converted from whatever datatype (COMP, PIC X, COMP-1, COMP-5) to the appropriate datatype expected by most C programs: int, long, double, float or char *. In addition char * strings are terminated with \0 (but may contain trailing spaces as inserted by most MOVE statements). The actual pointers passed as part of char * strings are transient, or wrappered character strings since normal Java does not allow direct access to memory allocated to objects. In this way incorrect modification of pointer values will not necessarily override important JVM data elements. But it also means that pointers to parameters will change each time a C call is made, even if they indicate the same COBOL element (Java variable).
There is a way to persist pointers from one call to the next. For example, if you need to pass a pointer to an element or group structure in one call and use it during a subsequent call when it is not passed as a parameter you may consider the UNSAFE calling convention. UNSAFE uses the Java Unsafe API, an internal API normally reserved for the JVM itself and certain performance enhancement or utility tools. It breaks the Java model of using opaque objects to represent data items. When UNSAFE calling convention is used BY REFERENCE parameters are passed as their actual pointers to their location in the Elastic COBOL linear memory. As such, they can only be used with -cache:disable (the default) to ensure that the linear memory is in sync with the Java intermediate values that hold their cached values. Furthermore, normal Java garbage collection algorithms may move around objects in memory at any time. This would result in an invalid "remembered" pointer by a called C routine. To resolve this issue, use -cache:external which allocates COBOL variables off of the Java heap making them immune to GC reorganizations.
As the name implies, UNSAFE is inherently unsafe for a variety of reasons. For one, pointers passed in one call may not be valid after the Java garbage collector (GC) moves Java objects within the Java heap. But, it can lead to performance improvement because C code can directly access the memory used by the JVM to store the COBOL variable values. Use -DDLL-CONVENTION=2 to force UNSAFE operations on all C/C++ calls.
Calling Convention | Special Name | DLL Convention |
DEFAULTCALL | 0 | - |
BACKWARDS | 1 | - |
CDECL | 2 | 0 |
STDCALL | 64 | 1 |
UNSAFE | 128 | 2 |
The BACKWARDS special name will pass parameters in reverse to the called function, as some application programming libraries (e.g., Pascal) interpret them this way. You can combine calling convention attributes, such as STDCALL and BACKWARDS, by defining your own special name and value, 65.
See Elastic COBOL Language Reference Manual for more information on calling conventions.
To assist in troubleshooting COBOL Native function operations, set the environment variable DEBUGCOBOLNATIVE to "1" and the stdout stream in C/C++ will contain additional parameter passing and symbol lookup information.
0 Comments