The Special-Names Paragraph

The Special-Names paragraph provides a means for specifying the currency string and the currency symbol, choosing the decimal point,

specifying symbolic-characters,

relating implementor-names to user-specified mnemonic-names, relating alphabet-names to character sets or collating sequences, and relating class-names to sets of characters.

You can select one of several pre-defined parameter passing conventions. Enhancements to the CALL statement and the PROCEDURE DIVISION header allow these parameter passing conventions to be used in inter-program communication.

General Format

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
   • ALPHASTART - determines whether valid numeric literals used in the ALPHABET clause can begin with 0 or with 1.
   • CHARSET - impacts which alphabet is considered the native character set. This directive is ignored in some environments.
   • NATIVE - impacts which alphabet is considered the native character set.
   • SYMBSTART - determines whether valid numeric literals used in the SYMBOLIC CHARACTERS clause can begin with 0 or with 1.

Syntax Rules

1. The clauses in the Special-Names paragraph may appear in any order.
2. At the outer level of a source unit that defines a class, the CURSOR and CRT STATUS clauses must not be specified.
3. In the factory or object of a class definition, the only clauses that can be specified are the CURSOR and CRT STATUS clauses.
4. If the Special-Names paragraph is specified in an interface definition, the ALPHABET, CURRENCY and DECIMAL-POINT clauses are the only permitted clauses.
5. Mnemonic-names can be any COBOL user-defined word. At least one constituent character must be alphabetic.
6. Function-name refers to a system device or function used by your COBOL system.

   Function-name refers to an external switch if its name is one of UPSI-0 through UPSI-7.

7. If function-name references an external switch

   or the SWITCH-n is used,
   

   the associated mnemonic-name cannot be specified anywhere

   except in the SET statement
   

   . At least one condition-name should be associated with it.

   No condition-name is required.

8. If function-name does not reference an external switch, the associated mnemonic-name can be specified only in the ACCEPT, DISPLAY, SEND or WRITE statements. A condition-name cannot be associated with such an implementor-name.
9. The literals specified in the literal phrase of the alphabet-name-1 clause:
   1. If numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.

      The lowest valid values for numeric literals in the ALPHABET clause are sensitive to the ALPHASTART Compiler directive.

   2. If nonnumeric and associated with a THROUGH or ALSO phrase, must each be one character in length.
   3. Cannot be specified as floating-point literals or DBCS literals.
10. If the literal phrase of the alphabet-name-1 clause is specified, a given character must not be specified more than once in an alphabet-name clause.
11. The words THRU and THROUGH are equivalent.
12. The words STANDARD-1 and ASCII are equivalent.
13. The reserved word IS is never required in the Special-Names paragraph.
14. The literals specified in the literal-4 phrase:
    1. If numeric, must be unsigned integers and must have a value within the range of one (1) through the maximum number of characters in the native character set.
    2. If nonnumeric and associated with a THROUGH phrase, must each be one character in length.
    3. Cannot be specified as floating-point or DBCS literals.
15. Literal-1, ... literal-5 must not specify a symbolic-character figurative constant.
16. The same symbolic-character-1 must appear only once in a SYMBOLIC CHARACTERS clause.
17. The relationship between each symbolic-character-1 and the corresponding integer-1 is by position in the SYMBOLIC CHARACTERS clause. The first symbolic-character-1 is paired with the first integer-1, the second symbolic- character-1 is paired with the second integer-1; and so on throughout the SYMBOLIC CHARACTERS clause; the division into IS or ARE phrases is documentary only.

    The lowest valid value for integer-1 is sensitive to the SYMBSTART Compiler directive.

18. There must be a one-to-one correspondence between occurrences of symbolic-character-1 and occurrences of integer-1, both within each IS or ARE phrase and within the entire SYMBOLIC CHARACTERS clause.
19. The ordinal position specified by integer-1 must exist in the native character set. If the IN phrase is specified, the ordinal position must exist in the character set named by alphabet-name-2; alphabet-name-2 must be described in an ALPHABET clause.
20. Literal-6 must be an alpnanumeric literal .

    or national literal
    .

21. Literal-6 must not be a figurative constant.
22. If the PICTURE SYMBOL phrase is not specified, literal-6 must consist of a single character that is not one of the following:
    • digits 0 through 9;
    • alphabetic characters A, B, C, D, L, P, R, S, V, X, Z, or their lower-case equivalents; or the space;
      • C and R can be used.
      • L can be used.
      • E cannot be used.
      • N cannot be used.
      • G cannot be used.
      • no lower-case alphabetic characters can be used.
      • lower-case alphabetic characters can be used except for those explicitly prohibited by this rule.
    • characters '+' '-' ',' '.' '*' '/' ';' '(' ')' '"' '='.
23. If the PICTURE SYMBOL phrase is specified, literal-6 may have any length and:
    1. must contain at least one nonspace character and
    2. may consist of any characters from the computer's coded character set except for the digits 0 through 9 and the characters '+' '-' ',' '.' '*'.
24. Literal-7 must be an alphanumeric literal consisting of a single character. It must not be a figurative constant. No two occurrences of literal-7 may be the same value.
25. Literal-7 may be any character from the computer's coded character set except for the following:
    • digits 0 through 9;
    • alphabetic characters A, B, C, D, E, N, P, R, S, V, X, Z, or their lower-case equivalents; or the space;
      • C and R can be used.
      • G cannot be used.
    • characters '+' '-' ',' '.' '*' '/' ';' '(' ')' '"' '='.
26. If literal-6 is of class alphanumeric, the associated currency symbol may be used only to define a numeric-edited item with usage display.

    If literal-6 is of class national, the associated currency symbol may be used only to define a numeric-edited item with usage national.

27. Integer-2 must be an unsigned integer in the range 0 to 65535.
28. Data-name-1 of the CURSOR IS clause must be declared in the Working-Storage Section .
29. The CRT STATUS clause specifies a data item into which a status value is moved after each Format 4

    or Format 5
    

    ACCEPT statement. In some environments, it can be defined only in the first 64K of working storage.

30. Data-name-2 must be described in the Working-Storage Section and must be three bytes long.
31. The CURSOR IS clause specifies the data item to contain the cursor address as used by the ACCEPT statement.

General Rules

1. External switches are set at run time by the operator, and the setting can be determined by testing the associated condition-names.
2. If mnemonic-name is associated with an external switch, the status of that switch can be altered by execution of a Format 1 SET statement (see the topic The SET Statement).
3. The alphabet-name-1 clause provides a means for relating a name to a specified character code set and/or collating sequence. When alphabet-name-1 is referenced in the PROGRAM COLLATING SEQUENCE clause (see the topic The Object-Computer Paragraph) or the COLLATING SEQUENCE phrase of a SORT or MERGE statement (see the topic The SORT Statement or The MERGE Statement), the alphabet-name-1 clause specifies a collating sequence. When alphabet-name-1 is referenced in a CODE-SET clause in a file description entry (see the topic File Description Entry Skeleton), the alphabet-name clause specifies a character code set.
   1. If the STANDARD-1

      or ASCII
      

      phrase is specified, the character code set or collating sequence identified is the American Standard Code for Information Interchange, as defined in American National Standard X3.4-1968.

      If the STANDARD-2 phrase is specified, the character code set identified is the International Reference Version of the ISO 7-bit code, as defined in International Standard 646, 7-bit Coded Character Set for Information Processing Interchange.

      If the EBCDIC phrase is specified, the character code set or collating sequence identified is EBCDIC.

      If the NATIVE phrase is specified, the native character code set or native collating sequence is used. The native collating sequence is either ASCII or EBCDIC, as specified by the NATIVE Compiler directive.)

      See the appendix Character Sets and Collating Sequences for details of the ASCII code set and the ASCII and EBCDIC collating sequences and their correspondence.

   2. If the literal phrase is specified, alphabet-name-1 cannot be referenced in a CODE-SET clause (see the topic The CODE-SET Clause). The character code set and/or collating sequence identified is that defined according to the following rules:
      1. The value of each literal specifies:
         1. The ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.
         2. The actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal, starting with the leftmost character, is assigned successive ascending positions in the collating sequence being specified.
      2. The order in which the literals appear in the ALPHABET clause specifies, in ascending sequence, the ordinal number of the character within the collating sequence being specified.
      3. Any characters within the native collating sequence which are not explicitly specified in the literal phrase, assume a position, in the collating sequence being specified, greater than any of the explicitly specified characters. The relative order within the set of these unspecified characters is unchanged from the native collating sequence.
      4. If a character code set is being specified, for each character within the native character set that is not specified by the literal-1 phrase, the implementor defines the ordinal number within the character code set being specified.
      5. If the THROUGH phrase is specified, the set of contiguous characters in the native character set, beginning with the character specified by the value of literal-1, and ending with the character specified by the value of literal-2, is assigned a successive ascending position in the collating sequence being specified. In addition, the set of contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in either ascending or descending sequence.
      6. If the ALSO phrase is specified, the characters of the native character set specified by the value of literal-1, and literal-3 are assigned to the same position in the collating sequence being specified

         , or in the character code set that is used to represent the data
         

4. The character that has the highest ordinal position in the program collating sequence is associated with the figurative constant HIGH-VALUE

   except when this figurative constant is specified as a literal in the Special-Names paragraph
   .

   If more than one character has the highest position in the program collating sequence, the last character specified is associated with the figurative constant HIGH-VALUE.

5. The character that has the lowest ordinal position in the program collating sequence is associated with the figurative constant LOW-VALUE

   except when this figurative constant is specified as a literal in the Special-Names paragraph
   .

   If more than one character has the lowest position in the program collating sequence, the first character specified is associated with the figurative constant LOW-VALUE.

6. Floating-point literals cannot be used in a user-specified collating sequence.
7. When specified as literals in the Special-Names paragraph, the figurative constants HIGH-VALUE and LOW-VALUE are associated with those characters having the highest and lowest positions, respectively, in the native collating sequence.
8. The SYMBOLIC CHARACTERS clause is used to define user-defined words that can be used like figurative constants. If the IN phrase is not specified, symbolic-character-1 represents the character whose ordinal position in the native character set is specified by integer-1. If the IN phrase is specified, integer-1 specifies the ordinal position of the character that is represented in the character set named by alphabet-name-2.
9. The internal representation of symbolic-character-1 is the internal representation of the character that is represented in the native character set.
10. The CURRENCY SIGN clause is used to specify a currency string that is placed into numeric-edited data items when they are used as receiving items and de-edited from the data item when it is used as a sending item that has a numeric or numeric-edited receiving item. In addition, it is used to determine which symbol is used in a character-string of a basic format PICTURE clause to specify the presence of this currency string. This symbol is referred to as the currency symbol.

    Literal-6 represents the value of the currency string.

    If the CURRENCY SIGN clause is specified with the PICTURE SYMBOL phrase, literal-7 is used as the currency symbol.

    If the CURRENCY SIGN clause is specified without the PICTURE SYMBOL phrase, literal-6 is used as the currency symbol.

    If the currency symbol is a lower-case letter, it is treated as its upper-case equivalent.

    If this clause is not present, only the currency sign defined in the COBOL character set is used in the PICTURE clause. See the section Character Set in the chapter Concepts of the COBOL Language.

11. The DECIMAL-POINT IS COMMA clause means that the function of comma and period are exchanged in the character-string of the PICTURE clause and in numeric literals.
12. If the NUMERIC SIGN clause is specified, the default for signed numeric items is for the sign to be stored as a trailing separate character.
13. Wherever a mnemonic-name is allowed, you can use a function-name.
14. If function-name does not reference an external switch, it can be selected from the following list:

    TAB	Skip to vertical tabulation position (inserts ASCII X"0B" in the output record as appropriate)	WRITE ADVANCING statement
    PRINTER	Printer	DISPLAY statement
    FORMFEED	Skip to new page (inserts ASCII X"0C" in the output record as appropriate)	WRITE ADVANCING statement
    COMMAND-LINE	Command transfer	ACCEPT and DISPLAY statements
    ARGUMENT-NUMBER	Command-line argument number	ACCEPT and DISPLAY statements
    ARGUMENT-VALUE	Command-line argument value	ACCEPT statement
    ENVIRONMENT-NAME	Environment variable name	DISPLAY statement
    ENVIRONMENT-VALUE	Environment variable value	ACCEPT and DISPLAY statements
    SYSERR	Standard error device	DISPLAY statement

    The following table reflects the support for function names offered by OS/VS COBOL, VS COBOL II and SAA in this COBOL system.

    Table 1: Function Names Support

    	OSVS	VSC2 Rel (2)	COBOL/370 or VSC2 Rel (3)/(4)	SAA L1
    SYSIN	y	y	y	y
    SYSIPT	U	U	y
    SYSOUT	y	y	y	y
    SYSLIST			y
    SYSLST	U	U	y
    SYSPCH	U	U	y
    SYSPUNCH	U	y	y
    CONSOLE	y	y	y	y
    C01	y	y	y	y
    C02	y	y	y
    C03	y	y	y
    C04	y	y	y
    C05	y	y	y
    C06	y	y	y
    C07	y	y	y
    C08	y	y	y
    C09	y	y	y
    C10	y	y	y
    C11	y	y	y
    C12	y	y	y
    S01	y	y	y
    S02	y	y	y
    S03		U	y
    S04		U	y
    S05		U	y
    CSP	y	y	y	y
    1 char rw literal	y
    AFP-5A			y

    y	Documented and accepted by mainframe compilers and the COBOL system.
    U	Undocumented but accepted by mainframe compiler.

15. The CLASS clause provides a means for relating a name to the specified set of characters listed in that clause. Class-name-1 can be referenced only in a class condition. The characters specified by the values of the literals in this clause define the exclusive set of characters which constitute class-name-1. The value of each literal specifies:
    1. The ordinal number of a character within the native character set, if the literal is numeric. This value must not exceed the value which represents the number of characters in the native character set.
    2. The actual character within the native character set, if the literal is nonnumeric. If the value of the nonnumeric literal contains multiple characters, each character in the literal is included in the set of characters identified by class-name-1.

    If the THROUGH phrase is specified, the contiguous characters in the native character set beginning with the character specified by the value of literal-4, and ending with the character specified by the value of literal-5, are included in the set of characters identified by class-name-1. Additionally, the contiguous characters specified by a given THROUGH phrase can specify characters of the native character set in ascending or descending sequence.

16. All clauses specified in the Special-Names paragraph for a source element also apply to source elements contained within that source element. The condition-names, mnemonic-names, class-names, currency symbols, alphabet-names and symbolic-characters specified in the containing source element's Special-Names paragraph can be referenced from any contained source element.
17. The CALL-CONVENTION clause allows you to select one of several pre-defined parameter-passing conventions which allow you to CALL subprograms written in languages other than COBOL, and which use different parameter passing conventions.
18. The CONSOLE IS CRT clause causes any ACCEPT or DISPLAY statement whose operand is not a screen-name, and that has no phrases specific to a particular format, to be treated as Format 5. If the CONSOLE IS CRT clause is not present, these statements are treated as the standard ANSI ACCEPT or DISPLAY.
19. The CURSOR IS clause specifies the data item to contain the cursor address used by the ACCEPT statement.
    1. At the start of an ACCEPT statement, if data-name-1 contains a value that is a valid character position on the screen, that position is used as the initial position for the cursor. Otherwise, data-name-1 is ignored, and the initial position for the cursor is the start of the first input field on the screen. At the end of an ACCEPT statement, if the position in data-name-1 has been used in that statement, data-name-1 is updated to show the position of the cursor at the termination of the ACCEPT statement.
    2. CURSOR IS has no effect on the positioning of fields on the screen.
    3. Data-name-1 must be 4 or 6 characters in length. If data-name-1 is 4 characters in length, the first two characters are interpreted as line number, and the second two as column number. If data-name-1 is 6 characters in length, the first three characters are interpreted as line number, and the second three as column number.
    4. The clause has no effect if data-name-1 contains an illegal position (for example, zeros, a nonnumeric value, or a value that is beyond the bottom of the screen).
    5. If data-name-1 contains a valid position that does not correspond to an input field being accepted by the current ACCEPT statement, the cursor is positioned to the next such field or, if there is none, to the first such field. The ordering of the fields is the order in which their descriptions appear in the Data Division.
20. The CRT STATUS clause specifies a 3-byte data item, into which a status value is moved after each Format 4 or Format 5 ACCEPT statement.

    If the CRT STATUS clause is specified in the Special-Names paragraph, every Format 4 or 5 ACCEPT statement (as described later in this chapter) places a value into data-name-2 to indicate the outcome of the ACCEPT operation. Data-name-2 consists of status keys which are set to indicate possible conditions resulting from the completion of the operation. They are described below.

Examples:

1. An example of using the CRT status key fields is provided in the topic CRT STATUS Clause of the Special-Names Paragraph.