Runtime Options

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.

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

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.

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.

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

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.

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.

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.

• 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.

This option has no effect on Windows platforms.

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.

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

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

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.