 |
Compaq COBOL
Reference Manual
Formats 6, 7, and 8
- 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).
- 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.
- 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).
- 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.
- When a Format 8 ACCEPT statement is specified, the value of
envlog-value is moved to dest-item (refer to
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.
- 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.
- 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.
- stment5 is executed if the exception condition does not
exist.
Technical Notes
All Formats
- On OpenVMS systems, if the data transfer is from a terminal, Ctrl/Z
is equivalent to an end-of-file indication. <>
- On Tru64 UNIX systems, if the data transfer is from a terminal,
Ctrl/D is equivalent to an end-of-file indication. <>
Format 1
- 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 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 systems to
name an input file.
- 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.
- On OpenVMS 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. <>
- An end-of-file indication during ACCEPT statement execution with an
AT END phrase causes control to transfer to the AT END imperative
statement.
- An end-of-file indication during ACCEPT statement execution without
the AT END phrase is an error. The program terminates abnormally.
- The ACCEPT statement fills dest-item with spaces if the
input is an empty record (for example, a carriage return only).
- On Tru64 UNIX, 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 Alpha, 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
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.
|
-
ACCEPT ITEMA.
| Input |
ITEMA |
|
COMPUTER
|
COMPUT
|
|
VAX
|
VAXsss
|
|
12.6
|
12.6ss
|
-
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
|
-
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)
|
|
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
|
-
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
- 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.
- In Format 2, the values of the operands before the word GIVING are
added. The sum is then stored in each rsult.
- In Format 3, data items in grp-1 are added to and stored
in the corresponding data items in grp-2.
Additional References
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.
|
- TO phrase: RESULTS
ADD 2 ITEMB TO ITEMA. ITEMA = 89
|
- 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.)
- 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.)
- 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.)
- GIVING phrase:
ADD ITEMB ITEMD (ITEMB) GIVING ITEMA. ITEMA = 4
|
- 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.)
6.8.3 ALTER
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
- The ALTER statement changes the destination of the GO TO statement
in proc.
- 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.
- 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
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.
|
- As written.
Output
PROC-A
PROC-B
PROC-D
PROC-C
PROC-F
-
ALTER PROC-A TO PROC-EE PROC-E TO PROC-CC.
Output
PROC-A
PROC-E
PROC-C
PROC-F
-
ALTER PROC-D TO PROC-EE PROC-C TO PROC-AA.
Output
PROC-A
PROC-B
PROC-D
PROC-E
error at PROC-E
6.8.4 CALL
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
- 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 (_).
- 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.
- The same arg can appear more than once in the USING phrase.
- The maximum number of arguments is 255.
- If there is no initial argument-passing mechanism (REFERENCE,
VALUE, CONTENT, or, for DESCRIPTOR), BY REFERENCE is the default.
- An argument-passing mechanism applies to every arg
following it until a new mechanism (if any) appears.
- 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.
- If arg is a nonnumeric literal, only BY REFERENCE, BY
CONTENT, or for OpenVMS Alpha systems, BY DESCRIPTOR can be used.
- 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.
- 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
- The program whose name is specified by prog-name is the
called program. The program containing the CALL statement is the
calling program.
- 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.
- The CALL statement transfers control to the called program.
- 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.)
- If prog-name is an identifier, the CALL statement can
transfer control only to Compaq COBOL programs.
- The ON EXCEPTION phrase is interchangeable with the ON OVERFLOW
phrase.
- 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.
- 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.
- If prog-name is not in the executable image and there is
no ON EXCEPTION phrase, an error condition exists; the program
terminates abnormally.
- 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.
- 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.
- 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.
- 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.
- 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.
- The arguments in the CALL statement USING phrase are made available
to the called program when the CALL executes.
- Called programs can contain CALL statements. However, a called
program must not execute a CALL statement that directly or indirectly
calls the calling program.
- 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 systems, because the Tru64 UNIX calling standard does
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.
- 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.
- 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.
- 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.
- 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.
- On Alpha systems, 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. <>
- If the GIVING phrase is specified, the function result is made
available in function-res when control returns to the calling
program.
|
