P3/COBOL Runtime Options

The P3/COBOL command-line command to run COBOL programs is a sub-command of the p3 command. See p3-utility for a description of the p3 command and its sub-commands, including the run command.

P3/COBOL Run Command

Syntax

$\small\mathsf{p3} \space \begin{Bmatrix} \small\mathsf{r}\\ \small\mathsf{run} \end{Bmatrix} \begin{bmatrix} \mathit{p3RuntimeOptions} \end{bmatrix} \begin{Bmatrix} \text{-} \mathsf{i} \space \texttt{"} \mathit{initialProgramName} \texttt{"}\\ \text{-} \mathsf{initial} \text{-} \mathsf{program} \space \texttt{"} \mathit{initialProgramName} \texttt{"} \end{Bmatrix} \begin{bmatrix} \text{-} \mathsf{a} \space \mathit{programArguments}\\ \text{-} \mathsf{arguments} \space \mathit{programArguments} \end{bmatrix}$

The initial_program is the name of the COBOL program to initially execute. The program_arguments is a string of one or more arguments to the initial program. They are passed as a single string actual parameter if the program accepts at least one alphanumeric USING argument.

Runtime Option Lifecycle

A RuntimeOptions instance may be customized through its public setters while it is being constructed. Complete these changes before supplying the instance to a RunUnit, Launcher, DataUtil, or another runtime component.

During initialization, P3/COBOL resolves the configuration for that component. Association and volume configuration collections are defensively copied and exposed as read-only data. Changing the original collections or their elements after initialization does not reconfigure an existing runtime component. To use different settings, construct new runtime options and initialize a new component from them.

Immutability applies to the option values, not to the runtime behavior they describe. Options that select behavior as a function of file, program, or database names are still evaluated dynamically at the time the corresponding resource is used. See Selecting Volume Configuration by File Name for an example.

Runtime Options

allocate-all-direct

<allocate-all-direct>false</allocate-all-direct>

Directs the runtime to allocate all storage in the operating system’s global heap memory accessible to non-Java programs (i.e., outside the JVM’s heap memory) if and only if this option is true. This option must be set to true if the COBOL program(s) pass pointers to native programs.

The possible values for boolean are:

allocate-omitted-return-arg

<allocate-omitted-return-arg>false</allocate-omitted-return-arg>

Directs the runtime to automatically allocate (“base”) omitted RETURNING/GIVING arguments in a CALL'ed program if and only if this option is true. If set, this allows the return argument to be passed as the value of the execute() method of the generated CALL'ed program as a convenience to non-COBOL calling programs.

The possible values for boolean are:

allow-packed-decimal-spaces

<allow-packed-decimal-spaces>false</allow-packed-decimal-spaces>

Directs the runtime to allow all SPACE bytes in a packed-decimal item, and to consider it to have the algebraic value of 0 if and only if this option is true. This option is often required to be set true when using COBOL programs originally written for the IBM System/360 and compatible systems.

The possible values for boolean are:

argument-rm

<argument-rm>
    <arg>someRmArgs</arg>
</argument-rm>

This option may supply arguments to the program being invokes in a manner compatible with RM/COBOL. Each argument will be passed to the program as if it were CALL ... USING a group-level argument BY CONTENT containing a 2-byte binary length followed by an alphanumeric item corresponding to the <arg> element of <arguments-rm>.

The possible values for argument-rm are <arg> XML element(s) containing text that comprises the corresponding alphanumeric item encoded in the native charset and passed BY CONTENT.

arguments

<arguments>
    <arg>someArgs</arg>
</arguments>

This option may supply arguments to the program being invokes. Each argument will be passed to the program as if it were CALL ... USING an alphanumeric argument corresponding to the <arg> element of <arguments>.

The possible values for arguments are <arg> XML element(s) containing text that comprises the corresponding alphanumeric argument passed BY VALUE.

beep

<beep>false</beep>

Directs the runtime to sound a beep tone whenever a terminal-mode ACCEPT is being processed.

The possible values for boolean are:

byte-order

<byte-order>false</byte-order>

This option determines the order of bytes within binary and national usage data. If the compiled Java code contains generated code that makes assumptions regarding runtime byte order then that same order must be used at runtime. If the runtime byte order does not match in those circumstances a fatal runtime error will result.

The possible values for byteOrderEnumeration are:

config-file

<config-file>runtime.p3c</config-file>

This option specifies the path to be used for an XML runtime configuration file as configFilePath.

database-associations

<database-associations>
    <database-association name="my_db">
        <driver>org.h2.Driver</driver>
        <host>jdbc:h2:./p3database;</host>
        <user-name>sa</user-name>
        <password />
    </database-association>
</database-associations>

This option provides runtime dynamic mapping of database names to specific database characteristics.

The possible content for the <database-associations> element is detailed in Configuring Database Associations. This option may only be used within the runtime configurations file as the command line version cannot be meaningfully specified. There is no default value for this option.

debug-handshake-timeout

<debug-handshake-timeout>10000</debug-handshake-timeout>

This option defines the maximum time in integer milliseconds between communications with a debugging client The debugging environment being used normally sets this automatically.

The default value for milliseconds is 10000 (10 seconds).

debug-port

<debug-port>9997</debug-port>

This option defines the port number to be used to communicate with a debugging client. The debugging environment being used normally sets this automatically. For more information see P3/COBOL Debugger. By setting this port you are implicitly enabling the debugger for this runtime. You will see some performance reduction in this case, even when a debugger is neither active nor attached. For this reason, specifying this option should not typically be used for production operation.

debugPortNumber may be any valid UDP port number that is not in use. This option is not defined by default, but is automatically set when the program is launched by the IDE for debugging.

debug-ports

<debug-ports>9997 9998</debug-ports>

Specifies a port pair used for debugger interaction with this run unit. The debugging environment being used normally sets this automatically. See also <debug-port>.

debugPortNumberList is a space-separated list of UDP port numbers. There is no default value.

debug-suspend

<debug-suspend>false</debug-suspend>

Directs the runtime to wait until a debugger attaches to the run unit before beginning execution.

The possible values for boolean are:

debug-zombie

<debug-zombie>true</debug-zombie>

Directs the runtime to continue to run even if the debugger is detached from the run unit.

The possible values for boolean are:

default-byte

<default-byte>0</default-byte>

This option defines the value to be used for uninitialized storage.

byteValue is specified as an unsigned decimal integer between 0 and 255 inclusive. This option is 0 by default.

dump-call-stack

<dump-call-stack>true</dump-call-stack>

Directs the runtime to dump the program call stack when an abnormal termination occurs if and only if this option is true.

The possible values for boolean are:

dump-data-stack

<dump-data-stack>false</dump-data-stack>

Directs the runtime to include program storage in the call-stack traceback dump if and only if this option is true.

The possible values for boolean are:

dump-histogram

<dump-histogram>false</dump-histogram>

Directs the runtime to dump any pending histogram results at termination if and only if this option is true. The histogram dump is written to two files based on the <histogram-path-name> option. The path-name.csv file contains a comma-separated file of every histogram bucket, and the path-name.out file contains a report of the histogram.

The possible values for boolean are:

dump-java-stack

<dump-java-stack>true</dump-java-stack>

Directs the runtime to dump the Java execution stack when an abnormal termination occurs if and only if this option is true.

The possible values for boolean are:

dump-storage

<dump-storage>false</dump-storage>

Directs the runtime to dump the contents of storage associated with active programs when an abnormal termination occurs if and only if this option is true. The dump is in the form of an XML document with an element for each data item defined by the programs. The dump is written to the standard error stream unless the dump-storage-file option specifies the path name of an alternative location. If the dump-storage-stylesheet option is specified, the dump document with be processed by the specified stylesheet and the result will be written to the dump destination.

The possible values for boolean are:

dump-storage-file

<dump-storage-file>/path/to/dump-file</dump-storage-file>

This option’s value determines the file/directory path used as the destination of an abnormal termination dump. If this option is specified all directories in the path must exist. If the file specified does not exist, it will be created if possible. If it does exist, it will be overwritten in the event of an abnormal termination of the run unit.

The possible value for storageDumpPath is any legal file pathname.

dump-storage-stylesheet

<dump-storage-stylesheet>/path/to/dump-stylesheet-file.xslt</dump-storage-stylesheet>

This option’s value determines the file/directory path used as the location of an XML xslt stylesheet that will be applied to the dump output document prior to writing the result to the destination. If this option is specified all directories in the path must exist, as well ast the stylesheet file itself.

The possible value for storageStylesheetPath is any legal file pathname.

esql-holdable-cursors

<esql-holdable-cursors>true</esql-holdable-cursors>

Directs the embedded SQL runtime to use the JDBC cursor hold setting for cursors declared HOLD.

The possible values for boolean are:

esql-program-qualified-cursors

<esql-program-qualified-cursors>true</esql-program-qualified-cursors>

Directs the embedded SQL runtime to qualify cursor names with the program that declares/opens the cursor.

The possible values for boolean are:

esql-trim-fixed-chars

<esql-trim-fixed-chars>false</esql-trim-fixed-chars>

Directs the embedded SQL runtime to trim trailing spaces from bound fixed-size CHAR columns if and only if this option is true.

The possible values for boolean are:

event-type-filter

<event-type-filter>ERROR DIAGNOSTIC</event-type-filter>

Selects which runtime event categories are reported. The value is a space-separated list of eventType names.

The possible values for eventType are:

The default is ERROR DIAGNOSTIC.

external-call-strategy

<external-call-strategy>
    <load-process>true</load-process>
    <library>
        <file>/path/to/native-library.dylib</file>
        <call-convention>NATIVE</call-convention>
    </library>
</external-call-strategy>

This option specifies the path to non-COBOL program libraries that will be called from the COBOL application. For more details see the External CALL Strategy Configuration.

external-library-directories

<external-library-directories>/path/to/native/libraries</external-library-directories>

This option specifies the directories to search for non-COBOL program libraries that will be called from the COBOL application. Any number of space-separated directory paths may be specified. Each will be examined and any native library files present will be added to the runtime repository for subsequent access via CALL from the COBOL program.

The default value of directoryPathList is the Current Working Directory.

The possible values for directoryPathList are a space-separated list of any valid directory paths.

file-associations

<file-associations>
    <file-association>
        <name-pattern>.*</name-pattern>
        <external-name>data/{0}</external-name>
    </file-association>
</file-associations>

This option provides runtime dynamic mapping of file names to arbitrary external file characteristics.

The possible content for the <file-associations> element is detailed in Configuring File Associations. This option may only be used within the runtime configurations file as the command line version cannot be meaningfully specified. There is no default value for this option.

file-flexible-line-termination

<file-flexible-line-termination>false</file-flexible-line-termination>

Directs the runtime to use any combination and/or contiguous sequence of delimiter characters to terminate a record when reading line sequential files. Additionally, if a record is not terminated by a delimiter before or at the maximum record length for the file, it is considered terminated after the last character in the record and any following characters, if any, are considered to be the first characters of the following line sequential record.

The possible values for boolean are:

file-io-forced-to-storage

<file-io-forced-to-storage>false</file-io-forced-to-storage>

This option directs to default file io subsystem to force all data to persistent storage at the time the corresponding COBOL IO operations are performed.

The possible values for boolean are:

file-line-delimiter

<file-line-delimiter>SYSTEM</file-line-delimiter>

Specifies the type of line terminator for line sequential files.

The possible values for delimiterEnumeration are:

filesystem-config-file

<filesystem-config-file>filesystem.p3c</filesystem-config-file>

This option is deprecated. Prefer configuring indexed-file volumes through file associations and the indexed file system options. This element may only be specified in the runtime configuration file; there is no command-line equivalent.

histogram

<histogram>false</histogram>

Directs the runtime to collect histogram events for the COBOL program(s) if and only if this option is true. See also the options below:

• dump-histogram
• histogram-path-name
• histogram-bucket-size
• histogram-group-by

The possible values for boolean are:

histogram-bucket-size

<histogram-bucket-size>PROCEDURE</histogram-bucket-size>

Specifies the collection bucket size.

The possible values for bucketSizeEnumeration in smallest to largest order are:

histogram-group-by

<histogram-group-by>PROGRAM</histogram-group-by>

Specifies the grouping of the histogram report file. Event results are aggregated by the grouping entity and sorted by that result.

The possible values for groupByEnumeration are:

histogram-path-name

<histogram-path-name>/path/to/histogram-files</histogram-path-name>

Specifies the base path name for the histogram files produced. Any missing directories will be created based on this path, and the proper extensions (".out", and ".csv") will be added.

initial-program

--initial-program

Directs the runtime to load and execute the specified COBOL program or classname.

The possible values of programName are any valid COBOL program name or the Java class name corresponding to a compiled COBOL program.

java-arguments

<java-arguments>-Dprop=value</java-arguments>

Provides an argument string for the Java command used when the runtime launches nested Java processes. There is no default value.

jdbc-connection-override

<jdbc-connection-override>com.turrettech.p3cobol.lib.sql.jdbc.JdbcConnection</jdbc-connection-override>

If present, this element provides a javaClassName which overrides the standard JdbcConnection class. This permits a user-written Java class to provide the JDBC connection rather than the standard connection using the options in this section.

The default value of javaClassName is com.turrettech.p3cobol.lib.sql.jdbc.JdbcConnection. Valid values are anything that implements the DatabaseConnection interface.

Check out the sample to see how it works.

jdbc-driver

<jdbc-driver>value</jdbc-driver>

This option is deprecated. Prefer database associations or <jdbc-connection-override>. When set, it supplies the JDBC driver class name. If unset, the first database association may supply an equivalent value when present.

jdbc-host

<jdbc-host>value</jdbc-host>

This option is deprecated. Prefer database associations or <jdbc-connection-override>. When set, it supplies the JDBC connection URL. If unset, the first database association may supply an equivalent value when present.

jdbc-password

<jdbc-password>value</jdbc-password>

This option is deprecated. Prefer database associations or <jdbc-connection-override>. When set, it supplies the JDBC password. If unset, the first database association may supply an equivalent value when present.

jdbc-username

<jdbc-username>value</jdbc-username>

This option is deprecated. Prefer database associations or <jdbc-connection-override>. When set, it supplies the JDBC username. If unset, the first database association may supply an equivalent value when present.

line-mode-accept

<line-mode-accept>true</line-mode-accept>

Directs the runtime to terminate format 1 (ANSI) console ACCEPT when line terminators are encountered if and only if this option is true.

The possible boolean values are:

listeners

<listeners>
    <listener name="run-unit" value="org.tempuri.SampleListener"/>
</listeners>

This option allows the specification of named runtime listener classes. It encloses <listener> elements each of which designates a listener name and value attribute.

The name must be one of the following:

maximum-decimal-precision

<maximum-decimal-precision>34</maximum-decimal-precision>

This option determines the maximum decimal precision retained during intermediate arithmetic calculations. This intermediate precision can have a profound effect on performance of computing-intensive applications, so if it is known that a specific maximum precision is adequate in these circumstances, this option may be used to take advantage of it. In particular, any setting at or below 18 digits will perform much better than settings above this value, due to the fact that fixed-point decimal numbers can be held and manipulated in long integer primitive types.

The valid values for precision are any integer in the range of 1 .. 64.

The default value for precision is 34.

native-access-enabled

<native-access-enabled>false</native-access-enabled>

Directs the runtime to use restricted methods in order to allow access to native, non-Java resources. For this option to be effective, the Java command line option --enable-native-access=ALL-UNNAMED must also be specified.

The possible boolean values are:

native-charset

<native-charset>NATIVE</native-charset>

The possible values for charsetEnumeration are:

native-data-pointers

<native-data-pointers>false</native-data-pointers>

Directs the runtime to store all data pointers as global heap memory addresses if the allocate-all-direct option is also specified. When both options are specified, all memory is allocated on the global heap rather than the Java heap, and any pointer data items will, when set, will contain the heap memory address in the native system byte order.

The possible values for boolean are:

packed-decimal-validation

<packed-decimal-validation>STRICT</packed-decimal-validation>

Directs the degree to which the runtime should validate packed decimal digits in COMP3-usage items when used in arithmetic calculations and comparisons.

The possible values for validationEnumeration are:

parameters

<parameters>
    <parameter name="param1" value="with it's value"/>
    <parameter name="param2" value="with another value"/>
</parameters>

This option provides a set of runtime option parameters that may be selected within a substitution string in the runtime configuration file in the same manner as an environment variable.

The possible content for the <parameters> element is detailed in Configuring Parameters. This option may only be used within the runtime configuration file as the command line version cannot be meaningfully specified. There is no default value for this option.

program-associations

<program-association>
    <name-pattern>([^.])*[.]COB$</name-pattern>
    <class-name>{1}</class-name>
</program-association>

This option provides runtime dynamic mapping of program names to arbitrary Java class names.

The possible content for the <program-associations> element is detailed in Configuring Program Associations. This option may only be used within the runtime configuration file as the command line version cannot be meaningfully specified. There is no default value for this option.

program-package

<program-package>programs</program-package>

This option determines the packageName that will be used by the runtime program loader when loading a generated COBOL program class file. Typically this option should have the same value as the corresponding compiler configuration value.

The valid values for packageName are any valid java package name. The default value for packageName is programs.

sort-engine

<sort-engine>AUTOMATIC</sort-engine>

Determines the engine type used to process SORT and MERGE statements.

The possible values for sortEngineTypeEnumeration are:

sort-engine-threads

<sort-engine-threads>1</sort-engine-threads>

Determines the maximum number of threads that the sort engine is allowed to use, regardless of any other settings.

The possible values of numberOfThreads is any non-zero positive integer. The default value for this option is 1.

sort-max-memory-records

<sort-max-memory-records>100000</sort-max-memory-records>

Determines the maximum number of records that the sort engine is allowed to keep in memory during a sort operation.

The possible values of numberOfRecords is any non-zero positive integer. The default value for this option is 100000.

sort-using-sharing-mode

<sort-using-sharing-mode>false</sort-using-sharing-mode>

Determines the sharing mode used for opening sort USING files. See Sharing Modes.

sqlca-compatibility

<sqlca-compatibility>ISO</sqlca-compatibility>

Determines the type of SQLCA used by the built-in ESQL.

The possible values for sqlcaCompatibilityEnumeration are:

strict-function-numval

<strict-function-numval>true</strict-function-numval>

Directs the runtime to strictly limit the valid characters accepted by NUMVAL and related numeric intrinsic functions if and only if this option is true.

The possible values for boolean are:

strict-numeric-class-test

<strict-numeric-class-test>true</strict-numeric-class-test>

Directs the runtime to strictly implement the IS NUMERIC class test according to the COBOL standard specification if and only if this option is true. If set to true, all digits and operational signs in DISPLAY numeric items must be correctly formed in order for the test to evaluate true. If set to false, the signs and digits will be considered valid if they are valid considering the selected zoned-decimal-validation option setting.

The possible values for boolean are:

strict-pointer-bounds

<strict-pointer-bounds>false</strict-pointer-bounds>

Directs the runtime to strictly enforce the check that a pointer addresses storage within the limits determined by the LINKAGE SECTION item to which it is associated ("based") if and only if this option is true. If set to true, a LINKAGE SECTION item that is used to receive a smaller size item than the actual argument and is then subsequently used as an actual argument to another CALL'ed program will be truncated to the size of the intermediate program’s LINKAGE SECTION item.

The possible values for boolean are:

switch-settings

<switch-settings>
    <switch name="switch-0" setting="WIRED_OFF"/>
    <switch name="switch-1" setting="ON"/>
</switch-settings>

This option provides for setting logical switches to specific values at runtime.

The possible content for the <switch-settings> element is detailed in Configuring Switch Settings. This option may only be used within the compiler configurations file as the command line version cannot be meaningfully specified. There is no default value for this option.

switch-vector

<switch-vector>"1"</switch-vector>

This option provides for setting logical switches to specific values at runtime.

The possible content for switchVector is a string of 1 or more "0", "1", or "x" characters (up to 32) that indicate the state of switches 0, 1, 2, ... An x indicates the switch corresponding switch should not be changed, a 0 turns the corresponding switch off and 1 turns it on. The vector is merged with the switch settings above, if any. There is no default value for this option.

terminal

<terminal>DEFAULT</terminal>

Directs the runtime to use a specific type of terminal emulator for terminal-mode ACCEPT and DISPLAY operations.

The possible values for terminalTypeEnumeration are:

terminal-configuration

<terminal-configuration>
    <font-name>Monospaced</font-name>
    <font-size>14</font-size>
    <bold>false</bold>
    <columns>80</columns>
    <rows>25</rows>
    <charset-name>UTF-8</charset-name>
    <title>P3/COBOL Application Terminal</title>
    <icon-image-file>/path/to/icon.png</icon-image-file>
    <auto-close-trigger>DoNotAutoClose</auto-close-trigger>
    <tab-behavior>CONVERT_TO_ONE_SPACE</tab-behavior>
</terminal-configuration>

Configures the Swing/ANSI terminal used when <terminal> selects an interactive emulator. This option may only be specified in the runtime configuration file; there is no command-line equivalent.

trailing-space-suppression

<trailing-space-suppression>false</trailing-space-suppression>

Directs the runtime to always suppress (delete) any trailing spaces in line sequential output records, and to extend input records to the maximum record size with space fill, if a shorter record is read. Records consisting of only space characters (including records generated by the ADVANCING phrase) will be entirely suppressed, i.e. of 0 length. The behavior when this option is set is consistent with the standard Micro Focus COBOL behavior for line sequential files output.

The possible values for boolean are:

truncate-binary

<truncate-binary>true</truncate-binary>

Directs the runtime to limit the value stored in binary items to that reflected by the item’s PICTURE if and only if this option is true. This is standard COBOL behavior, but programs originating in other COBOL environments may need this option set to false to achieve correct behavior.

The possible values for boolean are:

version

--version

Directs the runtime to write the runtime version information to the standard output.

xml-export-attributes

<xml-export-attributes>false</xml-export-attributes>

Directs the runtime to generate metadata attributes when forming XML elements for the EXPORT statement.

The possible values for boolean are:

xml-export-initial-values

<xml-export-initial-values>false</xml-export-initial-values>

Directs the runtime to export a data item even when it's value matches its initial value.

The possible values for boolean are:

xml-export-subscripts

<xml-export-subscripts>false</xml-export-subscripts>

Directs the runtime to export subscript attributes on data items that have multiple occurances.

The possible values for boolean are:

xml-ignore-unbindables

<xml-ignore-unbindables>true</xml-ignore-unbindables>

Directs the runtime to ignore imported XML elements that cannot be bound to any data item within the IMPORTed structure.

The possible values for boolean are:

xml-ignore-whitespace-content

<xml-ignore-whitespace>false</xml-ignore-whitespace>

The configuration element name is <xml-ignore-whitespace>. The command-line long name is --xml-ignore-whitespace-content.

Directs the runtime to ignore whitespace content in imported XML elements.

The possible values for boolean are:

xml-permissive-root-naming

<xml-permissive-root-naming>true</xml-permissive-root-naming>

Directs the runtime to bind the root element in an IMPORT operation to the top-level IMPORT target regardless of the name of the element.

The possible values for boolean are:

zoned-decimal-validation

<zoned-decimal-validation>STRICT</zoned-decimal-validation>

Directs the degree to which the runtime should validate zoned decimal digits in DISPLAY-usage items when used in arithmetic calculations and comparisons.

The possible values for validationEnumeration are:

Z

-Z

Used to indicate the end of parsed option on the command line invocation of the runtime.