This chapter describes how to prepare and run a program on this COBOL system. It explains how you can specify switches to control the behavior of the program at run time, how you can specify parameters on the command line that your program can then read, and how you can control the behavior of the run-time system.
You can get statistics on the run-time performance of a COBOL program using Profiler; see the chapter Profiler in your Utilities Guide for details.
You can create runnable programs in two ways:
See the chapter Packaging Applications for an introduction to executable file types.
When you run your program, you can specify:
Note: If you are using the 64-bit version of Server Express, the names of tools might vary. For more information see the chapter Working in 32-bit and 64-bit Modes.
The syntax for invoking a linked system executable file varies slightly from that for invoking a dynamically loadable module. The command line for running each type of program is described below.
Before you can run a program you must first set one or more of the environment variables SHLIB_PATH, LIBPATH and LD_LIBRARY_PATH. See the appendix Environment Variables for details.
To run a linked system executable program, enter the following command line at the system prompt:
module-name [program-params]
where the parameters are:
module-name | The name of a system executable file output by the cob command. See the chapter COBOL System Interface (Cob) for details on creating this type of file. If the module-name does not contain an explicit path then the directories specified by $PATH are searched. |
program-params | One or more parameters that are required by the program. Each parameter is a string, separated from adjoining parameters by one or more spaces. These parameters can be read by the program in a number of ways. See the chapter Writing Efficient Programs in your Program Development book for further details. |
To run dynamically loadable programs (that is, callable shared objects, .gnt files or .int files) use the cobrun command (or cobrun_t for multi-threaded programs). Enter the following command line at the system prompt:
cobrun [switch-param] program-name [program-param]
where the parameters are:
switch-param | One or more programmable and run-time switches that control events in a program at run time (see the section Switches in this chapter). |
program-name | The name of a dynamically loadable program, which is an
.int file, a .gnt file or a callable
shared object. See the chapter
COBOL System Interface
(Cob) for details on creating these types of files.
If versions of the program exist as an
.int file, a .gnt file, or a callable
shared object, and you do not specify an explicit filename extension in the
cobrun command, then by default, the callable shared object
version is run in preference to the .gnt file, and the
.gnt file in preference to the .int
file. You can change this order; see the description of the
program_search_intgnt
run-time tunable.
If program-name does not contain an explicit path the directories specified by $COBPATH, and in the case of a callable shared object, the directories specified by $LD_LIBRARY_PATH, $LIBPATH, or $SHLIB_PATH are searched. See the description of the program_search_order run-time tunable |
program-param | One or more parameters that are required by the program. Each parameter is a string, separated from adjoining parameters by one or more spaces. If any of the parameters contain an equal sign, the equal sign is mapped to parentheses as these have a special meaning to UNIX, whereas the equal sign does not. These parameters can be read by the program in a number of ways. See the chapter Writing Efficient Programs in your Program Development book for further details. |
A switch is a parameter you pass to the run-time system to control the behavior of your program at run time. These switches fall into two categories: programmable switches and run-time switches. Full details on the the switches are provided in the topic Run-time Switches.
Programmable switches consist of a digit in the range 0 through 8. These switches correspond to the COBOL switches that you define in the Special-Names paragraph of your program, enabling you to set these switches on or off when your program begins executing. Any changes made to the settings of these switches using the COBOL statement SET mnemonic-name TO ON or OFF is not effective once the application has terminated. For details of how to use the SET statement with COBOL switches, see your Language Reference.
Run-time switches are acted on by the run-time system itself. Each consists of an upper-case or lower-case letter. These switches affect optional aspects of the behavior of certain COBOL features at run time.
Switches that you specify before running your program can be set using the COBSW environment variable. Alternatively, if you are running a dynamically loadable program, you can set them on the cobrun command line; however, we recommend that you use COBSW instead.
To set a programmable switch or run-time switch on, precede it with a plus sign (+); to set it off, precede it with a minus sign (-).
If you do not explicitly set any switches either in the COBSW environment variable or on the cobrun command line, then their default values apply.
The format for setting switches in COBSW is:
The format for setting switches on the command line is:
where the parameters are:
![]() |
A programmable or run-time switch. The plus sign (+) sets the switch s on, while the minus sign (-) sets it off. |
![]() |
Either a programmable switch with a digit in the range 0 through 8, or a run-time switch with an upper-case or lower-case letter. |
Notes: You should note the following when setting switches:
Setting COBSW to:
COBSW=+1+4
sets the programmable switches as follows:
0 | off |
1 | on |
2 | off |
3 | off |
4 | on |
5 | off |
6 | off |
7 | off |
8 | off |
The command:
cobrun -2+5-7+7 ./myprog
loads the program myprog.int, myprog.gnt or myprog.so from the current directory (depending on the program search order) with programmable switches 5 and 7 on and switch 2 off. Note that since the last setting of switch 7 (that is +7) is the one used, that switch is turned on. Switches 0, 1, 3, 4, 6 and 8, which are not specified, are off by default.
The TMPDIR environment variable enables you to specify a different path in which to store temporary files. This can be necessary if the run-time system needs to page data to disk when creating heaps or sorting. For details of setting the TMPDIR environment variable, see the appendix Environment Variables.
You can access program parameters in a number of ways. For example, you can use one of the following formats of the ACCEPT statement:
accept data-name from command-line
or
accept data-name from mnemonic-name
where the parameters are:
data-name | The data item to receive the command line parameters. |
mnemonic-name | Defined in the Special-Names paragraph as:
command-line is mnemonic-name |
Full details on the available methods of accessing command line parameters are contained in the chapter Writing Efficient Programs in your Program Development book.
Running program myprog with the command line:
COBSW=+1+7 export COBSW myprog in-file.dat clear
causes the statement:
accept cmd-line from command-line
in the program to place
in-file.dat clear
into the data-item cmd-line.
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 section describes the use of run-time tunables. See the appendix Environment Variables for a list of environment variables used by Server Express. See the section Switches for information about run-time switches.
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:
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 book. |
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.
For example
setenv dd_MYFILE /usr/mydir/myfile set cobconfig_error_report=TRUE
The run-time tunables are listed and described in the topic Run-time Tunables
A run-time system error message is returned on a program that is syntactically correct but that encounters problems during the actual running of the program. For example, you could receive such an error if you try to access a file in the wrong mode or if you use a corrupt file. See the topic Run-time System Error Messages for a description of the format and all the possible run-time system errors.
Note: If you try to run a program, but the run is not successful, you should be aware that the program counter (pc) values for native code generated files, callable shared objects and system executable files are undefined.
The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of Micro Focus software components. The only component currently enabled to provide information using the Consolidated Tracing Facility is the run-time system.
To use the Consolidated Tracing Facility you perform the following steps:
See the topic Enabling Tracing for more information on using the Consolidated Tracing Facility.