Follow

Compiler Directives / Options

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
CONSOLE (graphical user interface window or ASCII terminal).

-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:

  • SQL_EBCDIC037_CP1_CS_AS
  • SQL_EBCDIC277_CP1_CS_AS

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, 23, 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.
object-computer.
heirloom-pc
program collating sequence is mainframe.
special-names.
alphabet mainframe is ebcdic.

 

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) |
1 (STDCALL) |
2 (UNSAFE)

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
number:class [;number:class]...

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
use JDBC batches of 100 for delete and/or rewrite/update operations.

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
use JDBC batches of 100 for delete and/or rewrite/update operations.

batchUpdateThreshold

 

Numeric value

Set batch mode threshold for
update VDB operations (delete & rewrite/update)

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
use JDBC batches of 100 for delete and/or rewrite/update operations.

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:

  • SQLCODE is null
  • RUN_SHOW-SQL-EXCEPTION option is missing or set to false
  • SQLCODE has positive value

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
com.heirloomcomputing.ecs.exec.smartheap.SmartHeapVectorOptimized

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:
vsam:

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).

vsql:

 

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.

vdb:

 

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.

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

0 Comments

Please sign in to leave a comment.
Powered by Zendesk