| Procedure Division - Intrinsic Functions | Procedure Division - ENTER - INVOKE | |
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.
Alternatively,
function-name can itself be used instead of an associated mnemonic-name.
When mnemonic-name is
associated with ARGUMENT-NUMBER in the SPECIAL-NAMES paragraph, then
identifier must be an unsigned integer.
When mnemonic-name is associated with ARGUMENT-VALUE or
ENVIRONMENT-VALUE in the SPECIAL-NAMES paragraph, then identifier must
be an alphanumeric data item.
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.
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. Identifier can be of any
class, category or usage, including an internal floating-point or
external floating-point item. 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. Screen-name cannot be an
item with an OCCURS clause. The LINE and COLUMN phrases
can appear in any order.
EXCEPTION and ESCAPE are
equivalent.
Identifier-4 must be a PIC
9(4) or a PIC 9(6) data item. Identifier-8 must be an
integer. It can be signed.
Integer-7 can be signed.
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.
The phrases following the
identifier can be in any order.
The SPACE-FILL, ZERO-FILL,
LEFT-JUSTIFY, RIGHT-JUSTIFY, PROMPT and TRAILING-SIGN options are
allowed only if the operand is an elementary item.
Elementary data items in
identifier-1 must be of USAGE DISPLAY.
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.
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:
If the FROM option is not given, it is equivalent to specifying FROM CONSOLE.
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.
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.)
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:
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.
If the mnemonic-name
associated with the function-name ENVIRONMENT-VALUE is used then,
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.
DAY-OF-WEEK,
and TIME are conceptual data items and, therefore, are not described in the COBOL program.
| 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. |
| 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. |
| 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. |
| 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. |
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.
The value returned from the
ACCEPT FROM LINE NUMBER phrase is always numeric. The value is
implementation-dependent.
The FROM USER NAME option
returns a user-id number on UNIX systems, or spaces on systems where
such a concept is meaningless.
The FROM ESCAPE KEY option
returns the two digit code generated by a termination key.
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.
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. The order of execution of
an ACCEPT statement is always:
The AT phrase gives the
absolute address on the screen where the ACCEPT operation is to start.
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.
Certain combinations of
line and column numbers have special meanings, as follows:
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.
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.) The ACCEPT operation starts
at line 1, column 1 if no AT phrase is specified.
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.
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.
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.
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.
If the PROMPT option is not
specified, those character-positions into which the operator does not
enter data produce spaces in the data item.
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.
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.
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.)
The LEFT-JUSTIFY option is
documentary only.
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.
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.
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.)
The WITH UPPER option
forces input into upper case.
The WITH LOWER option
forces input into lower case.
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.
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.
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.
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.
If a time-out exception
occurs, then the contents of any ACCEPT resultant-field will be defined
as follows:
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).
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.
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.)
All references to (NOT) ON
EXCEPTION phrases also apply to (NOT) ON ESCAPE phrases. 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. The ADD statement causes two or more numeric operands to be summed and the result to be stored.
Floating-point literals
and floating-point data items can be used anywhere a numeric data item
or literal can be specified. Your COBOL system ensures
that enough places are carried so as not to lose any significant digits
during execution. 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.
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.
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.
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.
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.
, literal-2
, and literal-3
must be nonnumeric literals and cannot be a figurative constant.
* Integer-1 may be signed.
Local-Storage 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.
* 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.
* Neither identifier-5,
identifier-6, identifier-7, nor identifier-8 can be a
function-identifier.
* GIVING and RETURNING are
equivalent.
* Identifier-8 must be 4
bytes in size.
Identifier-9 must be
defined as a data item in the Linkage Section with a level number of 01
or 77.
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 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.
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.
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.
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.
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.
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:
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.
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.
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:
The mechanism used in
this example is as follows:
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.
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.
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.
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.
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.
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:
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.
* 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.
* 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.
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.
* 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(n) USAGE COMP-5, where the
value of n is at least 9 and defines a data item that is large enough
to hold the maximum length of a data item in the COBOL system. The
contents of the additional data item are set to the number of bytes of
storage allocated to identifier-5.
*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 and is BINARY,
COMP-4, COMP-5 or COMP-X, then the data description of the additional
data item is identical to that of identifier-6, except its usage is
COMP-5. The contents of the additional data item are identical to the
COMP-5 representation of the contents of identifier-6. This conversion
and representation facilitates calling non-COBOL programs.
Otherwise, if identifier-6 is specified then 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 data
description of the additional item is equivalent to a signed numeric
item USAGE COMP-5 that occupies the number of bytes of storage
indicated by the value of integer-2, if specified, or the size of the
system area otherwise (typically the size of a POINTER on the system).
If LENGTH OF identifier-7 is specified, then the
data description of the additional item is equivalent to PIC S9(n)
USAGE COMP-5, where the value of n is at least 9 and defines a data
item that is large enough to hold the maximum length of a data item in
the COBOL system. The contents of the additional data item are set to
the number of bytes of storage allocated to identifier-7.
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 declared in the USING phrase of the
PROCEDURE DIVISION header that also has the BY VALUE phrase specified
or implied.
The additional data item generated as a result
of the CALL statement, described above, is related to this
corresponding parameter in the called program, as follows.
If the additional data item was subject to
conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the
data description of the corresponding parameter in the called program
must be identical to that of the data description of the additional
data item with the exception that the corresponding parameter's USAGE
can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the called
COBOL program, a conversion from the USAGE COMP-5 of the additional
data item to the USAGE of the corresponding parameter in the called
program is performed.
If the additional data item was not subject to
conversion to COMP-5, the data description of each parameter in the
called program must be the same as the corresponding additional data
item. This means there is no conversion or extension or truncation, of
the additional data item to match the corresponding parameter in the
called program.
If the program being called is not COBOL, the
size of the additional data item should not exceed the maximum size of
the system area (typically the size of a POINTER on the system);
otherwise the system might become catastrophically corrupt.
A called program can 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 the size
of a POINTER on the system) is determined outside the COBOL system and
limits the maximum value the return value can take, but the return
value might 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.
If the GIVING phrase is not specified and the
calling convention specifies updating the RETURN-CODE special register
(see 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.
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.
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.
It is an error to specify
the GIVING phrase for a called program that does not return a value.
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.
The END-CALL phrase
delimits the scope of the CALL statement.
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.
The OMITTED phrase is used
to pass unused parameters to a subprogram without having to declare a
dummy data item.
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.
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. The CANCEL statement ensures that the next time the referenced program is called it will be in its initial state.
If the name contains the entry-name contained in an ENTRY statement, the results are undefined.
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.
or GOBACK
statement.
or by execution of an
EXIT PROGRAM statement in a called program that possesses the initial
attribute.
The contents of data items
in external data records described by a program are not changed when
that program is canceled.
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.
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.
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.
The CLOSE statement terminates the processing of reels/units and files, with optional rewind and/or lock or removal where applicable.
Line
Sequential, 
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.
The
DISP option is applicable only to tape files.
It is documentary only.
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.
Following the successful
execution of a CLOSE statement, all
record or
file locks held by the run unit on the closed file are released.
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.
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.
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.
The current reel/unit is left in its current position.
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.
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.
This file cannot be opened again during this execution of this run unit.
Input Files and Input-Output Files (Reel/Unit Media):
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.
Output Files (Reel/Unit Media):
The following operations take place;
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.
The current reel or analogous device is positioned at its physical beginning.
The CLOSE statement
is executed as if none of the optional phrases is present.
This is an illegal combination of a CLOSE option and a file category. The results at object time are undefined.
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.
(This option has no
connection with the record or file locking used when sharing files.)
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.
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.
The COMPUTE statement assigns to one or more data items the value of an arithmetic expression.
or a floating-point
item.
"Equal" and "="
are synonymous.
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.
The CONTINUE statement is a no operation statement, indicating that no executable statement is present.
The DEL ETE statement logically removes a record from a mass storage file. It can be specified only for files with relative or indexed organization.
This rule is not
enforced.
and NOT INVALID KEY
phrase
in the DELETE statement. (See the section The INVALID KEY Condition in this chapter.)
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.
When using DELETE, the
record to be deleted must not be locked by another run unit.
Following the successful
execution of a DELETE statement, any record lock held by the run unit on
the deleted record is released.
The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.
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.
Alternatively,
function-name can itself be used instead of an associated mnemonic-name.
This restriction can be
ignored.
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.
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.
Screen-name cannot be an
item with an OCCURS clause. The LINE and COLUMN phrases
can appear in any order.
Integer-3 and identifier-4
must be 4 or 6 digits long. 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.
The phrases following the
identifier can be in any order.
Elementary data items in
identifier-1 must be of USAGE DISPLAY.
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.
If a DISPLAY verb is
followed by more than one identifier-1, any WITH clause applies only to
the operand immediately preceding it. 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.
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.
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.
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.
If the mnemonic-name
associated with the function-name ENVIRONMENT-VALUE is used then
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.
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.
Within identifier-1,
internal floating-point numbers are converted to external floating-point
numbers for display, so that:
Literal-1 may be a
floating-point literal. 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. The AT phrase gives the
absolute address on the screen where the DISPLAY operation is to start.
The order of execution of a
DISPLAY statement is always:
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.
Certain combinations of
line and column numbers have special meanings, as follows:
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.
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.
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.
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.
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.
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.
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.
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.
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. 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.
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.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Procedure Division - Intrinsic Functions | Procedure Division - ENTER - INVOKE | |