@section General instructions

@*
@*
The initial runtime.cfg file is found in the @code{$COB_CONFIG_DIR},
which defaults to @code{installdir/gnucobol/config} (see @code{cobcrun --info} for the
local path that is configured).
The environment variable @code{COB_RUNTIME_CONFIG} may define a different runtime
configuration file to read.
@*
If settings are included in the runtime environment file multiple times
then the last setting value is used, no warning occurs.
@*
Settings via environment variables always take precedence over settings
that are given in runtime configuration files. And the environment is
checked after completing processing of the runtime configuration file(s)
@*
All values set to string variables or environment variables are checked
for @code{$@{envvar@}} and replacement is done at the time of the setting.
You can also specify a default value for the case that envvar is not set:
 @code{$@{envvar:default@}} (the format @code{$@{envvar:-default@}} is supported, too).
@*
Any environment variable may be set with the directive @code{setenv}.

Example: @code{setenv COB_LIBARAY_PATH $@{LD_LIBRARY_PATH@}}
@*
Any environment variable may be unset with the directive @code{unsetenv}
(one var per line).

Example: @code{unsetenv COB_LIBRARY_PATH}
@*
Runtime configuration files can include other files with the
directive @code{include}.

Example: @code{include my-runtime-configuration-file}
@*
To include another configuration file only if it is present use the
directive @code{includeif}.
You can also use @code{$@{envvar@}} inside this.

Example: @code{includeif $@{HOME@}/mygc.cfg}
@*
If you want to reset a parameter to its default value use
 @code{reset parametername}.
@*
Most runtime variables have boolean values, some are switches, some have
string values, integer values (if not explicit noted: unsigned) and some
are size values.
The boolean values will be evaluated as following:
	to true:	 @code{1, Y, ON, YES, TRUE} (no matter of case)
	to false:	 @code{0, N, OFF}
A 'size' value is an unsigned integer optionally followed by K, M, or G
for kilo, mega or giga.
@*
For convenience a parameter in the runtime.cfg file may be defined by using
either the environment variable name or the parameter name.
In most cases the environment variable name is the parameter name (in upper
case) with the prefix @code{COB_}.
@*
For a complete list of the settings in use see @code{cobcrun --runtime-config}.
@*
Note:
If you want to *slightly* speed up a program's startup time, remove all
of the comments from the actual real configuration file that is processed.
@*
@*
@verbatim
@end verbatim
@section General environment
@verbatim


Environment name:  COB_DISABLE_WARNINGS
  Parameter name:  disable_warnings
         Purpose:  turn off runtime warning messages
            Type:  boolean
         Default:  false
         Example:  DISABLE_WARNINGS  TRUE

Environment name:  COB_ENV_MANGLE
  Parameter name:  env_mangle
         Purpose:  names checked in the environment would get non alphanumeric
                   change to '_'
            Type:  boolean
         Default:  false
         Example:  ENV_MANGLE  TRUE

Environment name:  COB_SET_DEBUG
  Parameter name:  debugging_mode
         Purpose:  to enable USE ON DEBUGGING procedures that were active
                   during compile-time because of WITH DEBUGGING MODE,
                   otherwise the code generated will be skipped
            Type:  boolean
         Default:  false
         Example:  COB_SET_DEBUG  1

Environment name:  COB_SET_TRACE
  Parameter name:  set_trace
         Purpose:  to enable COBOL trace feature
            Type:  boolean
         Default:  false
         Example:  SET_TRACE  TRUE

Environment name:  COB_TRACE_FILE
  Parameter name:  trace_file
         Purpose:  to define where COBOL trace output should go
            Type:  string       : $$ is replaced by process id
         Default:  stderr
         Example:  TRACE_FILE  ${HOME}/mytrace.$$

Environment name:  COB_TRACE_FORMAT
  Parameter name:  trace_format
         Purpose:  to define format of COBOL trace output
            Type:  string
         Default:  "%P %S Line: %L"
                   %P is replaced by Program-Id/Function-Id minimal length 29
                      with prefix
                   %I is replaced by Program-Id/Function-Id variable length,
                      without prefix
                   %L is replaced by Line number, right justified, length 6
                   %S is replaced by statement type and name
                   %F is replaced by source file name 
         Example:  TRACE_FORMAT  "Line: %L %S"
            Note:  format of GC2.2 and older:
                   "PROGRAM-ID: %I 	Line: %L 	%S"

Environment name:  COB_DUMP_FILE
  Parameter name:  dump_file
         Purpose:  to define where COBOL dump output should go
            Note:  The -fdump=all compile option prepares for dump
            Type:  string       : $$ is replaced by process id
         Default:  stderr
         Example:  DUMP_FILE  ${HOME}/mytrace.log

Environment name:  COB_DUMP_WIDTH
  Parameter name:  dump_width
         Purpose:  to define COBOL dump line length
            Type:  integer
         Default:  100
         Example:  dump_width 120

Environment name:  COB_CURRENT_DATE
  Parameter name:  current_date
         Purpose:  specify an alternate Date/Time to be returned to ACCEPT
                   clauses this is used for testing purposes or to tweak
                   a missing offset partial setting is allowed
            Type:  numeric string in format YYYYDDMMHH24MISS or date string
         Default:  the operating system date is used
         Example:  COB_CURRENT_DATE "2016/03/16 16:40:52"
                   current_date YYYYMMDDHHMMSS+01:00


@end verbatim
@section Call environment
@verbatim


Environment name:  COB_LIBRARY_PATH
  Parameter name:  library_path
         Purpose:  paths for dynamically-loadable modules
            Type:  string
            Note:  the default paths .:/installpath/extras are always
                   added to the given paths
         Example:  LIBRARY_PATH    /opt/myapp/test:/opt/myapp/production

Environment name:  COB_PRE_LOAD
  Parameter name:  pre_load
         Purpose:  modules that are loaded during startup, can be used
                   to CALL COBOL programs or C functions that are part
                   of a module library
            Type:  string
            Note:  the modules listed should NOT include extensions, the
                   runtime will use the right ones on the various platforms,
                   COB_LIBRARY_PATH is used to locate the modules
         Example:  PRE_LOAD      COBOL_function_library:external_c_library

Environment name:  COB_LOAD_CASE
  Parameter name:  load_case
         Purpose:  resolve ALL called program names to UPPER or LOWER case
            Type:  Only use  UPPER  or  LOWER
         Default:  if not set program names in CALL are case sensitive
         Example:  LOAD_CASE  UPPER

Environment name:  COB_PHYSICAL_CANCEL
  Parameter name:  physical_cancel
         Purpose:  physically unload a dynamically-loadable module on CANCEL,
                   this frees some RAM and allows the change of modules during
                   run-time but needs more time to resolve CALLs (both to
                   active and not-active programs)
           Alias:  default_cancel_mode, LOGICAL_CANCELS (0 = yes)
            Type:  boolean (evaluated for true only)
         Default:  false
         Example:  PHYSICAL_CANCEL  TRUE


@end verbatim
@section File I/O
@verbatim


Environment name:  COB_VARSEQ_FORMAT
  Parameter name:  varseq_format
         Purpose:  declare format used for variable length sequential files 
                   - different types and lengths precede each record
                   - 'length' is the data length, does not include the prefix
            Type:  0   means 2 byte record length (big-endian) + 2 NULs
                   1   means 4 byte record length (big-endian)
                   2   means 4 byte record length (local machine int)
                   3   means 2 byte record length (big-endian)
         Default:  0
         Example:  VARSEQ_FORMAT 1

Environment name:  COB_FILE_PATH
  Parameter name:  file_path
         Purpose:  define default location where data files are stored
            Type:  file path directory
         Default:  .  (current directory)
         Example:  FILE_PATH ${HOME}/mydata

Environment name:  COB_LS_FIXED
  Parameter name:  ls_fixed
         Purpose:  Defines if LINE SEQUENTIAL files should be fixed length
                   (or variable, by removing trailing spaces)
           Alias:  STRIP_TRAILING_SPACES  (0 = yes)
            Type:  boolean
         Default:  false
         Example:  LS_FIXED TRUE

Environment name:  COB_LS_NULLS
  Parameter name:  ls_nulls
         Purpose:  Defines for LINE SEQUENTIAL files what to do with data
                   which is not DISPLAY type.  This could happen if a LINE
                   SEQUENTIAL record has BINARY/COMP data fields in it.
            Type:  boolean
         Default:  false
            Note:  The TRUE setting will insert a null character x"00" before
                   those values to escape them, and redo on read-in.
         Example:  LS_NULL = TRUE

Environment name:  COB_SYNC
  Parameter name:  sync
         Purpose:  Should the file be synced to disk after each write/update
            Type:  boolean
         Default:  false
         Example:  SYNC: TRUE

Environment name:  COB_SORT_MEMORY
  Parameter name:  sort_memory
         Purpose:  Defines how much RAM to assign for sorting data
                   if this size is exceeded the  SORT  will be done
                   on disk instead of memory
            Type:  size  but must be more than 1M
         Default:  128M
         Example:  SORT_MEMORY 64M

Environment name:  COB_SORT_CHUNK
  Parameter name:  sort_chunk
         Purpose:  Defines how much RAM to assign for sorting data in chunks
            Type:  size  but must be within 128K and 16M
         Default:  256K
         Example:  SORT_CHUNK 1M


@end verbatim
@section Screen I/O
@verbatim


Environment name:  COB_BELL
  Parameter name:  bell
         Purpose:  Defines how a request for the screen to beep is handled
            Type:  FLASH, SPEAKER, FALSE, BEEP
         Default:  BEEP
         Example:  BELL SPEAKER

Environment name:  COB_REDIRECT_DISPLAY
  Parameter name:  redirect_display
         Purpose:  Defines if DISPLAY output should be sent to 'stderr'
            Type:  boolean
         Default:  false
         Example:  redirect_display Yes

Environment name:  COB_SCREEN_ESC
  Parameter name:  screen_esc
         Purpose:  Enable handling of ESC key during ACCEPT
            Type:  boolean
         Default:  false
            Note:  is only evaluated if COB_SCREEN_EXCEPTIONS is active
         Example:  screen_esc Yes

Environment name:  COB_SCREEN_EXCEPTIONS
  Parameter name:  screen_exceptions
         Purpose:  enable exceptions for function keys during ACCEPT
            Type:  boolean
         Default:  false
         Example:  screen_exceptions Yes

Environment name:  COB_TIMEOUT_SCALE
  Parameter name:  timeout_scale
         Purpose:  specify translation in milliseconds for ACCEPT clauses
                   BEFORE TIME value / AFTER TIMEOUT
            Type:  integer
                   0 means 1000 (Micro Focus COBOL compatible), 1 means 100
                   (ACUCOBOL compatible), 2 means 10, 3 means 1
         Default:  0
            Note:  the minimum and possible maximum value depend on the
                   screenio library used
         Example:  timeout_scale 3

Environment name:  COB_INSERT_MODE
  Parameter name:  insert_mode
         Purpose:  specify default insert mode for ACCEPT; 0=off, 1=on
            Type:  boolean
         Default:  false
            Note:  also sets the cursor type (if available)
         Example:  insert_mode Y

Environment name:  COB_MOUSE_FLAGS
  Parameter name:  mouse_flags
         Purpose:  specify which mouse events will be sent as function key
                   to the application during ACCEPT and how they will be
                   handled
            Type:  int (by bits)
         Default:  1
            Note:  0 disables the mouse cursor, any other value enables it,
                   any value containing 1 will enable internal handling (click
                   to position, double-click to enter).
                   See copy/screenio.cpy for list of events and their values.
           Alias:  MOUSE_FLAGS
         Example:  11 (enable internal handling => 1, left press => 2,
                       double-click => 8; 1+2+8=11)

Environment name:  COB_MOUSE_INTERVAL
  Parameter name:  mouse_interval
         Purpose:  specifies the maximum time (in thousands of a second)
                   that can elapse between press and release events for them
                   to be recognized as a click.
            Type:  int (0 - 166)
         Default:  100
            Note:  0 disables the click resolution (instead press + release
                   are recognized), also disables positioning by mouse click

Environment name:  COB_DISPLAY_PRINT_PIPE
  Parameter name:  display_print_pipe
         Purpose:  Defines command line used for sending output of
                   DISPLAY UPON PRINTER to (via pipe)
                   This is very similar to Micro Focus COBPRINTER
            Note:  Each executed DISPLAY UPON PRINTER statement causes a
                   new invocation of command-line (= new process start).
                   Each invocation receives the data referenced in
                   the DISPLAY statement and is followed by an
                   end-of-file condition.
                   COB_DISPLAY_PRINT_FILE, if set, takes precedence
                   over COB_DISPLAY_PRINT_PIPE.
           Alias:  COBPRINTER
            Type:  string
         Default:  not set
         Example:  print 'cat >>/tmp/myprt.log'

Environment name:  COB_DISPLAY_PRINT_FILE
  Parameter name:  display_print_file
         Purpose:  Defines file to be appended to by DISPLAY UPON PRINTER
            Note:  Each DISPLAY UPON PRINTER opens, appends and closes the file.
            Type:  string       : $$ is replaced by process id
         Default:  not set
         Example:  display_printer '/tmp/myprt.log'

Environment name:  COB_DISPLAY_PUNCH_FILE
  Parameter name:  display_punch_file
         Purpose:  Defines file to be created on first
                   DISPLAY UPON SYSPUNCH/SYSPCH
            Note:  The file will be only be closed on runtime exit.
            Type:  string       : $$ is replaced by process id
         Default:  not set
         Example:  display_punch './punch_$$.out'

Environment name:  COB_LEGACY
  Parameter name:  legacy
         Purpose:  keep behavior of former runtime versions, currently only
                   for setting screen attributes for non input fields
            Type:  boolean
         Default:  not set
         Example:  legacy true

Environment name:  COB_EXIT_WAIT
  Parameter name:  exit_wait
         Purpose:  to wait on main program exit if an extended screenio
                   DISPLAY was issued without an ACCEPT following
            Type:  boolean
         Default:  true
         Example:  COB_EXIT_WAIT off

Environment name:  COB_EXIT_MSG
  Parameter name:  exit_msg
         Purpose:  string to display if COB_EXIT_WAIT is processed, set to ''
                   if no actual display but an ACCEPT should be done
            Type:  string
         Default:  'end of program, please press a key to exit' (localized)
         Example:  COB_EXIT_MSG ''


@end verbatim
@section Report I/O
@verbatim


Environment name:  COB_COL_JUST_LRC
  Parameter name:  col_just_lrc
         Purpose:  If true, then COLUMN defined as LEFT, RIGHT or CENTER
                   will have the data justified within the field limits
                   If false, then the data is just copied into the column as is
            Type:  boolean
         Default:  TRUE
         Example:  col_just_lrc True
@end verbatim
