NAME

ccbl, runcbl - ACUCOBOL compiler and runtime system

SYNOPSIS

ccbl [ options ] program
runcbl [ options ] [ program ] [ parameters]
cobol [ options ] program

DESCRIPTION

(Reference, AcuCobol OnLine Documentation)

ACUCOBOL is a single-pass ANSI COBOL compiler. Errors encountered are printed on the screen (or in an error file if one is requested) referencing the line where the error was detected by source file and line number. A source listing, a symbol table listing and general information can be printed on request.

A successful compile (using ccbl) produces an object-code file. This file is ready to be run by the ACUCUBOL runtime system, runcbl. No linking is needed to run the program. Any programs that are called during execution are loaded dynamically at runtime by runcbl. Subprograms written in C may be linked into the run time system directly, and then called by a COBOL program using the CALL verb.

Runcbl has a source-level debugger built in to it. You can run any program under the debugger by specifying it at runtime. The debugger runs in its own window that overlays the running program. This prevents the debugger's output from interfering with program's output.

The executable named cobol is a small shell script that runs ccbl and creates a line-numbered source listing with error messages appearing after the associated line. This was added to emulate the behavior of older batch-mode compilers.

Many options are available. These are all indicated by an initial hyphen. The compiler's options are divided into different groups. Each group (except the first) has a distinguishing letter. For example, the options that controls listings all start with the letter "L". Any set of options from the same group may be specified together. For example, the "-Lo" option and the "-Ls" options may be grouped together as "-Los".

Options that require arguments may also be specified together, as long as the required arguments immediately follow the combined options, in the same order as the options. For example, "-o file1 -e file2" may also be specified as "-oe file1 file2".

Command line arguments that begin with a hyphen are not case sensitive. For example, "LO" and "-Lo" and "-lo" all mean the same thing. In this manual, argument group letters are shown in upper case, and the actual arguments are shown in lower case (for example, "-Lo"). This is done merely for clarity. Note that other command line arguments (such as file names) are case sensitive.

Several compile time options take a file name as an argument. As a special abbreviation, the character '@' can be placed in one of these names to stand for the name of the source program. This name has all directory information removed form it along with any characters following a period character (inclusive). This is then entered into the file name argument at the location of the '@' character.

For example, if you wanted to compile a program called "TEST.CBL", wanted the resulting object file to be named "TEST.OBJ", and wanted to place the errors in the file name "TEST.ERR", you could use the following command:

Debugger Commands

This section appears ahead of the compiler and runtime options, because the options take up more than eleven pages, and you really don't want to look at all of them. In fact, to spare you the pain, you turn on debugging by giving the -Zd option to ccbl, and the -d option to runcbl.

The debugger displays the first ten characters of the name of the current program, followed by the current address (in hexadecimal). This name is derived from the PROGRAM-ID paragraph.

Note that function keys (designated with <key>) may not work on all terminal types. Under the X11 Window System, the <Fn> keys do not work, but all others do.

ccbl options

Standard Options

 
Listing Options
By default, ACUCOBOL-GT does not create a listing. The following options cause a listing to be made and control what will appear in the listing.

Compatibility Options

ACUCOBOL-GT has several options available to aid in converting programs written for other COBOL environments. See the section on compatibility modes below for more information about this. By default, ACUCOBOL-GT runs in the VAX COBOL compatibility mode.

The source options modify the way the compiler treats the physical source files.

Reserved Word Options

ACUCOBOL-GT provides the ability to suppress certain sets of reserved words. When suppressed, these words are treated as user-defined words instead. This ability is provided to aid in converting programs written for other COBOL environments. Reserved words that have been added to the 1974 standard are divided into the groups identified below. By specifying the corresponding option, you cause that group of words to be treated as user-defined words.

Book 4, Appendix D contains a list of reserved words and shows which group each word belongs to. Some words belong to more than one group. Every group a word belongs to must be suppressed for the word to be treated as a user-defined word.

-R8: Suppresses words reserved by the 1985 COBOL standard.

-Rv: Suppresses words reserved by VAX COBOL that are not in the 1985 standard.

-Rr: Suppresses words reserved by RM/COBOL that are not in the 1985 standard.

-Ri: Suppresses words reserved by Data General ICOBOL that are not in the 1985 standard.

-Rs: Suppresses words added to ACUCOBOL-GT in order to support the Screen Section.

-Ra: Suppresses words reserved by ACUCOBOL-GT that are required for its unique extensions.

-Rw: This option allows you to suppress a particular reserved word. The option must be followed (as the next separate argument) by the reserved word you want to suppress. This option may be repeated to suppress multiple reserved words.

This option also allows you to suppress some non-reserved words, such as control names (e.g., "entry-field", "label") or property names (e.g., "max-text", "bitmap-number"). If you tell the compiler to suppress a non-reserved word, it issues the following warning:

Unknown reserved word: non-reserved word

-Rc: Allows you to change a reserved word. This option must be followed by two separate arguments. The first is the reserved word you want to change. The second is the word that you want to use instead. For example, "-Rc TITLE NAME" will allow you to use "TITLE" as a user-defined word and will cause the
word "NAME" to be treated as the reserved word "TITLE". You may not specify a word that is already reserved as the new reserved word. This option may be repeated to transform multiple reserved words.

-Rx: This option tells the compiler to ignore a particular word. The option must be followed (as the next separate argument) by the word you want the compiler to ignore. This option may be repeated to ignore multiple words.

Data Storage Options

-Dca: This selects the ACUCOBOL-GT storage convention. It is the default setting. This convention is also compatible with data produced by RM/COBOL (not RM/COBOL-85) and previous versions of ACUCOBOL-GT. It also produces slightly faster code.

-Dci: This selects the IBM storage convention. It is compatible with IBM COBOL, as well as with several others including RM/COBOL-85. It is also compatible with the X/Open COBOL standard.

-Dcm: This selects the Micro Focus storage convention. It is compatible with Micro Focus COBOL, when the Micro Focus "ASCII" sign-storage option is used (this is the Micro Focus default).

-Dcn: Causes a different numeric format to be used. The format is the same as the one used when the "-Dci" option is used, except that positive COMP-3 items use "x0B" as the positive sign value instead of "x0C". This option is compatible with NCR COBOL.

-Dcv: This creates numeric sign formats that are compatible with VAX/COBOL. These are identical to the IBM formats, except that unsigned COMP-3 fields place "x0C" in the sign position, instead of "x0F". The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). As a result, different COBOL vendors use different conventions. By using the options "-Dca", "-Dci", "-Dcm", "-Dcn", or "-Dcv", you may select alternate sign-storage conventions. Doing so is useful in the following cases:

   If you need to export data to another COBOL system and need to match its sign-storage convention.

   If you are importing data from another COBOL system, and that data contains key fields with signed data. Keys are treated alphanumerically, so if you use the incorrect sign-storage convention, ACUCOBOL-GT will not find a matching key when it is doing a READ.

The storage-convention affects how data appears in USAGE DISPLAY, COMP-2 and COMP-3 data types. For additional information and tables, see the Reference Manual, section 5.7.1.7, "USAGE clause."

-Ds: This causes USAGE DISPLAY numeric items with no SIGN clause to be treated as if they were described with the SIGN IS TRAILING SEPARATE clause. Several versions of RM/COBOL behave this way (all versions before 2.0, and some versions afterward).

-Db: Causes COMPUTATIONAL data items to be treated as if they were declared as BINARY data items. This is the default when you are using VAX/COBOL compatibility mode.

-D2: Causes COMPUTATIONAL data items to be treated as if they were declared as COMPUTATIONAL-2. This is the default when you are using RM/COBOL compatibility mode.

-Di: This option causes the compiler to initialize Working-Storage. Normally, the compiler will initialize all data items to spaces except for those items given a VALUE clause. If this option is specified, data items are initialized according to their type:

   Alphabetic, alphanumeric, alphanumeric edited, and numeric edited items are initialized to spaces.

   Numeric items are initialized to zero.

   Pointer items are initialized to null.

   Index items are initialized to the value 1.

Automatic initialization applies only to Working-Storage and does not apply to any item that (a) is given a VALUE clause, (b) is EXTERNAL, or (c) is subordinate to a REDEFINES phrase.

-D1: Causes any data item whose underlying type is binary to be stored in one byte if that data item has only one or two digits. Normally, such a data item would be stored in two bytes.

-Dm: Causes any data item whose underlying type is binary to be stored in the minimum number of bytes needed to hold it. Normally, binary types are stored in two, four, or eight bytes. This option allows storage in any number of bytes ranging from one to eight. The exact number of bytes used for a particular data item is described under the USAGE clause in the ACUCOBOL-GT Reference Manual.

-D5: Causes data items declared as BINARY to be treated as if they were declared as COMPUTATIONAL-5. This causes the values to be stored in the host machine's native byte-ordering instead of the machine-independent byte-ordering normally used. This option should be used with caution because it can lead to programs that are not portable.

-D6: Causes unsigned data items declared as PACKED-DECIMAL to be treated as if they were declared as COMPUTATIONAL-6. This saves one-half of a byte because the compiler will not generate any storage for the sign.

-Da: Allows you to specify the data alignment modulus for level 01 and level 77 data items. Normally, level 01 and level 77 data items are aligned on an even boundary (modulus 2). You can specify an alternate alignment boundary by following this option with the desired modulus. This should be specified as a single digit that immediately follows the "-Da" as part of the same argument. For example, "-Da4" specifies that data should be aligned on quad-byte boundaries.

-Dl: Allows you to limit the maximum alignment modulus that will be used for SYNCHRONIZED data items. Normally, a synchronized data item will be aligned on a 2, 4, or 8-byte boundary depending on its type. This option allows you to specify an upper bound to the modulus used. This should be specified as a single digit that immediately follows the "-Dl" as part of the same argument. For example, "-Dl4" specifies that the maximum synchronization boundary should be a 4-byte boundary. If you want to make programs that are compliant with the 88/Open COBOL specification, you should specify "-Dl4".

-Dw: Lets you modify the definition of certain data types. These data types are generally dependent on the host machine's native word size. You may use this option to:

   Maintain compatibility with COBOL source code written specifically for 16- or 32-bit machines (for example, to set the size of USAGE POINTER data items to 4 bytes).

   Make it easier to match a C structure for a particular machine.

   Optimize your data storage for a particular class of machines.

"-Dw" selects the maximum word size of the set of machines that you expect to run on. You follow this option with the maximum word size you desire, expressed as the number of bits per word. Currently, the legal forms are "-Dw16", "-Dw32", and "-Dw64".

Note that this option determines the maximum word size, not the exact word size.
 

The "-Dw" option affects the size of the following data types:
 

SIGNED-SHORT     UNSIGNED-SHORT
SIGNED-INT       UNSIGNED-INT
SIGNED-LONG      UNSIGNED-LONG
POINTER

It also affects the size of the RETURN-CODE special register.

Selecting a maximum word size does not inhibit the portability of your code. Instead, it limits the size of certain data items. If you attempt to use a data item that is too small for a particular machine, you may lose precseion. For example, USAGE POINTER data items are stored in 4 bytes if you use "-Dw16" or "-Dw32". If you attempt to run a program that stores an address in one of these items on a 64-bit machine, you may lose some of the address. While the program will technically run, the results may not
be useful.

For maximum portability, you should use "-Dw64". This will allow your code to run on all machines that run ACUCOBOL-GT. For strict compatibility with ACUCOBOL-85 Version 2.2 or earlier, you should use "-Dw32". For programs prior to Version 2.3, the only real effect of shifting from "-Dw32" to "-Dw64" is that USAGE POINTER data types expand from 4 bytes to 8 bytes. If your program does not depend on the size of POINTER data items, then you should be able to use "-Dw64" with no harm.

If you use any of the "-C" compile options that establish source compatibility with ACUCOBOL-85 Version 2.2 or earlier (e.g. "-C21"), then the default setting is "-Dw32". If you do not use these options, then the default setting is "-Dw64". You may override the default by using the "-Dw" option. For example, to compile for source compatibility with Version 2.1, but to set the target architecture to 64 bits, you would use "-C21 -Dw64". In order to use "-Dw64", you must use a Version 2.3 or later runtime.

See the related information on USAGE types in the Reference Manual, section 5.7.1.8. See also the information on RETURN-CODE and support for 64-bit architectures in Book 4, Appendix F, sections F.5.1.2 and F.5.1.3.

-Dy: Specifies that all data items whose underlying representation is binary should be treated as if they were described as SYNCHRONIZED. This option is not recommended unless you have a particular need for it. ACUCOBOL-GT is optimized for non-synchronized handling of binary data, so synchronization will usually not have beneficial results. Note, however, that you must specify this option if you want to make programs that are compliant with the 88/Open COBOL specification.

-Dz: This option causes the compiler to modify its size checking rules for numeric items. Instead of computing size error by examining the number of 9's in an item's picture, the compiler computes size error by examining the actual storage for that item. For example, normally a PIC 99 BINARY data item cannot hold a number larger than 99, although the storage for the item can hold a value up to 255. When "-Dz" is used, ACUCOBOL-GT will not cause a size error until a value greater than 255 is moved to this item. This option also affects truncation in MOVE statements and implied moves.

-Df: This option changes the way the compiler treats data items declared as COMP-1 and COMP-2.

Some compilers use COMP-1 and COMP-2 to specify single and double precseion floating point data items. However, ACUCOBOL-GT assigns a different meaning to COMP-1 and COMP-2 and uses FLOAT and DOUBLE to specify floating point data items.

When the "-Df" option is used, the compiler treats data items declared as COMP-1 as if they were declared FLOAT and data items declared as COMP-2 as if they were declared DOUBLE. With the "-Df" option, you have the following correspondence:
 

COMP-1    FLOAT      single precseion
COMP-2    DOUBLE     double precseion

The "-Df" option makes it easier to compile code originally written for another compiler--one that used COMP-1 and COMP-2 to specify floating point data items. The "-Df" option lets you compile such code without having to change COMP-1 and COMP-2 to FLOAT and DOUBLE.

Video Options

-Vh: Forces the default video intensity for ACCEPT and DISPLAY statements to be set to high intensity. The default for ACUCOBOL-GT is to use the normal operating intensity for the terminal being used.

-Vl: Forces the default video intensity for ACCEPT and DISPLAY statement to be set to low intensity.

-Va: This option must be used with either the "-Vh" or "-Vl" option. When used, the default intensity specified by the "-Vh" or "-Vl" option will be used only for ACCEPT statements. DISPLAY statements will use the opposite intensity. Thus "-Vha" will cause the default intensity for ACCEPT statements to be high while the default for DISPLAY statements will be low. When Screen Section items are used, then input and update fields will use the ACCEPT intensity, while output and literal fields will use the DISPLAY intensity.

-Vc: Causes any ACCEPT statement that contains a numeric or numeric edited receiving field to be treated as if the CONVERT phrase were also specified. this is the default for RM/COBOL-85 but not for RM/COBOL version 2 or VAX COBOL.

-Vx: Allows exception keys to be entered by the user for any ACCEPT statement. Normally, ACUCOBOL-GT inhibits the use of exception keys on ACCEPT statements that do not have a CONTROL KEY clause or an ON EXCEPTION clause.

-Ve: Alters the rules that determine which conditions cause an ON EXCEPTION phrase to receive control in a Format 1 ACCEPT statement. Normally, entering an exception key will cause the ON EXCEPTION phrase to receive control. If you specify this option, then you must follow the "-Ve" with a digit (as part of the same argument) taken from the following list:

'1': Exception keys cause the ON EXCEPTION phrase to execute (default handling).

'2': Conversion error causes the ON EXCEPTION phrase to execute. When a numeric item is being entered and the CONVERT phrase is specified, then entering an illegal number will cause the exception. '3': Combines the effects of both `1' and `2'.

By default, the runtime system handles conversion errors by displaying an error message and forcing the user to re-enter the data. If you specify "-Ve2" or "-Ve3", then conversion errors are returned to your program instead. For strict compatibility with VAX COBOL, you should specify "-Ve2", while for strict compatibility with RM/COBOL, you should specify "-Ve3". The default setting is recommended, however, because it provides a meaning for ON EXCEPTION that is more consistent with the rest of the ACUCOBOL-GT language.

-Vb: Causes the phrase "BLANK LINE", when used in a Screen Section entry, to be treated as if it were written "BLANK EOL". Most other COBOL compilers work this way, but the X/Open COBOL standard requires the syntax supported by ACUCOBOL-GT.

-Vq: Causes ACUCOBOL-GT to produce quiet programs by inhibiting the default bell produced by ACCEPT statements compiled in RM/COBOL compatibility mode. However, this does not override explicit BELL or BEEP phrases.

Miscellaneous Options

-Zd: Compiles the program for source-level debugging. See Chapter 3, "Debugger and Utilities," for additional details about this option.

-Zs: Compiles the program for symbolic debugging only. This is generally less useful than "-Zd" above, but may be useful in some circumstances. Section 3.1, "Runtime Debugger," describes the differences between symbolic debugging and source-level debugging.

-Zg: Enables the use of segmentation (overlays) in the source. If this option is not used, then section numbers will be ignored.

-Za: Causes the compiler to generate code to test array references at runtime. If an index is used which is out-of-bounds, the runtime system will print an error message showing the index value and the allowed bounds. (This causes some extra code to be generated and prevents certain table optimizations from occurring, so it should be turned off once a program is fully debugged.) With this option, the compiler does not re-use previously computed index values. Because subscript overflow is the most common cause of memory access violation errors, adding this option is a good first step when you are looking for the cause of a memory access violation. (See Chapter 6, section 6.4.1, "Memory Access Violations" for more details.)

-Zc: This "compact" option causes ACUCOBOL-GT to optimize for smaller code instead of faster code.

-Zi: Causes the program to be compiled as if it had the "IS INITIAL PROGRAM" phrase specified in its PROGRAM-ID paragraph. This can be useful, in some cases, when you are compiling programs that do not contain adequate memory management (no CANCEL verbs, for example).

-Zl: This option causes the compiler to allow data items larger than 64 KB. The program can be run only on machines that can address more than 64 KB at once. See the Reference Manual, section 5.1.6, "Large Data Handling."

-Zn: This turns off ACUCOBOL-GT's local optimizer. This is useful primarily to see if the optimizer is introducing errors in the generated object code. This option also prevents the compiler from re-using previously computed index values.

-Zo: Although still supported, this option has been replaced by the "-Fo" option. Both options produce the same results.

-Zr: Allows for recursive PERFORM statements. When this switch is used, the PERFORM verb is modified so that return addresses are stored on a stack. Only the most recent PERFORM statement has an active return address. When this option is used, a paragraph under the control of a PERFORM statement may (directly or indirectly) PERFORM itself. See the configuration option PERFORM-STACK.

This behavior is the default. For backward compatibility, "-Zr" acts like "-Zr1". If you compile for compatibility with Version 3.1 or earlier, recursive PERFORMs are turned off by default. This behavior may affect existing programs that do not compile for earlier compatibility. Event procedures require the ability to do recursive PERFORMs.

-Zr0: This option tells the compiler not to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.

-Zr1: This option tells the compiler to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.

-Zt: While still supported, this switch is obsolete because its effects are always performed by the compiler. This option makes certain table indexing operations faster. Generally, it improves performance for 32-bit binary indexes and for the indexing of multi-dimensional tables.

-Zw: This option prepares a program for import into the Acucorp workbench's Screen Painter. It causes the compiler to decorate windows and screen controls with additional information that can be used by the screen import utility. Graphical windows imported into the Screen Painter will be more complete if the program was first compiled with this option. Using this option makes your compiled program somewhat larger, so you should use it only when you are importing screens into the workbench.

You can also use the "-Ml", "-Mm" and "-Mu" options to affect the case of the additional information. This will affect how these items are seen in the Screen Painter, and in your subsequently generated code. Specifying "-Zw -Ml" will cause the data imported into the Screen Painter to be in lowercase. The default is uppercase ("-Mu"). To specify uppercase for the first letter of each word, and lower case for the rest of each word, use "-Mm<".

-Zx While still supported, this option has been replaced by the "-Fx" option. Both options produce the same results.

-Zy: This option lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. If you use this option, then the 4-digit year format will be used for ACCEPT FROM DATE providing that:

   The receiving field is numeric or numeric edited and contains eight or more integer digits; or

   The receiving field is not numeric or numeric edited and contains eight or more character positions.

If neither of the above conditions applies, then ACCEPT FROM DATE will return its normal 6-digit format even if you use "-Zy".

ACCEPT FROM DAY works in the same fashion, except that the receiving field must have seven or more digits/positions in order to receive the new format.

Information on ACCEPT FROM DATE and ACCEPT FROM DAY is located in the Reference Manual entry for ACCEPT, Format 3, in section 6.6.

-Zz: This option causes spaces in a USAGE DISPLAY numeric item to be treated as the value zero. "-Zz" must be specified at compile time in order to prevent the optimizer from mis-constructing the program. Note that this option should be used only if you need it, because it causes less efficient programs to be produced.

-Z3: Causes ACUCOBOL-GT to produce programs that can be run by the Version 1.3 runtime system. Specifying this will limit several features of later versions. If you use a restricted feature, you will receive an error message at compile time. This flag also implies the "-C3" option to ensure compatible behavior of the compiled program (see above).

-Z4: Similar to the "-Z3" option, except that the produced object can be run by the Version 1.4 runtime system. Implies "-C4".

-Z5: Causes the compiler to produce object files that can be run by the Version 1.5 runtime system. This option implies "-C5".

Using the Runtime System

The ACUCOBOL-GT runtime system (referred to in this manual as runcbl), runs the programs created by the compiler. Once compiled, programs are ready to run; no linking step is required. Programs compiled with ACUCOBOL-GT are machine transportable. runcbl accommodates for the differences between machines.

To run an ACUCOBOL-GT program, enter the following command (substitute the name of your runtime for runcbl):

runcbl [options] [program] [parameters]

Program is the name of a compiled program. If omitted, its name defaults to "cbl.out" (or to the name you have set with the runtime configuration variable DEFAULT-PROGRAM ). Remote name notation is allowed for the name of the compiled program, if your runtime is client-enabled. See sections 5.2.1 and
5.2.2 for more information about client-enabled runtimes and remote name notation.

Parameters are one or more arguments that can be passed to the program. These arguments can be accessed through the CHAINING phrase of the Procedure Division header in the compiled program. For details, see the entry for the "CHAIN Statement" in Reference Manual section 6.6. If parameters are specified, then program must also be specified. Under VMS, the parameters that are not in double quotes are converted to lower case. Parameters should be enclosed in double quotes to preserve case sensitivity.

Options is a series of one or more of the following flags. These options must be preceded by a hyphen. You can specify more than one option by simply combining them. Option characters may be either upper or lower case. The allowed options are:

-#: This option must be followed (as the next separate argument) by a series of letters that determine which SPECIAL-NAMES switches to turn on. There are 26 SPECIAL-NAMES switches. The letter "a" corresponds to switch 1, "b" to switch 2, and so forth. For example, to start the program with switches 1, 5 and 8 turned on, specify "-# aeh".

For convenience, you can turn on any of the first 8 switches by simply specifying the switch number or numbers without the "#" argument. For example, "-# aeh" can also be specified as "-158".

-a: This flag is now obsolete and should not be used.

-b: Inhibits the terminal initialization done by runcbl. This can be useful if the program is run in background, since the terminal initialization can prevent normal use of the terminal by the operating system. This is particularly true on UNIX systems. If you specify this flag, then the behavior of ACCEPT and DISPLAY statements is undefined, so this flag should be used with caution.

On UNIX machines, if this option is used then the "hang up" signal (turning off the terminal) is treated the same as a keyboard interrupt. This means you can block the hang up signal from having any effect by using the "-s" option. If "-b" is not used, a hang up signal terminates the runtime after a normal shutdown is performed.

-c: This option must be followed (as the next separate argument) by the name of an alternate runtime configuration file. It causes runcbl to use this configuration file instead of its default one. See the section on "Runtime Configuration" below.

Remote name notation is allowed for this option if your runtime is client-enabled. See sections 5.2.1 and 5.2.2 for more information about client-enabled runtimes and remote name notation.

-d: This starts the program in debugging mode. See Chapter 3, "Debugger and Utilities," for details.

-e: This option must be followed by the name of a file (as the next separate argument). This option causes the error output from the runtime system to be placed in this file. This can be used to trap runtime system error messages or trace output from the debugger. The file you specify will be opened as an empty file, so be careful not to follow "-e" with the file name of an existing file that you want to keep. Use "+e" to cause the error output to be appended to the named file.

Under UNIX systems, redirecting error output causes problems for "more" and "vi". For this reason, we offer two options for redirecting error messages under UNIX:

"-e" causes all of the runtime's tracing and error messages and DISPLAY UPON SYSERR output to go to "errorfile". It does not redirect stderr. This means that error output from programs called by CALL "SYSTEM" is not redirected. If you call "more" or "vi" from within COBOL, you can safely use "-e" to redirect error messages.

If you expect programs called by CALL "SYSTEM" to send their errors to the error file, use the option "-ee" instead of "-e".

Remote name notation is allowed for this option if your runtime is client-enabled. See sections 5.2.1 and 5.2.2 for more information about client-enabled runtimes and remote name notation.

-f: This option ensures that the runtime does not perform user interface functions when the COBOL program is functioning as a Common Gateway Interface (CGI) program on the Internet. This option causes the runtime to suppress warning messages that are normally displayed in a message box. If the runtime shuts down due to an error that is not handled by the COBOL program, it constructs an HTML page containing the shutdown message and sends it to the standard output stream before terminating. This option performs the same function as the environment variable "A_CGI" but does not affect the entire environment.

-h: This option causes the runtime to explicitly ignore hang-up signals. You can also ignore hang-up signals by specifying both the "-s" and "-b" options. However, the "-sb" combination also inhibits terminal initialization and prevents the user from killing a program with an abort key such as "Control-C" or "Delete". Unlike "-sb", the "-h" option ignores only the hang-up signals.

-i: This option must be followed (as the next separate argument) by a file name. This causes the keyboard input to be taken from this file. It can be used as an alternate to input redirection on UNIX systems. Remote name notation is not allowed for this option.

Examine your input files carefully, paying particular attention to the way the <enter key is represented. On many systems, it is represented by a hex "0A" (line feed). Note that the line feed does not, by default, terminate an ACCEPT. So, when you use the "-i" option, you will want to add the following to your "cblconfig" file:

KEYSTROKE TERMINATE=10 ^J

-import: This option is available only on Windows 95 and Windows NT systems. It requires the file "WEXPRT32.DLL", which must be installed in the same directory as the runtime executable. This option is used to import graphical screens created with ACUCOBOL-GT Version 3.x or AcuScreens(TM) so that these screens can be used with the AcuBench Screen Painter. If you are running with this option, simply right-click on any window to have the opportunity to add it to the file "import.out". See the AcuBench documentation for details.

-k: This option causes the immediate playback of a keystroke file. It must be followed (as the next separate argument) by a file name. The filename argument is the name of a file containing recorded keystrokes. The runtime internally calls W$KEYBUF using opcode "9" and this file name prior to executing the first COBOL program. The effect is that the keystrokes recorded in the file are treated as the runtime's first user input. For more information on W$KEYBUF, see Book 4, Appendix I. Remote name notation is not allowed for this option. Use this as an alternative to "-i" in Windows systems.

-l: Causes a listing of the contents of the runtime configuration file to be printed on the error output. Prints the runtime's version number on the first line. Also prints the steps taken by runcbl when it is trying to load a program, along with any problems encountered. This is useful for debugging problems with the configuration file or program path resolution (see the section on "Runtime Configuration" below). This is best used in conjunction with the "-e" option above to capture the debugging information in a file.

+L: Available on MS-DOS machines. This option enables automatic looping in conjunction with the C$CHAIN library routine. See C$CHAIN in Book 4, Appendix I for details about this option.

-o: This option must be followed by the name of a file that will take the display output from the program. This is similar to output redirection on UNIX systems. If "+o" is used instead, then the output is appended to the named file. Remote name notation is not allowed for this option.

-r: Starts the program in debugging mode (like "-d"). This option must be followed by the name of a file containing debugging commands. The debugger is run under control of this file. Remote name notation is not allowed for this option.

-s: Runs the program in "safe" mode. On non-UNIX systems, the "-s" option prevents the user from killing the program with the operating system's abort key (Control-C, Delete, etc.). However, any kill command will interrupt the program run. On UNIX systems only, the "-s" option must be issued twice (runcbl -ss) to protect it from the system's abort key. This option allows only a kill -9 to stop the program run.

"Safe" mode can help preserve the integrity of files used by the program. If the program is not in "safe" mode, then runcbl will automatically close its files if the user kills the program. Note that this keeps each file intact but does not keep separate files synchronized with each other, which may be required by the user's application.

-t: This option can be used to capture the runtime's terminal output to a disk file. This option must be directly followed by a filename of the output file.

The -t option can be used instead of piping the output to the "tee" command. Notice that piping runtime output to "tee" can cause the runtime to hang. This is because runtime detects that the output is not a terminal and so it will not set terminal attributes for the terminal. In such state, the runtime has a hard time accepting input, and the output may not be flushed to the screen in a timely manner.

When the "-t filename" flag is set, all the output to the terminal goes to this file, including cursor addressing codes. Also, input to the runtime will be captured in the output file only if it is shown by the runtime.

Note that this option can be used only with a version of the runtime which has an addressable terminal capability. It will not work with any of the graphical runtimes, nor will it work with the regular Extended DOS runtime.

-v: Prints the current version number of runcbl , the serial number, and the maximum number of users licensed to use the runtime simultaneously. No program is run.

-vv: Prints the current version number of runcbl, along with extended information. No program is run.

-w: This has the same effect as specifying "WARNINGS 0" and "MAKE-ZERO 0" in the runtime configuration file. This option is provided for compatibility with previous versions of ACUCOBOL-GT. We recommend that the corresponding configuration entries be used instead.

-x: When a file error "30" occurs, the root cause of this error is often not apparent. Specifying "-x" will cause the runtime system to display the operating system's corresponding error number on the error output. This information may help in determining the problem. You can use the "-e" option to direct the error output to a file.

-y: Specifies a pre-loaded object file library. This option must be followed (as the next separate argument) by the name of an ACUCOBOL-GT object library. The directory of the object modules contained in this library is loaded by runcbl before it loads the main program. All of the object modules in the library are thus available to be called at any time. Note that the main program may be contained in the library because the library is loaded first. You may pre-load multiple libraries by specifying multiple "-y" options. Libraries are described in more detail in Chapter 3.

Remote name notation is allowed for this option if your runtime is client-enabled. See sections 5.2.1 and 5.2.2 for more information about client-enabled runtimes and remote name notation.

-z: After an unexpected runtime termination resulting from a memory access violation, this option causes the program to output the current contents of memory where the violation occurred.