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 ].
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: 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 4 or 6 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 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", then 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 |
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.
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, then 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 except:
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:
This causes DISPLAY and ACCEPT statements without explicit UPON or FROM phrases to interact with the ACUCOBOL-GT 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, then 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, then 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, then 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, then 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.
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 where each character is treated as a "key" that contains various information. The second form is a simple numeric value where 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, then 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. For details on which values are returned, see the discussion of the CONTROL KEY phrase in section 6.6 of this manual.
13. If status-name is a group item, then 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 |
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.
| 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 |
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:
a) 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.
b) In the COLLATING SEQUENCE phrase of an indexed file's SELECT. This specifies an alternate collating sequence for the file's keys.
c) In the COLLATING SEQUENCE phrase of a SORT or MERGE statement. Here the alphabet specifies the collating sequence to use for key comparisons.
d) 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.
e) 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, then 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 ACUCOBOL-GT in the SPECIAL-NAMES paragraph if the "-Cv" compiler option is used:
SYSPCH
SYSPUNCH
C01 through C12
CSP
S01 through S05
See Appendix G, "IBM DOS/VS COBOL Compatibility", for more information.
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 ]
For more information, see section 5.9.6, "PROCEDURE Clause," and the User's Guide section 6.5.5, "Using Screen Section Embedded Procedures."
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.
3. Prior to executing an embedded procedure (see section 5.9.6), 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.
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 embedded procedure returns control to its ACCEPT statement, the value of SCREEN CONTROL determines what happens next. By setting this value in your embedded 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:
a) If ACCEPT-CONTROL is 0, the ACCEPT statement continues normally.
b) 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.
c) 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.
d) 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.
e) 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.
f) If none of the preceding applies, the ACCEPT statement continues normally.
5. If you set ACCEPT-CONTROL to 1, several special cases exist:
a) If you set CONTROL-VALUE to zero, the ACCEPT statement will remain in the current field.
b) 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", x"00" for a group-item CRT STATUS.
c) 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-STATUSis 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:
EVENT-TYPE holds a value that uniquely identifies the kind of event that occurred. The valid types are described in chapter 6, Book 2, "User Interface Programming."
EVENT-WINDOW-HANDLE 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.
EVENT-CONTROL-HANDLE 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.
EVENT-CONTROL-ID 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.
EVENT-DATA-1 holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.
EVENT-DATA-2 also holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.
EVENT-ACTION 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-FAIL-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.