Runtime Options

The allowed runtime options include:

-#       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.
--a2n Indicates to use the AcuToNet.dll method of .NET support. For version 9 and earlier, this interface provides .NET support. By default, this interface is no longer needed in versions 9 or later of ACUCOBOL-GT. A new internal method of .NET support was added to version 9 that enables greater .NET support than what could be achieved with the previous AcuToNet.dll method. If you experience issues with the new method of .NET support, you can revert back to the previous method by using this runtime option. There are other steps you must also perform. See Using AcuToNetdll Interface for more information.
--analyze This option turns on runtime tracing for the program being run. See Dynamic Runtime Tracing for full details.
-b Inhibits terminal initialization done by runcbl. This can be useful if the program is run in background because 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, the behavior of ACCEPT and DISPLAY statements is undefined; therefore use this flag with caution. A program can examine the ACU-NO-TERMINAL field after an ACCEPT FROM TERMINAL-INFO statement to determine whether it was started with -b. See ACCEPT Statement (Format 3) for more information.
-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 the default file. See Runtime Configuration.

Remote name notation is allowed for this option if your runtime is client-enabled. See Remote Name Notation

--char2gui This option converts character-based screens into graphical equivalents for AcuBench Screen Designer use. When you run your program with this option, ACUCOBOL-GT's Character-to-GUI Wizard launches in the background.

After your program starts, navigate to the screen you want to convert and right-click on the window's background. A pop-up menu appears. Select Build Graphical Screen to continue with the conversion. The Character-to-GUI Wizard then creates a graphical version of the current screen and displays it together with a Properties dialog box. You can use the Properties dialog box to make some basic changes to the screen. Repeat this process for each screen you want to convert.

When you are done, exit the application. When the application exits, the run time writes an import.out file into your current working directory that contains information describing the converted screens. You can then start AcuBench and, using the Add Screen function, display the contents of the import.out file in a Screen Designer window. If you already have a file called import.out in your current working directory, the wizard overwrites it; therefore, if you intend to convert screens in stages, you should rename the file and save it in a separate directory.

If you execute the program in AcuBench, the workbench creates a new program in the workspace Structural View upon exit. The program's Screen node contains entries for each screen described in the import.out file. Those screens open in the workbench development area, where they can be modified. Screen node entries can be moved in the workspace as needed.

The purpose of the Character-to-GUI Wizard is to simplify the initial task of converting traditional text-based applications into ones that use a graphical user interface. Although the wizard greatly reduces the task of converting character-based screens, it is only a first step in the process. It is expected that after you use the wizard, you will spend time manipulating the screens to your liking using AcuBench Screen Designer. You will also need to integrate the newly generated screen section code back into your program. See the AcuBench User's Guide for more information on using the Character-to-GUI Wizard.

-d This starts the program in debugging mode. See Runtime Debugger.
-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 run time system to be placed in this file. This can be used to trap run time system error messages and trace output. -e creates a new file or overwrites an existing file. Use +e to cause error output to be appended to the file. The format of the output can be tailored with the TRACE_STYLE configuration variable.

When specifying a run time error file name you can use the following format specifiers:

  • %p - If the name contains the string %p, that string is replaced with the process ID (PID) of the run time.
  • %d - If the name contains the string %d, that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month, and DD day.
  • %t - If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second, and TTT milliseconds.
  • %u - If the name contains the string %u, that string is replaced with the username.
  • %h - If the name contains the string %h, that string is replaced with the hostname.

Note that these specifiers may also be used in the file names configured with the ACU_MON_FILE and ACU_DUMP ACU_DUMP_FILE ACU_DUMP_WIDTH ACU_DUMP_TABLE_LIMIT configuration variables configuration variables.

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 Remote Name Notation for more information.

--embedded-config-file This option causes the runtime to load and use a configuration file embedded in a COBOL object library. The name of the embedded configuration file can be specified with the runtime -c option. Otherwise, it must be named cblconfi or cblconfig.

The configuration file may be embedded either by using cblutil or the COPY RESOURCE statement.

The object library must be preloaded using the run time -y command-line option. This allows configuration file settings to be available before the primary module is loaded.

Certain configuration variables must be set before the object library is loaded. Therefore, these variables cannot be set in an embedded configuration file. The following is a list of variables that cannot be set in an embedded configuration file:

  • CGI
  • MESSAGE-QUEUE-SIZE
  • ICON
  • NO-CONSOLE
  • LOCKS-PER-FILE
  • TEST-CHAR
  • MAX-FILES
  • MAX-LOCKS
  • WINDOW-TITLE

The run time uses the following higher default values for the LOCKS-PER-FILE, MAX-FILES , and MAX-FILES variables when --embedded-config-file is specified:

  • 256 LOCKS-PER-FILE
  • 255 MAX-FILES
  • 512 MAX-LOCKS
-f This option ensures that the run time 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 run time to suppress warning messages that are normally displayed in a message box. If the run time 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.
-g This option causes the error file (specified after the -e option) to be compressed with the gzip compression method. A compressed file must be decompressed with gzip before reading or editing. For clarity, give the error file a .gz extension. When appending to an existing file (with the +e option), you must use the same format (compressed or uncompressed) in which the file was originally created.
-h This option causes the run time 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.When using -i, add the following to your cblconfig file:

KEYSTROKE TERMINATE=10 ^J

This option has no effect on Windows platforms.

-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 run time executable. This option is used to import graphical screens created with ACUCOBOL-GT Version 3.x or AcuScreens so that these screens can be used with the AcuBench Screen Designer. If you are running with this option, simply right-click any window to have the opportunity to add it to the file import.out. See the AcuBench documentation for details.

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 run time 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.

See W$KEYBUF, for more information. Remote name notation is not allowed for this option. Use this as an alternative to -i in Windows systems.

-l Prints the run time configuration file on the error output. Prints the run time 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 Run time Configuration for more information. This is best used with the -e option to capture the debugging information in a file.
-m value file Turns on memory handling descriptions. These descriptions report detailed information about memory allocation, reallocation, and frees. See Memory Handling Descriptions for more information.
--no-acusw Inhibits the processing of the ACUSW environment variable.
--no-save-debug This option prevents the debugger from:
  • Reading the .adb file, thus causing the debugger to start in its default state.
  • 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.

--no-signal-handlers This switch allows you to initialize the run time without installing its signal handlers. This option is designed for use in environments like CICS that call the ACUCOBOL-GT run time from a C main program and want to install their own signal handlers. See acu_abend() for more information.
-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.

This option has no effect on Windows platforms.

-p Activates a built-in execution profiling facility, prompting the run time to collect information about I/O operations and CALLs, and to install a timer to track the amount of time spent in different parts of the code. Information collected by the run time is placed into an output file called acumon.xml. Use the -p0 option to include zero execution count paragraphs in the report. See The Profiler for more information.
-p0 Tells the profiler to include zero execution count paragraphs in the acumon.xml file. See The Profiler for more information.
-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 interrupts 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 closes its files if the user kills the program. This keeps each file intact but does not keep separate files synchronized with each other, which may be required by the your 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 run time detects that the output is not a terminal and so it will not set terminal attributes for the terminal. In such state, the run time 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 This option can be used only with a version of the runtime which has an addressable terminal capability. It does not work with any of the graphical run times or the Windows console run time.

--time Causes the run time, to write the total real time spent executing to its error output file upon shutdown. Use this option to measure the time it takes to execute a stand alone batch program.

Note that such real time measurements are inexact, because they do not account for time spent on other tasks or waiting for external output.

-u By default, the run time tests each use of a LINKAGE data item to check that the item passed by the calling program is at least as large as the item declared by the called program. This ensures that unallocated memory is not accidentally referenced. The -u option disables that test, as well as the test that verifies that all parameters of a subprogram were passed by the caller. (he same can be accomplished with the CHECK_USING configuration variable.
-v Displays pertinent details about the runtime, including the current version number of runcbl, the Data Execution Prevention status, the serial number, and the maximum number of users licensed to use the run time simultaneously. No program is run.
-vv (double v) Prints the current version number of runcbl, along with extended information. No program is run.
-vvv (triple v) This option is valid on UNIX systems and causes runcbl to display additional configuration information about the UNIX port. The information varies depending on the UNIX system and is subject to change without notice. No program is run.
-w This has the same effect as specifying WARNINGS 0 and MAKE-ZERO 0 in the run time configuration file. This option is provided for compatibility with previous versions of ACUCOBOL-GT. It is recommended that the corresponding configuration entries be used.
-x When a file error 30 occurs, the root cause of this error is often not apparent. Specifying -x displays 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.
--xreturn

Emits a status code if the run time fails to start properly. It may be used from the command line, but it is most useful with the acu_initv function. The code indicates the source of the failure. The possible status return values are:

  • 0 - Success
  • -1 - License has expired
  • -2 - License is not found
  • -3 - License user count exceeded
  • -4 - Library initialization failed
  • -5 - Library load failed
  • -6 - Configuration error
  • -7 - Debug initialization failed
  • -8 - File manager initialization failed
  • -9 - Memory allocation failure
  • -10 - Remote file manager initialization failed
  • -11 - Runtime initialization failed
  • -12 - Profile initialization failed
  • -13 - Mismatched version between runtime and support module
  • -14 - Exception encountered
-y Causes the run time to pre-load the -e specified ACUCOBOL-GT object library, UNIX/Linux shared object library, or Windows DLL. This option must be followed (as the next separate argument) by the name of the library to load. You can pre-load multiple libraries by specifying multiple -y options. If the library is a DLL, the C calling convention can be specified after the name. See Loading DLLs with Configuration Variables for more information.

The directory of the object module and ENTRY points contained in the library are loaded by the run time before it loads the main program. All of the object modules in the library are thus available to be called at any time. The main program may be contained in the library because the library is loaded first.

When specifying a shared object library, you can include the file suffix or use the SHARED_LIBRARY_EXTENSION configuration variable to specify the filename extension.

Note that shared libraries can also be loaded with the SHARED_LIBRARY_LIST configuration variable. You can also use the SHARED_LIBRARY_PREFIX configuration variable to specify a set of directories that the runtime will search when attempting to locate a shared library. For more information on these variables, see their entries in Configuration Variables.

Libraries loaded with the -y option remain in memory until the process exits. The CANCEL statement cannot be used to unload the library.

ACUCOBOL-GT object libraries are described in more detail in Object File Utility - cblutil Windows DLLs and UNIX shared libraries are described in Working with Windows Technologies and Working with C and C++ Programs.

Remote name notation is allowed. See Remote Name Notation.

Note: -y does not load client-side DLLs for thin client applications that make calls using the CALL verb @[DISPLAY]: syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL.
-z After an unexpected run time termination resulting from a memory access violation, this option causes the program to output the current contents of memory where the violation occurred.