Running

Descriptions of Run-time Switches

Chapter 13: Run-time Configuration

You can configure certain run-time behavior through the run-time configurables. There are three types of run-time configurable: environment variables, run-time tunables, and run-time switches.

This chapter lists and describes the run-time tunables you can use. See the appendix Micro Focus Environment Variables for a list of environment variables used by Server Express. See the chapter Descriptions of Run-time Switches for a list of run-time switches.

13.1 Introduction

When your run-time system or linked executable starts up, it attempts to read the run-time configuration file. The run-time configuration file specifies values for the run-time configurables. It is shared by all users of Server Express.

13.2 Run-time Configuration File

The run-time configuration file is a text file, which you can edit with your standard text editor. It is an optional file (no error will be issued if it does not exist) with the default name $COBDIR/etc/cobconfig . You can specify a filename for the configuration file by setting the environment variable COBCONFIG; for example:

COBCONFIG=$HOME/myconfig
export COBCONFIG

Each run-time configurable appears on a new line. Blank lines are ignored. A comment line starts with a #; however, as the configuration file is processed at run-time, we advise that you limit your comments, in order to keep to a minimum the time it takes to process it. The maximum number of characters permitted in a comment line is 80, including any new-line or carriage return characters that may be placed at the end of the line by some editors.

You can use the configuration file to:

• Set environment variables, such as dd_ filename mappings, or other environment variables significant to Server Express. Environment variables set in this way override values already set in the environment.
  
  
• Set run-time tunables. These control the behavior of certain aspects of the COBOL run-time system.

13.3 Format of a Run-time Configurable

Each run-time configurable is specified on one line in the run-time configuration file. The format for run-time tunables is:

set configurable_name=value

while for environment variables, the format is:

setenv configurable_name value

The parameters are:

Note that each space in the definition can be replaced with tabs or more than one space.

Example:

setenv dd_MYFILE /usr/mydir/myfile 
set cobconfig_error_report=TRUE

13.4 Run-time Tunables

The following sections describe the run-time tunables available.

arguments_are_initial

Syntax:

set arguments_are_initial={TRUE|FALSE} 

Value:

TRUE or FALSE 

This tunable affects the COBOL command line arguments returned from the syntax ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE. See the Language Reference for more details of this syntax.

If TRUE, the COBOL command line arguments are the same as the initial ones passed to the run-unit by the operating system. When using a trigger, such as cobrun, argument 0 is the trigger name and argument 1 is the name of the main COBOL program.

If FALSE, the COBOL command line arguments do not contain any trigger name. Instead, argument 0 is always the name of the main COBOL program.

If you are using a system executable to start your application, argument 0 is always the name of the executable (which, by default, is also the name of the main COBOL program), irrespective of the setting of this tunable.

When set to FALSE this tunable gives consistent results no matter how your application is packaged. For details on packaging applications, see the chapter Packaging Applications .

Set this tunable to TRUE for compatibility with Micro Focus Object COBOL Developer Suite V4.1 for UNIX and earlier.

Default:

FALSE

Example:

The command line:

myapp arg1 arg2

always returns myapp as argument 0.

The command line:

cobrun myapp arg1 arg2

returns myapp as argument 0 when this tunable is set to FALSE; when the tunable is set to TRUE the trigger name (cobrun) is returned as argument 0 and myapp as argument 1.

bll_cell_address_check

Syntax:

set bll_cell_address_check={TRUE|FALSE} 

Value:

TRUE or FALSE 

If TRUE, a test is run to determine if the top bit of the address of any BLL cell is set. If this bit is set, run-time system error 181 "Invalid parameter error" might be returned when testing the address of shared memory.

If FALSE, the test is suppressed. This is the recommended setting if BLL-cells are being allocated in shared memory.

Default:

TRUE

cobconfig_error_report

Syntax:

set cobconfig_error_report={TRUE|FALSE}

Value:

TRUE or FALSE

If FALSE, do not report any errors during processing of the configuration file.

Default:

TRUE. Any errors detected are reported and the run-time system terminates. Unknown or misspelled run-time tunables names are not reported.

command_line_accept

Syntax:

set command_line_accept={TRUE|FALSE}

Value:

TRUE or FALSE

If TRUE, the first ACCEPT or READ from STDIN takes the input from the command line.

Default:

FALSE. The first ACCEPT or READ from STDIN takes the input from the user. This provides direct ANSI conformance. You should set this if you want to execute a program that has been generated from convert3 or convert5.

command_line_linkage

Syntax:

set command_line_linkage={TRUE|FALSE}

Value:

TRUE or FALSE.

If TRUE, enables you to call a program and pass the command line to the main program as a parameter to be accessed via the Linkage Section. See the chapter Writing Programs in your Programmer's Guide to Writing Programs for information on passing the command line to a main program.

Default:

TRUE

core_on_error

Syntax:

set core_on_error=integer

Value:

integer

where integer specifies in what circumstances a core file is produced. You can look at core files with Animator. See your Debugging Handbook for details.

integer can be:

You can animate core files to determine the cause of the problem if you have the appropriate Animator information files.

Note: When a core file is produced, the run-time system itself cannot clean up COBOL file buffers or free system resources. This could lead to data file corruption that might not have occurred if no core file was produced.

Default:

0

See Also:

signal_regime
debug_on_error

current_day

Syntax:

set current_day=integer

Value:

Default:

The current day specified by the system clock.

current_month

Syntax:

set current_day=integer

Value:

Default:

The current month specified by the system clock.

current_year

Syntax:

set current_year=integer

Value:

Default:

The current year specified by the system clock.

debug_on_error

Syntax:

set debug_on_error={0|1}

Value:

0 or 1.

If you want to use just-in-time debugging, set this tunable to 1; this enables the Animator to start if a running program terminates with a run-time error.

Default:

0

Comments:

For more details of just-in-time debugging, see the Debugging Handbook.

debugger_command

Syntax:

set debugger_command="debugger"

Value:

debugger specifies the command to start the debugger. This can be one of the commands listed in the chapter Starting Animator in your Debugging Handbook.

You use this tunable in combination with the debug_on_error tunable.

Default:

cobanim

Comments:

For more details of just-in-time debugging, see the Debugging Handbook.

detect_alt_ctrl

Syntax:

set detect_alt_ctrl={TRUE|FALSE}

Value:

TRUE or FALSE.

Most UNIX environments do not detect input when the Ctrl, Alt, or Shift keys are available on a keyboard and are pressed by themselves. In these cases, detect_alt_ctrl must be set to FALSE. The operating system SCO Open Desktop from version 2 onwards does detect these keys individually and detect_alt_ctrl can be set to TRUE.

If detect_alt_ctrl is set to TRUE, then the run-time system detects the Ctrl, Alt, and Shift keys. These keys can then be used for COBOL utilities that would otherwise use the alternate key sequences of /c for Ctrl or /a for Alt. For example, the Development Environment is easier to use if detect_alt_ctrl can be set to TRUE.

Default:

FALSE

dynamic_dictionary_limit

Syntax:

set dynamic_dictionary_limit=integer

Value:

integer

where integer is the maximum size of memory to be allocated dynamically at run time for use by virtual heaps.

The Compiler uses virtual heaps when processing your programs, and this size is operating system dependent. If the memory limit is exceeded, the memory allocated to virtual heaps is paged by the Micro Focus COBOL system onto disk. If the amount of memory allocated to virtual heaps is not large enough to process your programs, then the compilation and generation times can be increased due to the overheads of paging the virtual heap accesses to disk.

This run-time tunable is equivalent to the -d run-time switch. The value of -d is used if the values are different.

Default:

30 buffers of 8K.

dynamic_memory_limit

Syntax:

set dynamic_memory_limit=integer

Value:

integer

where integer is the maximum size of memory to be allocated dynamically at run time, and is operating system dependent. Any CANCELs performed before this memory limit is reached do not release the memory occupied by the program being CANCELed. The program is available to be reused and hence CALL/CANCEL performance is greatly increased. This mode of working is called "logical Cancels".

As far as your program is concerned, the behavior of logical and real CANCELs is identical. If the dynamically allocated memory requirements exceed the size you set for dynamic_memory_limit, then all the memory that should have been freed by any CANCELs is freed. If you set this limit to zero, logical CANCELs are disabled.

This run-time tunable is equivalent to the -l run-time switch. The value of -l is used if the values are different.

Default:

Logical cancels are used.

faultfind_level

Syntax:

set faultfind_level=n

Value:

n can be any positive value. Specifying this tunable turns on FaultFinder; the last n events are dumped to a FaultFinder report if abnormal application termination occurs. The greater the value of n, the more memory is used.

See the chapter FaultFinder in your Debugging Handbook for information on FaultFinder.

Default:

0 (off)

See Also:

faultfind_outfile
faultfind_recsize

faultfind_outfile

Syntax:

set faultfind_outfile="[>>]filename"

Value:

filename is the file to which a FaultFinder report is written. If you specify >>, the output is appended to filename, if it already exists, otherwise a new file named filename is created.

See the chapter FaultFinder in your Debugging Handbook for information on FaultFinder.

Default:

fltfnd_out.pid, in the current working directory, where pid is the process ID of the the process that triggered the FaultFinder output.

See Also:

faultfind_level
faultfind_recsize

faultfind_recsize

Syntax:

set faultfind_recsize=record_size

Value:

record_size is a numeric value, in bytes, that specifies the amount of extra data that is to be kept for each trace operation.

The maximum value of record_size can be 1024 bytes.

See the chapter FaultFinder in your Debugging Handbook for information on FaultFinder.

Default:

64 bytes

See Also:

faultfind_level
faultfind_outfile

filename_quote_char

Syntax:

set filename_quote_char="character"

or:

set filename_quote_char='character'

Value:

character specifies the quotation character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE. Within a quoted filename, two adjacent quote characters are interpreted as a single quote when deriving the filename. It is necessary to quote filenames that have embedded spaces within them.

Default:

" (the double quote character)

filename_escape_char

Syntax:

set filename_escape_char="character"

or:

set filename_escape_char='character'

Value:

character specifies the escape character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE. The escape character is not treated as part of the filename but instead quotes the character immediately following the escape character (such as a space). It is necessary to quote filenames that have embedded spaces within them.

Default:

\0 (no character is used as an escape character)

intra_process_record_locking

Syntax:

set intra_process_record_locking={TRUE|FALSE}

Value:

TRUE or FALSE

TRUE enables the run-time system to share a file and to set record locks against a file within a process; this will occur if a file is opened more than once in different programs, or if a file is opened in different threads. Closing a shared file only releases the record locks obtained by opening the file.

If this tunable is set to FALSE, the ability to share a file and to set record locks against a file within a process is not defined by this system but by the operating system itself.

Note: The same_proc_excl_detection tunable, which provides file locking within a process, overrides the intra_process_record_locking tunable.

Default:

TRUE

lock_mode

Syntax:

set lock_mode={0|1|2|3}

Value:

0, 1, 2, or 3

Selects the locking implementation to be used, as follows:

Default:

2

Note: This tunable is only applicable if the file handler configuration option FILEMAXSIZE is set to 4. See the chapter File Handler Configuration in your File Handling book for information on the FILEMAXSIZE option.

long_filenames

Syntax:

set long_filenames={TRUE|FALSE}

Value:

TRUE or FALSE

Specifies whether file-names longer than 14 characters are to be allowed. If you create a file on a device that does not support long file-names you must set long_filenames to FALSE when accessing that file on a device that does support long file-names.

Default:

TRUE

pc_mono_palette

Syntax:

set pc_mono_palette=integer

Value:

integer selects the style of monochrome attribute palette that will be used by the run-time system when a call to the call-by-name routine CBL_SCR_SET_PC_ATTRIBUTES is made and a terminfo for which there is no color information is being used.

integer can be:

Default:

0

multi_close_limit

Syntax:

set multi_close_limit=integer

Value:

integer is a value in the range 0 - 1500, representing the number of logical closes after which a file is physically closed.

Every time a file is opened, the run-time system calls the operating system to open it - a physical open. When a file that has been opened more than once in the same process (without corresponding closes) is closed, in order that all locks are preserved, the run-time system closes the file (logical close) but does not call the operating system to close it. The run-time system only calls the operating system to physically close the file when a corresponding close has been done for each of the opens. This is the default behavior.

When set to a non-zero value, the run-time system forces a physical operating system close on a file which has been opened more than once within the same process if more than integer closes have occurred. The run-time system does a physical close for each of the integer logical closes, and then re-applies all outstanding locks on that file.

You should use this tunable with care as, due to the way in which the operating system does a physical close, all locks against all opens on a file are lost until the run-time system has time to reinstate them. We recommend that where possible, any multiple opens are nested so that all are closed prior to multiple re-opens. If you do need to keep a file open for a significant amount of time while other programs and/or threads open and close that file you need to use this tunable.

program_search_order

Syntax:

set program_search_order=integer

Value:

integer selects the program search order to be used, and can be a value from 1 to 4 as shown as shown in the following table:

Set program_search_order to 2 for compatibility with previous UNIX versions of Micro Focus COBOL, or to 3 for compatibility with previous DOS versions.

Note: If a program is called with a specific path the search sequence is not affected by the value of program_search_order and instead:

1. The run-time system is checked to see if the program is statically linked.
   
   
2. The path specified in the call is searched.

Default:

1

same_proc_excl_detection

Syntax:

set same_proc_excl_detection={TRUE|FALSE}

Value:

TRUE or FALSE

Detects if you have tried to open a file multiple times in one run unit. If TRUE, any OPEN request has conditions applied to determine whether or not it is already open, and if so, if it was opened exclusively, in which case a file error is generated. Currently, if the same file is opened twice by the same run unit, no file error is generated. This flag should be set to TRUE for RM COBOL compatibility.

Note: This tunable has been superceded by the intra_process_record_locking tunable which provides both file and record locking within a process. If you want to use same_proc_excl_detection, whether set to TRUE or FALSE, you must always set intra_process_record_locking=FALSE.

Default:

FALSE.

shared_memory_segment_size

Syntax:

set shared_memory_segment_size=integer

Value:

integer

where integer specifies, in bytes, the initial size of the shared memory block allocated by the run-time system. The minimum value you can specify for integer is 8192 (8K).

Default:

65536 (64 K)

signal_interface

Syntax:

set signal_interface={TRUE|FALSE}

Value:

TRUE or FALSE

TRUE causes the run-time system to use the signal() signal handling interface as used in Micro Focus COBOL version 3.1 and before. FALSE causes the run-time system to use the more robust sigaction() signal handling interface.

The default value should not need to be changed unless you are using signal handlers in non-COBOL programs. See the chapter Mixed-Language Programming in your Programmer's Guide to Writing Programs for more information on using signal handling in the COBOL environment. See your operating system documentation for more information on signal() and sigaction().

Default:

FALSE

signal_regime

Syntax:

set signal_regime(sig)=integer

or:

set signal_regime=1

Value:

integer

Selects the action the run-time system takes for the signal sig. The value of sig must be between 1 and the maximum signal number on your operating system. See your operating system documentation for details on signal values.

You should only use this tunable when Server Express is being used with third party software that uses signals.

If you are using signal handling in you own applications, you should use the cobpostsighandler() interface, and not the operating system signal handling interfaces, with this tunable. Also see the chapter Mixed-Language Programming in your Programmer's Guide to Writing Programs.

integer can have the following values:

Default:

0 for all signals

Comments:

If you use the alternative syntax (set signal_regime=1), then the signal regime for all signals is set to 1. Note that, for this syntax, the only value you can set is 1.

Environment Variables

The environment variables available to you are described fully in the main body of this manual. They are summarized in the appendix Micro Focus Environment Variables.

Running

Descriptions of Run-time Switches