PreviousProcedure Division - Intrinsic Functions Procedure Division - ENTER - INVOKENext"

Chapter 12: Procedure Division - ACCEPT - DIVIDE

12.1 COBOL verbs

12.1.1 The ACCEPT Statement

The ACCEPT statement causes data keyed at the console or supplied by the operating system to be made available to the program in a specified data item.

General Formats

Format 1

Format 2

Format 3

Format 4

Format 5

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 semantics described in this section.

Syntax Rules

Format 1
  1. The mnemonic-name in Format 1 must be associated with a function-name in the SPECIAL-NAMES paragraph in the Environment Division. See General Rule 12 in the section The SPECIAL-NAMES Paragraph in this chapter for a list of valid function-names.

  2. Alternatively, function-name can itself be used instead of an associated mnemonic-name.

  3. When mnemonic-name is associated with ARGUMENT-NUMBER in the SPECIAL-NAMES paragraph, then identifier must be an unsigned integer.

  4. When mnemonic-name is associated with ARGUMENT-VALUE or ENVIRONMENT-VALUE in the SPECIAL-NAMES paragraph, then identifier must be an alphanumeric data item.

  5. Identifier can be a USAGE DISPLAY-1 (DBCS) item or an external floating-point data item.

    Identifier can be an internal floating-point data item.

  6. The EXCEPTION phrase may be specified only if FROM is specified with either ENVIRONMENT-NAME or ARGUMENT-VALUE, or with the mnemonic-names associated with them.
Format 2
  1. Identifier can be of any class, category or usage, including an internal floating-point or external floating-point item.
Format 3
  1. No restrictions apply to the class, category or usage of the identifier. However, the actual value placed into the identifier and the validity of moving such values to the identifier are dependent on the FROM clause. See the Format 3 General Rules for more information.
Format 4
  1. Screen-name cannot be an item with an OCCURS clause.
Formats 4 and 5
  1. The LINE and COLUMN phrases can appear in any order.

  2. EXCEPTION and ESCAPE are equivalent.

  3. Identifier-4 must be a PIC 9(4) or a PIC 9(6) data item.
Format 5
  1. Identifier-8 must be an integer. It can be signed.

  2. Integer-7 can be signed.

  3. An ACCEPT statement whose operand is not a screen-name is treated as a Format 5 ACCEPT statement if it has an AT phrase, a FROM phrase with the CRT option, a WITH phrase, a MODE IS BLOCK phrase, or an EXCEPTION phrase; or if it has no FROM phrase but the CONSOLE option clause is specified in the SPECIAL-NAMES paragraph. If it has the FROM phrase with the CONSOLE option, or if it has no FROM phrase and the CONSOLE IS CRT clause is not specified in the SPECIAL-NAMES paragraph, it is treated as a Format 1 ACCEPT statement.

  4. The phrases following the identifier can be in any order.

  5. The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY, PROMPT and TRAILING-SIGN options are allowed only if the operand is an elementary item.

  6. Elementary data items in identifier-1 must be of USAGE DISPLAY.

  7. No elementary item in identifier-1 may be longer than 8191 bytes. If the MODE IS BLOCK phrase is used, the whole of identifier-1 must be no longer than 8191 bytes.

General Rules

All Formats
  1. The END-ACCEPT phrase delimits the scope of the ACCEPT statement. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.) END-ACCEPT is treated as a reserved word only if the MF(4) Compiler directive is set.
Format 1
  1. The ACCEPT statement causes the transfer of data from the logical or physical device. This data replaces the content of the data item referenced by identifier. If the data item referenced by identifier has an explicit or implicit usage of DISPLAY then replacement is direct and without conversion, otherwise conversion into the correct format takes place.

    The size of a data transfer is determined by the device and the run-time environment (see The SPECIAL-NAMES Paragraph for a list of function-names that can be used and your COBOL system documentation for details of devices and the limits of data transfer sizes).

    If the device is capable of transferring data of the same size as the receiving data item, the transferred data is stored in the receiving data item. If otherwise, then:

    1. If the size of the receiving data item (or the portion not yet currently occupied by transferred data) exceeds the size of the transferred data, the transferred data is stored aligned to the left in the receiving data item (or the portion not yet occupied) and additional data is requested.

    2. If the size of the transferred data exceeds the size of the receiving data item (or portion not yet occupied by transferred data), only the leftmost characters of the transferred data are stored in the receiving data item (or in the portion remaining). The remaining characters of the transferred data which do not fit into the receiving data item are ignored.

    If the FROM option is not given, it is equivalent to specifying FROM CONSOLE.

  2. If the function-name COMMAND-LINE, or a mnemonic-name associated with the function-name COMMAND-LINE, is specified, the contents of a system-dependent command-line buffer are transferred to the receiving data item.

  3. If the mnemonic-name associated with the function-name ARGUMENT-NUMBER is used, identifier receives the number of arguments contained in the command line. (This includes all arguments, those before the program-name, the program-name itself, and any arguments following the program-name. Hence no portability from types of program invocation is expected.)

  4. When mnemonic-name is associated with ARGUMENT-VALUE, the current command-line argument is placed into identifier. The determination of which command-line argument is current is as follows:

    1. Initially, the first command-line argument is current.

    2. A DISPLAY upon a mnemonic-name associated with ARGUMENT-NUMBER sets the current command-line argument number to the value of the identifier or literal specified in the DISPLAY statement.

    3. When an ACCEPT statement from a mnemonic-name associated with ARGUMENT-NUMBER has been executed since the last execution of a DISPLAY statement upon a mnemonic-name associated with ARGUMENT-NUMBER, the current command-line argument number is incremented prior to its use in this ACCEPT statement.

    If the current command-line argument number is 0, it is intended that the program-name of the main program of the run unit will be returned. However, the effects of variations on program invocation can impact these results so that a utility or calling program can be returned instead.

    If the current command-line argument number

    is not in the range 0 to 99 inclusive or

    exceeds the number of arguments on the command line when this ACCEPT statement is executed, imperative-statement-1, if specified, will be executed.

  5. If the mnemonic-name associated with the function-name ENVIRONMENT-VALUE is used then,

    1. If a previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, the value of the designated environment-variable is placed into identifier.

    2. If no previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, or if the specified environment-variable does not exist, the imperative statement associated with an ON EXCEPTION phrase is executed. The value in identifier is undefined in this case.

  6. The effect of retrieving command line arguments and the number of arguments in a program that is called by another program is defined as the same as if they were retrieved by the first program in the run unit.
Format 2
  1. The ACCEPT statement causes the information requested to be transferred to the data item specified by identifier according to the rules of the MOVE statement. DATE, DAY,

    DAY-OF-WEEK,

    and TIME are conceptual data items and, therefore, are not described in the COBOL program.

  2. DATE, without the phrase YYYYMMDD, is composed of the data elements year of the current century, month of the year, and day of the month. DATE, without the phrase YYYYMMDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display six digits in length, the character positions of which, numbered from left to right, are:

    Char Contents
    1-2 The two right-most numeric characters of the year in the Gregorian calendar.
    3-4 Two numeric characters of the month of the year in the range 01 through 12.
    5-6 Two numeric characters of the day of the month in the range 01 through 31.

  3. DATE, with the phrase YYYYMMDD, is composed of the data elements year in the Gregorian calendar, month of the year, and day of the month. DATE, with the phrase YYYYMMDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display eight digits in length, the character positions of which, numbered from left to right, are:

    Char Contents
    1-4 Four numeric characters of the year in the Gregorian calendar.
    5-6 Two numeric characters of the month of the year in the range 01 through 12.
    7-8 Two numeric characters of the day of the month in the range 01 through 31.

  4. DAY, without the phrase YYYYDDD, is composed of the data elements year of the current century and day of the year. DAY, without the phrase YYYYDDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display five digits in length, the character positions of which, numbered from left to right, are:

    Char Contents
    1-2 The two right-most numeric characters of the year in the Gregorian calendar.
    3-5 Three numeric characters of the day of the year in the range 01 through 366.

  5. DAY, with the phrase YYYYDDD, is composed of the data elements year in the Gregorian calendar and day of the year. DAY, with the phrase YYYYDDD, when accessed by a COBOL program, behaves as if it had been described as an unsigned elementary integer data item of usage display seven digits in length, the character positions of which, numbered from left to right, are:

    Char Contents
    1-4 Four numeric characters of the year in the Gregorian calendar.
    5-7 Three numeric characters of the day of the year in the range 01 through 366.

  6. DAY-OF-WEEK is composed of a single data element whose content represents the day of the week. DAY-OF-WEEK, when accessed by a COBOL program, behaves as if it had been described in a COBOL program as an unsigned elementary numeric integer data item one digit in length. In DAY-OF-WEEK, the value 1 represents Monday, 2 represents Tuesday, ... , 7 represents Sunday.

  7. TIME is composed of the data elements: hours, minutes, seconds and hundredths of a second. TIME is based on elapsed time after midnight on a 24-hour clock basis - thus, 2:41 P.M. would be expressed as 14410000. TIME, when accessed by a COBOL program behaves as if it had been described in a COBOL program as an unsigned elementary numeric integer data item eight digits in length. The minimum value of TIME is 00000000; the maximum value of TIME is 23595999. If the hardware does not have the facility to provide fractional parts of TIME, the value is converted to the closest decimal approximation.

Format 3
  1. The value returned from the ACCEPT FROM LINE NUMBER phrase is always numeric. The value is implementation-dependent.

  2. The FROM USER NAME option returns a user-id number on UNIX systems, or spaces on systems where such a concept is meaningless.

  3. The FROM ESCAPE KEY option returns the two digit code generated by a termination key.

  4. The EXCEPTION STATUS item contains a three-digit numeric value that identifies the type of exception condition that has occurred during the execution of a CALL statement.

    If EXCEPTION STATUS is to be examined this should be done immediately following the CALL statement. There must be nothing between the CALL and ACCEPT FROM EXCEPTION STATUS. File I-O operations will alter the exception status value making it unpredictable.

Format 4
  1. This format of the ACCEPT statement accepts screen items,which are defined in the Screen Section of the program, and allows full access to the enhanced screen handling facilities.

Formats 4 and 5
  1. The order of execution of an ACCEPT statement is always:

    1. the AT phrase

    2. the BLANK phrase

    3. if either of the Compiler directives ACCEPTREFRESH or XOPEN are specified, the current contents of screen items with the USING phrase are displayed

    4. the BELL phrase

    5. the ACCEPT operation.

  2. The AT phrase gives the absolute address on the screen where the ACCEPT operation is to start.

  3. If integer-3 or identifier-4 is 4 digits long, the first two digits specify the line, the second two the column. If 6 digits long, the first three digits specify the line, while the second three specify the column.

  4. Certain combinations of line and column numbers have special meanings, as follows:

    1. Until the column comes within range, out of range column values are reduced by the line length and the line value is incremented.

    2. Out of range line values cause the screen to scroll up one line. The effect is the same as if the line number of the bottom line had been specified.

    3. If the line and column numbers given are both zero, the ACCEPT starts at the position following that where the preceding Format 4 or Format 5 ACCEPT operation finished. Column 1 of each line is considered to follow the last column of the previous line.

    4. If the line number is zero, but a non-zero column number is specified, the ACCEPT starts at the specified column, on the line following that where the preceding Format 4 or Format 5 ACCEPT operation finished.

    5. If the column number is zero, but a non-zero line number is specified, the ACCEPT starts on the specified line, at the column following that where the preceding Format 4 or Format 5 ACCEPT operation finished.

  5. Prior to the execution of this ACCEPT statement, a DISPLAY statement which specifies the same screen-name or identifier-1 as is specified in this ACCEPT statement must have been executed. There must not have been any ACCEPT or DISPLAY statement executed since then.

  6. Prior to the execution of this ACCEPT statement, a DISPLAY statement which specifies the same screen-name or identifier-1 as is specified in this ACCEPT statement must have been executed. There must not have been any ACCEPT or DISPLAY statement executed since then.

  7. If the ON EXCEPTION phrase is specified, imperative-statement-1 is executed if the ACCEPT operation finishes with anything other than a normal termination. If the NOT ON EXCEPTION phrase is specified, imperative-statement-2 is executed if the ACCEPT operation terminates normally. (See the section The CRT STATUS Clause earlier in this chapter for possible types of termination.)

Format 5
  1. The ACCEPT operation starts at line 1, column 1 if no AT phrase is specified.

  2. If identifier is a group item and no MODE IS BLOCK phrase exists, then those elementary subordinate items which have names other than FILLER are accepted. They are positioned on the screen in the order their descriptions appear in the Data Division and are separated by the lengths of the FILLER items in the group. For this purpose, the first position on a line is regarded as immediately following the last position on the previous line. The items are accepted in the same order.

    Unless otherwise specified in the CURSOR IS clause (see the section The CURSOR IS Clause earlier in this chapter), the cursor is initially positioned at the start of the first item. As the ACCEPT operation into each item is terminated, the cursor moves to the start of the next item.

  3. If identifier-1 is a group item that has a variable-occurrence data item subordinate to it, the ACCEPT statement acts as if the MODE IS BLOCK clause were specified.

  4. If identifier-1 is a group item that has a variable-occurrence data item subordinate to it, the ACCEPT statement acts as if the MODE IS BLOCK clause were specified.

  5. The MODE IS BLOCK phrase indicates that the identifier is to be treated as an elementary item. Thus, even if it is a group item it is displayed as one item.

  6. If the PROMPT option is not specified, no character is output to mark empty character-positions. PROMPT without the CHARACTER option causes this to be done, using the character configured for this purpose.

  7. If the PROMPT option is not specified, those character-positions into which the operator does not enter data produce spaces in the data item.

  8. The WITH phrase allows you to specify certain options available during the operation. (See The Screen Section earlier in this chapter for descriptions of these clauses.)

    In addition to the options available as screen description clauses, the following options can be used in the WITH phrase; SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY TRAILING-SIGN and UPDATE. ZERO-FILL appears in this list and as a screen description clause because it has two different uses. Its second use is documented later in this chapter.

    A configuration option is available which allows the entry of data into numeric and numeric edited screen fields in free format mode. In COBOL, nonedited numeric data items are intended for holding data in an internal form; however, this format enables such data items to appear on the screen. See your COBOL system documentation on user interfaces for more details. If free format mode is in effect, the data will appear automatically reformatted as follows:

    The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN options amend this format.

  9. The SPACE-FILL option causes data in free format nonedited numeric data items to appear on the screen with zero-suppression in all integer character positions. This option affects only free format, nonedited numeric data items. This takes effect when initial data in the data item is displayed and again when the ACCEPT operation into the data item is terminated. Any leading sign is displayed in the rightmost space.

  10. The ZERO-FILL option causes data in free format nonedited numeric data items to appear on the screen with no zero-suppression. This takes effect when initial data in the data item is displayed and again when the ACCEPT operation into the data item is terminated. (See the section The ZERO-FILL Clause earlier in this chapter for this option's effect when used with alphabetic or alphanumeric data items.)

  11. The LEFT-JUSTIFY option is documentary only.

  12. The RIGHT-JUSTIFY option causes operator-keyed characters to be moved on the screen to the rightmost character positions of the field. This option affects only free format nonedited numeric data items. This takes effect upon display of the initial data (the current contents displayed) in the data item and also upon termination of the ACCEPT operation.

  13. The TRAILING-SIGN option causes the operational sign to appear in the rightmost character position of the field. This takes effect upon display of initial data in the data item and also upon termination of the ACCEPT operation. This option affects only signed, nonedited numeric data items which are in free format mode.

  14. The UPDATE option causes the current contents (initial data) of the data item to be displayed before the operator is prompted to key in new input. If the operator does not key in any new data, the initial data is then treated as though it were operator-keyed. If the UPDATE option is not specified, the display of initial data is a configuration option. (See your COBOL system documentation on user interfaces for details of configuration options.)

  15. The WITH UPPER option forces input into upper case.

  16. The WITH LOWER option forces input into lower case.

  17. If REDEFINES is used with identifier-1, the first description of the redefined data area is used and subsequent descriptions are ignored. If OCCURS or nested OCCURS are used the repeated data item is expanded into the full number of times it occurs, so that one definition is repeated for many fields.

  18. If identifier-8 or integer-7 has a negative value, this represents a request that no time-out "exception" should occur no matter how long there is between/before key-strokes.

  19. If identifier-8 or integer-7 is zero, this indicates that a time-out should not occur if characters are waiting. However, if no characters are waiting (when the ACCEPT is processed), then issue a time-out immediately.

  20. The ON EXCEPTION clause, if present, will be executed when a time-out occurs and a TIME-OUT clause is specified. The NOT ON EXCEPTION clause, if present, will be executed when a TIME-OUT clause is specified but no time-out (or other exception) occurs.

  21. If a time-out exception occurs, then the contents of any ACCEPT resultant-field will be defined as follows:

    1. Any field which has been partially modified will contain any information which has already been received.

    2. Fields which have "FULL" or "REQUIRED" attributes or any other attribute which would normally impact partial field input, will NOT be required to meet those attributes when a partial field entry has occurred when a time-out exception occurs.

    3. The rules listed above apply whether or not the timeout clock is reset upon each keystroke.

  22. If at run time a positive timeout interval greater than 2,147,483,647 hundredths of a second is detected the timeout value will be reset to 2,147,483,647 hundredths of a second (which is approximately eight months).

  23. The TIME-OUT value specifies the number of seconds (or tenths of a second) after the ACCEPT statement begins processing until a time-out exception occurs. A new ADISCF configuration option controls whether or not the timeout clock is "reset" each time a new keyboard action is detected. An application which wants some ACCEPT statements to be handled with a RESET and some without, can make specific calls to the ADIS run-time interface before or after the ACCEPT statements that need changes from the default. For example when ADIS was configured not to do resets, if a program had:
     ACCEPT INPUT-FIELD TIME-OUT AFTER +10

    a timeout would occur after 10 seconds had elapsed from the beginning of the ACCEPT, even if some characters were entered after 5 seconds into the ACCEPT processing.

    If, on the other hand, ADIS were configured to do resets, if a program had the same code given above, then each time a new character were entered, the TIMEOUT "clock" would be reset to zero.

  24. If a timeout exception occurs and no ON EXCEPTION phrase is specified, the CRT Status keys (if specified) are updated, the application continues to the next logical phrase, and the contents of the ACCEPT receiving field are as defined above. (The above is true whether or not a NOT ON EXCEPTION phrase is specified.)

  25. All references to (NOT) ON EXCEPTION phrases also apply to (NOT) ON ESCAPE phrases.

Formats 1 and 5
  1. For alphanumeric data items, the size of the field that is accepted from the screen during an ACCEPT statement is exactly the same size as the target field. Therefore, if you want data to appear at the right hand side of a field, you must enter it there.

12.1.2 The ADD Statement

The ADD statement causes two or more numeric operands to be summed and the result to be stored.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

All Formats
  1. In Formats 1 and 2, each identifier must refer to an elementary numeric item, except that in Format 2 each identifier following the word GIVING must refer to either an elementary numeric item or an elementary numeric edited item. In Format 3, each identifier must refer to a group item.

  2. Each literal must be a numeric literal.

  3. The composite of operands must not contain more than 18 digits (see the section Arithmetic Statements earlier in this chapter).

    1. In Format 1 the composite of operands is determined by using all of the operands in a given statement.

    2. In Format 2 the composite of operands is determined by using all of the operands in a given statement excluding the data items that follow the word GIVING.

    3. In Format 3 the composite of operands is determined separately for each corresponding pair of data items.

  4. In Format 3, CORR is an abbreviation for CORRESPONDING.

  5. Floating-point literals and floating-point data items can be used anywhere a numeric data item or literal can be specified.

General Rules

All Formats
  1. See the section The ROUNDED Phrase, The ON SIZE ERROR Phrase, The CORRESPONDING Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in this chapter; the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language, and the section Delimited Scope Statements in the chapter Concepts of a COBOL Program.

  2. If Format 1 is used, the values of the operands preceding the word TO are added together, then this sum is added to the current value of identifier-2 storing the result immediately into identifier-2, and repeating this process respectively for each successive operand following the word TO in left-to-right order.

  3. If Format 2 is used, the value of the operands preceding the word GIVING are added together, then the sum is stored as the new value of each data item referenced by identifier-3, the resultant identifier.

  4. If Format 3 is used, data items in identifier-1 are added to and stored in corresponding data items in identifier-2.

  5. Your COBOL system ensures that enough places are carried so as not to lose any significant digits during execution.

12.1.3 The ALTER Statement

The ALTER statement modifies a predetermined sequence of operations.

The ALTER statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

Although it is a part of the standard COBOL definition, this verb is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Format

Syntax Rules

  1. Each procedure-name-1, procedure-name-3, ..., is the name of a paragraph that contains a single sentence consisting of a GO TO statement without the DEPENDING phrase.

  2. Each procedure-name-2, procedure-name-4, ..., is the name of a paragraph or section in the Procedure Division.

General Rules

  1. Execution of the ALTER statement modifies the GO TO statement in the paragraph named procedure-name-1, procedure-name-3, ..., so that subsequent executions of the modified GO TO statements cause transfer of control to procedure-name-2, procedure-name-4, ..., respectively. Modified GO TO statements in independent segments can, under some circumstances, be returned to their initial states (see the section Independent Segments in the chapter Segmentation in your Language Reference - Additional Topics).

  2. A GO TO statement in a section whose segment-number is greater than or equal to 50 must not be referred to by an ALTER statement in a section with a different segment- number.

    All other uses of the ALTER statement are valid and are performed even if procedure-name-1, procedure-name-3 is in an overlayable fixed segment.

12.1.4 The CALL Statement

The CALL statement causes control to be transferred from one object program to another within the run unit.

You may CALL the target object program procedure indirectly, by address. Data, pointers to data, and pointers to procedures can be passed as parameters to the called program procedure, and returned by it. Parameter passing conventions can be controlled in order to allow the called program procedure to be written in languages other than COBOL, using different conventions. A called COBOL program can recursively call itself when a Local-Storage Section exists.

Example

  1. An example of using procedure-pointer in a CALL statement is provided in the Examples chapter in your Language Reference - Additional Topics.

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 semantics described in this section.

Syntax Rules

Syntax rules marked with an asterisk (*) are common to the CALL statement and to the CHAIN statement. In these rules, where "CALL or CHAIN statement" is specified, you should read "CALL statement" or "CHAIN statement" when applying the rules to the CALL statement or the CHAIN statement respectively.

  1. Mnemonic-name is necessary only if the object program that is to be invoked will expect a calling convention other than that used as the default by your COBOL system. Typically, the default COBOL calling convention is consistent with that used by a significant implementation of a non-COBOL language for the run-time environment.

    Mnemonic-name must be defined in the SPECIAL-NAMES paragraph. See the section The SPECIAL-NAMES Paragraph earlier in this chapter for details of how to do this and your COBOL system documentation on interfacing for details of which calling conventions are supported in your run-time environment.

  2. * Identifier-1 must be defined as an alphanumeric data item such that its value can be a COBOL or non-COBOL program-name.

  3. * Literal-1

    , literal-2

    , and literal-3

    must be nonnumeric literals and cannot be a figurative constant.

  4. * Integer-1 may be signed.

  5. * Identifier-2 and identifier-4 must be defined as a data item in the File Section, Working-Storage Section,

    Local-Storage Section

    Communications Section or Linkage Section, and must be a level 01 data item, or a level 77 data item

    , or an elementary item

    , or any group item.

  6. * Identifier-3 must be defined as a data item in the Linkage Section

    , Local-Storage Section or Working-Storage Section,

    and must be a level 01 data item, a level 77 data item

    , or other level data item.

  7. * Neither identifier-5, identifier-6, identifier-7, nor identifier-8 can be a function-identifier.

  8. * GIVING and RETURNING are equivalent.

  9. * Identifier-8 must be 4 bytes in size.

  10. Identifier-9 must be defined as a data item in the Linkage Section with a level number of 01 or 77.

  11. If the CALL statement specifies literal-1 (but not if it specifies identifier-1 or procedure-pointer-1), and if a call prototype (a program with the EXTERNAL clause in its PROGRAM-ID paragraph) has been included in the current compilation unit with a name that matches literal-1, then the following items are validated during syntax checking:

General Rules

General rules marked with an asterisk (*) are common to the CALL statement and to the CHAIN statement. In these rules, where "CALL or CHAIN statement" are specified, you should read "CALL statement" or "CHAIN statement" when applying the rules to the CALL statement or the CHAIN statement respectively.

  1. Mnemonic-name identifies the calling convention that this program will use when invoking the called program. If the calling convention assumed by the called program is different to that implied by mnemonic-name, then the COBOL system may become corrupt.

  2. Literal-1 or the content of the data item referenced by identifier-1is the name of the called program

    or called procedure.

    The program in which the CALL statement appears is the calling program. If the program being called is a COBOL program, literal-1 or the content of the data item referenced by identifier-1 must contain the program-name contained in the PROGRAM-ID paragraph of the called program (see The Program-ID Paragraph earlier in this chapter, particularly in regard to case sensitivity),

    or the entry-name contained in the ENTRY statement of a called program that must have been called previously and not canceled since. Alternatively, the name of the called program may be a name which identifies a file that contains executable program code for the called program. The result of specifying different names that identify the same file in two CALL statements or a CALL and a CANCEL statement are operating system specific. See your COBOL system documentation for details of how your system matches the given name to previously called programs, program filenames or programs held in library files.

    If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in the COBOL system documentation on interfacing.

  3. The content of the data item referenced by procedure-pointer-1 is the address of the called program that must be already resident in memory. If the program being called is a COBOL program, the address of the called program must originally have been derived from a SET statement with an ENTRY phrase and no CANCEL statement for that program must have been subsequently executed. If the program being called is not a COBOL program then the address of the called program must originally have been derived from a CALL to a non-COBOL program or procedure. It is an error to attempt to CALL a program with an address that is equal to NULL.

  4. If, when a CALL statement is executed, the program specified by the CALL statement is made available for execution, control is transferred to the called program. After control is returned from the called program, the ON OVERFLOW

    or ON EXCEPTION

    phrase is ignored and control is passed to the end of the CALL statement

    or, if the NOT ON EXCEPTION phrase is specified control is passed to imperative-statement-2. If control is passed to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the CALL statement.

  5. When a CALL statement is executed, the program specified by the CALL statement is made available if it is already resident in memory. If it is not already resident in memory then an attempt may be made to dynamically load the program (see your COBOL system documentation on interfacing). If a program with the specified name can be dynamically located and a sufficient, contiguous area of free memory is available, then the program is dynamically loaded and made available for execution.

    If the program specified by the CALL is not resident in memory, is not available for dynamic loading or is available but finds insufficient memory in which to load, then the program cannot be made available at that time and one of the following two actions will occur:

    1. If the ON OVERFLOW

      or ON EXCEPTION

      phrase is specified in the CALL statement, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of execution of imperative-statement-1, control is transferred to the end of the CALL statement

      and the NOT ON EXCEPTION phrase, if specified, is ignored.

    2. If the ON OVERFLOW or ON EXCEPTION phrase is not specified in the CALL statement, the NOT ON EXCEPTION phrase, if specified, is ignored.

      Program execution will stop, without an implicit CLOSE statement for any file that is in open mode in the run unit, and a run time error will be displayed.

  6. The run unit remains unaware of whether a called program is a COBOL program or a non-COBOL program or procedure until the called program has been located, prior to being made available for execution. The form of the program-name cannot be used, in general, to determine whether the program is a COBOL program or not. It is an error for a COBOL program and a non-COBOL program or for two non-COBOL programs to have the same program-name.

    Two or more COBOL programs in the run unit can have the same program-name, and the reference in a CALL statement to such a program-name is resolved by using the scope of names conventions for program-names. See the section Conventions for Program-names in the chapter Concepts of the COBOL Language.

    For example, when two programs in the run unit have the same name as that specified in a CALL statement:

    1. One of those two programs must also be contained directly or indirectly either within the separate program which includes the CALL statement or within the separate program which itself directly or indirectly contains the program which includes that CALL statement, and

    2. The other one of those two programs must be a different separate program.

    The mechanism used in this example is as follows:

    1. If one of the two programs having the same name as that specified in the CALL statement is directly contained within the program which includes that CALL statement, that program is called.

    2. If one of the two programs having the same name as that specified in the CALL statement possesses the common attribute and is directly contained within another program which directly or indirectly contains the program which includes the CALL statement, that common program is called unless the calling program is contained in that common program.

    3. Otherwise, the separate program is called.

  7. If the called program is a COBOL program and does not possess the initial attribute, it and each COBOL program directly or indirectly contained within it, is in its initial state the first time it is called within a run unit and the first time it is called after a CANCEL of the called program.

    If the called program is not COBOL, it is only in its initial state the first time it is called within a run unit. A CANCEL of such a program has no effect.

    On all other entries into the called program, the state of the program and each program directly or indirectly contained within it remains unchanged from its state when last exited. Some implementations of languages other than COBOL may provide alternative semantics and, if available, these will be detailed in your COBOL system documentation on interfacing.

  8. If the called program possesses the intial attribute, it and each program directly or indirectly contained within it, is placed into its initial state every time the called program is called in a run unit. Whether a called program is in the initial state or last used state is sensitive to the DYNAM Compiler directive.

  9. Files associated with a called program's internal file connectors are not in the open mode when the program is in an initial state. See the section Intial State Of A Program earlier in this chapter.

    On all other entries into the called program, the states and positioning of all such files is the same as when the called program was last exited.

  10. The process of calling a program or exiting from a called program does not alter the status or positioning of a file associated with any external file connector.

  11. If the program being called is a COBOL program, the USING phrase is included in the CALL statement only if there is a USING phrase in the PROCEDURE DIVISION header

    or ENTRY statement

    of the called program, in which case the number of operands in each USING phrase must be identical.

    The number of operands need not be identical.

  12. If the program being called is not a COBOL program, the USING phrase is included in the CALL statement only if one or more parameters are declared for the called program, in which case the number of operands in the USING phrase must be identical to the number of parameters in the called program. (Some implementations of languages other than COBOL may allow the number of operands to be other than identical.) The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:

  13. * The sequence of appearance of the operands in the USING phrase of the CALL

    or CHAIN

    statement and in the corresponding USING phrase in the called program's PROCEDURE DIVISION header

    or ENTRY statement or parameter list if the called program is not COBOL

    determines the correspondence between the data names used by the calling and called programs. This correspondence is positional and not by name equivalence; the first operand in the CALL

    or CHAIN

    statement's USING phrase corresponds to the first operand in the called program's USING phrase or parameter list, the second to the second, etc.

    If the correspondence cannot be completed because the numbers of operands are different, then if the remaining unmatched operands are in the CALL or CHAIN statement they are ignored and if they are in the PROCEDURE DIVISION header or ENTRY statement or parameter list then they must not be referenced within the called program. The positional correspondence may vary depending on the calling conventions implied by mnemonic-name.

    In the case of index-name, no such correspondence is established. Index-names in the called and calling programs always refer to separate indices.

  14. * The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called program at the time the call statement is executed.

  15. * The BY CONTENT, BY REFERENCE

    and BY VALUE

    phrases are transitive across the parameters which follow them until another BY CONTENT, BY REFERENCE

    or BY VALUE

    phrase is encountered.

    If no BY CONTENT, BY REFERENCE

    or BY VALUE

    is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

  16. * If the BY REFERENCE identifier-2 phrase is

    either specified or

    implied for a parameter, the program operates as if the corresponding data item in the called program occupies the same storage area as the data item in the calling program. The description of the data item in the called program must describe the same number of character positions as described by the description of the corresponding data item in the calling program.

    If the BY REFERENCE ADDRESS OF phrase is specified or implied then the program operates as if an additional data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-3 statement.

    If identifier-3 is in the Linkage Section and has a level number other than 01 or 77 or is in the Working-Storage Section, it is equivalent to passing the item BY CONTENT and the address of identifier-3 cannot be modified by the called subprogram.

    If the BY REFERENCE literal-2 phrase is specified or implied then the object program processes literal-2 as described for literal-3.

  17. * If the BY CONTENT phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase, though the called program can change the value of the data item referenced by the corresponding data-name in the called program's PROCEDURE DIVISION header. The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the PROCEDURE DIVISION header.

    If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-4 is specified then both the implied data description of the additional data item and its contents are identical to that of identifier-4. If literal-3 is specified then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-3 and with its contents set to the value of literal-3. If LENGTH OF identifier-5 is specified then the data description of the additional item is equivalent to PIC S9 (9) USAGE BINARY and its contents set to the number of bytes of storage allocated to identifier-5.

  18. * If the BY VALUE phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase, though the called program can change the value of the data item referenced by the corresponding data-name in the called program's PROCEDURE DIVISION header. The object program operates, conceptually, as if an additional data item had been declared in a system area (typically "the stack"), available to non-COBOL languages for passing parameters and that this additional data item occupies the same storage area as the data item in the called program. If identifier-6 is specified then both the implied data description of the additional data item and its contents are identical to that of identifier-6. If integer-1 is specified then the implied data description of the additional item is equivalent to a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage specified by the value of integer-2, if specified, or 4 bytes otherwise. If LENGTH OF identifier-7 is specified then the data description of the additional item is equivalent to PIC S9 (9) USAGE BINARY and its contents set to the number of bytes of storage allocated to identifier-7.

    Each parameter in the BY VALUE phrase of the CALL statement has a conceptual additional data item and a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header in the called program. The data description of each such parameter in the called program must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding conceptual additional data item. In addition, the implied size of the conceptual data item must not exceed the maximum size of the system area (typically 4 bytes) otherwise the system may become catastrophically corrupt.

    If the program being called is a COBOL program, each parameter in the BY VALUE phrase of the CALL statement must have a corresponding parameter in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    If the program being called is non-COBOL, see your COBOL system documentation on interfacing for details of when you need to use the BY VALUE phrase.

  19. A called program may pass data to the calling program either by using a parameter declared in the USING phrase of the calling program or by means of a returned value. A called program returns a value by means of an EXIT GIVING or GOBACK GIVING statement. As control is returned from the called program to the calling program, the returned value is held in a system area generally available for non-COBOL programs to return a value.

    The size of the system area (typically at least 4 bytes) is determined outside the COBOL system and limits the maximum value the return value can take, but the return value may not utilize the full size of the system area. The returned value is available to the calling program after control is returned, either implicitly in the special register RETURN-CODE or explicitly in the data item specified in the GIVING phrase.

  20. If the GIVING phrase is not specified and the calling convention specifies updating the RETURN-CODE special register (see Calling Convention in the earlier section Special-Names Paragraph) then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and the same size as the system area and as if a MOVE statement had been executed with the system area as the sending item and the RETURN-CODE special register as the receiving item. (See the section Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

  21. If the GIVING INTO phrase is specified in the calling program, identifier-8 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is implied for the returned value by the manner in which the value was returned from the called program. When control returns to the calling program, identifier-8 contains the return value.

  22. If the GIVING ADDRESS OF phrase is specified in the calling program, the called program must return a value with explicit or implicit USAGE POINTER. The object program operates as if the system area were declared as a COBOL data item with USAGE POINTER and as if a SET statement had been executed with the system area as the first operand and TO ADDRESS OF identifier-9 as the second operand.

  23. It is an error to specify the GIVING phrase for a called program that does not return a value.

  24. Called programs can contain CALL statements. However,

    if the Local-Storage Section has not been declared,

    a called program may not execute a CALL that directly or indirectly calls the calling program. If a CALL statement is executed within the range of a declarative, that CALL statement cannot directly or indirectly reference any called program to which control has been transferred and which has not completed execution.

  25. The END-CALL phrase delimits the scope of the CALL statement.

  26. Any values with implicit or explicit USAGE POINTER

    or USAGE PROCEDURE-POINTER

    that were originally derived from the address of a data item

    or procedure

    that is contained within a called program become invalid and must not be used after a CANCEL statement that references that called program is executed.

  27. The OMITTED phrase is used to pass unused parameters to a subprogram without having to declare a dummy data item.

  28. The OMITTED parameter is a BY REFERENCE parameter, equivalent to passing a null address to the calling subprogram. It is identical to BY VALUE 0 SIZE 4 but is subject to the type checking of call prototypes as a BY REFERENCE parameter.

  29. If BY REFERENCE does not immediately precede OMITTED, subsequent parameters are passed by the convention previously in force and the omitted parameter is treated as if the program had specified BY VALUE 0 SIZE 4.

12.1.5 The CANCEL Statement

The CANCEL statement ensures that the next time the referenced program is called it will be in its initial state.

General Format

Syntax Rules

  1. Literal-1 must be a nonnumeric literal.

  2. Identifier-1 must reference an alphanumeric data item.

General Rules

  1. Literal-1 or the content of the data item referenced by identifier-1 identifies the name of the program to be canceled. The name must contain the program-name contained in the PROGRAM-ID paragraph of the program to be canceled (see The Program-ID Paragraph earlier in this chapter, particularly in regard to case sensitivity). Alternatively, the name may identify a file that contains executable program code for the program to be canceled. The results of specifying different names that identify the same file in a CANCEL statement are operating system specific. See your COBOL system documentation for details of how your system matches the given name to previously called programs, program filenames or programs held in library files.

    If the name contains the entry-name contained in an ENTRY statement, the results are undefined.

  2. Subsequent to the execution of an explicit or implicit CANCEL statement, the program referred to therein ceases to have any logical relationship to the run unit in which the CANCEL statement appears. If the program referenced by a successfully executed explicit or implicit CANCEL statement in a run unit is subsequently called in that run unit, that program is in its initial state. See the section Initial State Of A Program earlier in this chapter.

  3. A program named in a CANCEL statement in another program must be callable by that other program. See the sections Scope Of Names and The CALL Statement, earlier in this chapter.

  4. When an explicit or implicit CANCEL statement is executed, all programs contained in the program referenced by the CANCEL statement are also canceled. The result is the same as if a valid CANCEL statement were executed for each contained program in the reverse order in which the programs appear in the separate program.

  5. A program named in the CANCEL statement must not refer directly or indirectly to any program that has been called and has not yet executed an EXIT PROGRAM

    or GOBACK

    statement.

  6. A logical relationship to a cancelled program is established only by execution of a subsequent CALL statement naming that program.

  7. A called program is cancelled either by being referred to as the operand of a CANCEL statement, by the termination of the run unit of which the program is a member,

    or by execution of an EXIT PROGRAM statement in a called program that possesses the initial attribute.

  8. No action is taken when an explicit or implicit CANCEL statement is executed naming a program that has not been called in this run unit, has been called and is at present canceled or is a non-COBOL program. Control is transferred to the next executable statement following the CANCEL statement.

  9. The contents of data items in external data records described by a program are not changed when that program is canceled.

  10. During execution of an explicit or implicit CANCEL statement, an implicit CLOSE statement without any optional phrases is executed for each file in the open mode that is associated with an internal file connector in the program named in the CANCEL statement. Any USE procedures associated with any of these files are not executed.

  11. The CANCEL statement determines whether or not a subprogram will be re-entered in initial or last-used state. It does not necessarily free any memory used by the subprogram. However, in many operating systems, if the subprogram has been dynamically loaded, this statement will also free the memory originally used by the subprogram. EXTERNAL files and data areas of the subprogram are never freed by a CANCEL statement.

12.1.6 The CHAIN Statement

The CHAIN statement transfers control from one object program to another in the run unit with no subsequent return of control. The effect is as though the chained program is the main program in the new run unit.

General Format

Syntax Rules

  1. The syntax of the CHAIN statement is similar to the syntax of the CALL statement and the two are subject to common syntax rules as indicated in the section The CALL Statement. All the identifiers, literals and integers in the general format of the CHAIN statement correspond to the identifiers, literals and integers of the CALL statement.

General Rules

  1. Literal-1 or the content of the data item referenced by identifier-1 is the name of the chained program. The program in which the CHAIN statement appears is the chaining program.

    The chained program must be a COBOL program that is not a nested program. The name of the chained program must contain the name contained in the PROGRAM-ID paragraph of the chained program (see The Program-ID Paragraph earlier in this chapter particularly in regard to case sensitivity). Alternatively, the name of the chained program may contain a name which identifies a file that contains executable program code for the chained program. See your COBOL system documentation for details of how your system matches the given name to previously chained programs, program filenames or programs held in library files.

  2. If, when a CHAIN statement is executed, the program specified by the CHAIN statement is made available for execution, control is transferred to the chained program, and the chaining program, together with any COBOL programs called by the chaining program, are canceled. The chained program is not under the control of a chaining program and so any EXIT PROGRAM executed within the chained program has no effect.

  3. If, when a CHAIN statement is executed, the program specified by the CHAIN statement is not made available for execution, thena fatal run time error is given.

  4. Chained programs can contain CHAIN statements. A CHAIN statement within a chained program may reference any program except itself.

  5. The form of the CHAIN statement is similar to the form of the CALL statement and the two are subject to common general rules as indicated in the section The CALL Statement. All the identifiers, literals and integers in the general format of the CHAIN statement correspond to the identifiers, literals and integers of the CALL statement. Also, where the expressions calling program and called program are used, these can be considered equivalent to the expressions chaining program and chained program.

  6. The chain operation moves the value from each data item referenced in the USING phrase of the CHAIN statement to the data item referenced by the corresponding data-name in the USING phrase of the PROCEDURE DIVISION header of the chained program.

  7. The value of any data item with USAGE POINTER or USAGE PROCEDURE-POINTER that is passed as an operand in the USING phrase must not represent the address that was originally derived from a COBOL data item.

  8. The END-CHAIN phrase delimits the scope of the CHAIN statement.

  9. The USING phrase must not be used if you have specified the Compiler directive INTLEVEL"1".

12.1.7 The CLOSE Statement

The CLOSE statement terminates the processing of reels/units and files, with optional rewind and/or lock or removal where applicable.

General Formats

Format 1 (Record Sequential Files)

Format 2 (
dialm.gifLine Sequential,
Relative and Indexed Files)

Syntax Rules

All Formats (All Files)
  1. The files referenced in the CLOSE statement need not all have the same organization or access.

Format 1 (Record Sequential Files)
  1. The REEL and UNIT phrases should be specified only for files which have had MULTIPLE REEL or MULTIPLE UNIT specified in their SELECT clause. If your run-time system does not recognize multi-unit files, the statements CLOSE REEL and CLOSE UNIT are "null" statements; that is, they are documentary only. It is important that no other files are open on the device(s) closed by a CLOSE REEL or CLOSE UNIT statement.

    The statements CLOSE REEL WITH LOCK and CLOSE UNIT WITH LOCK are treated as equivalent to CLOSE REEL FOR REMOVAL.

  2. The DISP option is applicable only to tape files.

    It is documentary only.

General Rules

All Formats (All Files)
  1. A CLOSE statement can be executed only for a file in an open mode.

  2. Following the successful execution of a CLOSE statement the record area associated with file-name-1 is no longer available. The unsuccessful execution of such a CLOSE statement leaves the availability of the record area undefined.

  3. If a file is in the open mode when a STOP RUN statement is executed, the file will be closed. If a file has been opened in a called program and not closed in that program prior to the execution of a CANCEL statement for the program, that file will be closed.

  4. Following the successful execution of a CLOSE statement, all record or file locks held by the run unit on the closed file are released.

  5. The execution of the CLOSE statement causes the value of the I/O status associated with file-name-1 to be updated. (See the section I/O Status earlier in this chapter.)

  6. The results of executing each type of CLOSE statement for each category of file are summarized in Table 12-1.

    Table 12-1: Relationship of Categories of Files and the Formats of the CLOSE Statement

    CLOSE Statement Format File Category
    Non-Reel/Unit Record Sequential Single-Reel/ Unit Record Sequential Multi-Reel/ Unit Non-record Sequential Single/ Multi-Reel/ Unit
    CLOSE C C, G A, C, G C
    CLOSE WITH LOCK C, E C, E, G A, C, E, G C, E
    CLOSE WITH NO REWIND record sequential only C, H B, C A, B, C X
    CLOSE REEL/UNIT record sequential only F F, G F, G X
    CLOSE REEL/UNIT FOR REMOVAL record sequential only F D, F, G D, F , G X
    CLOSE REEL/UNIT WITH NO REWIND record sequential only X X F, B X

    The definitions of the symbols in the table are given below. Where the definition depends on whether the file is an input, output or input- output file, alternate definitions are given; otherwise, a definition applies to input, output, and input-output files.

    1. Previous Reels/Units Unaffected

      Input Files and Input-Output Files:

      All reels/units in the file prior to the current reel/unit are processed except those reels/units controlled by a prior CLOSE REEL/UNIT statement. If the current reel/unit is not the last in the file, the reels/units in the file following the current one are not processed.

      Output Files:

      All reels/units in the file prior to the current reel/unit are processed except those reels/units controlled by a prior CLOSE REEL/UNIT statement.

    2. No Rewind of Current Reel

      The current reel/unit is left in its current position.

    3. Close File

      Input Files and Input-Output Files (Sequential Access Mode):

      If the file is at the end and label records are specified for the file, the labels are processed according to the operating system label convention. The behavior of the CLOSE statement when label records are specified but not present, or when label records are not specified but are present, is undefined. If the file is at the end and label records are not specified for the file, label processing does not take place, but other closing operations dependent on the run-time system are executed. If the file is not at the end, the closing operations dependent on the RTS are executed, but there is no ending label processing.

      Input Files and Input-output Files (Random or Dynamic Access Mode); Output Files (Random, Dynamic or Sequential Access Mode):

      If label records are specified for the file, the labels are processed according to the operating system standard label convention. The behavior of the CLOSE statement when label records are specified but not present, or when label records are not specified but are present, is undefined. If label records are not specified for the file, label processing does not take place, but other closing operations dependent on the run-time system are executed.

    4. Reel/Unit Removal

      The reel or unit can be accessed again, in the proper order of reels or units in the file, if a CLOSE statement without the REEL or UNIT phrase has previously been executed for this file followed by the execution of an OPEN statement for the file.

    5. File Lock

      This file cannot be opened again during this execution of this run unit.

    6. Close Reel/Unit

      Input Files and Input-Output Files (Reel/Unit Media):

      1. If the current reel/unit is the last or only reel/unit for the file, no reel/unit swap takes place; the current volume pointer remains unchanged, and the file position indicator is set to indicate that no next reel/unit exists.

      2. If another reel/unit exists for the file, a reel/unit swap occurs, the current volume pointer is updated to point to the next reel/unit existing in the file, the standard beginning reel/unit label procedure is executed, and the file position indicator is set to one less than the number of the first record existing on the new current volume. If no data records exist for the current volume, another reel/unit swap occurs.

      Output Files (Reel/Unit Media):

      The following operations take place;

      1. Execution of the standard ending reel/unit label procedure.

      2. A reel/unit swap.

      3. Execution of the standard beginning reel/unit label procedure.

      4. The next executed WRITE statement that references that file directs the next logical data record to the next reel/unit of the file.

      Input Files, Input-Output Files, and Output Files (Non-Reel/Unit Media):

      Execution of this statement is considered successful. The file remains in the open mode, the file position indicator remains unchanged, and no action takes place except as specified in General Rule 4.

    7. Rewind

      The current reel or analogous device is positioned at its physical beginning.

    8. Optional Phrases Ignored

      The CLOSE statement is executed as if none of the optional phrases is present.

    1. Illegal

      This is an illegal combination of a CLOSE option and a file category. The results at object time are undefined.

Format 1 (Record Sequential Files)

Except where otherwise stated in the general rules below, the terms "reel" and "unit" are equivalent and completely interchangeable in the CLOSE statement. Treatment of sequential mass storage files is logically equivalent to the treatment of a file on tape or analogous sequential media.

  1. In order to show the effect of various types of CLOSE statements as applied to various storage media, all files are divided into the following categories:

    1. Non-reel/unit. A file whose input or output medium is such that the concepts of rewind and reels/units have no meaning.

    2. Sequential single-reel/unit. A sequential file that is entirely contained on one reel/unit.

    3. Sequential multi-reel/unit. A sequential file that is contained on more than one reel/unit.

  2. If the OPTIONAL phrase has been specified for the file in the FILE-CONTROL paragraph of the Environment Division and the file is not present, the standard end-of-file processing is not performed for that file.

  3. If a CLOSE statement without the REEL or UNIT phrase has been executed for a file, no other statement (except the SORT or MERGE statements with the USING or GIVING phrases) can be executed that references that file, either explicitly or implicitly, unless an intervening OPEN statement for that file is executed.

  4. The WITH NO REWIND and FOR REMOVAL phrases will have no effect at object time if they do not apply to the storage media on which the file resides.

  5. If WITH LOCK is specified, the file cannot be reopened during the current execution of the run unit. Otherwise a normal CLOSE takes effect.

    (This option has no connection with the record or file locking used when sharing files.)

All Formats (All Files)
  1. If a CLOSE statement has been executed for a file, no statement

    other than a delete file

    can be executed that references that file, either explicitly or implicitly, unless an intervening OPEN statement for that file is executed.

  2. If WITH LOCK is specified, the file cannot be reopened during the current execution of the run unit.

12.1.8 The COMMIT Statement

The COMMIT statement releases all record locks in all files held by this run unit. For COBOL systems that support the WITH...ROLLBACK clause of the SELECT statement as other than documentary, COMMIT indicates the end of the current transaction and makes the effects of that transaction permanent.

General Format

General Rules

  1. Execution of the COMMIT statement causes all record locks in all files held by the run unit to be released.

  2. The file lock on an exclusive file is not affected by the COMMIT statement.

  3. If your COBOL system supports the WITH ... ROLLBACK clause of the SELECT statement as other than documentary, then the COMMIT verb:

    1. Indicates completion of the current transaction

    2. Makes all changes applied during the transaction permanent.

12.1.9 The COMPUTE Statement

The COMPUTE statement assigns to one or more data items the value of an arithmetic expression.

General Format

Syntax Rules

  1. Identifiers that appear only to the left of "=" must refer to either an elementary numeric item or an elementary numeric edited item

    or a floating-point item.

  2. "Equal" and "=" are synonymous.

General Rules

  1. See the sections The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in this chapter; and the sections Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language and Delimited Scope Statements in the chapter Concepts of a COBOL Program.

  2. An arithmetic expression consisting of a single identifier or literal provides a method of setting the values of identifier-1 equal to the value of the single identifier or literal.

  3. The COMPUTE statement allows the user to combine arithmetic operations without the need to explicitly store intermediate results in temporary data items, as would be necessary using the arithmetic statements ADD, SUBTRACT, MULTIPLY and DIVIDE. The expression is evaluated to as many digits as possible, and truncated or rounded to fit into identifier-1.

    The intermediate results obtained during the expression evaluation are truncated as if they were moved to data items whose PICTURE is determined by the COBOL system. This behavior is selected using the ARITHMETIC Compiler directive.

  4. If more than one identifier is specified for the result of the operation, that is preceding "=", the value of the arithmetic expression is computed, and then this value is stored as the new value of each occurrence of identifier-1 in turn.

12.1.10 The CONTINUE Statement

The CONTINUE statement is a no operation statement, indicating that no executable statement is present.

General Format

Syntax Rules

  1. The CONTINUE statement can be used anywhere a conditional statement or an imperative-statement can be used.

General Rules

  1. The CONTINUE statement has no effect on the execution of the program.

12.1.11 The DELETE Statement

The DELETE statement logically removes a record from a mass storage file. It can be specified only for files with relative or indexed organization.

General Format

Syntax Rules

  1. The INVALID KEY phrase must not be specified for a DELETE statement which references a file in sequential access mode.

  2. The INVALID KEY phrase must be specified for a DELETE statement which references any file not in sequential access mode for which an applicable USE AFTER STANDARD EXCEPTION PROCEDURE is not specified.

    This rule is not enforced.

General Rules

  1. The associated file must be open in the I/O mode at the time of execution of this statement. (See the section The OPEN Statement later in this chapter.)

  2. For files in sequential access mode, the last input-output statement executed for file-name-1 prior to the execution of the DELETE statement must have been a successfully executed READ statement. The operating system logically removes from the file the record that was accessed by that READ statement.

  3. For a file in random or dynamic access mode, the operating system logically removes from the file that record identified by the contents of a KEY data item associated with file-name. For a relative file, this KEY data item is the RELATIVE KEY and for an indexed file, it is the prime RECORD KEY. If the file does not contain the record specified by the key, an INVALID key condition exists. (See the section The INVALID KEY Condition in this chapter.)

  4. After the successful execution of a DELETE statement, the identified record is logically removed from the file and can no longer be accessed.

  5. The execution of a DELETE statement does not affect the contents of the record area associated with file-name-1.

  6. The file position indicator is not affected by the execution of a DELETE statement.

  7. Execution of the DELETE statement causes the value of the specified FILE STATUS data item, if any, associated with the file-name to be updated. (See the section I/O Status earlier in this chapter.)

  8. Transfer of control following the successful or unsuccessful execution of the DELETE operation depends on the presence or absence of the optional INVALID KEY phrase

    and NOT INVALID KEY phrase

    in the DELETE statement. (See the section The INVALID KEY Condition in this chapter.)

  9. The END-DELETE phrase delimits the scope of the DELETE statement. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.

  10. When using DELETE, the record to be deleted must not be locked by another run unit.

  11. Following the successful execution of a DELETE statement, any record lock held by the run unit on the deleted record is released.

  12. Execution of the DELETE statement causes the value of the I/O status associated with file-name-1 to be updated. (See the section I/O Status earlier in this chapter.)

12.1.12 The DELETE FILE Statement

The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.

General Format

General Rules

  1. The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.

  2. The specified files must be closed when the statement is executed, but not CLOSED WITH LOCK.

12.1.13 The DISPLAY Statement

The DISPLAY statement causes data to be transferred from specified data items to the appropriate hardware device, such as the CRT screen.

The DISPLAY statement also transfers data from your program to the CRT or video terminal screen: non-scrolling forms, into which you can enter data, are displayed.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

Format 1
  1. The mnemonic-name must be associated with a function-name in the SPECIAL-NAMES paragraph in the Environment Division. See General Rule 9 in the section The SPECIAL-NAMES Paragraph in this chapter for a list of valid function-names.

  2. Alternatively, function-name can itself be used instead of an associated mnemonic-name.

  3. Each literal can be any figurative constant, except ALL.

  4. If the literal is numeric, it must be an unsigned integer.

    This restriction can be ignored.

  5. When mnemonic-name is associated with ARGUMENT-NUMBER, then identifier-1 or literal-1 must each, if used, reference a data item defined as an unsigned integer or an unsigned integer literal respectively. Only a single identifier-1 or literal-1 can be used and the WITH NO ADVANCING phrase can not be used.

  6. When mnemonic-name is associated with ENVIRONMENT-NAME or ENVIRONMENT-VALUE, then identifier-1 or literal-1 must each, if used, reference an alphanumeric data item or a nonnumeric literal respectively. Only a single identifier-1 or literal-1 can be used and the WITH NO ADVANCING phrase can not be used.

  7. The ON EXCEPTION and NOT ON EXCEPTION phrases can only be specified when mnemonic-name is associated with ENVIRONMENT-NAME or ENVIRONMENT-VALUE.
Format 2
  1. Screen-name cannot be an item with an OCCURS clause.

Formats 2 and 3
  1. The LINE and COLUMN phrases can appear in any order.

  2. Integer-3 and identifier-4 must be 4 or 6 digits long.

Format 3
  1. A DISPLAY statement with an operand that is not a screen-name is treated as a Format 3 DISPLAY statement if it has an AT phrase, an UPON phrase with the CRT or CRT-UNDER option, a WITH phrase, or a MODE IS BLOCK phrase; or if it has no UPON phrase but the CONSOLE IS CRT clause is specified in the SPECIAL-NAMES paragraph. If it has the UPON phrase with the CONSOLE option, or if it has no UPON phrase and the CONSOLE IS CRT clause is not specified in the SPECIAL-NAMES paragraph, it is treated as a Format 1 DISPLAY statement.

  2. The phrases following the identifier can be in any order.

  3. Elementary data items in identifier-1 must be of USAGE DISPLAY.

  4. No elementary item in identifier-1 may be longer than 8191 bytes. If the MODE IS BLOCK phrase is used, the whole of identifier-1 must be no longer than 8191 bytes.

  5. If a DISPLAY verb is followed by more than one identifier-1, any WITH clause applies only to the operand immediately preceding it.

General Rules

Format 1
  1. When operands in a DISPLAY statement have USAGE other than DISPLAY, or have included signs, they are converted to USAGE DISPLAY with separate sign. The size of the operand is taken as the size after conversion.

  2. If a figurative constant is specified as one of the operands, only a single occurrence of the figurative constant is displayed.

  3. If the function-name COMMAND-LINE, or a mnemonic-name associated with the function-name COMMAND LINE, is specified, data overwrites the contents of a system-dependent command-line buffer from where it can be retrieved by subsequent use of ACCEPT FROM COMMAND-LINE. Only one operand is allowed in this case.

    All permissible function-names other than those specifically mentioned in the general rules for Format 1 of the DISPLAY statement are treated as equivalent to CONSOLE and each operand is transferred to the console device in the order listed. The total size of data displayed is equal to the sum of the sizes of each operand. The display starts from the current cursor position, overflowing onto the following line(s) if necessary.

    On earlier releases, trailing spaces after the last operand were not displayed.

  4. If the NO ADVANCING phrase is specified, the cursor is then left at the space following the last character displayed; otherwise it is positioned at the start of the next line. Scrolling can take place whenever the cursor is moved to a new line.

  5. If the mnemonic-name associated with the function-name ARGUMENT-NUMBER is used, then the position for any subsequent ACCEPT with a mnemonic associated with ARGUMENT-VALUE is set to retrieve the designated command-line argument. If the value associated with identifier-1 or literal-1 is less than 0, greater than 99, or greater than the total number of arguments on the command-line, then results are explicitly undefined.

  6. If the mnemonic-name associated with the function-name ENVIRONMENT-NAME is used then the variable to be read or set in any subsequent ACCEPT or DISPLAY with a mnemonic associated with ENVIRONMENT-VALUE is set to the designated variable-name specified in literal-1 or as the contents of identifier-1. The ON EXCEPTION phrase is ignored. If any problem occurs while trying to set an ENVIRONMENT-NAME for a subsequent ACCEPT or DISPLAY associated with ENVIRONMENT-VALUE, then it is only the subsequent ACCEPT or DISPLAY that must detect the ON EXCEPTION condition.

  7. If the mnemonic-name associated with the function-name ENVIRONMENT-VALUE is used then

    1. If a previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been done, then the value of the identifier is placed into the designated environment-variable.

    2. If no previous DISPLAY with a mnemonic-name associated with an ENVIRONMENT-NAME has been performed, or, for ACCEPT, if the specified environment-variable does not exist, or, for DISPLAY, not enough space can be allocated to store the environment variable, the imperative statement associated with an ON EXCEPTION phrase is executed. The value in identifier is undefined in this case.

  8. If the mnemonic-name associated with the function-name SYSERR is used, then a DISPLAY is performed as if to the CONSOLE except that all output is directed to the system's standard Error Device.

  9. When using DISPLAY UPON ENVIRONMENT-VALUE, trailing spaces are included in the value. You should use INSPECT REPLACING ALL SPACE BY LOW-VALUES to avoid this.

  10. Within identifier-1, internal floating-point numbers are converted to external floating-point numbers for display, so that:

    1. A COMP-1 item will display as if it has an external floating-point PICTURE clause of -.9(8)E-99.

    2. A COMP-2 item will display as if it has an external floating-point PICTURE clause of -.9(18)E-99 (even though this picture string is illegal if explicitly specified).

  11. Literal-1 may be a floating-point literal.
Format 2
  1. This format of the DISPLAY statement displays screen items, which are defined in the screen section of the program, and allows full access to the enhanced screen handling facilities.

Format 2 and 3
  1. The AT phrase gives the absolute address on the screen where the DISPLAY operation is to start.

  2. The order of execution of a DISPLAY statement is always:

    1. the AT phrase

    2. the BLANK phrase

    3. the BELL phrase

    4. the DISPLAY operation

  3. If integer-3 or identifier-4 is 4 digits long, the first two digits specify the line, the second two the column. If 6 digits long, the first three digits specify the line, while the second three specify the column.

  4. Certain combinations of line and column numbers have special meanings, as follows:

    1. Until the column comes within range, out of range column values are reduced by the line length and the line value is incremented.

    2. Out of range line values cause the screen to scroll up one line. The effect is the same as if the line number of the bottom line had been specified.

    3. If the line and column numbers given are both zero, the DISPLAY starts at the position following that where the preceding Format 2 or Format 3 DISPLAY operation finished. Column 1 of each line is considered to follow the last column of the previous line.

    4. If the line number is zero, but a non-zero column number is specified, the DISPLAY starts at the specified column, on the line following that where the preceding Format 2 or 3 DISPLAY operation finished.

    5. If the column number is zero, but a non-zero line number is specified, the DISPLAY starts on the specified line, at the column following that where the preceding Format 2 or 3 DISPLAY operation finished.

Format 3
  1. Part of this statement can be repeated to allow the display of several data items. If the first item has no AT phrase, it begins at line 1, column 1. Each subsequent item begins at the current cursor position as left after the previous item.

  2. If identifier-1 is a group item and no MODE IS BLOCK phrase exists, those elementary subordinate items which have names other than FILLER are displayed. They are displayed simultaneously, positioned on the screen in the order their descriptions appear in the Data Division, and separated by the lengths of the FILLER items in the group. For this purpose, the first position on a line is regarded as immediately following the last position on the previous line.

  3. The MODE IS BLOCK phrase indicates that the identifier is to be treated as an elementary item. Thus, even if it is a group item it is displayed as one item.

  4. The WITH phrase allows you to specify certain options available during the operation. (See the section The Screen Section earlier in this chapter for descriptions of these clauses.)

    In addition to the options available as screen description clauses, the following options can be used in the WITH phrase; SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY TRAILING-SIGN and UPDATE. ZERO-FILL appears in this list and as a screen description clause because it has two different uses. Its second use is documented later in this chapter.

    A configuration option is available which allows the entry of data into numeric and numeric edited screen fields in free format mode. In COBOL, nonedited numeric data items are intended for holding data in an internal form; however, this format enables such data items to appear on the screen. See your COBOL system documentation on user interfaces for more details. If free format mode is in effect, the data will appear automatically reformatted as follows:

    The SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN options amend this format.

  5. If the literal-1 is one of the following figurative constants it has a special effect as follows: SPACE clears from the specified cursor position to the end of the screen; LOW-VALUE moves the cursor to the specified position; ALL X"01" clears from the specified cursor position to the end of the line; ALL X"02" clears the whole screen; ALL X"07" sounds the bell. If the literal is a figurative constant that is not listed above and the SIZE option is not specified, one occurrence of its value is displayed.

  6. If the SIZE option is specified for a figurative constant that has no special effect, then that figurative constant is displayed as many times as necessary to reach the length specified in the SIZE option. However, if the display wraps around to a new line, it starts again at the beginning of the figurative constant.

  7. If the FOREGROUND-COLOR option is specified, then the specified color becomes the default foreground color if and only if the entire screen is cleared by this display .

    The entire screen is cleared either when the BLANK SCREEN option is specified or when literal-1 is SPACES and the DISPLAY starts at line 1 column 1.

  8. If the BACKGROUND-COLOR option is specified, then the specified color becomes the default background color if and only if the entire screen is cleared by this display.

  9. If REDEFINES is used within identifier-1, the first description of the redefined data area is used and subsequent descriptions are ignored. If OCCURS or nested OCCURS are used the repeated data item is expanded into the full number of times it occurs, so that one definition is repeated for many fields.

12.1.14 The DIVIDE Statement

The DIVIDE statement divides one numeric data item into others and sets the values of data items equal to the qu otient and re mainder.

General Formats

Format 1

Format 2

Format 3

Format 4

Format 5

Syntax Rules

All Formats
  1. Each identifier must refer to an elementary numeric item, except that any identifier associated with the GIVING or REMAINDER phrase must refer to either an elementary numeric item or an elementary numeric edited item.

  2. Each literal must be a numeric literal.

  3. The composite of operands, which is the hypothetical data item resulting from the superimposition of all receiving data items (except the REMAINDER data item) of a given statement aligned on their decimal points, must not contain more than eighteen digits.

  4. When Format 1, 2, or 3 is used, floating-point data items and literals can be used anywhere a numeric data item or literal can be specified. When Format 4 or 5 is used, no floating-point data items or literals may be specified.

General Rules

All Formats
  1. See the sections The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in this chapter; and the sections Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language and Delimited Scope Statements in the chapter Concepts of a COBOL Program. See also General Rules 5 and 7 for a presentation of the ROUNDED phrase and the ON SIZE ERROR phrase as they pertain to Formats 4 and 5.
Format 1
  1. When Format 1 is used, literal-1 or the value of the data item referenced by identifier-1 is stored in a temporary data item. The value in this temporary data item is then divided into the value of identifier-2. The value of the dividend (the value of the data item referenced by identifier-2) is replaced by this quotient; similarly, the temporary data item is divided into each successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is specified.
Format 2
  1. When Format 2 is used, the value of identifier-1 or literal-1 is divided into identifier-2 or literal-2 and the result is stored in each data item referenced by identifier-3.
Format 3
  1. When Format 3 is used, the value of identifier-1 or literal-1 is divided by the value of identifier-2 or literal-2 and the result is stored in each data item referenced by identifier-3.

Formats 4 and 5
  1. Formats 4 and 5 are used when a remainder from the division operation is desired, namely identifier-4. The remainder in COBOL is defined as the result of subtracting the product of the quotient (identifier-3) and the divisor from the dividend. If identifier-3 is defined as a numeric edited item, the quotient used to calculate the remainder is an intermediate field which contains the unedited quotient. If ROUNDED is used, the quotient used to calculate the remainder is an intermediate field which contains the quotient of the DIVIDE statement, truncated rather than rounded.

  2. In Formats 4 and 5, the accuracy of the REMAINDER data item (identifier-4) is defined by the calculation described above. Appropriate decimal alignment truncation (not rounding) will be performed for the content of the data item referenced by identifier-4, as needed.

  3. When the ON SIZE ERROR phrase is used in Formats 4 and 5, the following rules pertain:

    1. If the size error condition occurs on the quotient, no remainder calculation is meaningful. Thus, the contents of the data items referenced by both identifier-3 and identifier-4 will remain unchanged.

    2. If the size error condition occurs on the remainder, the contents of the data item referenced by identifier-4 remains unchanged. However, as with other instances of multiple results of arithmetic statements, the user will have to do his own analysis to recognize which situation has actually occurred.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousProcedure Division - Intrinsic Functions Procedure Division - ENTER - INVOKENext"