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
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.
In this Chapter
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.
Run-time Configuration File
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.
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.
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:
configurable_name |
The name of the run-time configurable. This will be the name of a
run-time tunable described in this chapter, or an environment variable
described in the appendix
Environment
Variables. For details on dd_ filename mappings see
your
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. Hexadecimal 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:
setenv dd_MYFILE /usr/mydir/myfile
set cobconfig_error_report=TRUE
Run-time Tunables
The following sections describe the run-time tunables available.
arguments_are_initial
Syntax:
set arguments_are_initial={TRUE|FALSE}
Parameters:
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. |
Properties:
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}
Parameters:
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. |
Properties:
cobconfig_error_report
Syntax:
set cobconfig_error_report={TRUE|FALSE}
Parameters:
TRUE or FALSE |
If FALSE, do not report any errors during processing of the
configuration file. |
Properties:
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}
Parameters:
TRUE or FALSE |
If TRUE, the first ACCEPT or READ from STDIN takes the input
from the command line. |
Properties:
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}
Parameters:
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 Efficient
Programs in your Program
Development book for information on passing the command line to a
main program. |
Properties:
core_on_error
Syntax:
set core_on_error=integer
Parameters:
integer |
Specifies in what circumstances a core file is produced. You
can look at core files with Animator. See your
Debugging
Guide for details.
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. |
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 a run-time
system error 114), and so on. |
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.
|
Properties:
See Also:
current_day
Syntax:
set current_day=integer
Parameters:
integer |
A value in the range 1 through 31, representing the required
day of the month. The value you specify is returned when you use the ACCEPT
identifier FROM DATE syntax or the CURRENT-DATE
intrinsic function. |
Properties:
Defa7ult: |
The current day specified by the system clock. |
current_month
Syntax:
set current_month=integer
Parameters:
integer |
A value in the range 1 through 12, representing the required
month of the year. The value you specify is returned when you use the ACCEPT
identifier FROM DATE syntax or the CURRENT-DATE
intrinsic function. |
Properties:
Default: |
The current month specified by the system clock. |
current_year
Syntax:
set current_year=integer
Parameters:
integer |
A value representing the required year. The value you specify
is returned when you use the ACCEPT identifier FROM
DATE or ACCEPT identifier FROM DAY syntax or the
CURRENT-DATE intrinsic function. |
Properties:
Default: |
The current year specified by the system clock. |
debug_on_error
Syntax:
set debug_on_error={0|1}
Parameters:
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. |
Properties:
Comments:
For more details of just-in-time debugging, see your
Debugging
Guide.
debugger_command
Syntax:
set debugger_command="debugger"
Parameters:
debugger |
specifies the command to start the debugger. This can be one
of the commands listed in the chapter
Debugging
Methods in your Debugging Guide.
You use this tunable in combination with the
debug_on_error tunable. |
Properties:
Comments:
For more details of just-in-time debugging, see your
Debugging
Guide.
default_cancel_mode
Syntax:
set default_cancel_mode=integer
Parameters:
integer |
where integer selects whether
logical or physical cancels are used.
integer can be
0 |
Physical cancels |
1 |
Logical cancels |
If you select logical cancels, any program canceled during
run-time will not be freed from memory. This is the default. The program is
available to be reused and hence the performance of CALL/CANCEL statements is
greatly increased. If you select physical cancels, any program canceled during
run-time will be freed from memory, making more memory available. As far as
your program is concerned, the behavior of logical and real cancels is
identical. |
Properties:
Default: |
Logical cancels are used |
detect_alt_ctrl
Syntax:
set detect_alt_ctrl={TRUE|FALSE}
Parameters:
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.
|
Properties:
dynamic_dictionary_limit
Syntax:
set dynamic_dictionary_limit=integer
Parameters:
integer |
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. |
Properties:
Default: |
30 buffers of 8K. |
faultfind_level
Syntax:
set faultfind_level=n
Parameters:
n |
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
Guide for information on FaultFinder. |
Properties:
See Also:
faultfind_outfile
Syntax:
set faultfind_outfile="[>>]filename"
Parameters:
filename |
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.
If filename contains the string
%p, this string is replaced by the process ID of the
program that started FaultFinder.
See the chapter
FaultFinder in your Debugging
Guide for information on FaultFinder. |
Properties:
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_recsize
Syntax:
set faultfind_recsize=record_size
Parameters:
record_size |
is a numeric value, in bytes, that specifies the internal
cache size used to store read/write data for the operation traceback log. All
read/write data is stored and reported. By using this configurable you might
improve performance. The default value is 64 and the maximum is 1024.
The maximum value of record_size
can be 1024 bytes.
See the chapter
FaultFinder in your Debugging
Guide for information on FaultFinder. |
Properties:
See Also:
filename_quote_char
Syntax:
set filename_quote_char="character"
or:
set filename_quote_char='character'
Parameters:
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. |
Properties:
Default: |
" (the double quote character) |
filename_escape_char
Syntax:
set filename_escape_char="character"
or:
set filename_escape_char='character'
Parameters:
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. |
Properties:
Default: |
\0 (no character is used as an escape character) |
intra_process_record_locking
Syntax:
set intra_process_record_locking={TRUE|FALSE}
Parameters:
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 occurs 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. |
Properties:
lock_mode
Syntax:
set lock_mode={0|1|2|3}
Parameters:
0, 1, 2, or 3 |
Selects the locking implementation to be used, as follows:
Lock Mode |
Description |
0 |
Uses the locking mechanism provided by Micro Focus
COBOL 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.
|
|
Properties:
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}
Parameters:
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. |
Properties:
multi_close_limit
Syntax:
set multi_close_limit=integer
Parameters:
integer |
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. |
pc_mono_palette
Syntax:
set pc_mono_palette=integer
Parameters:
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 COBOL for UNIX products prior to and including V4.0. 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 or files to use the correct palette.
|
|
Properties:
profile_behavior
Syntax:
set profile_behavior={0|1}
Parameters:
0 or 1 |
Specifies the behavior of the Profiler with regard to the
counting of time spent in called programs.
If profile_behavior is set to 0, time spent in a called
program is counted both in the called program and in the calling program.
If profile_behavior is set to 1, time spent in a called
program is counted only in the called program. |
Properties:
See Also:
The chapter
Profiler in your Utilities
Guide.
program_search_intgnt
Syntax:
set program_search_intgnt={TRUE|FALSE}
Parameters:
TRUE or FALSE |
Reverses the position of .int and
.gnt files in the program search order in whiich the
run-time system searches for dynamically loadable programs. If set to TRUE the
run-time system searches for an .int file before a
.gnt file. If set to FALSE the run-time system searches
for a .gnt file before an .int file.
|
Properties:
See Also:
program_search_order The section
Dynamically Loadable
Programs in the chapter
Running.
program_search_order
Syntax:
set program_search_order=integer
Parameters:
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:
- The run-time system is checked to see if the
program is linked or already loaded.
- If the COBPATH environment variable is set, the
paths specified are searched in order. Otherwise, the current directory is
searched.
- The path in which the calling program was loaded is
searched.
- If COBDIR is set, the
$COBDIR/dynload path is searched for COBOL system
programs. Otherwise, /usr/lpp/cobol/dynload (on AIX) or
/opt/lib/cobol/dynload (on other systems) is searched.
|
2 |
Uses the following search sequence:
- The run-time system is checked to see if the
program is linked or already loaded.
- The path in which the calling program was loaded is
searched.
- If the COBPATH environment variable is set, the
paths specified are searched in order. Otherwise, the current directory is
searched.
- If COBDIR is set the
$COBDIR/dynload path specified is searched. Otherwise,
/usr/lpp/cobol/dynload (on AIX) or
/opt/lib/cobol/dynload (on other systems) is searched.
|
3 |
Uses the following search sequence:
- The run-time system is checked to see if the
program is linked or already loaded.
- The current directory is searched.
- If the COBPATH environment variable is set, the
paths specified are searched in order.
- If COBDIR is set the path
$COBDIR/dynload specified is searched. Otherwise,
/usr/lpp/cobol/dynload (on AIX) or
/opt/lib/cobol/dynload (on other systems) is
searched.
|
4 |
Uses the following search sequence:
- The run-time system is checked to see if the
program is linked or already loaded.
- If the COBPATH environment variable is set, the
paths specified are searched in order. Otherwise, the current directory is
searched.
- The path in which the calling program was loaded is
searched.
- If COBDIR is set the path
$COBDIR/dynload specified is searched. Otherwise,
/usr/lpp/cobol/dynload (on AIX) or
/opt/lib/cobol/dynload (on other systems) is searched.
- The current directory is searched.
|
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:
- The run-time system is checked to see if the program is
statically linked.
- The path specified in the call is searched.
|
Properties:
redir_stdin_is_recsq
Syntax:
redir_stdin_is_recsq=={TRUE|FALSE}
Parameters:
TRUE or FALSE |
A setting of TRUE forces the run-time system to treat input
from a STDIN stream as if it was record sequential rather than line sequential,
the default. |
Properties:
shared_memory_segment_size
Syntax:
set shared_memory_segment_size=integer
Parameters:
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). |
Properties:
signal_interface
Syntax:
set signal_interface={TRUE|FALSE}
Parameters:
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 Program
Development book for more information on using signal handling in
the COBOL environment. See your operating system documentation for more
information on signal() and sigaction(). |
Properties:
signal_regime
Syntax:
set signal_regime(sig)=integer
or:
set signal_regime=1
Parameters:
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 Program
Development book.
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 Server Express 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 leads 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 Server Express 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. |
|
Properties:
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.