PreviousDescriptions of cob Error Messages Run-time ConfigurationNext"

Chapter 12: Running

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 and how you can specify parameters on the command line that your program can then read.

You can get statistics on the run-time performance of a COBOL program using Profiler; see the chapter Profiler in your Utilities Handbook for details.

12.1 Introduction

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:

12.2 Running Programs

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 the environment variable:

See the appendix Micro Focus Environment Variables for details.

12.2.1 Linked System Executable Programs

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 Programs in your Programmer's Guide to Writing Programs for further details.

12.2.2 Dynamically Loadable Programs

To run dynamically loadable programs (that is, callable shared objects, .gnt files or .int files) 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 Switch Parameters 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.

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 is searched. See the description of the program_search_order run-time tunable in the chapter Run-time Configuration

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 Programs in your Programmer's Guide to Writing Programs for further details.

12.2.2.1 Switch Parameters

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. A full listing and description of the switches available are contained in the chapter Descriptions of Run-time Switches.

12.2.2.1.1 Programmable 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.

12.2.2.1.2 Run-time Switches

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.

12.2.2.2 Setting Switches

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, as shown in the section Switches Available, apply.

The above rules are summarized in the following two diagrams.

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-8, or a run-time switch with an upper-case or lower-case letter.

Notes:

You should note the following when setting switches:


Examples:

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.

12.2.3 Switches Available

The switch parameter s can be any of the programmable or run-time switches listed in the following table. The Function column describes the effect of the switch when it is set on, and the Default Setting column indicates the setting that applies if you do not explicitly set the switch. Full details on the function of each of these switches are provided in the chapter Descriptions of Run-time Switches.

Table 11-1: Available Switches

Switch Title Function Default
Setting
0-8 Programmable Enable or disable COBOL switches that you define in the Special-Names paragraph of your program Off
A Animator Invokes Animator debugger Off
B, B1 Skip Locked Record Enables you to skip locked records when sequentially accessing a shared file Off
D ANSI COBOL Debug Invokes the ANSI COBOL Debug module Off
d Dynamic Paging Buffer Enables you to specify the amount of memory in bytes to be used for the RTS dynamic paging buffers 240 Kbytes
E Error switch Executes intermediate code output by cob which contains S-level compiler errors Off
F Numeric Field Check Enables various numeric data checks at run-time On
i Keyboard Interrupt switch Enables keyboard interrupts (including the suspend key for systems that support Job Control) On
L2 Record Terminator Determines the character to be treated as the record terminator (x"0D0A" or x"0A") Off
l Memory (lower-case L) Enables you to set the size of available memory Maximum bytes
available to RTS
N Null switch Enables null insertion for line sequential files On
O Divide-by-Zero Produces a run-time system error for a program compiled using the CHECKDIV directives, with parameters "OSVS", "VSC2" or "COBOL370" if it attempts to divide by zero. On
T Tab Enables tab insertion upon output for line sequential files Off
Z DBCS Space Conversion Converts DBCS spaces to ASCII spaces when reading a line sequential file or console input. Off

12.2.4 TMPDIR Environment Variable

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 Micro Focus Environment Variables.

12.2.5 Accessing Command Line Parameters

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 Programs in your Programmer's Guide to Writing Programs.

Example:

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.

12.2.6 Run-time System Error Messages

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. Refer to your Error Messages book 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.



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

PreviousDescriptions of cob Error Messages Run-time ConfigurationNext"