=========================================================================
M I C R O F O C U S
O P E R A T I N G S Y S T E M E X T E N S I O N S
V4.1.10
Running Under The DG/UX
Operating System Version R4.11MU03
On The AViiON
=========================================================================
RUNNING
========
This document describes the execution facilities supplied with Micro
Focus OSX to enable you to port files between Micro Focus COBOL systems
for UNIX and Micro Focus COBOL systems for DOS, Windows, Windows NT,
Windows 95 and OS/2; and to maintain these files after porting.
TABLE OF CONTENTS
==================
OVERVIEW
OPERATION
Invoking Your Program
Switches Available
TMPDIR Environment Variable
Accessing Command Line Parameters
Accessing Command Line Parameters
Run-time System Error Messages
The COBOL Profiler
OVERVIEW
========
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 run your program, including statically linked, dynamically linked
or dynamically loadable files, once you have compiled it. When you run
your program, you can specify switches to control the behavior of the
program, and you can specify parameters on the command line that your
program can read.
OPERATION
=========
This section describes how to invoke your program, specifying any
switches required to control its behavior.
Invoking Your Program
=====================
The syntax for invoking a statically or dynamically linked module varies
slightly from that for invoking a dynamically loadable module. The
command line for running each type of program is described below.
Statically Linked Module
------------------------
To invoke a statically linked module, enter the following command line at
the system prompt:
module-name [program-params]
where:
module-name is the name of an a.out module output by the cob
command. See the chapter COBOL System Interface
(cob) for details on creating this type of file.
program-params is 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, cobrun
maps this 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 COBOL User Guide for further details.
Dynamically Linked Module
-------------------------
Dynamically linked modules are invoked as statically linked modules.
However, you must first set the LD_LIBRARY_PATH environment variable,
which specifies where to look for shared libraries. The syntax for
setting this environment variable is:
LD_LIBRARY_PATH=<path-name> [:<path-name>]...
export LD_LIBRARY_PATH
where:
<path-name> specifies where to search for shared libraries. This
variable should be set to (or should include)
$COBDIR/coblib.
Dynamically Loadable Program
----------------------------
To run dynamically loadable (.int and .gnt) programs output by the cob
command, enter the following command line at the system prompt:
cobrun [(switch-param)] program-name [program-param]
where:
switch-param is 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 is the name of either the intermediate (.int) code
or the generated (.gnt) code file of the program
output by the cob command. See the chapter COBOL
System Interface (cob) for details on creating
these types of files. If both .int and .gnt
versions of the file exist and you do not specify
an explicit file extension in the cobrun command,
then by default, the .gnt version is run.
program-param is as defined in the section Statically Linked
Module.
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.
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.
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.
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:
COBSW={+/-s}...
The format for setting switches on the command line is:
where:
+/- sets the switch s on or off, respectively.
s is either a programmable switch with a digit in the
range 0 through 8, or an alphabetic switch with an
upper-case or lower-case letter.
Notes:
You should note the following when setting switches:
o switches can be separated by spaces (but this is not required);
however, there must not be a space between the sign ("+" or "-") and
its associated switch
o switches can be specified in any order, but each programmable or
alphabetic switch must be preceded by a sign
o individual switches can be set more than once, but the last setting
of any particular switch is the one accepted by the system
o switches remain set when COBOL subprograms are called
o switches set on the command line take precedence over those defined
in the COBSW environment variable
o switches are case sensitive.
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 from the current directory 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.
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.
Table 1 : Available Switches
Switch Title Function Default
Setting
------------------------------------------------------------------
0-8 Programmable enable or disable COBOL off
switches switches that you define
in the Special-Names paragraph
of your program
A Animator switch invokes Animator debugger off
A1 Base Animator invokes the base Animator off
switch
B Skip Locked Record enables you to skip locked off
switch records when sequentially
accessing a shared file
D ANSI COBOL Debug invokes the ANSI COBOL Debug off
switch module
d Dynamic Paging enables you to specify the 250 Kbytes
Buffer switch amount of memory in bytes to
be used for the RTS dynamic
paging buffers
E Error switch executes intermediate code off
output by cob which contains
S-level compiler errors
e COBOL Symbol causes RTS to search for C on
switch programs and symbols to
satisfy CALL operations or
EXTERNAL data items
F Numeric Field enables various numeric data on
Check switch checks at run-time
i Keyboard Interrupt enables keyboard interrupts on
switch (including the suspend key
for systems that support Job
Control)
K Indexed Files enables sequence checking off
Sequence Check of indexed keys in
switch ISAM files
l Memory switch enables you to set the max bytes
(lower-case L) size of available memory available to
RTS
N Null switch enables null insertion for on
line sequential files
O Divide-by-Zero disables run-time error 48, on
causing program to continue
with undefined results
p Dynamic Linkage causes the RTS to set up on
Fixup switch the addressability for all
the Linkage Section items in
a program when it is called
Q File Status Error causes an internal RTS table off
switch to map all status "9" errors
reported to your code to a
status which conforms with
statuses returned in the COBOL
dialect of your choice
S Sort switch forces all SORT statements in off
your source code to be treated
as if you had specified the
SORT... WITH DUPLICATES IN
ORDER statement.
s Sort Memory switch specifies the amount of off
memory used as internal
workspace when performing a
SORT operation
T Tab switch enables tab insertion upon off
output for line sequential
files
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. The
syntax for setting this environment variable is:
TMPDIR=<directory>
export TMPDIR
where:
<directory> is the location used by SORT for its temporary work
files. If you do not specify a directory, the system
default directory will be used.
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:
data-name is the data item to receive the command line
parameters.
mnemonic-name is 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 COBOL
User Guide.
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.
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 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 and executable files are undefined.
The COBOL Profiler
==================
The COBOL Profiler is a facility that enables you to obtain detailed
statistics on the run-time performance of a COBOL program.
When you submit a COBOL source program to the cob command (see the
chapter COBOL System Interface (cob) for details on the cob command), you
can specify the PROFILE Compiler directive. This causes the Compiler to
include code in your program to produce performance statistics about each
paragraph of the program each time you run the compiled program. If your
program contains no paragraphs, this report is not produced.
The performance statistics produced using the PROFILE Compiler directive
for that run of the program are contained in a file called:
program-name.ipf
where program-name is the name of the program that was run. If an
executable file is produced, then program-name is the first entry point
name in the executable file.
These performance statistics are in compact form and must be converted to
a readable format. This is done by running Profiler, provided as part of
your Micro Focus COBOL system.
Invoking the Profiler Program
-----------------------------
To run Profiler, enter a command line of the form:
cobprof file-names directives
where:
file-names are one or more files containing compact Profiler
output. Profiler always searches for a file with
the extension .ipf; if you specify any other
extension, it is ignored. If you profile more than
one program at one time, Profiler output for all
the programs is written to the output file for the
first program, that is file-name1.prf.
directives are one or more of the directives that control the
operation of Profiler. To specify a directive to
Profiler, you must precede it with a plus sign (+).
Each directive can be preceded by a plus sign, but
only one is required at the start of a list of
directives.
Directives must be separated by one or more spaces.
Where a Profiler directive takes a parameter, you
can enclose the parameter either in quotation marks
or in parentheses. If you use either of these,
however, you must escape them using the backslash
character ( \).
Profiler Output
---------------
When you run Profiler, the following banner is displayed:
* Micro Focus COBOL for UNIX Profiler Vv.r
* Copyright (c) 1993 Micro Focus Ltd.
* name-1
.
.
.
* name-n
where name is one of the names in file list in the command line.
For example, if you submit a program prog1 to the cob command with the
PROFILE directive, run the program, and then enter:
cobprof prog1 +LIST
the following output is produced on the console:
* Micro Focus COBOL for UNIX Profiler Vn.n
* Copyright (c) 1993 Micro Focus Ltd.
* prog1
Total time: 172 milliseconds. Module called once.
%time time entries ms/entry paragraph
-----------------------------------------------------------------
64.53 111 21 5 TEST-ROUTINE
17.44 30 1 30 PARA1
16.28 28 15 2 NAME-ENTRY
1.74 3 1 3 END-SECTION
0.00 0 1 0 INITIAL(UNNAMED) PARAGRAPH
The Profiler output gives the total execution time (in milliseconds) for
the program run and then breaks this down for each section and paragraph
in the program as follows:
-------------------------------------------------------------------------
Output Description
-------------------------------------------------------------------------
%time total percentage of execution time spent in the
named section or paragraph
time total time (in milliseconds) spent in the named
section or paragraph
entries number of times the named section or paragraph was
entered
ms/entry average time (in milliseconds) per entry to the
section or paragraph
paragraph section or paragraph to which performance
statistics apply. The initial (unnamed) paragraph
listed is the initialization code executed before
the user part of the program is entered.
The product of the ms/entry and the number of entries should equal the
total time spent in the section or paragraph; however, because all three
values are truncated, there can be a slight discrepancy.
=========================================================================
Micro Focus and Animator are registered trademarks of Micro Focus
Limited.
Micro Focus COBOL and OSX are trademarks of Micro Focus Limited.
OS/2 is a registered trademark of International Business Machines
Corporation.
Windows is a trademark of Microsoft Corporation.
UNIX is a registered trademark of X/Open Company Limited.
=========================================================================
@(#)Vrn/running.1/4.0.00/30Oct95/nrV
Copyright (C) 1993-95 Micro Focus Limited