Compaq COBOL
Reference Manual

Formats 6, 7, and 8

117. When a Format 6 ACCEPT statement is specified, the value of arg-count is moved to dest-item. This represents the number of arguments on the program run command line (see ARGUMENT-NUMBER in the SPECIAL-NAMES paragraph in Chapter 4).
118. When the current argument position indicator is zero, it refers to the zeroth command line argument, in other words the command that invoked the COBOL program.
119. When a Format 7 ACCEPT statement is specified, the value of the command line argument indicated by the current argument position indicator is moved to dest-item (see ARGUMENT-VALUE in the SPECIAL-NAMES paragraph in Chapter 4).
120. The current argument position indicator is determined by the following:
     • In the absence of a Format 4 DISPLAY, the initial value of the current argument position indicator is 1.
     • The current argument position indicator is incremented by 1 after execution of a Format 7 ACCEPT statement.
121. When a Format 8 ACCEPT statement is specified, the value of envlog-value is moved to dest-item (see ENVIRONMENT-VALUE and ENVIRONMENT-NAME in the SPECIAL-NAMES paragraph in Chapter 4). This value represents the value of the environment variable or system logical named by the current ENVIRONMENT-NAME item.
122. stment3 is executed if an attempt is made to read beyond the last argument on the command line, or if the argument does not exist.
123. stment4 is executed if the name of the environment variable or logical has not been set by a Format 5 DISPLAY, or if the environment variable or logical does not exist.
124. stment5 is executed if the exception condition does not exist.

Technical Notes

All Formats

1. On OpenVMS Alpha and Windows NT systems, if the data transfer is from a terminal, Ctrl/Z is equivalent to an end-of-file indication. <>
2. On Tru64 UNIX systems, if the data transfer is from a terminal, Ctrl/D is equivalent to an end-of-file indication. <>

Format 1

3. An ACCEPT statement without the FROM phrase takes input from the default input device (the keyboard). To take input from a file on Tru64 UNIX and Windows NT systems, the environment variable COBOL_INPUT can be used to specify a text file containing input data. To take input from a file on OpenVMS Alpha systems, the logical COB$INPUT or SYS$INPUT can be used to specify a text file containing input data.
   Alternatively, input device redirection (<) can be used on Tru64 UNIX and Windows NT systems to name an input file.
4. An ACCEPT statement that includes the FROM phrase transfers data from the file-device-name associated with the SPECIAL-NAMES paragraph description of input-source.
5. On OpenVMS Alpha systems, the object of a logical name is not necessarily a device. Therefore, no open mode is implied. As a result, input-source can be associated with any device-name in the SPECIAL-NAMES paragraph. For example, input-source can refer to PAPER-TAPE-PUNCH as well as PAPER-TAPE-READER. <>
6. An end-of-file indication during ACCEPT statement execution with an AT END phrase causes control to transfer to the AT END imperative statement.
7. An end-of-file indication during ACCEPT statement execution without the AT END phrase is an error. The program terminates abnormally.
8. The ACCEPT statement fills dest-item with spaces if the input is an empty record (for example, a carriage return only).
9. On Tru64 UNIX and Windows NT, you can enter a maximum of 256 characters during a Format 1 ACCEPT statement. <>

Formats 3 and 4

• The Compaq extensions to the ACCEPT and DISPLAY statements support data input and display only on VT100 and later terminal types, including emulators of these terminal types.
• On OpenVMS, control sequences from SMGTERMS.TXT are used to accomplish cursor positioning, screen erasure, and video attributes. Refer to the chapter on support for non Compaq terminals of the OpenVMS RTL Screen Management (SMG$) Manual if you wish to customize SMGTERMS.TXT. <>
• You should accept data only from input fields that are within screen boundaries. That is, the terminal operator should see all the characters entered (assuming the NO ECHO, CONVERSION, and PROTECTED phrases are not specified). If you accept data from an input field that positions the cursor outside screen boundaries, the result is not an error condition, but your program might produce unexpected results.
  Values for screen boundaries depend on the terminal attributes. Refer to the appropriate terminal user's guide for more information on screen boundaries.
• Line positioning can be a one- or two-step process. The first (or only) step is absolute positioning, which is using the value of line-num or line-id to determine the line position. The second step is relative positioning, which is adding the value of plus-num to line-id to determine the line position. Relative positioning beyond the bottom line of the current screen results in scrolling.
  For example, suppose that the screen for which you are programming has a maximum of 24 lines and you need to scroll the screen up one line before accepting data. The following sample statements illustrate how to use relative positioning to accomplish this operation (assume ITEMA has a value of 14, and the current line position is 20):

  ACCEPT DEST-EXAMPLE FROM LINE NUMBER PLUS 5. ACCEPT DEST-EXAMPLE FROM LINE NUMBER ITEMA PLUS 11.

  
  The following sample statements would produce undefined results because absolute line positioning is beyond the bottom of the screen (assume ITEMB has a value of 25):

  ACCEPT DEST-EXAMPLE FROM LINE NUMBER 25. ACCEPT DEST-EXAMPLE FROM LINE NUMBER ITEMB. ACCEPT DEST-EXAMPLE FROM LINE NUMBER ITEMB PLUS 0.

  
  The last ACCEPT statement illustrates that use of the PLUS option does not necessarily mean that scrolling will always occur. Absolute line positioning always occurs before the relative positioning specified by the PLUS option. In this case, line-id (ITEMB) has a value of 25. Therefore, the line position is outside the screen boundary before the PLUS option executes, and program results are undefined.

• When you use the CONTROL KEY phrase, key-dest-item stores the terminator key code. The Compaq COBOL User Manual contains information on these key code values in its description of programming video forms.
• In Formats 3 and 4, the maximum number of characters in dest-item or key-dest-item is 1024.
• When you use the CONTROL KEY phrase with the PROTECTED WITH AUTOTERMINATE phrase, and the maximum number of characters is entered to terminate the ACCEPT statement, key-dest-item is filled with spaces.
• The ALPHABET clause has no effect on the CONVERSION clause for either ACCEPT or DISPLAY.
• Unexpected behavior can occur when an ACCEPT statement with the EDITING, PROTECTED, and DEFAULT IS CURRENT phrases and without the CONVERSION phrase is executed. The behavior occurs when a numeric data item has a negative scale factor or is signed. To avoid this behavior, it is suggested that the CONVERSION phrase be used in these circumstances.

Additional References

• Section 4.1.3, SPECIAL-NAMES section in Chapter 4
• Compaq COBOL User Manual sections on using command-line arguments and environment variables
• Section 6.1.4, Scope of Statements
• Section 6.8.10, DISPLAY
• Section 6.8.22, MOVE statement

Examples

In the following examples, the character s represents a space. The examples assume that the time is just after 2:15 P.M. on October 7, 1992. The Environment and Data Divisions contain the following entries:

SPECIAL-NAMES. CONSOLE IS IN-DEVICE. DATA DIVISION. 01 ITEMA PIC X(6). 01 ITEMB PIC 99V99. 01 ITEMC PIC 9(8). 01 ITEMD PIC 9(5). 01 ITEME PIC 9(6). 01 ITEMF PIC 9. 01 ITEMG COMP-1. 01 ITEMH PIC S9(5) COMP.

1. ACCEPT ITEMA.

   Input	ITEMA
   COMPUTER	COMPUT
   VAX	VAXsss
   12.6	12.6ss

2. ACCEPT ITEMB FROM IN-DEVICE.

   Input	ITEMB	Equivalent to
   1623	1623	16.23
   4	4sss	Invalid data
   60000	6000	60.00
   -1.2	-1.2	Invalid data
   1.23	1.23	Invalid data
   COMPUTER	COMP	Invalid data

3. ACCEPT ITEMB WITH CONVERSION.

   Input	ITEMB	Equivalent to
   1623	1623	16.23
   4	4sss	04.00
   60000	6000	60.00
   -1.2	-1.2	01.20
   1.23	1.23	01.23
   COMPUTER	COMP	Invalid data

   STATEMENT	RESULT
   ACCEPT ITEME FROM DATE.	ITEME = 921007
   ACCEPT ITEMC FROM TIME.	ITEMC = 14150516 (OpenVMS and Tru64 UNIX) ITEMC = 14150500 (Windows NT)
   ACCEPT ITEMD FROM DAY.	ITEMD = 92280
   ACCEPT ITEMF FROM DAY-OF-WEEK.	ITEMF = 3
   ACCEPT ITEMA FROM TIME.	ITEMA = 141505
   ACCEPT ITEME FROM TIME.	ITEME = 150516
   ACCEPT ITEMD FROM DAY-OF-WEEK.	ITEMD = 00003
   ACCEPT ITEMG WITH CONVERSION.

   Input	Result Equivalent to
   .123E-02	0.00123
   -12.3E+02	-1230
   1004E-07	1.004000E-04

4. ACCEPT ITEMH WITH CONVERSION.

   Input	Result Equivalent to
   27	27
   -44	-44

Additional examples containing Compaq extensions to the ACCEPT statement (Formats 3, 4, and 5) are described in the Compaq COBOL User Manual. Refer to the description of programming video forms.

Also, examples containing extensions to the ACCEPT statement (Formats 6, 7 and 8) that access command line arguments are described in the Compaq COBOL User Manual.

6.8.2 ADD

Function

The ADD statement adds two or more numeric operands and stores the sum in one or more receiving fields.

num

is a numeric literal or the identifier of an elementary numeric item.

rsult

is the identifier of an elementary numeric item. However, in Format 2, rsult can be an elementary numeric edited item. It is the resultant identifier.

stment

is an imperative statement executed when a size error condition has occurred.

stment2

is an imperative statement executed when no on size error condition has occurred.

grp-1

is the identifier of numeric group item.

grp-2

is the identifier of numeric group item.

Syntax Rule

CORR is an abbreviation for CORRESPONDING.

General Rules

1. In Format 1, the values of the operands before the word TO are added together. This total is then added to each occurrence of rsult.
2. In Format 2, the values of the operands before the word GIVING are added. The sum is then stored in each rsult.
3. In Format 3, data items in grp-1 are added to and stored in the corresponding data items in grp-2.

Additional References

• Section 6.1.4, Scope of Statements
• Section 6.6.1, Arithmetic Operations
• Section 6.6.2, Multiple Receiving Fields in Arithmetic Statements
• Section 6.6.3, ROUNDED Phrase
• Section 6.6.4, ON SIZE ERROR Phrase
• Section 6.6.5, CORRESPONDING Phrase
• Section 6.6.7, Overlapping Operands and Incompatible Data

Examples

Each of the examples assume the following data descriptions and initial values:

INITIAL VALUES

03 ITEMA PIC 99 VALUE 85. 85 03 ITEMB PIC 99 VALUE 2. 2 03 ITEMC VALUE "123". 05 ITEMD OCCURS 3 TIMES 1 2 3 PIC 9.

1. TO phrase: RESULTS

   ADD 2 ITEMB TO ITEMA. ITEMA = 89

2. SIZE ERROR clause:

   ADD 38 TO ITEMA ITEMB ITEMA = 85 ITEMB = 40 ON SIZE ERROR MOVE 0 TO ITEMB. ITEMB = 0

   
   (When the SIZE ERROR condition occurs, the value of the affected resultant identifier does not change. The SIZE ERROR condition occurs on ITEMA but not on ITEMB.)

3. NOT ON SIZE ERROR clause:

   ADD 14 TO ITEMA ITEMA = 99 ON SIZE ERROR MOVE 0 TO ITEMB. NOT ON SIZE ERROR MOVE 1 TO ITEMB. ITEMB = 1

   
   (If the SIZE ERROR condition had occurred, the value of ITEMA would have been 85 and ITEMB would have been 0.)

4. Multiple receiving fields:

   ADD 1 TO ITEMB ITEMD (ITEMB). ITEMB = 3 ITEMD (3) = 4

   
   (The operations proceed from left to right. Therefore, the subscript for ITEMD is evaluated after the addition changes its value.)

5. GIVING phrase:

   ADD ITEMB ITEMD (ITEMB) GIVING ITEMA. ITEMA = 4

6. END-ADD:
   

   IF ITEMB < 10 ADD 7 ITEMB TO ITEMD (ITEMB) ITEMD (2) = 2 ON SIZE ERROR MOVE 0 TO ITEMB ITEMB = 0 END-ADD ADD 1 TO ITEMB. ITEMB = 1

   
   (The first ADD terminates with END-ADD. If the SIZE ERROR condition had not occurred, the second ADD statement would have executed anyway; the value of ITEMB would have been 3.)

Function

The ALTER statement changes the destination of a GO TO statement.

proc

is the name of a paragraph that contains one sentence: a GO TO statement without the DEPENDING phrase.

new-proc

is a procedure-name.

General Rules

1. The ALTER statement changes the destination of the GO TO statement in proc.
2. When the changed GO TO executes, it transfers control to new-proc instead of the procedure it previously referred to.
   However, when the GO TO statement is in an independent segment (segment-number 50 to 99), the GO TO statement could return to its initial state under some circumstances.
3. A GO TO statement in a section with a segment-number greater than 49 cannot be changed by an ALTER statement in a section with a different segment-number.

Additional References

• Section 6.7, Segmentation
• Section 6.8.16, GO TO statement

Examples

The examples assume the following Procedure Division code:

PROC-AA. DISPLAY "PROC-A". PROC-A. GO TO PROC-BB. PROC-BB. DISPLAY "PROC-B". PROC-B. GO TO PROC-DD. PROC-CC. DISPLAY "PROC-C". PROC-C. GO TO PROC-FF. PROC-DD. DISPLAY "PROC-D". PROC-D. GO TO PROC-CC. PROC-EE. DISPLAY "PROC-E". PROC-E. GO TO. PROC-FF. DISPLAY "PROC-F". PROC-F. EXIT.

1. As written.

   Output
   PROC-A
   PROC-B
   PROC-D
   PROC-C
   PROC-F

2. ALTER PROC-A TO PROC-EE PROC-E TO PROC-CC.

   Output
   PROC-A
   PROC-E
   PROC-C
   PROC-F

3. ALTER PROC-D TO PROC-EE PROC-C TO PROC-AA.

   Output
   PROC-A
   PROC-B
   PROC-D
   PROC-E
   error at PROC-E

Function

The CALL statement transfers control to another program in the executable image.

prog-name

is a nonnumeric literal or the identifier of an alphanumeric data item. It is the name of the program to which control transfers.

arg

is the argument. It identifies the data that is available to both the calling and called programs. It is any data item described in the File Section, Working-Storage Section, or Linkage Section, or it is a nonnumeric literal. It must not be a function-identifier.

function-res

is the identifier of an elementary integer numeric data item with COMP, COMP-1, or COMP-2 usage and no scaling positions. function-res can be subscripted, and it can be qualified. When control returns to the calling program, function-res can contain a function result.

stment

is an imperative statement executed for an on exception or an overflow condition.

stment2

is an imperative statement executed for a not on exception or a not on overflow condition.

Syntax Rules

1. prog-name must be from 1 to 31 characters long. It can contain the characters "A" to "Z", "a" to "z", "0" to "9", and hyphen (-), dollar sign ($), and underline (_).
2. prog-name is the entry-point in the called program. For COBOL programs, prog-name is the program-name specified in the PROGRAM-ID paragraph.
3. The same arg can appear more than once in the USING phrase.
4. The maximum number of arguments is 255.
5. If there is no initial argument-passing mechanism (REFERENCE, VALUE, CONTENT, or, for DESCRIPTOR), BY REFERENCE is the default.
6. An argument-passing mechanism applies to every arg following it until a new mechanism (if any) appears.
7. The CALL statement has a USING phrase only if a USING phrase is in the Procedure Division header of the called program. Both USING phrases must have the same number of arguments.
8. If arg is a nonnumeric literal, only BY REFERENCE, BY CONTENT, or for OpenVMS Alpha systems, BY DESCRIPTOR can be used.
9. OMITTED, a reserved word, indicates the absence of a specific argument. OMITTED does not change the default argument-passing mechanism; it generates BY VALUE 0 for the omitted argument.
10. If the argument-passing mechanism is BY VALUE, arg must be either: (a) an integer numeric literal in the range -2**31 to +2**31-1, (b) a COMP-1 data item, or (c) a word or longword integer COMP data item.

General Rules

1. The program whose name is specified by prog-name is the called program. The program containing the CALL statement is the calling program.
2. When the CALL statement executes, the contents of prog-name are interpreted as follows:
   • Hyphens are treated as underline characters.
   • Lowercase letters are treated as uppercase (See the Technical Notes relating to case sensitivity later in this section).
   • Leading and trailing spaces and tab characters are ignored.
3. The CALL statement transfers control to the called program.
4. Two or more programs in the run unit can have the same prog-name. The scope of names conventions for program-names resolve the CALL statement references to duplicate prog-names. (See the section on Conventions for Resolving Program-Name References.)
5. If prog-name is an identifier, the CALL statement can transfer control only to Compaq COBOL programs.
6. The ON EXCEPTION phrase is interchangeable with the ON OVERFLOW phrase.
7. If prog-name is not in the executable image and there is an ON EXCEPTION phrase, any NOT ON EXCEPTION phrase is ignored, stment executes, and control is transferred to the end of the CALL statement.
8. If prog-name is in the executable image, and there is an ON OVERFLOW phrase or ON EXCEPTION phrase, both phrases are ignored. Control is transferred either to the end of the CALL statement or, if NOT ON EXCEPTION is specified, to stment2. After stment2 executes, control is transferred to the end of the CALL statement.
9. If prog-name is not in the executable image and there is no ON EXCEPTION phrase, an error condition exists; the program terminates abnormally.
10. If the called program does not have the initial attribute, it, and each program directly or indirectly contained in it, is in its initial state: (a) the first time it is called in an image, and (b) the first time it is called after a CANCEL to the called program.
    On all other entries, the state of the called program is the same as when it was last exited. The program state includes internal data.
11. If the called program has the initial attribute, it, and each program directly or indirectly contained in it, is in its initial state every time it is called.
12. Files associated with a called program's internal file connectors are not in the open mode:
    • The first time the program is called
    • The first time the program is called after execution of a CANCEL statement referring to the program
    • Every time the program is called, if it has the initial attribute
    
    On all other entries, the status and positioning of such files in a called program are the same as when the program was last exited.
13. 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.
14. The arguments' order of appearance in the USING phrases of the CALL statement and the called program's Procedure Division header determine correspondence between the data-names used by the calling and called programs. Data-names correspond by position in the USING phrase, not by name.
    No correspondence exists for index-names. If a table is passed as an argument, the index associated with that table in the called program will be the one specified in the INDEXED BY phrase in the called program, not the index specified in the calling program.
15. The arguments in the CALL statement USING phrase are made available to the called program when the CALL executes.
16. Called programs can contain CALL statements. However, a called program must not execute a CALL statement that directly or indirectly calls the calling program.
17. The CALL statement can make data available to the called program by four argument-passing mechanisms:
    • REFERENCE---The address of (pointer to) arg is passed to the called program. This is the default mechanism: arguments are passed BY REFERENCE if there is no explicit mechanism in the CALL statement.
    • CONTENT---The address of a temporary data item that contains the contents of arg is passed to the called program.
    • On OpenVMS, DESCRIPTOR---The address of (pointer to) the data item's descriptor is passed to the called program.
      The parameter-passing mechanism BY DESCRIPTOR is not supported on Tru64 UNIX or Windows NT systems, because the Tru64 UNIX and Windows NT calling standards do not define such a mechanism. Programs that include BY DESCRIPTOR will receive a compile-time diagnostic. <>
    • VALUE---The value of arg is passed to the called program. If arg is a data-name, its description in the Data Division can be either:
      • COMP usage with no scaling positions; the picture can specify no more than nine digits
      • COMP-1 usage
    
    Note that OMITTED, a Compaq COBOL reserved word, is equivalent to BY VALUE 0 and can be used in place of that BY VALUE argument-passing mechanism.
18. If the called program is a COBOL program, the CALL statement can pass arguments only BY REFERENCE or BY CONTENT. If the called program is a non-COBOL program, the mechanism for each arg in the CALL statement USING phrase must be the same as the mechanism for each data-name in the called program's argument list.
19. If the BY REFERENCE phrase is either specified or implied for a parameter, the called program references the same storage area for the data item as the calling program. This mechanism ensures that the contents of the parameter in the calling program are always identical with the contents of the parameter in the called program.
20. If the BY CONTENT phrase is either specified or implied for a parameter, a copy of arg is moved to a temporary memory location, and the address of the temporary memory location is passed to the called program. This mechanism ensures that the called program cannot change the original contents of arg. However, the called program can change the value of the temporary memory location.
21. The data description of each arg in the calling program must be identical to each arg in the called program. The compiler does not convert, extend, or truncate any arg passed to a called program.
22. If the GIVING phrase of the CALL statement is not specified, the function result is made available in the RETURN-CODE special register when control returns to the calling program.
23. If the GIVING phrase is specified, the function result is made available in function-res when control returns to the calling program.