PreviousRunning Descriptions of Run-time SwitchesNext"

Chapter 12: Run-time Configuration

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

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 the Object COBOL system.

12.1 Introduction

When your run-time system or statically 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 the Object COBOL system.

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

12.2 Format of a Run-time Configurable

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

set configurable_name=value

while for for environment variables, the format is:

configurable_name=value
export configurable_name 

The parameters are:

configurable_name The name of the run-time configurable. This will be the name a run-time tunable described in this chapter, or an environment variable described in the appendix Micro Focus Environment Variables. For details on dd_ filename mappings see your Programmer's Guide to File Handling.
value The value to be assigned to the run-time configurable. The values that can be assigned to a run-time tunable are described in this chapter. For a run-time tunable, value is validated according to the type and values allowed for that tunable, and the value of cobconfig_error_report.

Where value is numeric, a leading zero indicates that the value should be treated as octal (that is, base 8). For example, 07 (octal) is 7 (decimal), while 010 (octal) is 8 (decimal); however, 08 (octal) and 09 (octal) are invalid octal values. Hexidecimal values can also be set by using numeric values that begin with with 0x.

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

Example

dd_MYFILE /usr/mydir/myfile 
export /usr/mydir/myfile 
SOMESHORTNAMES="JOE FRED JACK MARY"
export SOMESHORTNAMES

12.3 Run-time Tunables

The following sections describe the run-time tunables available.


animator_interrupt_char

Syntax:
set animator_interrupt_char=integer
Value:

integer

Where integer specifies the decimal value, in the range 0 - 255, of the key to be used as the interrupt in Animator.

When you are executing your program using Animator's Zoom command, your application might not recognize the function or cursor keys. This is because on some keyboards the function and cursor keys send sequences beginning with the Escape character, that by default the Zoom command takes as the interrupt character.

To prevent this, you can set animator_interrupt_char to a more suitable value. The value represents the code generated by the keyboard for the key to use to interrupt Animator's Zoom and Go operations. You should use a value that is not already being used on your system, perhaps 2, that corresponds to Ctrl/B. The key must generate a single character.

The range allowed for integer means that you can assign a normal text key as the interrupt character; however, if you do, you can no longer use that key to enter its normal character.

Default:

27. This represents the Escape key.


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 misspelt 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 takes the input from the command line.

Default:

FALSE. The first ACCEPT 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 the utility rtscore, if it available on your system.

integer can be:

0 The run-time system never produces a core file on any signal or run-time system error. This is the default behavior of the run-time system and prevents use of rtscore.
1 The run-time system produces a core file when any system signal is received that would normally produce a core file on the host system; for example, SIGILL, SIGSEGV (which would usually produce an run-time system error 114), and so on.
2 Behaves in the same way as 1, with the addition that the run-time system produces a core file when any other error condition is diagnosed; for example, run-time system error 12 ("Attempt to open a file which is already open"). The error is reported first, before the core file is produced.

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


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, Toolbox 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.


file_io_buffer_mode

Syntax:
set file_io_buffer_mode={0|1|2}
Value:

Specifies how file I/O buffering should be handled:

2 Enables buffering for all sequential, line sequential and relative files. This setting turns off the COBEXTBUF environment variable.
1 Equivalent to turning on the COBEXTBUF environment variable.
0 All buffering is turned off.

file_io_buffer_mode is automatically set to zero (no buffering) if two instances of the same file are open, or if the file was opened without usingLOCK MODE IS EXCLUSIVE.


Note: If file buffering is set, WRITE statements write data to the buffers, not directly to the file. Data is written to the file only when the buffers are flushed (this happens periodically at no set interval, or when you close the file). You can write buffered information to disk immediately by calling EXTFH with an opcode of 0C.


HP-UX:
If this tunable is specified, its setting overrides that of the HP-UX tunable file_io_buffering.

Default:

1

HP-UX:
If the HP-UX tunable file_io_buffering is set to:

As file_io_buffering is by default set to TRUE, then if file_io_buffering is not set, file_io_buffer_mode is set to 2.


isam_block_size

Syntax:
set isam_block_size={512|1024|2048|4096}
Value:

Specifies the size, in bytes, of the block to use when creating indexed files. For example:

set isam_block_size=1024

specifies a block size of 1024 bytes (or 1K)

This tunable replaces the cobcf utility that was available on some earlier products.

Default:

1024.


isam_open_key_check

Syntax:
set isam_open_key_check={TRUE|FALSE} 
Value:

TRUE or FALSE

Specifies whether or not the key descriptions specified in the program should be verified with those in an existing file during open processing.

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:

Lock Mode
Description
0 Uses the locking mechanism provided by v3.1 and earlier versions.
1 Provides compatibility with DOS and OS/2 locking mechanisms.
2 Provides interlanguage locking. This method causes record locks to lock the physical record.
3 Provides compatibility with C-ISAM version 5 and above.
Default:

2


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


noretry_on_decl

Syntax:
set noretry_on_decl={TRUE|FALSE}
Value:

TRUE or FALSE

Specifies whether or not locked records are retried when declaratives exist for the file, and the program has been compiled with RETRYLOCK NORM.


Note: This must be set to provide compatibility with COBOL v1.3.


Default:

FALSE


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:

0 Selects a CGA-emulation palette. This is the default, and is the recommended setting.
1 Selects a backwards-compatible palette that works in the same manner as previous products. This palette should not be used as it is incorrect (it does not conform to any actual PC monochrome palette), but is provided in case certain programs or files rely upon it (for instance, character screen sets saved using Dialog System when running under this incorrect palette). Wherever possible, you should attempt to convert such programs/files to use the correct palette.
Default:

0


posix_lock_prob

Syntax:
set posix_lock_prob={TRUE|FALSE}
Value:

TRUE or FALSE

The implementation in Object COBOL of compatibility with DOS and OS/2 files has created a problem in how UNIX handles file locks. On UNIX, if a file is opened twice within a program, and that file is subsequently closed using a file descriptor received from one of the open operations, any locks obtained by the other open operation are lost. This is the expected behavior of a file-close operation, as described in the POSIX standard X/Open guidelines.

This tunable provides compatibility with the behavior exhibited in V3.0. To obtain the old behavior, set the tuneable to TRUE.

Default:

FALSE


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:

Search Order
Description
1 Uses the following search sequence:
  1. The run-time system is checked to see if the program is statically linked.

  2. If the COBPATH environment variable is set, the paths specified are searched in order. Otherwise, the current directory is searched.

  3. The path in which the calling program was loaded is searched.

  4. If COBDIR is set, the path specified is searched. Otherwise, /opt/lib/cobol/ (on SVR4) or /usr/lib/cobol (UNIX SVR3) is searched.
2 Uses the following search sequence:
  1. The run-time system is checked to see if the program is statically linked.

  2. The path in which the calling program was loaded is searched.

  3. If the COBPATH environment variable is set, the paths specified are searched in order. Otherwise, the current directory is searched.

  4. If COBDIR is set, the path specified is searched. Otherwise, /opt/lib/cobol/ (on SVR4) or /usr/lib/cobol (UNIX SVR3) is searched.
3 Uses the following search sequence:
  1. The run-time system is checked to see if the program is statically linked.

  2. The current directory is searched.

  3. If the COBPATH environment variable is set, the paths specified are searched in order.

  4. If COBDIR is set, the path specified is searched. Otherwise, /opt/lib/cobol/ (on SVR4) or /usr/lib/cobol (UNIX SVR3) is searched.
4 Uses the following search sequence:
  1. The run-time system is checked to see if the program is statically linked.

  2. If the COBPATH environment variable is set, the paths specified are searched in order. Otherwise, the current directory is searched.

  3. The path in which the calling program was loaded is searched.

  4. If COBDIR is set, the path specified is searched. Otherwise, /opt/lib/cobol/ (on SVR4) or /usr/lib/cobol (UNIX SVR3) is searched.

  5. The current directory is searched.

Note: When using cobrun COBPATH is set to $COBDIR/dialog:$COBPATH


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


routine_table_size

Syntax:
set routine_table_size=integer
Value:

integer

integer is a value in the range 10-65535 specifying the maximum number of simultaneously loaded COBOL programs. Note that some system support programs (such as Adis) require slots in the routine table, so the maximum number of user programs may be smaller than the specified value. The default value of 255 means that only 128 programs can be animated. To animate more than 128 programs, increase the value of integer.

Default:

255.


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 RMCOBOL compatibility.

Default:

FALSE.


se_compat_locking

Syntax:
set se_compat_locking={TRUE|FALSE}
Value:

TRUE or FALSE.

Specifies file locking compatibility. If set to TRUE, file locking is compatible with Server Express; otherwise file locking is compitable with Object COBOL for UNIX.

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, if it is available on your system. If it is not available the signal() interface is used.

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 Micro Focus Object COBOL 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 Interfacing and Mixed Language Programming in your Programmer's Guide to Writing Programs.

integer can have the following values:

Value
Action
0 The run-time system uses the signal sig if it needs to.

By default, the run-time system sets-up signal handlers for all signals whose operating system default action would cause termination. The run-time system can thus catch these signals and tidy-up (for example, close any open files to prevent file corruption) before exiting.

1 The run-time system uses the signal sig if, and only if, a handler was not already posted for this signal.

This is useful if the third-party software is invoked before Micro Focus Object COBOL and sets up a handler for signal sig. If this tunable is not set for this signal, the run-time system overwrites the third-party software's handler with its own; this will lead to unpredictable behavior, such as run-time system error 115 ("Unexpected signal") being produced.

If a handler was posted, the run-time system will not post any handlers for this signal and so any run-time system functionality which relies on this signal will not work.

2 The run-time system never uses the signal sig.

This is only of use if the third-party software is invoked after Micro Focus COBOL and sets-up a handler for signal sig. Use of this setting is strongly discouraged for any signal whose operating system default action is to cause termination; if this signal is received between the run-time system being invoked and the third-party software setting up its handler, the default action of the operating system occurs, and the process exits without the run-time system being able to tidy-up. This could lead to problems such as file corruption.

Any run-time system functionality which relies on this signal will not work.

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.


skip_on_lock

Syntax:
set skip_on_lock={TRUE|FALSE}
Value:

TRUE or FALSE

Specifies whether or not a READ WITH LOCK of a locked record in a program compiled with the directive NODETECTLOCK causes a subsequent READ NEXT/PREVIOUS to reread the logical NEXT/PREVIOUS record or the currently locked record.

Default:

FALSE


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.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousRunning Descriptions of Run-time SwitchesNext"