Heirloom COBOL Runtime Options

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.

DB2.FUNCTIONS.SCHEMA

Schema name

Provides a specific schema name when referencing installed db2 functions in a postgres database. If the functions are installed in pg_catalog or the current schema this option is not required.

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

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

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.

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.

JVM-ERROR-EXIT

TRUE, FALSE

When a COBOL program exits or when an unhandled exception is thrown, by default a java System.exit() is performed. This causes issues with transaction environments and also when COBOL programs are called from java applications, for example a spring boot server calling a COBOL program. Prior to JDK17 the solution to this was to override the SecurityManager and intercept and ignore the exit(). This JVM feature is now deprecated and so the solution is to ensure that on errors system.exit() is not called by setting this flag to FALSE.

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.

MDTHELP

TRUE, FALSE

Controls BMS modified data tag handling. TRUE is the default as of 2023-09-19 and attempts to closely emulate mainframe behavior as precisely as possible. FALSE enables the original implementation for existing applications relying on previous behaviors.

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.

RELEASE_DUPLICATE_SAVEPOINTS 

(DEFAULT) YES | 1 | ON | TRUE
NO | 0 | OFF | FALSE

When creating savepoints with the same name, postgresql does not release the previous savepoints of the same name. To enforce the release set RELEASE_DUPLICATE_SAVEPOINTS  to YES | 1 | ON | TRUE.

This is the default behavior.

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

SQLCODESTATEMAP

path to file

The contents of the specified mapping file should have the following format:

SQLSTATE=SQLCODE

For e.g:
42703=-666
56803=-216
44634=-104

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

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.

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

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.