The Configuration File

Many aspects of the runtime system can be controlled through runtime configuration variables. These variables can be modified by each site that uses the runtime, as well as directly by an ACUCOBOL-GT program.

Runtime configuration variables may be placed in either the runtime configuration file or the machine's environment. When placed in the machine's environment, the keywords must be all upper case and must use underscores instead of hyphens. When they are placed in the runtime configuration file, upper and lower case are equivalent, as are hyphens and underscores. Entries consist of a keyword, one or more spaces or tabs, and then one or more values. The maximum length of a configuration file value is 4095 characters.

The runtime seeks the name of the runtime configuration file in this way:

a. Looks for "-c" runtime option

b. Looks for environment variable A_CONFIG

c. Uses name from table:

System
Default runtime configuration file
MS-DOS
\etc\cblconfi
Windows
\etc\cblconfi
Windows NT/
Windows 2000
\etc\cblconfi
OS/2
\etc\cblconfi
MPE/iX
/etc/cblconfig
UNIX
/etc/cblconfig
VMS
SYS$LIBRARY:A_CONFIG.DAT

It is possible to use multiple configuration files by nesting one inside another. You can specify another file to process within the configuration file you give to the runtime with the following syntax:

!COPY filename

No processing will be done to filename (for example FILE_PREFIX is not applied) so you must specify a file that the runtime can find.

Note: You can specify remote name syntax if your runtime is an AcuServer client. Otherwise, the file must be an absolute path or a path relative to the current directory.

For example, if you have some configuration variables in a global place such as /etc/cblconfig, then individual users can execute the runtime using this configuration file instead of the usual one. The settings in the usual configuration file take effect also, because their settings are copied in with !COPY:

#Get all the standard variables
!copy /etc/cblconfig
#Now set personal settings
USE_MOUSE 1

Many runtime configuration variables may also be changed by the source program with the SET ENVIRONMENT verb. Note also that most configuration variables can be read with the ACCEPT FROM ENVIRONMENT verb. Variables that CANNOT be read with ACCEPT FROM ENVIRONMENT are marked with an asterisk (*). If the variable to be read is numeric, then the receiving field must be defined either as a numeric field or as an alphanumeric field of five or more characters. If it is defined as alphanumeric and is longer than five characters, then the value that is read from the environment will occupy the leftmost five characters of the field and the remainder will be space-filled. Keywords are:

132_MODE - This variable specifies that MS-DOS video cards for 132-column display are used. It also describes the technique used by the video card manufacturer to enter 132-column mode. Following are the settings for the cards for which we have information:

ATI Integra, VGA/Wonder, EGA/Wonder
35
ATI Prism Elite
83
Chips & Technologies chip sets
96
Genoa 6000 Series
96
Paradise Systems
85
Trident chip sets
83
Tseng Labs chip sets
35

3D_LINES - This variable has meaning only on graphical systems such as Windows. Set this variable to "1" (on, true, yes) to cause the runtime to display lines and boxes with 3-D shading. This makes the lines appear to be inscribed into the surface of the screen. The variable is especially helpful in giving a 3-D look to a program originally designed on a character system. Only black lines on a non-black background are shown with shading. Other lines are displayed normally.

The set of colors available to ACUCOBOL-GT significantly impacts how effective the shading is. Normally, the shading is most effective when the background is low-intensity white. The other low-intensity colors are next best.

The shading is only marginally effective with a high-intensity background. For this reason, the 3D_LINES setting is not used when a high-intensity background is drawn. Note that, by default, ACUCOBOL-GT shows background colors in high-intensity, so you need to use at least one other variable to arrange for a low-intensity background color. For example, the BACKGROUND_INTENSITY variable could be set to "1" to force a low-intensity background.

You may freely change the way lines are displayed in COBOL by using the SET ENVIRONMENT verb to set 3D_LINES prior to displaying a line or a box.

* Setting it to "1" gives you the 3-D effect.

* Setting it to "0" (off, false, no) gives you normal lines.

The runtime remembers which lines are drawn with 3-D, so you don't need to keep track of this yourself. Note, however, that if you attach a 3-D line to a non-3-D line, the intersection uses the 3D_LINES setting currently in effect. The default value is "0".

7_BIT - When this variable is set to "1" (on, true, yes), ACUCOBOL-GT supports 7-bit communications instead of 8-bit. This variable is designed specifically for machines that use 7-bit communications with parity enabled. When 7_BIT is set to the default of "0" (off, false, no), 8-bit communications are used.

A_LICENSE_RETRIES - This variable affects UNIX networks with multiple-user licenses for the runtime. When set to a positive, non-zero value, this entry causes the runtime to retry ("value" times) any failed attempt to register with the network license manager, acushare. The variable A_RETRY_DELAY specifies how many seconds the runtime will wait between retries.

The default value is "0" (no retries).

A_RETRY_DELAY - This variable affects UNIX networks with multiple-user licenses. If A_LICENSE_RETRIES is set to a positive integer value, then the value of A_RETRY_DELAY determines how many seconds the runtime waits between repeated attempts to register itself with the network license manager, acushare.

The default value is "10".

A_WAIT_FOR_LICENSE - This variable affects DOS and Windows networks with multiple-user licenses. If A_WAIT_FOR_LICENSE is set to "1" (on, true, yes), the runtime waits until the number of users on the network has been counted before executing the COBOL application. If the counting procedure determines that the user limit has been exceeded, the application is not executed.

A value of "0" (off, false, no) causes the application to begin running in parallel with the user counting procedure. If the user limit has been exceeded, the application is stopped at the next ACCEPT statement.

The default value is "0".

ACCEPT_TIMEOUT - This variable causes all ACCEPT statements to time out just as if there were a BEFORE TIME phrase present in the ACCEPT statement. The value assigned to ACCEPT_TIMEOUT is the timeout period, in seconds. This timeout value is applied to every ACCEPT statement that can have a BEFORE TIME phrase specified for it. If a particular ACCEPT statement has a BEFORE TIME phrase explicitly coded for it, that phrase takes precedence, and ACCEPT_TIMEOUT does not apply to that statement. The default value is "0", which indicates no timeout value.

ACTIVE_BORDER_COLOR - This variable is used on character-based hosts to specify the color and video attributes of the characters used to form the border (box) around the active floating window. ACTIVE_BORDER_ COLOR can be set to a variety of numeric values that express combinations of color and video attributes.

If ACTIVE_BORDER_COLOR is set to "0", the active window's border is drawn with the colors and video attributes specified in the COBOL program when the window is initially created. The default value is "0".

ACUCOBOL - This variable holds the full path to the ACUCOBOL-GT installation directory. For example, if the runtime is installed in C:\Acucorp\ Acucbl500\AcuGT\bin\wrun32.exe, then the configuration variable would be set to C:\Acucorp\Acucbl500\AcuGT.

This variable is used to locate extensions to the runtime.

ALFRED_BITMAP_FILE - This variable holds the path and name of the "alfred by Acucorp" bitmap.

ALFRED_. . ._BITMAP - This group of variables allows you to specify which bitmap in the bitmap file to use with a given toolbar button. The middle entry of this variable can be one of the following: INPUT, IO, PG_DN, PG_UP, PREV_REC, and NEXT_REC.

ALFRED_. . ._COLOR - This group of variables allows you to customize some of the color and video attributes that alfred uses to display select program and record elements. The middle entry of this variable can be one of the following: LABEL, ENTRY, BANNER_LABEL, BANNER_TEXT, HIGHLIGHT, DISABLED, HELP, and KEY.

ALFRED_ENTRY_FIELDS - This variable controls whether a box is placed around the entry field created for each field of a record. Note that entry fields are used only when you are editing a file that has an XFD. The default setting is BOXED, which indicates that a box is placed around all entry fields. If any other value is given, entry fields are not boxed.

ALFRED_GET_PRINTER - This variable holds the name of a COBOL program that returns information about the printer. alfred calls the named program with a single USING argument. The program should return the name of the printer to be used and the number of lines allowed per page. You must provide the COBOL program. The group item that is passed is defined in the file "alfred.ws" located in the ACUCOBOL-GT installation subdirectory "tools".

ALFRED_MESSAGE_FILE - This variable points to the full path name of the file containing the error messages and help messages for alfred. alfred is a record-level editor for use with indexed files.

The default value is "alfred.msg".

ALFRED_PRINT_HEADER_n - This group of variables is used to configure up to nine print headers (n = 1-9).

ALFRED_PRINTER_NAME - This variable holds the name of the printer to use. Its value is used if ALFRED_GET_PRINTER (described above) is undefined or does not return a valid printer name. Note that if ALFRED_GET_PRINTER doesn't return a printer name and this variable is undefined, alfred attempts to use "-P SPOOLER".

ALFRED_TOOLS_FILE - This variable holds the path and name of the bitmap file to use with the alfred toolbar. It is predefined to point to the standard toolbar bitmap file in ".. \tools\alftools.bmp". If you want to substitute your own toolbar icons, simply redefine this variable to hold the path and name of your bitmap file. The file must contain at least six bitmaps. If this variable is blank, or if alfred can't open the named file, or it doesn't contain bitmap data, the toolbar uses text buttons.

APPLY_CODE_PATH - When set to "1" (on, true, yes), this variable causes the CODE_PREFIX variable to be applied to object files with full path names (those beginning with a "/", forward slash). Otherwise, CODE_PREFIX is not applied to files with full path names. For example, if your application specifies the file:

/accounting/objects/payroll
and your CODE_PREFIX variable is set to:
CODE_PREFIX /master_obj
and APPLY_CODE_PATH is set to on, the runtime looks for your file in:
/master_obj/accounting/objects/payroll

The default value of APPLY_CODE_PATH is "0" (off, false, no).

APPLY_FILE_PATH - When set to "1" (on, true, yes), this variable causes the FILE_PREFIX variable to be applied to data files with full path names (those beginning with "/", forward slash). Otherwise, FILE_PREFIX is not applied to files with full path names. For example, if your application specifies the file:

/accounting/data/ind.dat
and your FILE_PREFIX variable is set to:
FILE_PREFIX /master_data
and APPLY_FILE_PATH is set to "on", the runtime looks for your file in:
/master_data/accounting/data/ind.dat

The default value of APPLY_FILE_PATH is "0" (off).

AUTO_BUFFER - This variable affects only non-networked, single-tasking machines (such as non-networked MS-DOS machines). When set to a non-zero value, this entry causes all disk I/O to be buffered (similar to MASS_UPDATE). In addition, to ensure that files are not easily corrupted by power failures, all disk buffers are flushed whenever one of these two conditions is met:

* A Format 1 or Format 2 ACCEPT statement executes.
* The count of file update operations (WRITE, REWRITE, DELETE) equal the value specified for AUTO_BUFFER.

The default value is "50".

AUTO_DECIMAL - When set to "1" (on, true, yes), this variable checks the data item descriptions of numeric entry fields with a decimal point for the number of digits that must be filled to the right of the decimal point. When all the digits after the decimal point are entered, the field will terminate if the AUTO_TERMINATE phrase is specified. The number of digits to the right of the decimal point can vary, depending on how many are indicated in the picture of each numeric entry field. You must specify AUTO_TERMINATE phrase for this feature to work.

The exception to this is when an entry field has an AUTO_DECIMAL property specified, in which case, the coded value will be used.

The default value of this variable is "0" (off, false, no).

AUTO_PROMPT - When set to "1" (on, true, yes), this variable causes all ACCEPT statements without a PROMPT clause to be treated as if they had a PROMPT SPACES clause. This causes the screen to be erased at the field position prior to the data's being entered. This variable is provided for compatibility with ACUCOBOL-85 Version 1.3 and earlier, which behaved this way. The default setting is "0" (off, false, no).

BACKGROUND_INTENSITY - This variable is used to choose a background intensity. Use one of these values:

0 The runtime uses the default intensity, which is based on your hardware and operating environment. Under MS-DOS, the default background intensity is low-intensity. Under Windows, the default background intensity is high-intensity.

1 The runtime uses low-intensity.

2 The runtime uses high-intensity.

There are two important exceptions:

* The runtime always assigns low-intensity to the background if the background color is black. Using high-intensity would cause the background to be dark gray, which tends to make the screen look muddy.

* Many devices do not support a background intensity independent from the foreground intensity (most terminals for example). If this is the case the runtime declares the background intensity to be low-intensity.

The default value is "0".

BELL - When set to "0" (off, false, no), this variable inhibits all bells generated by ACCEPT and DISPLAY statements. Note that this overrides explicit WITH BELL clauses as well as implicit bells. The default setting is "1" (on, true, yes).

BOXED_FLOATING_WINDOWS - When this variable is set to "1" (on, true, yes) all floating windows displayed on character-based hosts are drawn with a border (box). If this variable is set to "0" (off, false, no), floating windows are drawn with a border only when the BOXED phrase appears in the statement that creates the window. This variable has an effect only on character-based host systems. The default value is "0" (off, false, no).

BTRV_MASS_UPDATE - When this variable is set to "1" (on, true, yes), a Btrieve file is opened in exclusive mode. No other processes may open the file at the same time. When this variable is set to "0" (off, false, no), a Btrieve file is opened in accelerated mode, and other processes may open the file.

BUFFERED_SCREEN - This variable controls how the Terminal Manager should buffer its output on UNIX systems. Normally, all queued output is sent to the screen after each DISPLAY statement. If this value is set to "1" (on, true, yes), then output is sent only when the internal buffer is full, an ACCEPT statement is executed, or an internal 1-second timer expires. This can speed up output on some systems by reducing the number of times the operating system is called. It also causes a short delay before messages are seen. We recommend keeping this setting at the default "0" (off, false, no) unless you are experiencing poor screen performance.

CANCEL_ALL_DLLS - The CANCEL_ALL_DLLS configuration variable is used to change the default behavior of a CANCEL ALL statement. The default behavior is for CANCEL ALL to free all DLLs loaded with a prior CALL statement. Setting CANCEL_ALL_DLLS to "0" (off, false, no) indicates that CANCEL ALL should not free any DLLs. If you want to free a particular DLL when CANCEL_ALL_DLLS is set to "0", you must specify the DLL's name in a CANCEL statement.

The default value of CANCEL_ALL_DLLS is "1" (on, true, yes).

CARRIAGE_CONTROL_FILTER - The value of this variable affects how carriage-control characters are treated when found in LINE SEQUENTIAL data files.

RM/COBOL version 2 handles carriage-control characters in a line sequential file differently on different systems. By default, both ACUCOBOL-GT and RM/COBOL-85 remove carriage-control characters from input records for line sequential files. This is the ANSI standard. RM/COBOL version 2, however, does not remove form-feed characters on MS-DOS machines and does not remove form-feed or carriage-return characters on UNIX systems. Some existing RM/COBOL version 2 programs depend on this behavior.

You can retain any or all of these characters in the input record by setting CARRIAGE_CONTROL_FILTER to a value as follows:

1 form-feed characters are retained

2 carriage-return characters are retained

4 line-feed characters are retained

You can specify two or three characters to be retained by adding the appropriate values together. For example, a value of 6 retains carriage-returns and line-feeds (2 plus 4). Setting the variable to "0" causes the default action of removing all three characters.

Note that on VMS systems, carriage-control information is not placed directly into data records and is instead maintained separately. For this reason, the CARRIAGE_CONTROL_FILTER setting has no effect on VMS systems and should not be considered portable to those machines.

The default value is "0".

CGI_AUTO_HEADER - This variable is used to suppress the output of an HTML header for a program written as a Common Gateway Interface program. Set the variable to "0" (off, false, no) to suppress the output of the HTML header. The default value is "1" (on, true, yes).

CGI_NO_CACHE - This variable allows you to choose whether the HTML output of a Common Gateway Interface (CGI) program will be cached by the requesting client. The default value is "1" (on, true, yes), which means there is no caching.

CGI_STRIP_CR - When this variable is set to "1" (on, true, yes), the runtime automatically removes carriage return characters from data entered in HTML TEXTAREAS (multiple line entry-fields). Stripping the carriage returns from this kind of input prevents double-spacing problems, as well as conflicts that may arise if the data is used in a context that does not expect a carriage return character to precede each line feed character. Some browsers send a carriage return line feed sequence to the CGI program, and when this sequence is written to a file on operating systems that terminate text lines with line feed characters only, the file may appear to be double spaced. The default value is "0" (off, false, no).

For example, if you enter the following three lines in a TEXTAREA for a field called "thetext":

Sometext line 1
Sometext line 2
Sometext line 3

The browser sends the following to the CGI program:

thetext=Sometext+line+1%0D%0ASometext+line+2%0D%0ASometext+line+3%0D%0A

If the CGI_STRIP_CR is set to "1" (on, true, yes), the runtime strips the carriage return characters so that the input line is the following:

thetext=Sometext+line+1%0ASometext+line+2%0ASometext+line+3%0A

CHAIN_MENUS - When this variable is set to "1" (on, true, yes), the runtime system automatically destroys any menu displayed by a program performing a CHAIN or CALL PROGRAM. The menu is not actually destroyed until the chained-to program displays a new menu. Setting this variable to "0" (off, false, no) inhibits the destruction of the menu. The default value is "off".

CHECK_USING - When this value is "1" (on, true, yes), the runtime system tests each use of a LINKAGE data item to make sure 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. Setting this value to "0" (off, false, no) inhibits this check. The default value is "1". If you set this value to "0", you should test your programs carefully, because you may get memory corruption.

C-ISAM_COMPRESS_KEYS - This variable allows you to turn off key compression in C-ISAM files. By default, the ACUCOBOL-GT interface to C-ISAM uses the key compression feature of C-ISAM. But some C-ISAM emulators do not understand the compressed keys and cannot read the files created. This variable allows you to turn off the compression.

When the variable is set to "0", key compression is not used. When it's set to "1" (the default), key compression is used. Note that this value is examined each time a file is created, so its setting can be changed for each file. The setting is meaningful only when the file is created. After that, the file retains its compression mode.

CLOSE_ON_EXIT - When set to "1" (on, true, yes), this variable enables the automatic closing of all files except print files when a program performs an EXIT PROGRAM statement. When set to "2" it enables the automatic closing of all files when a program exits. When set to "0" (off, false, no) no files will be automatically closed. The default value is "0".

CODE_CASE - This variable allows you to adjust the case of object file names. It has three possible values:

0 (the default) object file names are not translated

1 object file names are translated to lower case

2 object file names are translated to upper case

Translation occurs before the CODE_SUFFIX and CODE_PREFIX configuration options are applied. Be sure that these options specify the correct case.

CODE_MAPPING - This variable allows you to modify CALL, CHAIN, and CANCEL names at runtime. This can be particularly useful if you are using AcuServer^TM or AcuConnect^TM. When this variable is set to "1" (on, true, yes), every CALL, CHAIN, and CANCEL statement checks the current configuration for a name that matches the CALL name. This is handled in the same way that file name processing is done (the environment is checked for an uppercase version of the name, with any hyphens treated as underscores). If a matching name is found, its value is substituted. This is done recursively until no more matching names are found.

After this substitution occurs, the CALL name handling proceeds normally (and includes any effects of CODE_PATH, CODE_SUFFIX, and CODE_CASE).

The default value for this variable is "0" (off, false, no).

CODE_PREFIX - This variable defines a series of directories to be searched for program object files. The value "." is the default.

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. For example:

CODE_PREFIX  C:\"program files"

Remote name notation is allowed for this variable if your runtime is client-enabled.

Up to 4096 characters can be specified for the value of this variable.

CODE_SUFFIX - The value of this variable is automatically appended to the end of program file names when those names do not contain explicit suffixes. A suffix is the portion of a file name that follows a period. For example, if CODE_SUFFIX were set to "COB", then CALL "PGMFILE" would look for a program called "PGMFILE.COB". If you do not set this variable, the runtime will try appending a suffix of ".acu" and then will try a blank suffix. The default value is empty.

CODE_SYSTEM* - The runtime configuration variable CODE_SYSTEM tells the runtime if double-byte character data is being accepted or displayed, and which code system (that is, which standard for encoding Japanese and other Asian character sets, for example is being used. Each code system has a range of values that it allows within each byte of a two-byte character, so identifying the code system allows the runtime to recognize character boundaries when it is processing double-byte data for ACCEPT and DISPLAY statements.

Setting CODE_SYSTEM to the proper value allows your COBOL applications to handle input and display of double-byte character data without source program changes. The syntax is:

CODE_SYSTEM  setting

The table below shows the possible settings of the CODE_SYSTEM variable, the code system to which each setting refers, and some examples of operating systems to which the particular code system applies:

Setting Code System Op. System Examples

BIG5
Big Five (Taiwan)

Chinese DOS,
Windows
DBC
Acucorp Generic
Double-byte Coding
Scheme

Other double-byte
machines
EUC
Extended UNIX

Most UNIX machines
GB
Code of Chinese
Graphic Character
Set (People's
Republic of
China)

Chinese DOS,
Windows
KSC
Korean Character
Standard

Korean DOS
SJC
Shift JIS Code
(Japanese Industrial
Standard)
DOS/V, Windows,
some UNIX machines

The default "0" means ASCII or EBCDIC single-byte characters.

The following table shows the decimal values that the respective code systems allow for each byte of the two-byte character:

Code System Setting 1st byte 2nd byte

BIG5
161 - 254
64 - 126
(second format)
161 - 254
161 - 254
DBC
128 - 255
128 - 255
EUC
142
161-223
(second format)
161 - 254
161 - 254
GB and KSC
161- 254
161 - 254
SJC
129 - 159
64 - 252 (not 127)
(second format)
224 - 239
64 - 252 (not 127)

Note that the first and second byte values are co-dependent; that is, both values must fall within the respective ranges shown in the table. If either value is not within its allowable range, then each byte will be treated as a single character.

COLOR_MAP* - This variable can be used to assign colors to programs that do not contain explicit color settings. The default value is empty. (See the Adding Color section of this manual for more information.)

COLOR_MODEL* - This variable is typically used when a character-based application is moved to a graphical environment. Use the COLOR_MODEL setting to perform uniform changes to your program's color scheme. These changes are represented by rules that act on your colors. An example of a rule is "exchange the foreground and background colors". Use COLOR_MODEL to change your color scheme in a global way.

The default color model is model "0". It causes no changes to occur to your color scheme. The remaining 10 models are "1" through "10"

* The odd-numbered models transform only those parts of your program that are entirely black and white. Any character position that contains any color is left unchanged.

* The even-numbered models apply the changes regardless of color. When selecting a COLOR_MODEL, you can ignore the even-numbered models if you are satisfied with the color portions of your program.

Each color model is actually a composite; it's the equivalent of two or more runtime configuration variable settings:

* COLOR_MODEL "1" is equivalent to:
COLOR_TRANS "5", INTENSITY_FLAGS "34", and BACKGROUND_INTENSITY "1".

* COLOR_MODEL "2" is equivalent to:
COLOR_TRANS "4", INTENSITY_FLAGS "34", and BACKGROUND_INTENSITY "1".

* COLOR_MODEL "3" is equivalent to:
COLOR_TRANS "3" and INTENSITY_FLAGS "34".

* COLOR_MODEL "4" is equivalent to:
COLOR_TRANS "1" and INTENSITY_FLAGS "34".

* COLOR_MODEL "5" is equivalent to:
COLOR_TRANS "1" and INTENSITY_FLAGS "129".

* COLOR_MODEL "6" is equivalent to:
COLOR_TRANS "1", INTENSITY_FLAGS "129", and BACKGROUND_INTENSITY "2".

* COLOR_MODEL "7" is equivalent to:
COLOR_TRANS "3" and INTENSITY_FLAGS "161".

* COLOR_MODEL "8" is equivalent to:
COLOR_TRANS "1" and INTENSITY_FLAGS "161".

* COLOR_MODEL "9" is equivalent to:
COLOR_TRANS "3" and INTENSITY_FLAGS "193".

* COLOR_MODEL "10" is equivalent to:
COLOR_TRANS "1" and INTENSITY_FLAGS "193".

COLOR_TABLE* - This variable is typically used when a character-based application is moved to a graphical environment. Use the COLOR_TABLE variable to cause transformations of individual color combinations. For example, a COLOR_TABLE entry might cause a red foreground on a black background to be translated to a white foreground on a blue background.

Follow the word COLOR_TABLE with the original foreground and background numbers, separated by a comma. Follow these by an equal sign and then the new foreground and background numbers, again separated by a comma.

For example, to transform the color combination of foreground 5 on background 2 to foreground 13 on background 2, you would use:

COLOR_TABLE   5, 2 = 13, 2

Foreground and Background Settings

1 low-intensity Black

2 low-intensity Blue

3 low-intensity Green

4 low-intensity Cyan

5 low-intensity Red

6 low-intensity Magenta

7 low-intensity Brown

8 low-intensity White

9 high-intensity Black

10 high-intensity Blue

11 high-intensity Green

12 high-intensity Cyan

13 high-intensity Red

14 high-intensity Magenta

15 high-intensity Brown

16 high-intensity White

COLOR_TRANS - This variable is typically used when a character-based application is moved to a graphical environment. It determines how the initial colors in an application are transformed. By default, it is set to "0", which causes no transformation. It may be set to any of these values:

1 This mode causes the foreground and background colors to be exchanged for each other. This is equivalent to running the entire program in reverse-video.

2 This causes white to be exchanged for black and black to be exchanged for white. The foreground and background colors are transformed independently. For example, a green foreground on a black background would turn into a green foreground on a white background. This setting usually has the effect of transforming a black background into white while maintaining the general color scheme of the application.

3 The foreground and background colors are exchanged for each other, but only if they are either black or white. If either the foreground or background contains a color other than black or white, then nothing happens. This is equivalent to running the monochrome parts of your program in reverse-video while maintaining the color portions unchanged.

4 The foreground and background colors are exchanged for each other, but only if the background is black. This mode ensures that you never have a black background.

5 If the colors are foreground white and background black, they are exchanged for each other. Otherwise, nothing happens.

Note that if your application is entirely black-and-white, then the first three COLOR_TRANS options are essentially identical.

COLUMN_SEPARATION - This variable sets the default separation distance between columns in a list box. The value is expressed in 10ths of characters. For example, to place a ½ character space between list box columns, you would assign a value of "5". The default value of COLUMN_SEPARATION is "5".

COMPRESS_FACTOR - This is the file compression factor, from "0" (no compression) to "100" (maximum compression). Values 2-100 are treated as percentages. They specify how much of the space saved by file compression is to be deleted from the compressed records. A factor of "1" is a special case - it gives the default, which causes 70% of the space saved by compression to be deleted from each record. Compression is established only at the time the file is created.

COMPRESS_FILES - Setting this variable to "1" (on, true, yes) causes ACUCOBOL-GT to treat all indexed files as if they had the WITH COMPRESSION phrase specified for them. This affects the status of newly created files only. When the variable is set to the default value of "0" (off, false, no), only those files with the COMPRESSION phrase specified are compressed. You can specify the amount of compression with COMPRESS_FACTOR.

CURRENCY - This variable can be used to set the desired currency character at runtime. It is followed with the desired character. The default is to use the character specified in the source program's CURRENCY phrase (or "$" if the CURRENCY phrase is absent).

CURSOR_MODE - This variable determines when the cursor should be visible. It has three values:

1 always visible

2 always invisible

3 invisible except during ACCEPT statements, then visible

The default value is "3". Note that a change to the value does not take effect until the next ACCEPT or DISPLAY statement. The sample program menubar.cbl contains examples of how to modify the cursor from within a program. The cursor is always set to Normal, Visible when the runtime exits or when the SYSTEM library routine is called.

CURSOR_TYPE - This variable determines the way the cursor looks. It can be set to one of the following values ("3" is the default):

1 normal cursor (usually underscore)

2 bright cursor (usually block)

3 normal cursor except when in insert mode, then bright

4 vertical bar (when available)

DECIMAL_POINT - This variable sets the character to be used as the program's decimal point. Follow it with the desired character. If you use this variable to set the decimal point to a comma, then the place and function of the decimal point and comma are reversed (just like the phrase DECIMAL_POINT IS COMMA). The default is to use the decimal point specified by the program's source.

DEFAULT_FONT - This variable defines which font to use for the "DEFAULT_FONT". When DEFAULT_FONT is set to "0" (the normal setting), the font used depends on the host system as follows:

System Font Used

Graphical MEDIUM-FONT
Non-graphical FIXED-FONT

System	Font Used
Graphical	MEDIUM-FONT
Non-graphical	FIXED-FONT

You can set DEFAULT_FONT to one of the following values to use a different font. The following words are valid settings:

System Font Used

TRADITIONAL TRADITIONAL-FONT

FIXED FIXED-FONT
LARGE LARGE-FONT
MEDIUM MEDIUM-FONT

SMALL SMALL-FONT

System	Font Used
TRADITIONAL	TRADITIONAL-FONT
FIXED	FIXED-FONT
LARGE	LARGE-FONT
MEDIUM	MEDIUM-FONT
SMALL	SMALL-FONT

Due to the way the runtime initializes the windowing subsystem, the DEFAULT_FONT setting is effective only when it is placed in the configuration file or the host system's environment. Setting DEFAULT_FONT from inside a COBOL program has no effect.

DEFAULT_HOST - If the application program is opening an existing file or creating a new file, you need to tell the runtime which file system to use. You accomplish this with one of two configuration variables: DEFAULT_HOST or filename_HOST.

DEFAULT_HOST filesystem

designates the file system to be used for files that are not individually assigned. If this variable is not given a value, and if you have not individually assigned a file system (with filename_HOST), then the Vision file system is used.

DEFAULT_MAP_FILE - Use this variable to point to the character map file used for translating international character sets between machines that use differing character codes. The map file is a simple text file that you create with an editor of your choice. Each line in the map file must contain two values in either decimal or hexadecimal: the character code of the character on the client machine, and the character code of the same character on the remote machine. Use a # sign to indicate a comment.

The runtime first searches for the configuration variable server_MAP_FILE and, if it is found, uses that setting to locate the map file. If that variable is not set, the runtime searches for DEFAULT_MAP_FILE. If this variable is not set, then no character translation is done. Example:

DEFAULT_MAP_FILE= c:\etc\pc_iso.txt

DEFAULT_PROGRAM - Use this variable to specify the name of the program to be run by default if no program name is specified on the command line. The name you give here is treated exactly as it would be if you had typed it on the command line. The default is "cbl.out".

Remote name notation is allowed for this variable if your runtime is client-enabled.

DEFAULT_TIMEOUT - This variable is used by the runtime and plug-in to define the length of time, in seconds, that the runtime or plug-in will wait for a response from acuserve before timing out. The default value for this variable is 25 seconds. Some networks have long connect times and the default value may not be long enough to allow the application to connect. For example, to change the timeout default of 25 seconds to one minute, you would set the following:

DEFAULT_TIMEOUT = 60

If the runtime or plug-in receives an error before the specified time, the runtime or plug-in will time out immediately. This variable only works with AcuServer client runtimes and AcuServer client plug-ins.

DISABLED_CONTROL_COLOR - This variable allows character-based hosts to use color and video attributes to distinguish disabled screen controls from enabled controls. It can be set to a variety of numeric values that express combinations of attributes. When it is set to "0" (off, false, no), disabled controls appear the same as enabled ones.

DISPLAY_SWITCH_PERIOD - This variable helps to determine how frequently the program's threads switch control. After a thread performs the value of DISPLAY_SWITCH_PERIOD display operations, the runtime switches control to another thread (if one exists). Note that because a single DISPLAY statement can compile into multiple "display operations," and because thread switching is also affected by other program operations (such as file I/O), it is impossible to predict or control when a thread will change control based on the presence of DISPLAY statements in the source.

By setting DISPLAY_SWITCH_PERIOD to lower values, windows that are updated by multiple threads update more uniformly, but more time is spent in the thread switching code. Setting DISPLAY_SWITCH_PERIOD to higher values decreases the switching overhead, but also causes the windows to update in blocks. In most cases, applications that use threads run well with the default setting of "5".

DLL_CONVENTION - This variable allows you to specify the calling convention used to call a DLL. When this variable is set to "0", the standard C interface is used for calling DLLs. When this variable is set to "1", then the Pascal interface is used. The default for this variable is "1".

DLL_SUB_INTERFACE - This variable identifies the routine to be used as the "sub" interface routine within a DLL. It applies only to Windows systems. Set DLL_SUB_INTERFACE to the name of the routine you want to use. This name may be "sub" or any name you choose. The runtime checks DLL_SUB_INTERFACE when a DLL is loaded. You may change its value afterwards without any effect on DLLs that have already been loaded.

If DLL_SUB_INTERFACE is blank (default), then the runtime does not look for a "sub" interface routine in a called DLL.

DOS_BOX_CHARS* - This variable allows you to redefine the line drawing characters on DOS systems. The value of the DOS_BOX_CHARS variable is a list of characters that draw the line segments. It should be a thirteen-character string that corresponds, in order, to the line segments as listed below. To redefine the DOS line drawing characters, specify the characters you want in the following order:

1. horizontal line

2. vertical line

3. upper left corner

4. upper right corner

5. lower left corner

6. lower right corner

Four three-way intersections--

7. missing bottom line

8. missing left line

9. missing top line

10. missing right line,

and--

11. the four-way intersection

12. upper-half block

13. lower-half block

These line drawing characters may also be specified by decimal value. Characters which are not available on a particular machine should be specified with the decimal value "0".

The default value for DOS_BOX_CHARS depends on the CODE_SYSTEM variable. If CODE_SYSTEM is not set, or is set to "0" (or ASCII or EBCDIC), then the default is:

DOS_BOX_CHARS 196 179 218 191 192 217 193 195 194 180 197 223 220

If CODE_SYSTEM is set to a non-zero value, which is the case in the ACUCOBOL-GT JPN version, then the default is:

DOS_BOX_CHARS 6 5 1 2 3 4 21 25 22 23 16 0 0

DOS_OUTPUT_METHOD - This variable has meaning only on MS-DOS systems. It controls the method the runtime uses to display screen output.

Set this variable to "0" or "HARDWARE" to cause the MS-DOS runtime to display screen output by directly accessing the video hardware. This is the default unless the CODE_SYSTEM variable has a non-zero value.

Set this variable to "1" or "BIOS" to cause the MS-DOS runtime to perform screen output by calling the machine's BIOS. This is useful in cases where you want to "trap" the output with some program that can examine the calls to the BIOS.

If you set the CODE_SYSTEM variable to anything other than ASCII (value "0"), then the BIOS method is used automatically. This ensures that double-byte character sets are handled correctly.

You can also use this option to turn off the optimization of screen output. The extended MS-DOS runtime sends characters to the screen only if they differ (or their attributes differ) from characters that are already on the screen. To turn off this screen optimization, set DOS_OUTPUT_METHOD to "2" or "HARDWARE-NO-OPTIMIZE" for the HARDWARE method without optimization, or set it to "3" or "BIOS-NO-OPTIMIZE" for the BIOS method without optimization. The default method is "0" (HARDWARE with optimization).

DOS_WATCOM_10 - This variable has meaning only on Extended MS-DOS systems. It controls how the C clock ( ) function returns values when used with the Watcom C compiler, Version 10.0. Versions prior to ACUCOBOL-GT 5.0, use the Watcom C compiler, Version 10.0, rather than Watcom C Version 11.0. With Version 10.0, the C clock ( ) function returns values based on a different clock rate than Version 11.0. If you re-link the runtime with the earlier version of the Watcom C compiler, this can affect the way ACCEPT statements time out.

When the DOS_WATCOM_10 variable is used, the runtime attempts to work around this difference. Set the variable to "1" (on, true, yes). The default is "0" (off, false, no).

DOUBLE_CLICK_TIME - This variable has meaning only on systems that support a mouse. It controls the "double-click" rate on systems that do not control it themselves, such as MS-DOS.

Specify the maximum time (in hundredths of a second) allowed between two clicks that are to be interpreted as a double-click. For example, if DOUBLE_CLICK_TIME were set to "75" (three-quarters of a second), then any two clicks that occur at least that close together would be considered a double-click rather than two single clicks. The default value is "50" (one-half of a second).

DUPLICATES_LOG - This variable is used during bulk addition of Vision files. It causes Vision to write files rejected for having illegal duplicate keys to a log file. Set DUPLICATES_LOG to the name of a file in which to store the records. If this log file already exists, it will be overwritten. You must use a separate log file for each file opened with bulk addition. You can do this by changing the setting of DUPLICATES_LOG between OPEN statements, as follows:

SET ENVIRONMENT "DUPLICATES_LOG" TO "file1.rej"
OPEN OUTPUT FILE-1 FOR BULK-ADDITION

SET ENVIRONMENT "DUPLICATES_LOG" TO "file2.rej"
OPEN EXTEND FILE-2 FOR BULK-ADDITION

If no duplicate records are found, the log file is removed when the Vision file is closed. If DUPLICATES_LOG has not been set, or is set to spaces, then no log file is created.

Note that the duplicate-key log file may not be placed on a remote machine using AcuServer. The log file must be directly accessible by the machine that is running the program.

EDIT_MODE - This is an obsolete entry that has been replaced by the KEYSTROKE variable. Its setting is ignored.

EF_UPPER_WIDE - This variable determines which font measure is used to compute the width of an entry field with the UPPER style. If the value is "1" (on, true, yes), the entry field is sized with the wide font measure. The default value is "1".

EF_WIDE_SIZE - This variable sets the boundary size that determines whether an entry field is sized with the standard or wide font measure. An entry field that has a specified width greater than the value of EF_WIDE_SIZE is always sized with the standard font measure. Entry fields that are both non-numeric and not larger than EF_WIDE_SIZE are sized with the wide font measure. The default value is "5". Setting this variable to "0" causes all entry fields to be sized with the standard font measure (exception: see EF_UPPER_WIDE above). Note that setting the value of this variable to a number larger than your largest entry field causes all entry fields to use the wide font measure.

EOF_ABORTS - This variable is helpful if you are using the "-i" runtime flag and are experiencing looping when an input file terminates prematurely. Set this variable to "1" (on, true, yes) if you want the runtime to shut down when an ACCEPT statement detects an end-of-file condition. The default setting of "0" (off, false, no) causes the ACCEPT statement to handle the end-of-file condition normally.

EOL_CHAR - This variable determines the character that is used to mark the end of each line when a pre-existing line sequential file is read. This should be set to the ASCII value of the desired character. The default value is "10" (line-feed). This option may be useful if you must process a line-oriented file that has an unusual line terminator. This variable has no effect under VMS (RMS does not support it).

ERRORS_OK - Normally, the runtime system prints a message and halts if a file error occurs and there is no AT END, INVALID KEY, or Declarative statement to handle it. By setting this value to "1" (on, true, yes), you cause the runtime to continue as if no error occurred. The default value is "0" (off, false, no). In general, use of the ERRORS_OK variable is not recommended.

EXIT_CURSOR - When a STOP RUN is executed, the ACUCOBOL-GT runtime system normally places the cursor on the last line of the screen and then scrolls the screen one line. This allows the operating system prompt to appear on a new blank line at the bottom of the screen. To inhibit this behavior, set EXIT_CURSOR to "0" (off, false, no). This causes the runtime system to leave the cursor in its current location when the program exits. The default value "1" (on, true, yes) causes the standard ACUCOBOL-GT cursor positioning.

This variable has no effect on Windows systems.

EXTEND_CREATES - Setting this variable to "1" (on, true, yes), causes OPEN EXTEND statements to create a new file when the file being opened is not present. The default value is "0" (off, false, no).

EXTERNAL_SIZE - ACUCOBOL-GT manages external data items by allocating them in "pools". The minimum size of each pool is set by the EXTERNAL_SIZE variable. When a new external data item is needed, it is allocated from an existing pool. If it doesn't fit in any of the allocated pools, a new pool is allocated. The size of this pool is the same as the size of the data item, but never smaller than the value specified by the EXTERNAL_SIZE variable. Using this larger pool reduces memory fragmentation. Because external data items remain allocated after programs are canceled, it's best to allocate the external data items together so they don't break up the memory space. The default value for EXTERNAL_SIZE is "4096". The maximum value is "32767".

EXTRA_KEYS_OK - This variable allows you to open an indexed file without specifying all of that file's alternate keys. When it is set to "1" (on, true, yes), you may open an indexed file that contains more keys than are described by your program, and no file error occurs. However, you still receive a file error if you open a file that does not contain all of the keys described in your program. EXTRA_KEYS_OK is useful when you are adding new alternate keys to an existing file because you do not need to rework your existing programs.

This variable is ignored if you:

a.) use a Version 1.4 or earlier ACUCOBOL-GT object file; or

b.) use the Data General MINISAM file system.

The default value is "0" (off, false, no)

F10_IS_MENU - By convention, the F10 key is used by Windows and Windows NT to activate program menus. This action is controlled automatically by the program. The F10_IS_MENU configuration variable allows you to set the runtime to handle the F10 key as a user defined key. The default setting is "1" (on, true, yes). When you change the setting to "0" (off, false, no) you inhibit the menu activation capability. The mouse continues, however, to work with the menu.

FAST_ESCAPE - This variable determines how long the runtime waits after receiving an escape key before deciding that the key is actually intended as an escape key, and not as the start of a function key sequence. (Increasing the number causes the runtime to wait longer.) The default setting varies with the machine. It is generally between 20 and 100.

This variable has no effect on MS-DOS or Windows systems.

FIELDS_UNBOXED - On most GUI systems, including Microsoft Windows, entry fields are boxed by default. This can cause problems when you are converting applications that have fairly full screen displays, because the box adds roughly 50% to the height of the field. This can make it difficult to fit all the existing fields onto the user's screen.

FIELDS_UNBOXED provides a global method of removing boxes on entry fields. If this field is set to "1" (yes, true, on), the system does not display a box around entry fields. Technically this has three effects:

1. If it is set when the entry field is initially created, the NO-BOX property is automatically implied.

2. If it is set when a floating window is initially created, the window's LABEL-OFFSET property is given a default value of zero.

3. When an entry field is measured by the CELL phrase of the DISPLAY FLOATING WINDOW statement, its height is measured without the box.

On character-based systems, setting this variable to "1" (on, true, yes) eliminates the display of the left and right delimiting symbols used in the textual emulation of entry fields. (See GUI_CHARS for more information about these delimiting symbols.) Eliminating these symbols affects the location at which the entry fields are displayed on character-based systems.

The default value for this option is "0" (off).

This variable can be overridden for individual entry fields in the program with the BOXED style in the entry field definition.

FILE_CASE - This variable allows you to adjust the case of data file names. Possible values are:

0 (default) No translation of the name is done.

1 Data file names are translated to lower case.

2 Data file names are translated to upper case.

Translation occurs before the FILE_SUFFIX and FILE_PREFIX variables are applied. Be sure that these variables specify the correct case.

File name translation does not occur if the file name starts with -F, -D, or
-P.

FILE_CONDITION* - This variable can be used to alter the File Status value of an individual file status condition. We recommend that you use one of the four pre-defined file status code sets instead.

FILE_IO_PROCESSES_MESSAGES* - This variable can be used to control whether the runtime processes system messages while performing file I/O operations. When it is set to "1" (on, true, yes), the runtime processes system messages while doing file I/O operations. This was the default behavior prior to Version 3.2. Note that the processing of system messages during file I/O should only be enabled under special conditions, as described below.

To understand when it is appropriate to set this variable, it is important to be familiar with system messages and how the ACUCOBOL-GT runtime and your program respond to them. For the purposes of this discussion, system messages are the mechanism used by graphical systems, such as Windows, to communicate with your program. They are what the operating system uses to communicate user and system activity to the program. They are similar to ACUCOBOL-GT's events. Prior to Version 3.2, the runtime automatically processed system events during file operations. This allowed the user to manipulate an application window (for example, minimizing it) while file I/O operations were performed. If the application suspends the processing of system messages, the system appears to the user to be frozen.

Starting with Version 3.2, this feature was turned off by default. This is because the processing of messages outside of an ACCEPT statement can cause flaws in a program that uses multithreading or modeless windows. It also creates a state where event procedures can be called at unexpected times. In addition, the controls of the application are not actually functional, though they appear to be working to the user.

Generally speaking, setting this variable is useful only when the application does not use multithreading, modeless windows, or event procedures.

Note that the proper way to process system messages while performing other operations is to start a second thread that performs an ACCEPT statement while the main thread continues with the work. This allows the system to process messages under control of an ACCEPT, which provides a well-defined point in your program from which event procedures can be called.

FILE_PREFIX - This variable defines a series of directories to be searched for data files. The value "." is the default.

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. For example:

FILE_PREFIX  C:\"Sales Data"

Remote name notation is allowed for the FILE_PREFIX variable if your runtime is client-enabled (for indexed files, remote name notation requires the Vision file system). Up to 4096 characters can be specified for the value of this variable.

FILE_STATUS_CODES* - This variable determines which set of file status codes to use. The default value is "85".

FILE_SUFFIX - The value of this variable is automatically appended to data file names that do not contain an explicit suffix. A suffix is the portion of a file name that follows a period. For example, if FILE_SUFFIX is set to "DAT", then opening a file called "EMPFILE" would actually open the file called "EMPFILE.DAT". The default value is empty.

FILE_TRACE - This variable allows you to start file tracing without opening the debugger. Set this variable to a non-zero value to save information about all file OPENs, READs, and WRITES in the error file. This is equivalent to specifying "tf n" from the debugger (where n is an integer). The default is "0".

FILE_TRACE_FLUSH - Set this variable to "1" (on, true, yes) to flush the error file after every WRITE statement. This is equivalent to using "t flush" from the debugger. The default is "0" (off, false, no).

filename - This variable allows you to map a Vision Version 4 file to a different directory. Vision examines the name of each physical file it attempts to open to determine if the file should be mapped to a different directory. The variable used is the file's base name followed by an underscore and the file's extension, all letters in upper-case.

For example, assume you open "/usr/data/custfile.dat", and a variable "CUSTFILE_DAT" has the value "/usr2/data/custfile.dat". Vision treats this value as the actual file name to open, and "custfile.dat" ends up in the "/usr2/data" directory rather than "/usr/data".

Because the extension is included in the variable name, you can place different parts of a multi-segment file in different directories. If no name is found for a particular segment, then the segment name is used unchanged. Note that you can move parts of a file around by simply moving the segment and adding/modifying its corresponding configuration name. Name mapping is done directly by Vision (as opposed to, for example, FILE_PREFIX, which is handled by the runtime). As a result, all programs that use Vision (such as vutil and vio) use this variable when present. For programs other than the runtime, the variable must be set in the environment rather than the configuration file.

This variable is similar to the filename_VERSION variable described later.

filename_DATA_FMT - This variable specifies a format for naming the data segments of a Vision 4 file. The configuration variable starts with the file's base name followed by an underscore and the file's extension, all letters in upper case.

Suppose that the regular name of your COBOL file is "/usr1/gl.dat". The variable you would use to set the data segment naming format for this file is GL_DAT_DATA_FMT.

The variable must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and extension for each segment. Part of this pattern is a special escape sequence (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_DATA_FMT=gl%d.dat would result in data segments named /usr1/gl.dat (remember that the first data segment is not affected), /usr1/gl1.dat, /usr1/gl2.dat, and so forth.

Escape Sequence Definitions:

The %d in the value of the filename_DATA_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page ("man printf") that explains them in detail. Here are the basics:

"%d" expands into the decimal representation of the segment number.

"%x" expands into the hexadecimal representation (with lower case a-f) of the segment number.

"%X" expands into the hexadecimal representation (with upper case A-F) of the segment number.

"%o" expands into the octal representation of the segment number.

You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. "%02d" would result in "00", "01", "02", and so forth, when expanded.

To embed a literal "%" in the file name, use "%%".

The escape sequence can be positioned anywhere in the file name, including the extension.

Note that while the runtime checks for this segment naming variable in the runtime configuration file as well as in the environment, utilities such as vutil and vio check only the environment. Therefore, if you are using this variable with the runtime and vio or vutil, you must set the variable in the environment and not in the configuration file.

See filename_INDEX_FMT for details about naming the index segments. Both variables should be set to corresponding patterns.

filename_HOST - If the application program is opening an existing file or creating a new file, you need to tell the runtime which file system to use. You accomplish this with one of two configuration variables: DEFAULT_HOST or filename_HOST.

filename_HOST filesystem

assigns an individual data file to a file system. Any file so assigned uses the designated file system, and not the one specified by DEFAULT_HOST.

Substitute the base name of the file for filename. The name you substitute should not include any directory names and should not include a file extension.

filename_INDEX_FMT - This variable specifies a format for naming the index segments of a Vision Version 4 file. The configuration variable starts with the file's base name followed by an underscore and the file's extension, all letters in upper case.

Suppose that the regular name of your COBOL file is "/usr1/gl.dat". The variable you would use to set the format for naming the file's index segments is GL_DAT_INDEX_FMT.

The variable must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and how to form the extension for each segment. Part of this pattern is a special character (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_INDEX_FMT=gl%d.idx would result in index segments named /usr1/gl0.idx, /usr1/gl1.idx, /usr1/gl2.idx, and so forth.

Escape Sequence Definitions:

The %d in the value of the filename_INDEX_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page ("man printf") that explains them in detail. Here are the basics:

"%d" expands into the decimal representation of the segment number.

"%x" expands into the hexadecimal representation (with lower case a-f) of the segment number.

"%X" expands into the hexadecimal representation (with upper case A-F) of the segment number.

"%o" expands into the octal representation of the segment number.

To embed a literal "%" in the file name, use "%%".

The escape sequence can be positioned anywhere in the file name, including the extension.

See filename_DATA_FMT for details about naming the index segments. Both variables should be set to corresponding patterns.

filename_LOG - This variable specifies individual log files to be used by the transaction logging system. The format of the variable is:

filename_LOG logfilename

where filename is the base name of the data file, and logfilename is the name of the log file. filename should not include any directory names, or a file extension. logfilename can include the absolute or relative directory path ending with the name of the log file. If the log file is not found, a new file is created with the specified name. Note that logfilename can have remote name notation.

FILENAME_SPACES - When this configuration variable is set to "1" (on, true, yes), filenames may contain embedded spaces and the runtime considers the last non-space character as the end of the name. The default is "1". When this configuration variable is set to "0" (off, false, no), then filenames may not contain embedded spaces and the name terminates at the first space character. For example:

C:\temp dir\my file name

is read as:

C:\temp

This affects the behavior of the library routines that take a filename as an argument:

C$CHDIR
C$COPY
C$DELETE
C$FILEINFO
C$FULLNAME
C$MAKEDIR
C$RESOURCE
CBL_COPY_FILE
CBL_CREATE_DIR
CBL_DELETE_DIR
CBL_DELETE_FILE
I$IO
RENAME
W$BITMAP
W$KEYBUF
$WINHELP
WIN$PLAYSOUND

filename_VERSION - This configuration variable sets the file format on a file-by-file basis. The filename is replaced by the base name of the file (the file name minus directory and extension). The meaning of the variable is the same as for "V_VERSION ". This variable is useful if you want to have all your files in one format, with a few exceptions. For example, you might want to maintain most of your files in Version 3 format to conserve file handles, but have a few files in Version 4 format to take advantage of the larger file size. Note that this variable only affects the file format when it is created. You can always rebuild the file in another format later.

This variable (and the "V_VERSION" variable) is most helpful when you are using transaction management. The transaction system does not record the format of the created file if an OPEN OUTPUT is done during a transaction, because the transaction system is not tied to any particular file system. If you need to recover a transaction, then the system will recreate the OPEN OUTPUT files using the settings of the "VERSION" variables.

filesystem_DETACH - This configuration variable detaches any file system from the runtime. The syntax is:

filesystem_DETACH n

where filesystem corresponds to the first five letters of the file system name and n is a non-zero value. Examples of file systems that may be detached using this feature are:

Btrieve BTRIE_DETACH

C-ISAM C-ISAM_DETACH

DBMaker DBMAK-DETACH

Informix INFOR_DETACH

MS SQL Server MSSQL_DETACH

ODBC ODBC_DETACH

Oracle ORACL_DETACH

RMS RMS_DETACH

Sybase SYBAS_DETACH

Vision VISIO_DETACH

The file systems may be detached only when the runtime is started, not during execution. If you detach all file systems, the runtime will terminate with an error message. For example, if you detach Vision with VISIO_DETACH on a standard runtime, the runtime will terminate with this message to std err: No file system available.

This feature automatically supports new file systems added to the runtime.

FLUSH_ALL - When this variable is set to "1" (on, true, yes), files opened for MASS-UPDATE are flushed along with other files. This means that the local cache used to hold the MASS-UPDATE buffers is flushed whenever the operating system cache is flushed. When this variable is set to the default value of "0" (off, false, no), files opened for MASS-UPDATE are not flushed.

FLUSH_COUNT - This variable allows you to flush the disk buffers after a certain number of file updates has occurred. For example, if you set this variable to "10", then the buffers are flushed after every ten updates to disk files. Only indexed files are counted. When the buffers are flushed, the exact action depends on the operating system:

MS-DOS (including the Windows environment) - MS-DOS's buffers are written to disk and the file's directory information is updated. This is roughly equivalent to the action that occurs when a file is closed.

OS/2 - This variable has no effect.

UNIX - The "sync" system routine is called. This causes all of UNIX's cache to be written to disk. This operation is only scheduled - it occurs when the system finds time to do it. Because the system does this every 30 seconds anyway, probably the only reason to request a call to "sync" is if you have unreliable power.

VMS - VMS does not have a system cache, so this variable has no effect.

Windows NT/Windows 2000 - Handled the same as under MS-DOS.

Note that setting this variable to a low non-zero value improves the chances of recovering a file after a power failure, but decreases performance. If FLUSH_COUNT is set to "0", then the system buffers are flushed only when a file is closed. The default setting is "0".

FLUSH_ON_ACCEPT - This variable causes the system's buffers to be flushed whenever a Format 1 or Format 2 ACCEPT statement is executed. You turn on this variable by setting its value to "1" (on, true, yes). The default setting is "0" (off, false, no). This variable is particularly useful for MS-DOS sites that have a habit of turning off their machines. Note that this variable is not recommended for multi-user systems because of the performance penalty.

FLUSH_ON_CLOSE - This configuration variable applies only to Extended DOS and Windows systems. When this variable is set to "1" (on, true, yes), the cache buffers will be flushed to disk when the file is closed. Versions prior to 4.3.1 flushed the cache buffers for safety reasons. This, however, reduced system performance, significantly in some programs. This feature is turned "off " by default.

FLUSH_ON_COMMIT - When this variable is set to "0" (off, false, no), the COMMIT verb does not request the host operating system to flush all buffers to disk.

If flushing is prevented, COMMIT and UNLOCK ALL have the same effect. The default setting is "0" (off, false, no).

FLUSH_ON_OPEN - This variable causes the system's buffers to be flushed on the first WRITE, REWRITE, or DELETE that occurs after an indexed file is opened for I/O. The purpose of this is to update the "user count" field in the file's header to keep it accurate. When this variable is set to "1" (on, true, yes), this feature is turned on; when set to "0" (off, false, no), it's turned off. The default setting is "0" except for MS-DOS systems, where it is "1".

FONT* - This variable has meaning only on graphical systems such as Windows. You determine the font used for accepting and displaying data on screen by setting the variable FONT to one of these values:

1 Use the graphical font (default). The character set for this font is referred to as the "ANSI" set.

2 Use the MS-DOS font. The character set for this font is called the "OEM" character set.

This setting must be made in the configuration file before you execute the program. Altering the value of FONT from inside your program has no effect.

By default, data is stored on disk using the same character set that was used when the data was entered. Thus, if you use the graphical font to accept data, that data is stored in the ANSI character set. If you use the MS-DOS font, then data is stored in the OEM character set.

Existing data moved into a graphical environment from MS-DOS applications was originally stored in the OEM character set. What happens if you now choose the graphical font? As long as your application uses only standard ASCII characters, the underlying representation is the same, and so the data is completely interchangeable. See the variable TRANSLATE_TO_ANSI if you are using non-ASCII characters.

FONT_AUTO_ADJUST - This variable allows you to disable an automatic font adjustment that is applied on Windows machines. The runtime attempts to adjust automatically for differences in the relative proportions between "small fonts" and "large fonts." You can inhibit the adjustment by setting this variable to "0" (off, false, no).

Also note that this variable computes the width of a printer font in the same way that the width of a screen font is computed. This behavior can be suppressed by compiling with the "-C43" option.

FONT_SIZE_ADJUST - This variable allows you to adjust the size of the standard font measurement that is computed for graphical controls (applies to variable-pitch fonts only). The value of FONT_SIZE_ADJUST is added directly to the computed standard font size. For example, a setting of "1" adds one pixel to the computed width of the font. Note that because the standard font measure is used to compute the width of nearly all controls, any adjustment made by this variable has a significant impact on the layout of your screens.

After applying the adjustment, the runtime checks and ensures that the computed font measure is not less than one (1) or greater than the widest character in the font. If you find that the default size of most controls is slightly smaller than you prefer, you might try setting FONT_SIZE_ ADJUST to a small value (typically "1").

Note that the adjustment to the font measure is made after the wide font measure is computed (this is important because the wide font measure depends on the standard font measure).

Generally, it is recommended that FONT_SIZE_ADJUST (and FONT_WIDE_SIZE_ADJUST) be left at its default value of "0". You can also use negative values, but there is rarely a need to do so.

Note that in order to improve performance, the runtime computes the font sizes only occasionally. Although you can change the variable dynamically at runtime, the exact time when the new setting takes effect is difficult to predict. For this reason, we recommend that you either set it in your program prior to constructing your initial screen, or directly in the configuration file.

Also note that this variable computes the width of a printer font in the same way that the width of a screen font is computed. This behavior can be suppressed by compiling with the "-C43" option.

FONT_WIDE_SIZE_ADJUST - This variable allows you to adjust the size of the wide font measurement (applies to variable-pitch fonts only). The wide font measure is normally used when the runtime is measuring small or uppercase entry fields. The value of FONT_WIDE_SIZE_ADJUST is added directly to the computed wide font size.

After applying the adjustment, the runtime ensures that the computed wide font measure is not smaller than the (adjusted) standard font measure or larger than the widest character in the font. If your uppercase fields are not quite as wide as you prefer, try setting this variable to a small value (typically "1" or "2").

Generally, it is recommended that FONT_WIDE_SIZE_ADJUST (and FONT_SIZE_ADJUST) be left at its default value of "0". You can also use negative values, but there is rarely a need to do so.

FOREGROUND_INTENSITY - Use this variable to set the default foreground intensity.

0 The runtime uses the default intensity for the output device. For both MS-DOS and Windows, this default is low-intensity.

1 The runtime uses low-intensity.

2 The runtime uses high-intensity.

If your program specifies a default intensity, then the runtime never assigns high-intensity if the foreground is black. As with the background, we do this to prevent a washed-out appearance. There's one exception to this rule. The runtime assigns high-intensity to a black foreground if the output device does not support independent background intensities. In this case, the device typically shows the background in high-intensity and keeps the foreground black. Note that if your program explicitly sets high-intensity, then that is used regardless of the foreground color. The default value for this variable is "0".

FULL_BOXES - This variable applies only in text-mode environments. When FULL_BOXES is set to "1" (on, true, yes) a full, four-sided box is drawn around boxed entry fields. By default, to save screen space on character-based systems, only the left and right edges of a box are drawn around boxed entry fields. The default value of FULL_BOXES is "0"(off, false, no).

GUI_CHARS* - This variable configures a character-based host runtime to substitute some specific characters when it is performing textual emulation of graphical controls. If the GF-GUI-MAP terminal database entry doesn't exist or has the character "0" in a particular character's position, the runtime examines the GUI_CHARS variable to determine what character to display. GUI_CHARS is used only by character-based host runtimes.

The value of GUI_CHARS is a 14-character string strictly ordered to correspond with the following graphical elements (defaults are in parentheses):

1. System menu button (*)

2. Title left corner (+)

3. Title right corner (+)

4. Title fill character (=)

5. Minimizer (.)

6. Maximizer (^)

7. Scroll bar up button (^)

8. Scroll bar down button (v)

9. Scroll bar left button (<)

10. Scroll bar right button (>)

11. Scroll bar page area ( )

12. Scroll bar slider (#)

13. Left entry field/check box ([)

14. Right entry field/check box (])

The characters may be specified in ASCII or decimal form. To specify an ASCII value, precede the value with a space. For example, to use "-" in place of "=" for the title fill character, make the following entry in the runtime configuration file:

GUI_CHARS    0 0 0 - 0 0 0 0 0 0 0 0 0 0

GUI_CHARS    0 0 0 -

The presence of a "0" (zero) following a space causes the default character to be used.

HINTS_OFF - Controls how long the pop-up hint is displayed before being erased. Set this variable to the number of hundredths of seconds to display the hint. The default value is "400" (four seconds). If you set this value to "0", the hint remains displayed until some other event (such as using the button or typing) causes it to disappear.

HINTS_ON - Controls how long the mouse must remain stationary over a bitmap button before displaying its pop-up hint. Set this variable to the number of hundredths of a second that the mouse must be stationary. The default value is "75" (three-quarters of a second). If you set this variable to "0", pop-up hints are not displayed. Setting this variable to "1" or "2" is not recommended because it may result in the pop-up hint being displayed while the mouse is moving across the button face (because the mouse motion events may occur less than 0.02 seconds apart).

HOT_KEY* - ACUCOBOL-GT offers two methods for assigning hot keys - the HOT_KEY variable, described here, and the KEYSTROKE hot-key format described in the The KEYSTROKE Variable section of the "Setting Up Your Terminals" chapter.

Using the HOT_KEY variable described below, you can easily assign a whole range of keys to a single hot-key program and determine which key activated the program. This lets you write a single program that handles an entire menu. Each menu item can act as a "hot key" to call this program.

This HOT_KEY format differs from the KEYSTROKE hot-key described in the "Setting Up Your Terminals" chapter in three ways:

*You assign a hot key by referencing its exception value instead of referencing its key code.

*You may assign a range of exception values to activate the same program.

*A hot-key program activated using the HOT_KEY format is passed a third parameter, which contains the value of the exception key that activated the program. This parameter is a COMP-1 data item.

Use the HOT_KEY variable to associate an exception value, or range of values, with a program. HOT_KEY has the following format:

HOT_KEY  program = value1 [, value2]

where program is the name of the program to run, value1 is the lower (or only) exception value that activates the program, and value2 is the upper value of the activation range. Value2 may be omitted; if it's used, it must include the separating comma. You must place program in single or double quotes if you require a lower-case program name.

For example, to assign a program called "mymenu" to exception values 100 through 200, use the following entry:

HOT_KEY  "mymenu" = 100, 200

Remote name notation is allowed for the HOT_KEY variable if your runtime is client-enabled.

Multiple HOT_KEY entries may reference the same program. This allows you to specify non-contiguous activation ranges. (Be aware that no more than 16 hot-key entries can be included in the COBOL configuration file. Using a contiguous range of exception values assigns many keys while counting as only one entry towards the limit.)

If you specify a value1 value of "0", then all hot-key references to program are removed. Within a given run unit, this is the only way to remove the assignment of an exception value to a hot-key program after it has been assigned. You will probably use SET ENVIRONMENT in your source code to do this.

If you assign multiple hot-key programs to the same exception value, the results are undefined.

You may assign different hot keys using both the HOT_KEY variable, described here, and the KEYSTROKE hot-key format described in the "Setting Up Your Terminals" chapter. The results are undefined if you assign the same key using both formats. The total number of hot-key entries defined by both methods cannot exceed 16.

HTML_TEMPLATE_PREFIX - This variable is used to specify a series of directories for locating HTML template files. This variable is similar to FILE_PREFIX and CODE_PREFIX. It specifies a series of one or more directories to be searched for the desired HTML template file. The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system). This is the default.

Remote name notation is not allowed for the HTML_TEMPLATE_PREFIX variable, even if your runtime is client-enabled.

ICOBOL_FILE_SEMANTICS - This variable affects the behavior of indexed and relative files when reversing direction after reading past the beginning or end of a file. Normally, if you perform a series of READ NEXTs that reach to the end of the file (returning file status "10"), a subsequent READ PREVIOUS returns the last record in the file. The file pointer's position after each READ NEXT is just past the end of the last record. Similarly, reading past the beginning of the file and then doing a READ NEXT returns the first record in the file.

Under ICOBOL, these conditions produce different results. The record returned by the READ PREVIOUS is the second-to-last record in the file, and the record returned by the READ NEXT is the second record in the file. Essentially, when a series of READs passes either end of the file, the record pointer remains on the first or last record.

Setting ICOBOL_FILE_SEMANTICS to "1" (or true, on, yes) causes the runtime to emulate ICOBOL's handling. This is useful when porting ICOBOL programs to ACUCOBOL-GT. This option is only effective in programs that have been compiled for ACUCOBOL-85 2.0, or later. The default value is "0" (off, false, no).

ICON - This variable has meaning only on graphical systems such as Windows. Use this variable to designate a program's "minimized" icon. (By default it uses the non-debugger icon provided with ACUCOBOL-GT.) Set ICON to the name of the file that contains the icon. This file should be an ".ICO" file that contains a 16-color icon. (Although the file may contain icons in other formats, the runtime accesses only the 16-color icon.) The icon should be created using an icon editor like the one in the Windows Software Development Kit.

For example, if your custom icon were contained in the file "PAYROLL.ICO" in the directory \ACCT\ICONS, you would add the following line to your COBOL configuration file:

ICON  \ACCT\ICONS\PAYROLL.ICO

Note that the ICON variable determines the icon used only when your application is minimized. It does not determine the icon displayed by the Program Manager.

INACTIVE_BORDER_COLOR - This variable is used on character-based hosts to specify the color and video attributes of the characters that comprise the border (box) around an inactive floating window. INACTIVE_BORDER_ COLOR can be set to a variety of numeric values that express combinations of color and video attributes.

If INACTIVE_BORDER_COLOR is set to "0", the inactive window's border is drawn with the colors and video attributes specified in the COBOL program when the window is first created. The default value is "0".

INPUT_STATUS_DEFAULT - The value of this variable is returned when an ACCEPT FROM INPUT STATUS statement is executed on a machine that cannot determine the input status of the terminal. This can be used to make a running program behave correctly on a new machine. The value must be a single digit. The default value is "0".

If the input is redirected (not attached to a terminal), the SCRIPT_STATUS variable (later in this section) determines whether ACCEPT FROM INPUT STATUS returns the value of the variable INPUT_STATUS_DEFAULT or returns the actual status of the input file.

INSERT_MODE - This variable determines whether or not keystrokes are inserted in front of any existing text when the user types an entry. Set this variable to "1" (on, true, yes) to enable insertion. The default value is "0" (off, false, no), which causes typing to replace existing text.

The user can change the state of INSERT_MODE with various key actions. For example, pressing the "Insert" key can enable insertion. This variable has no affect on Windows controls.

INTENSITY_FLAGS - This variable takes effect only if you use COLOR_TRANS and only if it changes your color scheme. After any color transformation is completed, the runtime system then transforms the foreground and background intensities according to the setting of INTENSITY_FLAGS. The value for this variable is actually the sum of the values you choose from the list below. The default value is "0".

Set INTENSITY_FLAGS to a combination of the following options by adding their values together:

1
Exchanges the foreground and background intensities for each other. This is useful if you are swapping a black background into the foreground and want to assign the foreground's intensity to the background.

2
Causes the foreground intensity to be inverted. That is, if the foreground is high-intensity, it becomes low-intensity. Otherwise it becomes high-intensity. This is useful if you are transforming the background to white and the foreground to black. Setting this causes your low-intensity foreground to be shown as gray while your high-intensity item shows as black.

4
Forces the foreground to high-intensity. This is not applied to a black foreground.

8
Forces the foreground to low-intensity. This may not be used if "4" is used.

16
Causes the "4" or "8" setting to be used even if the COLOR_TRANS setting had no effect. This is an override switch that you can use to cause all foreground intensities to be set to high or low.

32
Forces the background to high-intensity. This is not applied to a black background.

64
Forces the background to low-intensity. This may not be used if "32" is used.

128
Forces the background to high-intensity, but only if it is black. This may be used in conjunction with setting "32" or "64" for special effects.

256
Causes the "32", "64", or "128" setting to be used even if the COLOR_TRANS setting had no effect.

These transformations are performed in the order listed above. After this variable is applied, the COLOR_TABLE setting is applied to the program.

IO_CREATES - Setting this variable to "1" (on, true, yes) causes the runtime system to create a relative or indexed file when the program attempts to open a non-existent file for I/O. This is provided for compatibility with some other COBOL systems. The default value is "0" (off, false, no).

IO_READ_LOCK_TEST - When this variable is set to "1" (on, true, yes), the runtime will cause a read with no lock to fail if the file is opened for I-O and the record is locked. This setting will work with Vision files only. The setting is provided for compatibility with some other COBOL systems. The default value is "0" (off, false, no). The default behavior is to allow the read to succeed.

ISOLATE_FILE_CREATES - It is possible to experience unexpected file errors when trying to create a file if another process is simultaneously creating or removing the same file name. Setting ISOLATE_FILE_CREATES to "1" (on, true, yes) causes files to be created with temporary names and then renamed when they are fully formed. This prevents another process from interfering with the creation. This option is effective only with Vision, and has undefined effects when used with other file systems. We recommend that you use this option only if you are experiencing unexpected errors when trying to create a file.

JUSTIFY_NUM_FIELDS - When this variable is set to "1" (on, true, yes), all entry fields that have a numeric or numeric-edited VALUE data item associated with them are right justified (the same as if the RIGHT style were specified). You can inhibit this for a given field by specifying the LEFT style for the entry field. Note that this variable is examined only when each entry field is created and has no further effect. The default value is "0" (off, false, no).

KEY_MAP - This is an obsolete variable that has been replaced by the KEYSTROKE variable. Its setting is ignored.

KEYBOARD* - This variable sets global terminal attributes. For details, see The KEYBOARD Variable section in the "Setting Up Your Terminals" chapter.

KEYSTROKE* - This variable redefines the action of a particular keystroke. It can also control mouse handling. For information on redefinition of keystrokes, see The KEYSTROKE Variable section in the"Setting Up Your Terminals" chapter.

LC_ALL - This variable supports the transfer of double-byte character variables and string literals and has meaning only on 32-bit Windows systems that support double-byte characters (e.g. Asian Windows machines)It is needed only if you are passing data to a COBOL program from another language, such as Visual Basic, and are using C$GETVARIANT or C$SETVARIANT. By using the LC_ALL configuration variable, you cause the runtime to set the locale to a particular value. There is only one situation in which the runtime detects the machine it is on and automatically sets the appropriate locale value, and that is on Japanese machines. Therefore, you do not need to set this variable on Japanese machines. The runtime automatically sets the locale, LC_ALL, to "Japanese_Japan.932".

The default value for this variable is "C". The C locale assumes that all characters are 1 byte and that their value is always less than 256. The value of LC_ALL is in the format:

language[_country[.code_page]]

.code_page

where "language" is one of the supported language strings, "country" is one of the supported country or region strings, and "code_page" is the Windows code page setting for the language and country. "country" and "code_page" are optional. For example, the following are all equivalent:

LC_ALL Japanese
LC_ALL Japanese_Japan
LC_ALL Japanese_Japan.932
LC_ALL .932

For Korean double-byte character support under Windows use:

LC_ALL Korean

For Chinese use:

LC_ALL Chinese

LC_ALL Chinese-simplified

LC_ALL Chinese-traditional

Check with your software developer for the LC_ALL settings that suit your machine.

LISTS_UNBOXED - Meaningful only in character-based environments, this variable indicates whether list boxes should be boxed (set to a value of "0", off, false or no) or unboxed (set to a value of "1", on, true or yes). The default setting is "0".

LOCK_DIR - When set, this controls automatic device locking on UNIX systems. The default value is empty.

LOCK_OUTPUT - When set to "1" (on, true, yes), this variable causes all files open for OUTPUT to be locked for exclusive use. Setting this can dramatically improve performance on VMS machines. Some other COBOL systems lock files that are open for OUTPUT. The default value is "0" (off, false, no).

LOCK_SORT - When this variable is set to "1" (on, true, yes), input files to the SORT verb are opened for INPUT ALLOWING READERS. This can improve the performance of the SORT verb slightly and also ensure that the data being sorted is not modified. The default value is "0" (off, false, no).

LOCKED_RECORD_DELAY - On MS-DOS systems, this variable specifies an amount of time the runtime waits before returning a record locked condition after it encounters a locked record. When you have code that sits in a tight loop waiting for a record to become unlocked, you can set this variable to allow other users to access the file. The value in LOCKED_RECORD_ DELAY is the wait time in hundredths of a second. For example, a value of "100" would cause a 1 second delay. The default value is "0". The maximum value is "32767".

LOCKING_RETRIES - This variable is designed for Windows 95/98 and DOS-based networks. It gives you some control over situations where a user must wait for access to a shared file. The runtime will try repeatedly to acquire the file lock, up to 400 times by default. Set this variable to the number of attempts you would like the runtime to make to acquire the file lock.

LOCKS_PER_FILE - This value determines the maximum number of record locks that can be held on a file by a single process. This value affects only the files that are maintaining multiple record locks. The default setting is "10". The maximum value is "8191" for Vision files. Setting this variable to its maximum value can waste resources and is not recommended.

LOG_BUFFER_SIZE - This sets the maximum buffer size, in bytes, for the transaction log file. Acceptable values are from "0" to "32767". LOG_BUFFER_SIZE is examined before each write to the log file. Its default value is "512". If LOG_BUFFER_SIZE is set to "0", then writes to the log file are synchronous (unbuffered).

LOG_DEVICE - Setting this variable to "1" (on, true, yes) causes the transaction management system to assume that the log file is actually a device, rather than a file. This means that a special device locking method is used on the log file. It also guarantees that the log file is opened "append" and that no seeks are performed on it. This allows for the use of a tape device for the log file on many systems. The default setting is "0" (off, false, no).

LOG_DIR - This variable allows you to specify the directory to be used for temporary files generated by the transaction management system. The value is treated as a prefix, much like FILE_PREFIX. If you do not specify a directory for these temporary files, they are placed into the current directory.

In general, you should not use remote name notation in the LOG_DIR variable. Although remote name notation is allowed for the LOG_DIR variable, it is not advisable to place temporary files on a remote server.

LOG_ENCRYPTION - If this value is set to "1" (on, true, yes), record images are encrypted before they are written to the transaction log file. The default setting is "0" (off, false, no).

LOG_FILE - This identifies the name of the default log file for transaction management. The default log file is opened at the beginning of the first transaction unless NO_LOG_FILE_OK is set to "1." If it does not exist, it is created. This variable can be set programmatically with the SET ENVIRONMENT verb. The default setting is empty. Unless you have set NO_LOG_FILE_OK to "1", you must set the LOG_FILE variable if you want to use transaction management.

Remote name notation is allowed for the LOG_FILE variable if your runtime is client-enabled.

LOGGING - Setting this variable to "0" (off, false, no) disables the logging of file updates to the log file. This means that the data file recovery process is impossible. Because rollback information is maintained internally by the runtime, however, the program can still use the transaction management system to start, commit, and roll back transactions. The default setting is "1" (on, true, yes).

MAKE_ZERO - When set to "1" (on, true, yes), this variable causes a numeric data item that contains non-numeric data to be treated as zero when that item is used in a numeric statement. Setting the value to "0" (off, false, no) causes the item to be treated "as is" with whatever effects that has. The default value is "1" (on, true, yes).

MASS_UPDATE - When set to "1" (on, true, yes), this variable causes all OPEN...WITH LOCK statements to be treated as if they were written OPEN...WITH MASS_UPDATE. This does not apply to OPEN INPUT, however. Setting this variable improves file performance for applications that lock files, but may lead to file corruption if the program is killed before it completes. The default value is "0" (off, false, no).

MAX_ERROR_LINES - This variable sets the maximum number of lines that can be included in the error file. It's especially useful when you are using the file trace function of the debugger. When the size of the error file reaches the number of lines specified in this variable, the error file is "rewound" to its beginning, and subsequent lines of output overwrite existing lines in the file. For example, if you set the maximum to "300", then lines 301 and 302 would overwrite lines 1 and 2 in the file.

To help you locate the end of the file, the message "*** End of log ***" is output whenever the runtime shuts down. Line numbers are included in each line of the file, in columns one through seven. The default value is "0", which means do not limit the size of the file.

This variable is not available on VMS systems.

MAX_FILES - This value sets the maximum number of files that can be opened by the runtime system. The default value is "32". Keeping this value small conserves memory. Many operating systems limit the number of files that can be opened by a single process, so you may have to make some adjustments there too. The highest allowable value of MAX_FILES varies with the operating system:

System Max value

UNIX, MPE/iX, VMS 255

MS-DOS, OS/2, Windows 95/98 128
Windows NT 4.0/5.0 and Windows 2000 (32-bit) 256

Windows NT 3.5 or 3.5.1 64

System	Max value
UNIX, MPE/iX, VMS	255
MS-DOS, OS/2, Windows 95/98	128
Windows NT 4.0/5.0 and Windows 2000 (32-bit)	256
Windows NT 3.5 or 3.5.1	64

MAX_LOCKS - This value sets the maximum number of record locks that can be held by the runtime system for all of the files together. The default value matches the setting of MAX_FILES. Many operating systems also have limits to the number of record locks that can be held, so you may have to make adjustments there too. The maximum value is "8191" for Vision files. Setting this variable to its maximum value can waste resources and is not recommended.

MENU_ITEM* - This variable affects the behavior of pull-down menus.

The default action of a menu item is to return an exception value equal to the item's ID. You can change the default action of a particular item by using MENU_ITEM.

Use MENU_ITEM in the same fashion as the KEYSTROKE variable, except that the last entry on the line is the menu's ID, not the key code. For example, to cause a menu item whose ID is "200" to act the same as the "Delete" key, use the following:

MENU_ITEM  Edit=Delete  200

Alternately, you could cause menu item "200" to call the notepad sample program by using:

MENU_ITEM   Hot_Key="notepad"  200

MESSAGE_BOX_COLOR - This variable is used on character-based hosts to specify the color and video attributes of characters displayed in a message box window. MESSAGE_BOX_COLOR can be set to a variety of numeric values that express combinations of color and video attributes.

If MESSAGE_BOX_COLOR is set to "0" (the default value), the message box is displayed with the default window colors and attributes.

MESSAGE_QUEUE_SIZE - This variable sets the initial size of the message queue, in bytes. The message queue is dynamically resized, as needed, to hold large messages. However, it is not resized to hold multiple messages (instead, the sending threads wait until the queue empties). Setting the value larger than the default allows more messages to be queued. Setting it to a smaller value allows fewer messages to be queued and conserves memory. The default size is 1024.

MIN_REC_SIZE - This variable sets the minimum record size for print records, and for line sequential files for which trailing space removal has been specified. The default value is "1". If set to "0", then a record is reduced to zero size (except for the line delimiter) if the line is blank. You may also set MIN_REC_SIZE to higher values to establish a minimum record size other than one.

MONOCHROME - When set to "1" (on, true, yes), this variable disables color output for MS-DOS machines with graphics video cards. The default value is "0" (off, false, no).

ACUCOBOL-GT assumes that all MS-DOS machines with graphics video cards are color machines (because the card has color capabilities). If you have a monochrome monitor attached to such a machine, the results can be difficult to see. You tell ACUCOBOL-GT to disable color output for these machines through the MONOCHROME variable. When this variable is set to "1", ACUCOBOL-GT uses only black and white.

MOUSE* - This variable has meaning only on systems with a mouse. When the user selects a field in the Screen Section, the exact behavior depends on the field's underlying type. The runtime distinguishes between three classes of fields: numeric, numeric-edited, and all others. These are referred to respectively as NUMERIC, EDITED, and ALPHA.

You can control the behavior of the mouse with regard to each of these field types with the MOUSE variable. This variable takes as its arguments one of the field-type names and two keywords . The first keyword defines how the field is selected when the user presses the left button. The second keyword indicates the shape that the mouse pointer should take while in the field.

The first keyword can be one of the following:

None - Indicates that this type of field may not be selected with the mouse. When this keyword is used, then the second keyword (which defines the mouse's shape) is ignored. The mouse adopts the shape used for areas of the screen that are not part of any field.

Field - Indicates that pressing the left button anywhere in the field causes the cursor to be positioned at the beginning of the field.

Character - Indicates that pressing the left button in the field positions the cursor at the character pointed to by the mouse. If this is past the last non-prompt character in the field, the cursor is placed just after the last non-prompt character

The second keyword indicates the shape that the mouse pointer should take while in the field. It can be one of the following:

Arrow - The mouse pointer appears in the default arrow shape.

Bar - The mouse appears as a vertical bar. This is the "I-Bar" shape typically used to indicate that the mouse can be positioned at a particular character.

Cross - The mouse appears as cross-hairs.

You may also define the shape that the mouse takes when it is used in the
current field. Because the action of the mouse is the same for all field types once they become the current field, the mouse shape is the same for all three types. You set the desired shape using the Current keyword in the MOUSE variable. The default shape is the Bar shape.

Note that depending on where you are setting the MOUSE variable, there are three methods of setting its configuration.

If you want to implement this variable in a configuration file, the variable can be set without using the equal sign. For example:

MOUSE_NUMERIC_SHAPE     Bar

If you are setting the variable as part of your environment in DOS or Windows, the variable would look like this:

SET MOUSE_NUMERIC_SHAPE=Bar

If you are setting the variable in your program using COBOL syntax, the variable would look like this:

SET ENVIRONMENT "MOUSE_NUMERIC_SHAPE" TO "Bar"

The default configuration is as follows:

MOUSE_ALPHA_CHARACTER Bar

MOUSE_NUMERIC_FIELD Arrow
MOUSE_EDITED_FIELD Arrow
MOUSE_CURRENT Bar

Note that you may place multiple entries on the MOUSE configuration line, but you are not required to do so.

The following configuration variables can also be used to set the behavior of the mouse:

To set field selection: To set cursor shape:

MOUSE_ALPHA_SELECT MOUSE_ALPHA_SHAPE

MOUSE_EDITED_SELECT MOUSE_EDITED_SHAPE
MOUSE_NUMERIC_SELECT MOUSE_NUMERIC_SHAPE
MOUSE_CURRENT_SHAPE

To set field selection:	To set cursor shape:
MOUSE_ALPHA_SELECT	MOUSE_ALPHA_SHAPE
MOUSE_EDITED_SELECT	MOUSE_EDITED_SHAPE
MOUSE_NUMERIC_SELECT	MOUSE_NUMERIC_SHAPE
	MOUSE_CURRENT_SHAPE

With these variables, you need to set the first and second keywords separately. For example, to change the defaults shown above for a numeric field, you would enter:

MOUSE_NUMERIC_SELECT  character
MOUSE_NUMERIC_SHAPE  bar

MOUSE_FLAGS - This variable has meaning only on systems with a mouse. Indicate which mouse actions return an exception value to your program by setting the value of the variable MOUSE_FLAGS. Mouse actions that you don't want to deal with are ignored. The value you set is actually one or more values added together. The possible values are:

1
Causes ACUCOBOL-GT to use its automatic mouse handling facility. (default)
2
Enables the "left button pushed" action.
4
Enables the "left button released" action.
8
Enables the "left button double-clicked" action.
16
Enables the "middle button pushed" action.
32
Enables the "middle button released" action.
64
Enables the "middle button double-clicked" action.
128
Enables the "right button pushed" action.
256
Enables the "right button released" action.
512
Enables the "right button double-clicked" action.
1024
Enables the "mouse moved" action.
2048
Forces the mouse pointer always to be the default arrow shape when you are using automatic mouse handling. If this is not set, then the shape of the mouse pointer varies depending on various other configuration options. See MOUSE above.
16384
This causes all enabled mouse actions that occur within your application's window to return an exception value. If this is not set, then only mouse actions that occur within the current ACUCOBOL-GT window return a value. (The current ACUCOBOL-GT window is a window created by your program with the DISPLAY WINDOW verb.)

For example, if you wanted your program to receive an exception value whenever the user pressed either the left or right button, you would set:

MOUSE_FLAGS  130

Sites with MS-DOS also require USE_MOUSE (described later in this section).

NO_CONSOLE - This variable has meaning only on graphical systems that create an application window, such as Windows. Set this variable to "1" (on, true, yes) to indicate that you've built your own user interface entirely in C or that you are using an interface created by a code-generating tool. This is equivalent to executing the runtime system with the "-b" command-line option. When this variable is set to "1", the runtime won't create its own application window. Instead, your C code must build its own window. When you provide your own user interface, you may not use ACCEPT or DISPLAY verbs in your COBOL program (except for those that don't interact with the screen or keyboard).

The default value is "0" (off, false, no).

NO_LOG_FILE_OK - Setting this variable to "1" (on, true, yes) eliminates the need to specify a default transaction log file with the LOG_FILE variable. When this variable is set, the runtime will write transaction recovery information only to the log files specified via the filename_LOG variables.

The default value is "0" (off, false, no).

NUMERIC_VALIDATION - If this variable is set to "1" (on, true, yes), the runtime checks for proper format when data is converted to a numeric type (via a MOVE, for example). When NUMERIC_VALIDATION is set to the default "0", numeric conversion checking does not occur.

OLD_ARIAL_DIMENSIONS - The Arial font shipped with Windows 98 Version 2 has a character width of 35 pixels, while the Arial font shipped with earlier versions of Windows and Windows NT has a width of 23 pixels. This might cause field overlap or screen distortions in programs that rely on the smaller version of the Arial font. Setting this variable to "1" (on, true, yes) causes the runtime to use the 23-pixel measurement for fields, regardless of which version of Arial (35- or 23-pixel) is being used.

Note that because the new version of Arial is physically wider, uppercase characters may truncated when their size is computed with the smaller measurement. This variable will not adjust for all possible issues that may arise. Some reprogramming of your screens may be required.

The default value of "0" (off, false, no) will cause fields to be sized according to the version of Arial used.

OPEN_FILES_ONCE - This variable allows different logical files that access the same physical file to open the physical file only once. The default for this variable is "1" (on, true, yes). This variable is valid only for Unix runtimes.

PAGE_EJECT_ON_CLOSE - When set to "1" (on, true, yes), this variable causes print files to print a page advance record when the file is closed, unless the close contains the NO REWIND phrase. This is provided for compatibility with RM/COBOL version 2. The default value is "0" (off, false, no).

PERFORM_STACK - This variable sets the depth to which PERFORM statements can be nested at runtime when the "-Zr" compile-time option is used. The default value is "128". The maximum value is "10916". Setting this variable to its maximum value can waste resources and is not recommended.

PROMPTING - This variable is used on character-based hosts to turn ENTRY-FIELD prompting off or on. When PROMPTING is set to "0" (off, false, no) prompting is not performed. The default value of PROMPTING is "1" (on, true, yes).

QUEUE_READERS - This variable evens out user access by modifying the rules Vision uses when several users are accessing a file. This variable applies to UNIX machines. Because of restrictions, it is recommended only for sites that are experiencing performance problems with updaters.

By default, the runtime allows multiple readers to access a file simultaneously, while updaters require exclusive access to the file. When a file has many readers, an updater can get blocked out of the file for a period of time while the runtime waits for a moment when there are no active readers. While this allows processes that read the file to have nearly immediate access, updaters may need to wait for a noticeable amount of time.

The QUEUE_READERS variable lets you request that the runtime service each user in turn. This means a reader has the same priority for accessing a file as an updater does. Each user is processed in turn so that access to files is evenly balanced among all the users.

By default, QUEUE_READERS is set to "0" (off, false, no). Set it to "1" (on, true, yes) to force the readers to take turns instead of having immediate access.

Because of technical limitations in the UNIX file system, if you use this variable you must provide read-write access to all indexed and relative files that the runtime uses. This is true even for files that are open only for input - UNIX requires that the runtime have write access to the files in order to place the kind of lock that causes each user to take turns.

QUIT_MODE - This variable has meaning only on graphical systems such as Windows. It gives you control over the "Close" action that appears on the System menu in a graphical environment. (The QUIT_MODE variable is only used with the main application window. All other windows return the CMD-CLOSE event when they are closed.)

Many COBOL programs should not be shut down in an uncontrolled manner. This is especially true of any application that updates several files in a row. If the program is halted after updating the first file but before updating the last, the files are left in an inconsistent state. For this reason, ACUCOBOL-GT allows you to control the Close action.

To do this, you set QUIT_MODE to a non-zero value. The value that you specify affects the Close action as follows:

-2 Disable Close: disables the Close action entirely. The Close menu item appears gray on the System menu, and the user is not able to select it.

-1 Close only on input: the runtime disables the Close action except when it is waiting for user input. This prevents the user from stopping the runtime in the middle of a series of file operations, but still allows the user to quit the application any time that the application is waiting for input.

0 Always Close: the runtime halts the program whenever Close is selected from the system menu.

>0 Program controlled Close: when a positive value is used, the Close item becomes a standard menu item with an ID equal to the value of QUIT_MODE. You may then handle the Close item just like any other menu item.

For example, if you set QUIT_MODE to "100", then your program receives exception value 100 when the user selects the Close item. If you wanted to call a special shutdown program when the user selected Close, you could assign the Close action to a hot-key program:

MENU_ITEM  Hot_Key ="shutdown"  100

In this example, the "shutdown" program might pop up a small window to confirm that the user wanted to exit and, if so, do a STOP RUN.

If you start your program in "safe" mode with the "-s" runtime option, then QUIT_MODE is initialized to "-2" instead of "0". This prevents the user from using the Close menu item. A QUIT_MODE entry in the configuration file takes precedence over the default handling of "-s".

If a user attempts to end the Windows session when it is not allowed, a pop-up message box asks the user to terminate the application first. You can customize the message that appears in the box by setting the TEXT variable, message number 18.

RECURSION - ACUCOBOL-GT allows a program to call itself, directly or indirectly. A CALL statement that attempts to call an active program is termed a recursive call.

To use recursive calls, you must set the variable RECURSION to "1" (on, true, yes). The default setting for RECURSION is "0" (off, false, no), which disallows recursive calls.

The runtime system shares the program code for recursively called programs. Thus, while each recursion level has its own set of data, there is only one copy of the Procedure Division code in memory, regardless of how many active copies of the program there are. The runtime system does not, however, share overlays. Each copy of the program in memory has its own overlay area.

REL_DELETED_VALUE - This variable is helpful when you use relative files and need to have a valid record that contains binary zeros. However, because binary zeros is the deleted record marker, you have to be able to change this marker. REL_DELETED_VALUE can hold the ASCII character value for the new deleted record marker.

RENEW_TIMEOUT - When set to "1" (on, true, yes), this variable restarts the timeout used by ACCEPT BEFORE TIME after each keystroke that the user makes. The default setting is "0," which means that the timeout is canceled as soon as the user starts typing.

RESIZE_FRAMES - This variable is used to turn off the automatic resizing of frames that is performed on character-based hosts. By default, a character-based host runtime automatically resizes frames to visually surround all controls whose home coordinates are bounded by the frame. This makes it easier to maintain applications that run on both character and graphical systems. To turn automatic resizing off, set RESIZE_FRAMES to "0" (off, false, no). The default value is "1" (on, true, yes).

RESIZE_FREELY - Normally, under a graphical host (such as Windows), the runtime does not allow you to resize an AUTO-RESIZE window larger than its logical size (as determined by the number of rows and columns the program requested when it created the window). When the RESIZE_FREELY variable is set to "1" (on, true, yes), the user can resize the window to any size. Maximizing the window causes the window to occupy the entire available screen. The region of the window that lies outside of the logical area is not accessible by the program and is shown as the background color of the logical window (defined as the last background color to be applied to the entire window). Setting this option is essentially a cosmetic change to the way your application looks when maximized. The default value is "0" (off, false, no).

RESTRICTED_VIDEO_MODE - This value determines which rules are followed when the program is positioning attribute characters for "magic cookie" terminals (terminals whose attributes occupy screen positions). The default setting is "0". For more details, see the Restricted Video Modes section in the "Setting Up Your Terminals" chapter.

RMS_NATIVE_KEYS - This variable is for use only on VMS systems. When it is set to "1" (on, true, yes), it causes the runtime to specify a key type for numeric keys. In order to make use of this variable, you must also create XFD files at compile-time ("-Fx"), and you must set the configuration variable XFD_DIRECTORY to point to the directory containing those XFD files.

When these steps have been taken, the runtime will create RMS files with keys having either the packed decimal or integer attribute, under certain conditions dictated by the RMS file system. In particular, a key will have the packed decimal or integer attribute only if it is a single-segment key and only if there is a single field in the key. In this case, a USAGE COMP-3 data item in the key will receive the packed decimal attribute, and a USAGE COMP-5 data item (if it is 2, 4, or 8 bytes long) will receive the integer attribute.

One effect of having this attribute set on key fields is that the order of the data is changed. Without this attribute, a file that has records with keys -3, -2, -1, 0, 1, 2, 3 would have those records ordered in this way: 0, 1, -1, 2, -2, 3, -3. With this attribute, those records would be ordered in this way: -3, -2, -1, 0, 1, 2, 3. The default setting for this variable is "0" (off, false, no).

SCREEN* - This variable controls a variety of screen configuration options. For details, see The SCREEN Variable section in the "Setting Up Your Terminals" chapter.

SCRIPT_STATUS - This variable controls the behavior of ACCEPT FROM INPUT STATUS when the input is not attached to a terminal. If SCRIPT_STATUS has its default setting "0" (off, false, no), an ACCEPT FROM INPUT STATUS statement returns a fixed value when the program has redirected input. The value returned is the value of the INPUT_STATUS_DEFAULT variable.

When SCRIPT_STATUS is not "0", and input is redirected, then ACCEPT FROM INPUT STATUS returns the actual status of the script file (i.e., it returns "1" (on, true, yes) unless the script file has been exhausted).

SCROLL - This variable affects when screen scrolling occurs. When it is set to "1" (on, true, yes), scrolling and cursor positioning occur normally. When it is set to "0" (off, false, no), screen scrolling occurs only as the result of a SCROLL phrase in an ACCEPT or DISPLAY statement, and any DISPLAY statement that references a line past the bottom of the current window is ignored. ACCEPT statements that reference a line past the bottom of the current window are placed in the home position of the window. The default setting is "1".

server_MAP_FILE - This variable is used to point to the character map file used for translating international character sets between a client machine and a specific server that uses different character codes. The map file is a simple text file that you create with an editor of your choice. Each line in the map file must contain two values in either decimal or hexadecimal: the character code of the character on the client machine, and the character code of the same character on the server. Use a # sign to indicate a comment.

The map file may be stored on either the client machine or the server machine.

Note that the server specified in the configuration variable name must match the server specified in the remote name notation that points to the data files. For example, if you are using AcuServer to access remote files on a machine named sun3, you would use remote name notation to specify the directory that contains the data files. It might look like this:

@sun3:/user/acct/inventory

Then, create a map file and use this configuration variable to point to the map file:

sun3_map_file  @sun3:/user/acct/inventory/map.txt

If the map file is local, your value might look like this:

sun3_map_file  C:\user\utility\map.txt

If the map file is located on a server, you must have the AcuServer product on that server, to enable client access.

The runtime first searches for the configuration variable server_MAP_FILE and, if it is found, uses that setting to locate the map file. If that variable is not set, the runtime searches for DEFAULT_MAP_FILE. If that variable is also not set, then no character translation is done.

SERVER_NUMBER - This variable is for sites using the AcuServer product. It associates this copy of the ACUCOBOL-GT runtime system with a specific instance of the acuserve daemon executing on a server host machine. This variable is used only if the site is executing multiple instances of the acuserve daemon simultaneously on the same server host, and if the site wants to assign a specific runtime to a specific instance of acuserve. The default value is "1". A companion variable with the same name assigns numbers to the acuserve daemons; it is set in the server configuration file on the server host.

SHARED_CODE* - For many UNIX machines, ACUCOBOL-GT supports the ability to have multiple users share the same copy of a COBOL program's object code in memory. This variable indicates which programs you want to share code. Use of shared memory is recommended only if you have a problem with limited memory and excessive swapping. In this case, the advantage of reduced swapping usually more than makes up for the overhead added by sharing memory. To use shared code for all of your programs on UNIX, add the following line:

SHARED_CODE   1

This causes all programs to attempt to share code. Every code segment loaded into memory is placed into shared memory until shared memory is full. Further code segments are then placed in conventional memory.

Since shared memory is a limited resource under UNIX, you should probably restrict the use of shared code to those programs where it is most beneficial. This ensures that other programs do not use up all of the available shared memory first. To do this, specify each program you want to share as follows:

SHARED_CODE  Program1
SHARED_CODE  Program2
SHARED_CODE  Program3

When you use this method, "Program1", "Program2", and so forth are the PROGRAM-IDs from the programs' Identification Divisions (note that a program's object file name is not used). If you use this method, then setting SHARED_CODE to "1" has no effect.

SHUTDOWN_MESSAGE_BOX - This variable allows you to specify whether or not you want the runtime's shutdown message to be displayed in a message box. If this variable is set to "0" (off, false, no), the runtime displays the shutdown message to the screen. The default value is "1" (on, true, yes).

SORT_DIR - This variable allows you to place temporary files used by the SORT verb in another directory. By default these files are stored in the current directory. You can specify an alternate directory to hold the sort files by setting the variable SORT_DIR to the desired directory. This value is treated as a prefix, much like FILE_PREFIX. You can improve the performance of the SORT verb by placing the temporary files on a fast device. Care should be taken, however, that the device has enough free space to hold twice the size of the data to be sorted.

SORT_FILES - This variable sets the number of temporary files used by SORT. The acceptable range is from 4 to 32. (The maximum is 16 for the regular MS-DOS runtime.) The default value is "4".

Increasing the number of files used usually improves SORT performance, particularly for large sorts. Note that you must have enough available file handles to open all of the temporary files concurrently. In general, the number of files available is more important than the amount of memory used. If you are experiencing long sorts, try increasing the number of files before you increase the amount of sort memory.

The SORT verb removes all of its temporary files, except for one, prior to beginning its output phase.

SORT_MEMORY - This variable specifies the number of 64 KB blocks of memory that the SORT verb tries to allocate when it executes. For users of the standard MS-DOS runtime, the range is from 1 to 4. For all other runtimes, including MS-DOS 386, the range is from 1 to 16. The default value is "4" in all cases. Using a value lower than the default can be useful if memory is tight on the host machine. Using a higher value may enhance SORT performance.

Take care, when increasing the SORT_MEMORY setting, to ensure that you do not assign too much memory to the runtime. For most operating systems, the memory used by SORT is not returned to the system. While the runtime may use the memory for other purposes, this memory is not available to other programs until the runtime exits.

The SORT verb attempts to allocate the amount of memory specified in SORT_MEMORY, but it uses less if that much is not available.

SORT_RESERVE - The SORT verb dynamically allocates memory, which it releases when it finishes. Prior to doing this, however, it allocates a reserve area to be used by the SORT process should either the Input or Output Procedure need to use additional memory (for example, if they call another program). The value of the SORT_RESERVE variable determines the size of this area. It is expressed in kilobytes and can vary from 1 to 64. The default value is "16".

SPACES_ZERO - This variable applies only to object files generated with ACUCOBOL-85 Version 1.5 and earlier. For later object files, use the "-Zz" compiler option. When SPACES_ZERO is "1" (on, true, yes), it alters the method in which USAGE DISPLAY data items are used by the runtime system. The main effect is that, in most cases, a data item containing spaces is treated as if it contained zeros. Note that this may not occur in all instances because the ACUCOBOL-GT compiler may construct code that directly acts on a data item without first converting it to a number. The default value is "0" (off, false, no).

SPOOL_FILE - This variable allows you to hold a "pipe" open when you close the named file with the CLOSE WITH NO REWIND verb. This enables you to gather multiple reports into a single job for the print spooler.

The value given to the SPOOL_FILE variable must be the ASSIGN name of a sequential file that has been attached to a pipe. The pipe must be attached to the ASSIGN name in the COBOL configuration file via the "-P" option. Only one pipe can be held open in this manner.

STOP_RUN_ROLLBACK - When this variable is set to "1" (on, true, yes), the system performs an implied ROLLBACK rather than a COMMIT after a STOP RUN.

With a "0" (off, false, no) setting for this variable, the system performs an implied COMMIT after a STOP RUN. The default value for this variable is "0".

STRIP_TRAILING_SPACES - This variable provides an alternate method for determining which LINE SEQUENTIAL files have trailing spaces removed from records written to them. At the time a LINE SEQUENTIAL file is opened, the value of this variable is examined. If this variable is "1" (on, true, yes), then automatic space suppression is applied to this file. The default value is "0" (off, false, no).

SWITCH_PERIOD - This variable helps determine how frequently threads switch control. When a thread executes SWITCH_PERIOD number of selected operations, the threads switch control. The selected operations are generally comparisons. Comparison operations are used to cause compute-bound threads to switch.

Setting the value of SWITCH_PERIOD lower increases the overhead spent switching threads, but increases the uniformity of thread execution. Setting the value very low can significantly hurt performance. The default value is 500.

TEMP_DIR - This variable lets you specify where certain temporary files used by the ASSIGN clause are created on MS-DOS and VMS systems. These temporary files are created when you use the %TMP% option for assigning a file to a simulated pipe with "-P".

TEMPORARY_CONTROLS - By default, graphical controls are created as permanent controls. By setting this variable to "1" (true, on, yes), you cause controls to be created temporary by default. This is useful when you are converting older programs that assume that a screen update overwrites any existing screen data. You can make individual controls permanent or temporary explicitly by using the PERMANENT and TEMPORARY styles.

TEXT* - This variable controls the text of runtime messages. The ACUCOBOL-GT runtime system displays a number of informational and warning messages to the end user. Several of these messages can be customized via entries in the configuration file.

For each message that you want to change, place the word "TEXT" in your configuration file, followed by a message number from the list below, an "=" sign, and then the text you would like to use.

For example, the standard message #1 is "Press return". You can change that message to "push enter" by placing this line in your configuration file:

TEXT  1=push enter

Note that there is no space before or after the equal sign, and that the new message is not in quotes.

These are the standard runtime messages and their numbers:

Message #
Text
1
"Press return"
2
"Number required"
3
"Entry required"
4
"Field must be filled with data"
5
"Too many hot keys active"
6
"Program missing or inaccessible"
7
"Not a COBOL program"
8
"Corrupted program"
9
"Inadequate memory available"
10
"Unsupported version of object code"
11
"Program already in use"
12
"Too many external segments"
13
"Large-model program not supported"
18
"Please end this application first"
19
"Japanese objects not supported"
20
"Too many lines"
21
"License manager (acushare) not running"
22
"Data must fit this format:"
23
"&Ok"
24
"&Yes"
25
"&No"
26
"&Cancel"
Messages 23, 24, 25, and 26 are used by character-based versions for the message box facility.
28
"Unable to access the file "%s" due to heavy usage by other users. Would you like to continue waiting for it?"
See the configuration variable WAIT_FOR_FILE_ACCESS.
30
"Connection refused - perhaps AcuConnect is not running"

31
"Please enter a value between %ld and %ld".
This message is displayed when the user enters a value outside of the allowed range for an entry-field
(see MIN-VAL/MAX-VAL in the entry-field reference). The first "%ld" is replaced by the MIN-VAL setting. The second "%ld" is replaced by the MAX-VAL setting. You may omit these if you desire. Note that the second character in the sequence is the letter "l", and not the number one ("1").

TRANSLATE_TO_ANSI - This variable has meaning only on graphical systems such as Windows. It is used only if:

* you are using the graphical system's font to accept data, and

* you store your data using the OEM character set.

Set the variable TRANSLATE_TO_ANSI to "1" to turn on a character set translator. Then, if you use the graphical system's font for accepting data, the runtime translates from one character set to the other for you. Data that is accepted from the screen is translated into the OEM character set before it is stored on disk. Data stored in the OEM character set is translated to the ANSI character set before it is displayed on screen. This also applies to the printer, if you are using Windows spooling and the printer uses an ANSI font.

Setting TRANSLATE_TO_ANSI to "0" (default) turns off the translation process.

TREE_ROOT_SPACE - This variable controls the number of screen columns between the left edge of the Tree-View control and the root level text. TREE_ROOT_SPACE is used only with the LINES-AT-ROOT property. If LINES-AT-ROOT is not specified, the root level item text will be displayed starting at the leftmost screen column inside the tree-view control.

For example, if TREE_ROOT_SPACE is set to 5, there will be 5 screen columns before the text of each root level item. The screen column where the root level line will be drawn is determined by this formula:

root level-line = (TREE_ROOT_SPACE - 1)/2 + 1

Taking off from the previous example, if TREE_ROOT_SPACE=5, the root level line will be drawn in screen column 3, counting from the left edge of the Tree-View control.

This has the effect of centering the vertical root level line in the space between the left edge of the Tree-View control and the last root level text.

The "+" or "-" button is displayed in the column to the right of this vertical line if the TREE_ROOT_SPACE is set to a value greater than or equal to 2. If the TREE_ROOT_SPACE is set to 1, the "+" or "-" button appears in the first screen column of the Tree-View control. The default value of TREE_ROOT_SPACE is 2.

TREE_TAB_SIZE - This configuration variable is one of two variables that affect the appearance of character-based Tree-View controls. TREE_TAB_SIZE controls the number of screen columns between each level in the visual representation of the tree. For example, if TREE_TAB_SIZE is set to 10, the horizontal distance between the first character of text in the first level and the first character of text in the succeeding levels of the tree will be 10 screen columns each. The default value of TREE_TAB_SIZE is 3.

See TREE_ROOT_SPACE above.

TRX_HOLDS_LOCKS - This variable allows you to control which locks are released at the end of a transaction. If this variable is set to "1", then locks set using the READ statement that are not specifically released or replaced by extended transaction locks (for example, by a REWRITE) are held at the end of the transaction. Locks are released during a transaction by any operation that would ordinarily release them, unless those locks were replaced by extended transaction locks.

If TRX_HOLDS_LOCKS is set to "0" (the default), then locks are released at the end of a transaction, and the UNLOCK verb has no effect during a transaction.

UPPER_LOWER_MAP* - This variable allows you to define which upper-case characters correspond to which lower-case characters, for characters outside of the standard ASCII character set (those whose underlying decimal values are 128 or larger).

You might find this useful if you are experiencing problems with the UPPER or LOWER option of the ACCEPT statement when non-standard characters are entered (such as an "e" with an accent above it). The ACUCOBOL-GT runtime system relies heavily on C library routines to handle conversions between upper- and lower-case characters. On many machines, these routines do not handle characters outside of the standard ASCII character set correctly.

To specify corresponding characters, use UPPER_LOWER_MAP followed by pairs of characters, where the first character is the upper-case version and the second character is the lower-case version. Separate the characters by a space. Describe the characters either by typing them at the keyboard or by entering the decimal value that represents them.

For example, on a standard IBM PC, the video card represents an upper-case "U" with an umlaut (Ü) as character 154, and the lower-case "u" with an umlaut (ü) as 129. The upper-case "E" with an accent character is 144 (É) and the lower-case "e" with an accent is 130 (é). To express this in the configuration file, you would add the following line:

UPPER_LOWER_MAP  154 129 144 130

This could be extended to include all of the character pairs available.

By default, MS-DOS, Windows, and OS/2 machines come with the UPPER_LOWER_MAP defined to be the character pairs available on the standard video cards produced by IBM. Note that using "code pages" can change this, so the default may not work in all cases for these machines. For machines other than MS-DOS and OS/2, the default is empty (which means that C library routines are used for conversion). If you experience difficulties, UPPER_LOWER_MAP allows you to define a mapping that reflects your hardware configuration.

Only characters whose decimal values are 128 or greater may be mapped by this technique.

USE_LOCAL_SERVER - This variable is used by the runtime and plug-in to specify whether or not you want to run client applications on the same machine as an AcuServer file server. When USE_LOCAL_SERVER is set to the default of "0" (off, false, no), AcuServer is bypassed when accessing local files that have remote name notation. The remote name is stripped off and the file I/O operation is handled by the runtime or plug-in. Set this variable to "1" (on true, yes) to use AcuServer to access local files that have remote name notation. This variable only works with AcuServer client runtimes and AcuServer client plug-ins.

USE_MOUSE - This variable enables the mouse for MS-DOS systems (makes it visible on screen).

Set USE_MOUSE to "1" (on, true, yes) to make the mouse visible. For this setting to have any effect, it must be present in either the COBOL configuration file or the MS-DOS environment when the runtime starts. The default value is "0" (off, false, no).

V_BUFFERS - This variable determines the number of indexed block buffers to allocate. These buffers are used to improve the performance of indexed files. Each buffer is 512 bytes plus some overhead. Setting this number larger generally improves file performance. Setting it smaller saves memory. This value has no effect on versions of ACUCOBOL-GT which do not use Vision files. The value can range from "0" (no buffering) to "2097152". The default value is "128" for MS-DOS and "64" otherwise.

V_BUFFER_DATA - The setting of this variable determines whether or not Vision indexed file data blocks (as opposed to key blocks) are held in the memory-resident disk buffers. When it is set to "1" (on, true, yes), both data blocks and key blocks use the buffers. When set to "0" (off, false, no), only key blocks use the buffers. Setting this value to "1" usually improves performance unless very few buffers are being used. Note that holding data blocks in the buffers slightly increases the chances of losing data if a file opened for MASS-UPDATE is not closed properly (power failure, etc.). The default setting of this variable is "1".

V_BULK_MEMORY - Vision allocates a memory buffer for each file opened for bulk addition. The size of this buffer is controlled by the V_BULK_MEMORY configuration option. The default size of this buffer is 1 MB.

Note that the default size is fairly large because it is assumed that only a few files will be open for bulk addition on a system at any one time. If this buffer cannot be allocated, the OPEN fails with a status indicating inadequate memory.

To change the size of the allocated memory buffer to, for example, 500 KB, you would enter:

V_BULK_MEMORY = 500 KB

V_FORCE_OPEN - This variable allows you to force the runtime to open broken files that would normally cause an error 98. This means you can write COBOL programs to recover these files in ways that are not available with vutil. Set V_FORCE_OPEN to "1" (on, true, yes) to open the files. The default is "0" (off, false, no).

V_INTERNAL_LOCKS - This variable allows you to control whether the runtime enforces internal record or file locking. When V_INTERNAL_LOCKS is set to "0" (off, false, no), Vision tracks locks but does not enforce internal record or file locking. As a result, the runtime does not return a record or file locked condition for a record or file that was previously locked by the same run unit. When V_INTERNAL_LOCKS is set to "1" (the default), internal record and file locking are enforced.

V_LOCK_METHOD - This variable selects which locking method Vision uses to control simultaneous access to indexed files. It affects only the Vision file system, and only files directly accessed by the runtime (it does not apply to files accessed via AcuServer).

The default setting of "0" causes Vision to lock the first byte of the file for every access to the file (both reads and updates). This ensures that the process is not interfered with by another process. This locking method is always used by Vision Version 2 files.

Setting this variable to "1" (one) causes Vision to lock the first byte of the file for all operations except random READs or READ NEXTs. These two operations proceed without the lock. Instead they perform some additional reads of the file, to ensure that they get consistent results. If they get inconsistent results, they are retried, this time locking the first byte as other operations do. This locking method is available only for Vision Version 3 and Version 4 files.

Note that this variable must have the same setting for all the runtimes accessing a file, whether they are reading or writing to it. For example, if a runtime set withV_LOCK_METHOD=1 is reading from a file, any runtimes that are writing to that same file must also have V_LOCK_METHOD set to 1.

Lock method "1" can produce better performance on some machines. These machines fall into two categories:

* Machines that take a long time to place a lock.

* Machines that do not queue lock requests, and are very busy. In this case, some users typically get good performance, while others get poor performance.

If you are experiencing poor performance on Vision version 3 or 4 files, setting V_LOCK_METHOD to "1" may help.

Setting this variable to "2" (two) enables "asynchronous reads" of Vision files. This can reduce the number of file locks required to perform READs and READ NEXTs. V_LOCK_METHOD=2 works only for Vision 4 files.

If any process reading a particular file is using V_LOCK_METHOD=2, all other processes updating that file must be Version 5.0.0 or greater. This is because Version 5.0.0 contains changes that affect the way Vision updates the tree structure of its files. This requirement is not enforced by Vision, however, so it is important for users to pay careful attention to the versions of programs accessing the files to avoid receiving erroneous data.

V_MARK_READ_CORRUPT - This variable allows you to configure Vision so that it does not mark a file as broken if it encounters a corruption during a read or start operation. The effect is that the user is allowed to retry the program. This may be useful when the error is spurious (for example due to a network caching glitch). If the user retries the program and once again receives a file-corrupt message, then the file should be rebuilt or recovered normally. To enable this option, set the configuration option "V_MARK_READ_CORRUPT" to "0" (off, false, no). The default setting is "1" (on, true, yes).

V_READ_AHEAD - Setting this variable to "0" (off, false, no) turns off Vision's read-ahead logic. This may improve performance in cases where highly random file processing is being used. The default value is "1" (on, true, yes).

V_SEG_SIZE - This configuration variable sets the maximum size of a Vision 4 file segment in bytes. The default value is 2,147,482,112 (i.e., 2GB - 1536), except on older HP/UX machines where it is 1,073,740,288 (i.e., 1GB - 1536) due to an operating system limitation. You may not use larger values, but you can set smaller ones. The default value is the maximum allowed. The value specified will automatically be rounded down to a multiple of the block size of the file being created. For example, if the default V_SEG_SIZE value is used and a file with a block size of 1024 is created, the segment size for that file will be 2,147,481,600 (i.e., 2GB - 2048).

Using a smaller value for the segment size can help if you do not have 2GB free on any disk or for testing purposes. The minimum value allowed is 81,920 bytes. To minimize the number of files created, you should set this value as high as possible.

The segment size of a file is set at file creation time and cannot be modified without recreating the file (i.e., using vutil -rebuild with a different V_SEG_SIZE setting). vutil uses this variable, but since it does not use a configuration file, this variable must be set in the environment.

V_VERSION - This specifies the version number of new Vision files that are created. The default value is "4", which produces current Vision files (Version 4). Version 4 files are generated in a dual file format, with data records filed in one segment and overhead key information filed in another. The value "3" produces Version 3 files, in which data and keys are stored in a single file. The value "2" produces Version 2 files. Any value other than "2" or "3" produces Version 4 files.

V23_GRAPHICS_CHARACTERS - Programs written for and executed with UNIX versions of the runtime up to and including Version 2.4.0 use hex values 1-8 to display line-drawing characters on the screen. Runtimes after Version 2.4.0 use hex values offset by one (1). When older programs are used with runtimes released after Version 2.4.0, line-drawing characters do not display as expected. To use the old values for line-drawing characters, set this variable to "1" (on, true, yes).

If the variable is set to "0" (off, false, no) or is not set at all, the runtime will use the newer offset values. This variable works only for UNIX systems.

V30_MEASUREMENTS - This variable affects whether the runtime sizes certain controls using the rules from ACUCOBOL-GT Version 3.0 or from the current version. Setting the variable to "1" means that Version 3.0 sizing rules are used for controls. When V30_ MEASUREMENTS is set to the default "0", then the current sizing rules are in effect. The related configuration variables, V31_MEASUREMENTS and V32_MEASUREMENTS have the same effect of setting the sizing rules to that of their respective versions.

V31_FLOATING_POINT - This variable allows you to disable a correction that was made to the way floating point numbers are displayed. Because some loss of precision in the display of "USAGE DOUBLE" fields had been possible in Version 3.1, an improvement was introduced. Setting this variable to "1" means that the Version 3.1 way of displaying floating point numbers is used. When V31_FLOATING_POINT is set to the default "0", then the correction is in effect.

V42_TRANSPARENT - This configuration variable is designed for Windows systems. It allows you to choose whether a transparent label placed within a frame appears according to the rules of Version 4.2.0 or according to those of Version 4.3.0. In Version 4.2.0, a transparent label placed inside a frame assumed the color of the frame background. In version 4.3.0, however, such a label assumed the color of the parent window. This variable allows you to choose between these two results. When V42_TRANSPARENT is set to "0" (off, false, no), then the Version 4.3.0 way of displaying the transparent style is used. When V42_TRANSPARENT is set to "1" (on, true, yes), then the Version 4.2.0 way of displaying the transparent style is used.

V43_PRINTER_CELLS - This variable affects whether the runtime sets the width of a printer cell according to the rules from Version 4.3 or from the current version. Version 4.3 (and prior versions) computed the width of a printer cell based on the average width of a selected printer font. The width of a printer cell is currently computed in the same way that cells are computed for the screen, namely by the width of the "0" character. For fixed-width fonts, such as Courier, these values are the same for all characters. For proportional fonts, such as Times New Roman, some characters might be wider than the "0" character.

If the current computation is causing your application to print incorrectly, then setting this variable to "1" (on, true, yes) will use Version 4.3 rules instead. When V43_PRINTER_CELLS is set to the default "0" (off, false, no), then the current rules are in effect.

WAIT_FOR_ALL_PIPES - This variable determines if the runtime calls the wait system call each time a "-P" file is closed. When WAIT_FOR_ALL_PIPES is set to "0", the runtime does not make this call until it is ready to close the last pipe it knows about. Setting this variable to the default "1" means that the runtime calls the wait system call when a "-P" file is closed.

WAIT_FOR_FILE_ACCESS - This configuration variable is designed for Windows 95/98 systems. It gives you some control over situations where a user must wait for access to a shared file. The runtime will try repeatedly to acquire the file lock, up to 400 times. If it has been unable to obtain a file lock after 400 tries, it will (by default) display a message box, asking if the user would like to continue waiting. If the user clicks the "Yes" button, then the runtime will try again another 400 times (or the value of LOCKING_RETRIES ). If the user clicks the "No" button, then the runtime will return an error to the COBOL program (such as file error 30,33 (system error) or file error 99 (record locked).

WAIT_FOR_FILE_ACCESS lets you choose one of three behaviors: either the user will always see the message box and make a choice, or the program will always return an error code if it cannot acquire the lock, or the runtime will always behave as if the user answered "yes" to the message box.

You can modify the text shown to the user in the message box via the TEXT configuration variable. The message is number 28. To include the filename in your message, insert "%s" at the place where you want the name of the file to appear. You can introduce line breaks by including "\n" in the message.

Possible values for the WAIT_FOR_FILE_ACCESS variable are:

0 "No" Do not display message box if lock is not acquired. Send error to COBOL program.

1 "Ask" Show the message box and ask the user. (Default)

2 "Yes" Do not show the message box. Assume that the user wants to wait for the file. This ensures that the user eventually can access the file, but introduces a small risk of an infinite loop if the system's lock table becomes corrupt.

For programs running in background ("-b" runtime option), or programs with redirected input or output, the "Ask" option is treated the same as the "Yes" option.

WAIT_FOR_LOCKS - This determines how the runtime handles file status error 99 conditions. It can have one of the following values:

0 Do not wait for locked records, return error 99.

1 Wait for the locked record if a Declarative is available for the file, otherwise return error 99.

2 Always wait for the locked record, never return error 99.

Any other value (including the default value of "-1") causes the runtime to wait for locked records only if you have compiled for RM/COBOL compatibility and the file does not have a Declarative.

WARNINGS - This variable controls whether a warning message is printed when non-numeric data is used in a context where numeric data is required. There are four possible settings:

0 (off, false, no) No warning is printed.

1 (on, true, yes) A warning is printed. This is the default.

2 A warning is printed. If you are in the debugger, an automatic breakpoint occurs.

3 A warning is printed and the runtime shuts down.

WARNING_ON_RECURSIVE_ACCEPTS - An event procedure may CALL another procedure which may contain ACCEPT statements, which, in turn, may contain embedded procedures. Although this is handled in the same fashion as nested PERFORMs and is perfectly legal, doing this poses the danger of going from one ACCEPT to another uncontrollably. When the limit of 10 nested accepts is reached, the program starts overwriting memory. It is possible to warn the user when the limit is reached by giving this configuration variable a zero ("0") value. This gives users the opportunity to continue at their own risk. Giving WARNING_ON_RECURSIVE_ACCEPTS a non-zero value suppresses the warning.

To avoid overwriting memory, you may choose to re-code affected programs to terminate the ACCEPT and perform the CALL after you exit from the ACCEPT. You may also use CHAIN or CALL PROGRAM instead of the regular CALL, if applicable.

WHITE_FILL - This variable has meaning only on graphical systems such as Windows. Some graphical systems (such as Windows) use a "background brush" when they resize a window. By default, the background brush color for ACUCOBOL-GT is black ("0", off, false, no). If you have arranged your default background to be white, you see a black flash when you resize the window. This does not affect the final appearance of the window, but is briefly noticeable while the window is being redrawn.

Set WHITE_FILL to "1" (on, true, yes) to cause ACUCOBOL-GT's background brush to be set to white instead of black. Doing this also causes the initial screen that ACUCOBOL-GT paints to be white instead of black.

Note that this variable must be set in the configuration file to be effective. Modifying this variable with the SET ENVIRONMENT verb has no effect.

WIN_ERROR_HANDLING - This variable has meaning only on graphical systems such as Windows. Use WIN_ERROR_HANDLING to control how hardware errors are handled.

When this variable is set to the default of "1" (on, true, yes), certain errors are handled directly by the host environment, and do not automatically return a file error code. For these errors, a dialog box is displayed that describes the error and offers "Cancel" and "Retry" buttons. The user may correct the error and press "Retry". If the user presses "Cancel", then your program receives the file error that it would have normally received.

If you set WIN_ERROR_HANDLING to "0" (off, false, no), then the dialog box is not shown and your program receives the error directly.

WIN3_CLIP_CONTROLS - This option is specific to Windows and Windows NT versions of ACUCOBOL-GT. It affects the way in which updates to a window interact with graphical controls in a window. Normally, Windows allows updates to a parent window to show through any controls in that window. The controls are then updated to create the proper final appearance. This is very fast, but it can cause controls to flash when the background is being updated. When this option is set to "1" (true, on, yes), the controls are clipped from the update region in the parent window before the parent is repainted. This causes the controls to remain relatively stable; however, screen repaints can be significantly slower, particularly when the runtime is creating and destroying controls. The default setting for this option is "0" (off, false, no). We recommend that you experiment with both settings to see which you prefer. Note that this option is examined when a floating window is created. Once a window is created, changes to this option have no effect on that window. Also note that when turned on, this option causes the Windows WS_CLIPCHILDREN style to be used whenever floating windows are created.

WIN3_EF_PADDED - This variable has meaning only on Windows systems. Under Windows, unboxed entry fields include a small amount of extra space so the cursor can be seen when it is placed after the last character position. This space can be a problem if you want to convert a program and align screen items. When WIN3_EF_PADDED is set to "0", this extra space does not appear in unboxed entry fields, and the entry field has only enough space for its character positions. When this variable is set to the default "1", the extra space appears in unboxed entry fields.

WIN3_GRID - This option is specific to Windows and Windows NT. When set to a non-zero value, it causes a fine grid to be drawn in each floating window. The grid outlines the character cells in the windows. This is intended to be used as a debugging tool to help you see how various controls line up against the window's character cells. It can also help you adjust the layout of a screen.

The grid is drawn using the color number that WIN3_GRID is set to (see the COLOR phrase for the exact values). For example, setting WIN3_GRID to four draws a cyan grid. The grid is drawn with dashed lines. Every fifth horizontal line, and every tenth vertical line, is drawn with a solid line.

WIN32-_3D - This configuration variable causes the runtime to use the native 3-D features of Windows when drawing controls with the 3-D style. This has an effect only with the 32-bit Windows runtime. Turn this feature on by setting WIN32_3D to "1" (on, true, yes). When set to the default of "0" (off, false, no), the runtime supplies its own 3-D effects. The advantage of using the native Windows 3-D is that you get a slightly more modern appearance and a closer match to the appearance of other Windows programs. The disadvantages are:

Windows always draws the border using the colors selected in the system's control panel. As a result, the effect looks right only when placed on a window whose background is the USER-GRAY color. You can accomplish this easily by creating STANDARD windows that specify BACKGROUND-LOW.

The Windows 3-D effect is slightly larger than the runtime's 3-D effect. Windows draws a 1-pixel wide border around the control that is the same color as the USER-GRAY color. This border is essentially invisible against a window with the USER-GRAY background. However, this border can overwrite anything else that may be positioned there. The net effect is that you can't place controls as close together as you can with the runtime's 3-D.

This 3-D style can be used only with the 32-bit runtime.

The runtime adjusts for the physical differences between the two styles. Under either style, the position and usable size of the controls' interior should be same.

WINDOW-INTENSITY - This configuration variable controls whether the color settings specified in the COLOR phrase of the DISPLAY WINDOW statement are used or ignored by the runtime. If you set the value of this variable to "0" ("off", "false", "no"), the COLOR intensity settings in the DISPLAY WINDOW statements are ignored. The default value of the "WINDOW_INTENSITY" variable is "1" ("on", "true", "yes"), which allows the runtime to set the window's color intensity as specified in the COLOR phrase of the DISPLAY WINDOW statements.

WINDOW_TITLE - This variable has meaning only on graphical systems such as Windows. The ACUCOBOL-GT runtime system automatically sets the title of the application window to the base name of the initial object file. For example, if you run a program called notepad.cbx, then the title on the main window is set to "Notepad". The title is shown in lower case except for the first letter, which is made upper case.

You may provide an alternate title by setting WINDOW_TITLE to the desired text. No translation of the text is done, so you should enter it using the desired case.

WRAP - The setting of this variable determines whether a DISPLAY statement wraps around or is truncated when it extends past one line. When it is set to "0" (off, false, no), DISPLAY statements are truncated. Also, any DISPLAY statement that references a column past the right edge of the current window is ignored. An ACCEPT statement that references a column past the right edge is placed in the home position of the window. The default value for this setting is "1" (on, true, yes).

XFD_DIRECTORY* - This variable tells the runtime system the name of the directory that contains the data dictionaries built by the ACUCOBOL-GT compiler. The default value is the current directory.

Remote name notation is allowed for the XFD_DIRECTORY variable if your runtime is client-enabled.

System	Default runtime configuration file
MS-DOS	\etc\cblconfi
Windows	\etc\cblconfi
Windows NT/ Windows 2000	\etc\cblconfi
OS/2	\etc\cblconfi
MPE/iX	/etc/cblconfig
UNIX	/etc/cblconfig
VMS	SYS$LIBRARY:A_CONFIG.DAT

ATI Integra, VGA/Wonder, EGA/Wonder	35
ATI Prism Elite	83
Chips & Technologies chip sets	96
Genoa 6000 Series	96
Paradise Systems	85
Trident chip sets	83
Tseng Labs chip sets	35

BIG5	Big Five (Taiwan)	Chinese DOS, Windows
DBC	Acucorp Generic Double-byte Coding Scheme	Other double-byte machines
EUC	Extended UNIX	Most UNIX machines
GB	Code of Chinese Graphic Character Set (People's Republic of China)	Chinese DOS, Windows
KSC	Korean Character Standard	Korean DOS
SJC	Shift JIS Code (Japanese Industrial Standard)	DOS/V, Windows, some UNIX machines

BIG5	161 - 254	64 - 126
(second format)	161 - 254	161 - 254
DBC	128 - 255	128 - 255
EUC	142	161-223
(second format)	161 - 254	161 - 254
GB and KSC	161- 254	161 - 254
SJC	129 - 159	64 - 252 (not 127)
(second format)	224 - 239	64 - 252 (not 127)

1	Exchanges the foreground and background intensities for each other. This is useful if you are swapping a black background into the foreground and want to assign the foreground's intensity to the background.
2	Causes the foreground intensity to be inverted. That is, if the foreground is high-intensity, it becomes low-intensity. Otherwise it becomes high-intensity. This is useful if you are transforming the background to white and the foreground to black. Setting this causes your low-intensity foreground to be shown as gray while your high-intensity item shows as black.
4	Forces the foreground to high-intensity. This is not applied to a black foreground.
8	Forces the foreground to low-intensity. This may not be used if "4" is used.
16	Causes the "4" or "8" setting to be used even if the COLOR_TRANS setting had no effect. This is an override switch that you can use to cause all foreground intensities to be set to high or low.
32	Forces the background to high-intensity. This is not applied to a black background.
64	Forces the background to low-intensity. This may not be used if "32" is used.
128	Forces the background to high-intensity, but only if it is black. This may be used in conjunction with setting "32" or "64" for special effects.
256	Causes the "32", "64", or "128" setting to be used even if the COLOR_TRANS setting had no effect.

MOUSE_ALPHA_CHARACTER	Bar
MOUSE_NUMERIC_FIELD	Arrow
MOUSE_EDITED_FIELD	Arrow
MOUSE_CURRENT	Bar

1	Causes ACUCOBOL-GT to use its automatic mouse handling facility. (default)
2	Enables the "left button pushed" action.
4	Enables the "left button released" action.
8	Enables the "left button double-clicked" action.
16	Enables the "middle button pushed" action.
32	Enables the "middle button released" action.
64	Enables the "middle button double-clicked" action.
128	Enables the "right button pushed" action.
256	Enables the "right button released" action.
512	Enables the "right button double-clicked" action.
1024	Enables the "mouse moved" action.
2048	Forces the mouse pointer always to be the default arrow shape when you are using automatic mouse handling. If this is not set, then the shape of the mouse pointer varies depending on various other configuration options. See MOUSE above.
16384	This causes all enabled mouse actions that occur within your application's window to return an exception value. If this is not set, then only mouse actions that occur within the current ACUCOBOL-GT window return a value. (The current ACUCOBOL-GT window is a window created by your program with the DISPLAY WINDOW verb.)

Message #	Text
1	"Press return"
2	"Number required"
3	"Entry required"
4	"Field must be filled with data"
5	"Too many hot keys active"
6	"Program missing or inaccessible"
7	"Not a COBOL program"
8	"Corrupted program"
9	"Inadequate memory available"
10	"Unsupported version of object code"
11	"Program already in use"
12	"Too many external segments"
13	"Large-model program not supported"
18	"Please end this application first"
19	"Japanese objects not supported"
20	"Too many lines"
21	"License manager (acushare) not running"
22	"Data must fit this format:"
23	"&Ok"
24	"&Yes"
25	"&No"
26	"&Cancel" Messages 23, 24, 25, and 26 are used by character-based versions for the message box facility.
28	"Unable to access the file "%s" due to heavy usage by other users. Would you like to continue waiting for it?" See the configuration variable WAIT_FOR_FILE_ACCESS.
30	"Connection refused - perhaps AcuConnect is not running"
31	"Please enter a value between %ld and %ld". This message is displayed when the user enters a value outside of the allowed range for an entry-field (see MIN-VAL/MAX-VAL in the entry-field reference). The first "%ld" is replaced by the MIN-VAL setting. The second "%ld" is replaced by the MAX-VAL setting. You may omit these if you desire. Note that the second character in the sequence is the letter "l", and not the number one ("1").