Special-Names Paragraph

The SPECIAL-NAMES paragraph describes several miscellaneous aspects of the operating environment. The phrases may be listed in any order, with two exceptions. The switch declarations must come first, and alphabets must be defined before they are referenced in SYMBOLIC CHARACTERS phrases.

General Format

SPECIAL-NAMES.
  [ {switch-name} [ IS mnemonic-name ]
    {system-name}
  [ {ON } STATUS IS cond-name ] ... ] ...
    {OFF}  
  [ {alphabet-entry } ... ]
  [ SYMBOLIC CHARACTERS
     { {name} ... {IS } {number} ... } ... 
                  {ARE}
  [ IN alphabet-name ] ]
  [ CLASS class-name IS
     { lit-1 [ {THROUGH} lit-2 ] } ... ] ...
               {THRU   }
  [ CURRENCY SIGN IS char ]
  [ DECIMAL-POINT IS COMMA ]
  [ NUMERIC SIGN IS TRAILING SEPARATE ]
  [ CONSOLE IS CRT ]
  [ CURSOR IS cursor-name ]
  [ CRT STATUS IS status-name ]
  [ SCREEN CONTROL IS control-name ]
  [ EVENT STATUS IS event-status ].

Alphabet Entry

Format 1

ALPHABET alphabet-name IS (STANDARD-1}
                          {STANDARD-2}
                          {NATIVE    }
                          {EBCDIC    }

Format 2

ALPHABET alphabet-name IS
   {literal-1 [ THROUGH literal-2   ] } ...
              [ THRU literal-2      ]
              [ {ALSO literal-3} ...]

Syntax Rules

  1. switch-name must be one of the system names: SWITCH-1, SWITCH-2, ... SWITCH-26 or the word "SWITCH" followed by a switch number (a numeric literal 1 through 26 or an alphanumeric literal "A" through "Z"). It represents one of the 26 program switches.
  2. mnemonic-name is a user-defined word that may be used in a SET statement to change the state of the associated program switch or to refer to a device in an ACCEPT or DISPLAY statement.
  3. Each system-name must be associated with a mnemonic-name. Also, no system-name may be given an ON or an OFF STATUS. system-name must be one of the following: CONSOLE, SYSIN, SYSIPT, SYSOUT, SYSLIST, SYSLST, SYSOUT-FLUSH, or SYSERR.
  4. cond-name is a user-defined word that can be used to test the status of a program switch.
  5. For each switch-name, at least one mnemonic-name or one cond-name must be specified. No more than one ON STATUS and one OFF STATUS phrase may be specified for a particular switch-name.
  6. name is a user-defined word that names a symbolic character.
  7. number is an integer literal that must be in the range of ordinal positions in the alphabet being referenced.
  8. There must be a one-to-one correspondence between occurrences of name and number. The relationship between each name and number is by position in the SYMBOLIC CHARACTERS clause. The first name is paired with the first number, the second with the second, and so on.
  9. Class-name is a user-defined word that defines a class name.
  10. lit-1 and lit-2 are numeric or alphanumeric literals.
  11. char is a one-character nonnumeric literal that specifies a currency symbol.
  12. cursor-name must be the name of a data item appearing in the Data Division that is four or six characters in length. cursor-name must describe an elementary unsigned numeric integer or a group item containing two such elementary data items.
  13. status-name must name a group item in the Data Division that is three characters in length or must name an elementary numeric data item.
  14. control-name must name a group item with the following structure:
    01 SCREEN-CONTROL.
       03 ACCEPT-CONTROL   PIC 9.
       03 CONTROL-VALUE    PIC 999.
       03 CONTROL-HANDLE   USAGE HANDLE.
       03 CONTROL-ID       PIC X(2) COMP-X.

    You must use the preceding structure, but you may use your own names for the variables.

  15. event-status must refer to a group item with the following structure:
    01 EVENT-STATUS.
       03 EVENT-TYPE           PIC X(4) COMP-X.
       03 EVENT-WINDOW-HANDLE  USAGE HANDLE OF WINDOW.
       03 EVENT-CONTROL-HANDLE USAGE HANDLE.
       03 EVENT-CONTROL-ID     PIC X(2) COMP-X.
       03 EVENT-DATA-1         USAGE SIGNED-SHORT.
       03 EVENT-DATA-2         USAGE SIGNED-LONG.
       03 EVENT-ACTION         PIC X COMP-X.

    You can find a copy of this format in the COPY library crtvars.def. You may name the data items in the EVENT-STATUS declaration arbitrarily, but the data types, storage, and group structure must match the example given. (For compatibility with older source code, the compiler accepts an EVENT-STATUS item that does not have EVENT-ACTION. The runtime behaves as if EVENT-ACTION contains the value 0, indicating normal event handling.) The SIGNED-LONG data item, EVENT-DATA-2, may be compiled with any -Dw setting (-Dw limits the word-size of the target machine). If you use -Dw16 or -Dw32, you should not run the generated object on a 64-bit machine.

  16. alphabet-name is a user-defined word that defines an alphabet name.
  17. The optional word ALPHABET is required in an alphabet declaration if it immediately follows a SYMBOLIC CHARACTERS declaration.
  18. literal-1, literal-2, and literal-3 may be any literal, but if they are numeric, they must be in the range of 1 through 256.
  19. literal-2 and literal-3 must have a size of one character if they are alphanumeric literals.
  20. literal-1 must also have a size of one character if it is associated with a THROUGH or ALSO phrase.

General Rules

  1. The switch-name clause associates status names (cond-name) and switch names (mnemonic-name) with a particular program switch. These can be used to test the on/off status of a switch or to change the switch's status.
  2. The system-name clause associates a user-defined mnemonic-name with one of the predefined system devices. These names may be used in the ACCEPT and DISPLAY statement to refer to the following devices:
    System Name ACCEPT DISPLAY
    CONSOLE system input system output
    SYSIN system input (illegal)
    SYSIPT system input (illegal)
    SYSOUT (illegal) system output
    SYSLST (illegal) system output
    SYSLIST (illegal) system output
    SYSOUT-FLUSH (illegal) system output
    SYSERR (illegal) error output

    The system input and system output devices are normally the console's keyboard and screen, but may be redirected with operating system commands or with the -i and -o runtime options. The "error output" device is normally the console screen, but may be redirected with the -e runtime option.

  3. The SYMBOLIC CHARACTERS clause defines symbolic characters. A symbolic character is a user-defined figurative constant and can be used anywhere a figurative constant may be. For each name, the character it represents is set to the character whose ordinal position in the native character set is specified by the corresponding number. Note that the ordinal position of a character is one greater than its internal representation. Thus a carriage-return character in ASCII (internal value of "13") would be specified as ordinal position "14".
  4. The CLASS clause defines a class name. A class name is used in a class test to determine whether or not a data item entirely consists of a certain set of characters.

    The class name must be unique in the source context. Make sure that there is no name clash between the class name and reserved COBOL words, user-defined variables, enumerators, events, or methods. This is particularly important for COM objects, ActiveX controls, and .NET assemblies, which may have enumerators that use the same identifier as a class name they define. If there is a name clash, rename the class, or if possible, the other element to make the class name unique. Otherwise compiler errors may result. We suggest prefixing ActiveX and .NET class names with an "@" sign to avoid ambiguities.

    For each numeric literal specified in the CLASS clause, the value of the literal specifies the ordinal number of the character in the native character set to include in the class. For example, "33" would refer to the space character (decimal value 32) in the ASCII character set.

    For each alphanumeric literal, the value of the character or characters in the literal specifies the characters to include in the class.

    If the THROUGH phrase is used, lit-1 and lit-2 must be numeric literals or alphanumeric literals containing only one character. The set of contiguous characters between lit-1 and lit-2 (inclusive) is included in the class. The two literals may be specified in either ascending or descending order.

  5. The CURRENCY SIGN clause specifies the PICTURE clause currency symbol. It can be any character from the computer's character set.
  6. If no CURRENCY SIGN clause is present, the dollar sign is used.
  7. The DECIMAL-POINT IS COMMA clause exchanges the functions of the comma and the period in PICTURE clauses and numeric literals.
  8. The NUMERIC SIGN clause specifies that all USAGE DISPLAY numeric data items in the program that do not have an explicit SIGN clause should be treated as if they had a SIGN TRAILING SEPARATE clause. A compile-time option exists to do the same thing. This is usually done to match the behavior of other COBOL systems.
  9. The CONSOLE IS CRT clause causes the compiler to assume that:
    • UPON CRT is specified for every DISPLAY statement that does not have an UPON phrase
    • FROM CRT is specified for every ACCEPT statement that does not have a FROM phrase

    This causes DISPLAY and ACCEPT statements without explicit UPON or FROM phrases to interact with the Micro Focus Window Manager instead of with the low-level (ANSI-style) console driver. Note that CONSOLE IS CRT is automatically implied by the compiler unless the -Ca compiler option is used. If CONSOLE IS CRT is present in a program compiled with -Ca, CONSOLE IS CRT takes precedence.

  10. The CURSOR clause specifies the name of a data item that will be used to control the console's cursor position throughout the program. If the cursor-name data item is four characters long, the first two characters are the cursor's line number, and the last two characters are the column number. If cursor-name is six characters long, the row and column numbers are each three characters long.

    At the beginning of each ACCEPT statement, cursor-name should specify a location in one of the fields being entered. If it does, the cursor will begin the ACCEPT statement at that location. If cursor-name does not specify a valid position, and more than one field is being entered by the ACCEPT statement, the cursor will start at the beginning of the next valid field (the next field described in the Screen Section definition of the screen-name referenced in this ACCEPT). If the cursor position is past the last field, or before the first field, the cursor will be placed at the beginning of the first field.

    At the conclusion of the ACCEPT statement, the cursor's final location will be placed in cursor-name.

    Note: The Micro Focus runtime system will limit the placement of the cursor in some circumstances. It will not place a cursor past the end of valid data in a field. In this case, the cursor will be placed as close to the requested position as possible. Also note that if you specify a CURSOR clause in SPECIAL-NAMES, you must initialize the cursor location prior to every ACCEPT statement.

    If you specify a CURSOR clause in SPECIAL-NAMES, you may not use the CURSOR phrase of the ACCEPT statement, because this would lead to multiple specification of the initial cursor position.

    If you don't initialize cursor-name with numeric data, you'll receive a nonnumeric data warning message on your first ACCEPT statement.

    The cursor may not start over a prompt character (except at the beginning of a field), unless that prompt character is a space.

    The following code demonstrates how a CURSOR clause could be used with a Format 1 ACCEPT statement:

    identification division.
    program-id. testcurs.
    ***  This program shows how the CURSOR clause 
    ***  can be used with a Format 1 ACCEPT statement.
    environment division.
    configuration section.
    special-names.
        cursor is cursor-name.
    data division.
    working-storage section.
    
    01  cursor-name.
        05  c-line      pic 9(3).
        05  c-col       pic 9(3).
    
    01  accept-field    pic x(10) value "abcdefghij".
    procedure division.
    main-logic.
    
    display window erase.
    
    display accept-field line 6 col 6.
    
    ***  Position the cursor over the "c" in the value 
    ***  of accept-field, which is the eighth column 
    ***  on the screen.
    
       move 6 to c-line.
       move 8 to c-col.
       accept accept-field line 6 col 6 update.
       stop run.
  11. The CRT STATUS phrase provides a method for returning the termination status of every ACCEPT statement. At the end of each ACCEPT statement, status-name is filled in with information regarding how the ACCEPT terminated. Two forms of status values are supported. One form is a three-character group item in which each character is treated as a key that contains various information. The second form is a simple numeric value in which each status condition is identified by a unique numeric value. The next two rules describe these two forms.
  12. If status-name is a numeric data item, a unique value will be moved to this item at the end of each ACCEPT statement. This value is the same as the CONTROL KEY value described in the ACCEPT statement. See the discussion of the CONTROL KEY phrase in Procedure Division Statements for details on which values are returned.
  13. If status-name is a group item, the first two characters are assigned values according to the following table:
    Key 1 Key 2 Meaning
    '0' '0' Termination key pressed
    '0' '1' Auto-skip out of last field
    '1' x'00' - x'FF' Exception key pressed
    '2' x'00' End-of-file key pressed
    '3' x'00' Statement timed out
    '9' x'00' No items fall within screen

    If Key 1 is 1, Key 2 contains the exception key value of the key that was pressed. See Procedure Division Statements for a table of key values.

    The third character always contains the same value that is returned by the CONTROL KEY phrase of the ACCEPT statement, if this value is in the range of 0 to 255. This is the same value returned when status-name refers to a numeric data item instead of a group item (rule 12 above).

    When Key 1 is set to "0", a normal termination has occurred. Any other value indicates an exception condition.

    Note: This form of the CRT STATUS phrase is provided for compatibility with the X/Open COBOL specification, as well as for compatibility with some other COBOL systems. This method of determining the status of an ACCEPT statement differs in several details from the other methods of determining the ACCEPT status supported by Micro Focus. In particular, the other methods return a single numeric value to describe the status (same as the value stored in Key 3). We recommend that only one technique be used to test for the ACCEPT status to avoid confusion. The following table summarizes the various statements and phrases available to return an ACCEPT statement's status.
    Status Statement Status Type
    CRT STATUS group-item 3-byte key
    CRT STATUS numeric-item Numeric value
    CONTROL KEY IS item Numeric value
    ACCEPT item FROM ESCAPE Numeric value
    ON EXCEPTION item Numeric value

    Also note that the formation of Key 2 is tricky. In the case of a normal termination, Key 2 will contain a normal COBOL character digit, but in the other cases, it will contain a binary value. The easiest way to test the status value is to use hexadecimal constants to express the binary value. Alternately, you can declare Key 2 to be COMP-X and test the exception values against numeric literals. Note that some other COBOL systems define Key 2 to be PIC 99 COMP. If you convert programs that use this construct, be sure to use the -D1 or -Dm compile-time flags to cause this data item to be stored in one character. If you do not do this, Key 2 will occupy two characters and return invalid values.

  14. The ALPHABET clause specifies the alphabet to be used for character translations and collating sequences.

    An alphabet may be used in the following circumstances:

    • In the CODE-SET phrase of a sequential file's FD. The alphabet specifies a character translation map. A Format 2 alphabet may not be used for this purpose.
    • In the COLLATING SEQUENCE phrase of an indexed file's SELECT. This specifies an alternate collating sequence for the file's keys.
    • In the COLLATING SEQUENCE phrase of a SORT or MERGE statement. Here, the alphabet specifies the collating sequence to use for key comparisons.
    • In the PROGRAM SEQUENCE phrase of the OBJECT-COMPUTER paragraph. This specifies the collating sequence for any alphanumeric comparisons done in the program. It also specifies the default collating sequence for SORT and MERGE verbs. The character that is first in the program collating sequence is treated as the LOW-VALUES character for the program. The character that is last in the program collating sequence is treated as the HIGH-VALUES character for the program. The one exception to this is that in Special-Names, LOW-VALUES and HIGH-VALUES always refer to the first and last characters in the native collating sequence.
    • In a SYMBOLIC CHARACTERS clause in SPECIAL-NAMES, to indicate the alphabet to which the symbolic character belongs.

    A Format 2 alphabet is used to describe a collating sequence. Explicitly named characters are listed in the order of their positions in the new collating sequence.

    Any characters in the native collating sequence that are not explicitly named in the ALPHABET clause assume a position greater than any of the explicitly named characters. The relative order of these unnamed characters remains the same as in the native collating sequence.

    If a literal in the ALPHABET clause is numeric, it designates a character by specifying that character's ordinal position in the native character set. For example, 66 would designate the letter A in the ASCII character set.

    If the literal is alphanumeric, it is the actual character. For alphanumeric literals that contain more than one character, the characters are assigned successive ascending positions in the new collating sequence.

    Here's an example :

       ALPHABET TINY IS "01", "Z", "AB", SPACE

    This alphabet contains 6 characters. Character 0 is the first character in the sequence, character 1 is the second. Character "Z" is the third, and characters "A" and "B" are the fourth and fifth. The space character is the sixth character. If you were to sort a file using this alphabet, all items that started with "Z" would appear before items that started with "A" or "B". Anything that started with a space would be last.

    Any characters in the native collating sequence that are not explicitly named assume a position in the new collating sequence greater than any of the explicitly named characters. The relative order of these characters remains unchanged from the native collating sequence. In the example above, this means that anything that starts with "C" comes after anything that starts with spaces, and anything starting with "D" comes after "C".

    If the THROUGH phrase is specified, the set of contiguous characters in the native character set beginning with literal-1 and ending with literal-2 are assigned successive ascending positions in the new collating sequence. The THROUGH phrase may specify characters in ascending or descending sequence.

    For example, the following alphabet will sort the alphabetic characters backwards:

    ALPHABET REV-ALPHA IS "Z" THROUGH "A", 
               "z" THROUGH "a"

    If the ALSO phrase is specified, literal-1 and literal-3 are assigned the same position in the collating sequence. This is one of the most useful capabilities of the Format 2 ALPHABET clause. For example, the following alphabet will cause the upper case and lower case of each letter to be treated as the same character for sorting:

    ALPHABET NO-CASE IS 1 THRU 65,   'A' ALSO 'a', 
    'B' ALSO 'b',   'C' ALSO 'c',   'D' ALSO 'd', 
    'E' ALSO 'e',   'F' ALSO 'f',   'G' ALSO 'g', 
    'H' ALSO 'h',   'I' ALSO 'i',   'J' ALSO 'j', 
    'K' ALSO 'k',   'L' ALSO 'l',   'M' ALSO 'm', 
    'N' ALSO 'n',   'O' ALSO 'o',   'P' ALSO 'p', 
    'Q' ALSO 'q',   'R' ALSO 'r',   'S' ALSO 's', 
    'T' ALSO 't',   'U' ALSO 'u',   'V' ALSO 'v', 
    'W' ALSO 'w',   'X' ALSO 'x',   'Y' ALSO 'y', 
    'Z' ALSO 'z'

    The "1 THRU 65" phrase causes the portion of ASCII that exists in front of "A" to be sorted in its normal sequence ("A" is the 66th character in ASCII). Then each lower-case character is mapped to its corresponding upper-case character. The remaining characters then follow implicitly.

  15. The following IBM DOS/VS COBOL system names are supported by Micro Focus in the SPECIAL-NAMES paragraph if the -Cv compiler option is used:
       SYSPCH
       SYSPUNCH
       C01 through C12
       CSP
       S01 through S05

    To enable printing to printer channels C01-C12, set the runtime configuration variable COBLPFORM as described in Appendix H in the ACUCOBOL-GT Appendices manual.

    For more information about IBM DOS/VS COBOL conversions, see IBM DOS/VS COBOL Conversions in Transitioning to ACUCOBOL-GT.

  16. The following HP COBOL special names are supported by Micro Focus in the SPECIAL-NAMES paragraph if the -Cp compiler option is used:
       NO SPACE CONTROL
       TOP

    For more information, see HP COBOL Conversions, in Transitioning to ACUCOBOL-GT.

General Rules - Screen Control Entry

In the following rules, the four elementary items belonging to the SCREEN CONTROL group item are referenced by the names in this example:

01 SCREEN-CONTROL.
   03  ACCEPT-CONTROL    PIC 9.
   03  CONTROL-VALUE     PIC 999.
   03  CONTROL-HANDLE    USAGE HANDLE.
   03  CONTROL-ID        PIC X(2) COMP-X.
  1. The following statement allows an embedded procedure to control its ACCEPT statement:
    [ SCREEN CONTROL IS control-name ]

    See PROCEDURE Clause and Using Screen Section Embedded Procedures for more information.

  2. Input and update fields in a Screen Section entry are given field numbers.* The compiler computes the field number for any Screen Section entry by examining all of the input and update fields in that entry’s level 01 group item. Each input and update field in a level 01 Screen Section entry is numbered sequentially, starting at one. For example, consider the following Screen Section entry:
    01 SCREEN-1.
       03 LITERAL-1 VALUE "Field 1: ". 
       03 FIELD-1, PIC X(5) TO WS-1.
       03 LITERAL-2 VALUE "Some data: ", LINE + 1. 
       03 DATA-1, PIC X(5) FROM WS-2.
       03 LITERAL-3 VALUE "Field 2: "., LINE + 1. 
       03 FIELD-2, PIC X(5) USING WS-3.

    This Screen Section entry has two input or update fields: FIELD-1 and FIELD-2. In this case, FIELD-1 is field number 1 and FIELD-2 is field number 2. Note that LITERAL-1, LITERAL-2, and DATA-1 do not receive field numbers because they do not contain a TO or USING phrase—DATA-1 is a display-only (FROM) field. The literals prompt the end user for entries.

    *Graphical controls in the Screen Section are also assigned field numbers. The rules that govern how field numbers are assigned to graphical controls are given in general rule 6 of the Format 2 Screen Description, in Screen Description Entry.

  3. Prior to executing an embedded procedure, an ACCEPT statement initializes the SCREEN CONTROL variable. It sets ACCEPT-CONTROL depending on the reason for entry (if it is a notify (“NTF-…”) event, ACCEPT-CONTROL is set to 1; otherwise, the default is 0), and it sets CONTROL-VALUE to the field number of the Screen Section entry that is executing the embedded procedure.

    On entry to an embedded procedure, CONTROL-HANDLE contains the handle of the current control, and the CONTROL-ID field contains its ID. If the current Screen Section item (the one that names the embedded procedure) is not a graphical control, CONTROL-HANDLE and CONTROL-ID are set to NULL and 0, respectively. See PROCEDURE Clause for more information.

    When the ACCEPT statement terminates, it sets ACCEPT-CONTROL to 0 and sets CONTROL-VALUE to the field number of the last field to have the cursor. This will be zero if the Screen Section entry contains no fields. CONTROL-HANDLE and CONTROL-ID fields contain the handle and ID of the graphical control that was active when the ACCEPT terminated. If the ACCEPT terminated while in a textual (i.e., non-graphical) field, they are set to NULL and 0, respectively.

  4. When an after procedure or exception procedure returns control to its ACCEPT statement, the value of SCREEN CONTROL determines what happens next. By setting this value in your after or exception procedure, you can cause the program to skip fields, continue ACCEPTING data, or terminate the ACCEPT with or without an exception. ACCEPT-CONTROL serves as a flag that is checked to determine how to proceed; SCREEN-CONTROL provides a needed value, as shown in this list:
    1. If ACCEPT-CONTROL is 0, the ACCEPT statement continues normally.
    2. If ACCEPT-CONTROL is 1, the ACCEPT statement moves the cursor to the field identified by the value of CONTROL-VALUE. The ACCEPT statement then continues from there.
    3. If ACCEPT-CONTROL is 2, the ACCEPT statement terminates normally. The value of CONTROL-VALUE determines the termination value of the ACCEPT statement. You can determine its value by examining CRT STATUS or by using the ACCEPT FROM ESCAPE KEY verb.
    4. If ACCEPT-CONTROL is 3, the ACCEPT statement terminates with an exception, assuming that exceptions are allowed. The value of CONTROL-VALUE sets the exception value of the ACCEPT statement. You may use CRT STATUS or the ACCEPT FROM ESCAPE KEY verb to determine the statement’s exception value.
    5. If ACCEPT-CONTROL is 4, control is transferred to the graphical control whose ID matches CONTROL-ID. This works identically to setting ACCEPT-CONTROL to 1, except that the CONTROL-ID field is used and the search is made using the control’s ID instead of the field numbers.
    6. If none of the preceding applies, the ACCEPT statement continues normally.
  5. If you set ACCEPT-CONTROL to 1, several special cases exist:
    1. If you set CONTROL-VALUE to zero, the ACCEPT statement will remain in the current field.
    2. If you set CONTROL-VALUE to a field number that does not exist, the ACCEPT statement will terminate. In this case, the CRT STATUS value for the ACCEPT statement will be zero for a numeric CRT STATUS or 0, 2, x00 for a group-item CRT STATUS.
    3. If you set CONTROL-VALUE to the field number of a protected field, control will pass to the first unprotected field with a higher field number. If no such field exists, the ACCEPT statement will terminate as in case (b) above.
  6. When a Screen Section ACCEPT statement executes, it examines the value of SCREEN CONTROL. If the ACCEPT-CONTROL field is 1, then the ACCEPT statement starts at the field identified by CONTROL-VALUE. This overrides any initial field identified by the CURSOR Special-Names entry. Note that this is usually easier than using the CURSOR clause to identify a starting point in a Screen Section ACCEPT. If the specified field does not exist (or is protected) the cursor is placed at the numerically closest legal field. If two fields are equally close, the one with the larger field number is used.

General Rules - Event Status Entry

EVENT-STATUS is used to identify which data item is to receive information about screen events.

In the description below, the seven elementary items belonging to the EVENT-STATUS group item are referenced by the names in this example:

01 EVENT-STATUS.
   03 EVENT-TYPE           PIC X(4) COMP-X.
   03 EVENT-WINDOW-HANDLE  USAGE HANDLE OF WINDOW.
   03 EVENT-CONTROL-HANDLE USAGE HANDLE.
   03 EVENT-CONTROL-ID     PIC X(2) COMP-X.
   03 EVENT-DATA-1         USAGE SIGNED-SHORT.
   03 EVENT-DATA-2         USAGE SIGNED-LONG.
   03 EVENT-ACTION         PIC X COMP-X.

When a system event occurs during an ACCEPT statement, the EVENT-STATUS data item is filled with the following information:

Holds a value that uniquely identifies the kind of event that occurred.

Holds the handle of the floating window in which the event occurred. If the event occurred in a control, this will be the handle of the floating window that contains the control.

Holds the handle of the control in which the event occurred. If the event did not occur in a control, this item is set to NULL.

Holds the ID of the control in which the event occurred. IDs are assigned by the application when each control is created. If the event did not occur in a control, this item will have the value zero.

Holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.

Also holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.

Holds a value that determines the continued handling of an event when an event procedure terminates. On entry to the procedure, EVENT-ACTION is set to zero. The following values are meaningful on exit from the procedure (symbolic names in acugui.def):

EVENT-ACTION-NORMAL (value 0) The event is processed normally, causing the control to terminate for terminating events.
EVENT-ACTION-TERMINATE (value 1) The event is processed normally, and then it terminates the active control. This action forces termination of events that do not normally terminate.
EVENT-ACTION-CONTINUE (value 2) The event is processed normally, but it does not terminate the active control, even if it would ordinarily do so.
EVENT-ACTION-IGNORE (value 3) The event is not processed further, but it does not terminate the active control. We do not recommend this action because it short-circuits the runtime’s event handler. Events receive a certain amount of processing before the event procedure is entered. Ignoring an event does not prevent this processing from occurring.
EVENT-ACTION-FAIL (value 4) This setting is used in response to certain events to indicate that a specific action should be taken, usually to prevent the event from taking its normal action. Events that use this setting state that they do so in the event description, along with a description of the effects of setting it.
EVENT-ACTION-TERMINATE (value 7) The effect of this setting is exactly the same as that of EVENT-ACTION-FAIL with the additional effect of EVENT-ACTION-TERMINATE: after performing the “fail” operation, the control terminates with an exception status of W-EVENT.
EVENT-ACTION-FAIL-TERMINATE

Certain screen controls produce events that understand the special EVENT-ACTION setting of EVENT-ACTION-FAIL. This setting usually causes the control to process the event in a special fashion. For example, setting EVENT-ACTION-FAIL in response to a MSG-GOTO-CELL-MOUSE event for the grid control prevents the cursor from entering the cell the user clicked.

Returning EVENT-ACTION-FAIL to a control and have that event also terminate the control. To do this, set EVENT-ACTION to EVENT-ACTION-FAIL-TERMINATE.

Like EVENT-ACTION-TERMINATE, the effect of this setting is exactly the same as that of EVENT-ACTION-FAIL with the additional effect of EVENT-ACTION-TERMINATE: after performing the “fail” operation, the control terminates with an exception status of W-EVENT.

However, this setting also corrects another issue. In earlier versions, the ACCEPT-CONTROL field of the SCREEN CONTROL item was set to 1 when entering an exception procedure that was triggered by a message-style event (any event that starts with MSG- in its name). Normally, message-style events do not cause termination and so the exception procedure is not entered. However, when you set EVENT-ACTION to EVENT-ACTION-TERMINATE, the control terminates and the exception procedure is entered. Having ACCEPT-CONTROL set to 1, however, meant that as soon as the exception procedure terminated, the control would reactivate. You had to explicitly override this by setting ACCEPT-CONTROL to 0 in the exception procedure.

This two-step process to terminate a control in the Screen Section is difficult to remember and generally unclear. This has been corrected so that the default ACCEPT-CONTROL value in this case is 0 instead of 1. This means that when setting EVENT-ACTION to EVENT-ACTION-TERMINATE or EVENT-ACTION-FAIL-TERMINATE, the ACCEPT statement terminates with an exception once the exception procedure completes.

Since this is a change to the semantics of ACUCOBOL-GT, you can inhibit this change by compiling with semantic compatibility for an earlier version of the product (prior to 4.3). For example, you can inhibit this by compiling with -C42. Note that object files produced by earlier versions of the compiler do not see this change.