# GnuCOBOL runtime configuration
#
# Copyright (C) 2015-2023 Free Software Foundation, Inc.
# Written by Simon Sobisch, Ron Norman
#
# This file is part of the GnuCOBOL runtime.
#
# The GnuCOBOL runtime is free software: you can redistribute it
# and/or modify it under the terms of the GNU Lesser General Public License
# as published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# GnuCOBOL is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with GnuCOBOL.  If not, see <https://www.gnu.org/licenses/>.


#
## General instructions
#

# The initial runtime.cfg file is found in the  $COB_CONFIG_DIR  ,
# which defaults to  installdir/gnucobol/config  (see  cobcrun --info  for the
# local path that is configured).
# The environment variable  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  ${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:
#   ${envvar:default}  (the format  ${envvar:-default}  is supported, too).

# Any environment variable may be set with the directive  setenv  .
# Example:  setenv COB_LIBARAY_PATH ${LD_LIBRARY_PATH}

# Any environment variable may be unset with the directive  unsetenv
# (one var per line).
# Example:  unsetenv COB_LIBRARY_PATH

# Runtime configuration files can include other files with the
# directive  include  .
# Example:  include my-runtime-configuration-file

# To include another configuration file only if it is present use the
# directive  includeif  .
# You can also use  ${envvar}  inside this.
# Example:  includeif ${HOME}/mygc.cfg

# If you want to reset a parameter to its default value use
#   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:	  1, Y, ON, YES, TRUE  (no matter of case)
# 	to false:	  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  COB_  .

# For a complete list of the settings in use see  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.


#
## General environment
#

# 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
#             Note:  file is opened for append if name starts with "+"
#          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_CORE_ON_ERROR
#   Parameter name:  core_on_error
#          Purpose:  to enable operating system handling of signals and to
#                    raise an ABORT signal on runtime error instead of the
#                    default error handling, which will commonly kill the
#                    process after creating a coredump
#             Type:  0   means catching all default signals and do full
#                        internal error handling as done in versions pre 3.2
#                        along with full internal handling of COBOL runtime
#                        errors
#                    1   means to forward any signals; whatever happens
#                        by means of system signal handers will happen,
#                        which may include creating coredumps and killing
#                        the process before libcob does any cleanup; preserve
#                        full internal handling of COBOL runtime errors
#                    2   is identical to 1, but on runtime errors explicit
#                        raises SIGABRT after displaying it along with the  
#                        stacktrace and after doing minimal cleanup
#                    3   similar to 2, but instead of raising SIGABRT execute
#                        "gcore -a -o NAME $$" (where $$ is the process id and
#                        NAME is specified by COB_CORE_FILENAME) as early as
#                        possible before doing the normal internal error
#                        handling; if the command does not work or if a signal
#                        handler was executed before a SIGABRT is raised
#          Default:  0
#          Example:  core_on_error 3
#             Note:  If the operating system kills the process as part of the
#                    signal handling no COBOL centric dump will be created and
#                    no cleanup will be done either.
#                    When catching a signal (for example 11) it will be
#                    returned as exit code of the process, the generated
#                    coredumps store the reason for the error in the variable
#                    "runtime_err_str".

# Environment name:  COB_CORE_FILENAME
#   Parameter name:  core_filename
#          Purpose:  to adjust the default name or specify a folder for a
#                    COB_CORE_ON_ERROR=3 generated coredump
#             Type:  string
#          Default:  ./core.libcob
#          Example:  core_filename /home/me/SomeApp.core

# Environment name:  COB_STACKTRACE
#   Parameter name:  stracktrace
#          Purpose:  to disable stracktrace creation on abort
#             Type:  boolean
#          Default:  true
#          Example:  STRACKTRACE  no

# 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;
#                    file is opened for append if name starts with "+";
#                    may be disabled by setting it to "NONE"
#             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
#                    statement; this is used for testing purposes or to tweak
#                    a missing offset, partial setting is allowed
#             Type:  numeric string in format YYYYDDMMHHMISS or date string
#                    or seconds since the epoch as @SSSSSSSS
#          Default:  the operating system date is used
#          Example:  COB_CURRENT_DATE "2026/03/16 16:40:52"
#                    current_date YYYYMMDDHHMMSS+01:00

#
## Call environment
#

# 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:  TRUE/YES/1  unload module on CANCEL
#                    FALSE/NO/0  unload module on STOP RUN only
#                    NEVER       never unload module, only useful for profilers
#                                and tracing tools that do a post-mortem lookup
#                                of function address
#          Default:  false
#          Example:  PHYSICAL_CANCEL  TRUE

#
## File I/O
#

# 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
#             Note:  This setting is most useful if you want to REWRITE those
#                    files.
#          Example:  LS_FIXED TRUE

# Environment name:  COB_LS_VALIDATE
#   Parameter name:  ls_validate
#          Purpose:  Defines for LINE SEQUENTIAL files that the data should be
#                    validated as it is read (status 09) / written (status 71).
#             Type:  boolean
#          Default:  true (per COBOL 2022)
#             Note:  If active effectively disables COB_LS_NULLS.
#          Example:  LS_VALIDATE FALSE

# 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 plus
#                    validating that they only occur after a null character.
#                    Decreases LINE SEQUENTIAL performance and prevents writing
#                    escape sequences or formatting within the data.
#                    Only checked if COB_LS_VALIDATE is disabled.
#          Example:  LS_NULL = TRUE

# Environment name:  COB_LS_SPLIT
#   Parameter name:  ls_split
#          Purpose:  Defines for LINE SEQUENTIAL files what to do when a record
#                    is longer than the program handles. If 'ls_split=true' then
#                    the data is returned as multiple records with io status 06,
#                    otherwise the record is truncated, io status set to 04 and
#                    the file skips to the next LF.
#             Type:  boolean
#          Default:  true (per COBOL 2022)
#          Example:  LS_SPLIT = FALSE

# 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

# Environment name:  COB_SEQ_CONCAT_NAME
#   Parameter name:  seq_concat_name
#          Purpose:  Does DD_asgname hold multiple input file names
#             Type:  boolean
#          Default:  false
#          Example:  seq_concat_name = true

# Environment name:  COB_SEQ_CONCAT_SEP
#   Parameter name:  seq_concat_sep
#          Purpose:  Character separating file names
#             Type:  char
#          Default:  +
#          Example:  seq_concat_name = '&'

#
## Screen I/O
#

# 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 and
#                    disabling blinking on some systems
#             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 ''

#
## Report I/O
#

# 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