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.
"-ee" - 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 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 AcuScreensTM so that these screens can be used with the AcuBench Screen Designer. 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.
It is important to note that the original purpose of the screen import utility was specifically to upgrade users from AcuScreens to AcuBench, and it was not intended as a permanent device to keep importing all the new screens you create either from scratch or from AcuBench. For that reason, when new control types are added, the screen import utility is not necessarily updated at all, or it may be updated with basic information about the new control type but not all the different properties and styles of the new control type. You should not rely on this utility to be able to import all new screens you create.
When the screen import utility tries to import an unrecognized type or property of a control, you will see the following message on your screen:
This screen contains at least one control type that the Screen Import Utility does not know about. You should add these controls manually.
-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 Appendix I in Book 4, "Appendices." 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 Appendix I in Book 4, "Appendices" for details about this option.
--no-save-debug This option has two effects: (a) it prevents the debugger from reading the ".adb" file, thus causing the debugger to start in its default state, and (b) it prevents the debugger from writing out a new ".adb" file when it exits.
The debugger saves state information in a ".adb" file which is used when the debugger is executed in another run. This information includes window placement and breakpoint settings. There are some cases when you may find this inconvenient, and the "--no-save-debug" option provides a way to eliminate this behavior.
-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.
-vv (double "v") 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.