7.texi

@comment *********************************************************************
@comment ** 7. PROCEDURE DIVISION                                           **
@comment *********************************************************************
@newchapter{7,PROCEDURE DIVISION}
@diagram{PROCEDURE DIVISION,PD-Overview-Info,PD-Overview-TeX,None}
The @code{PROCEDURE DIVISION} of any GnuCOBOL program marks the point where all executable code is written.
@menu
* 7.1:  PROCEDURE DIVISION USING.
* 7.2:  PROCEDURE DIVISION CHAINING.
* 7.3:  PROCEDURE DIVISION RETURNING.
* 7.4:  PROCEDURE DIVISION Sections and Paragraphs.
* 7.5:  DECLARATIVES.
* 7.6: Common Clauses on Executable Statements.
@detailmenu
*   7.6.1: AT END + NOT AT END.
*   7.6.2: CORRESPONDING.
*   7.6.3: INVALID KEY + NOT INVALID KEY.
*   7.6.4: ON EXCEPTION + NOT ON EXCEPTION.
*   7.6.5: ON OVERFLOW + NOT ON OVERFLOW.
*   7.6.6: ON SIZE ERROR + NOT ON SIZE ERROR.
*   7.6.7: ROUNDED.
@end detailmenu
* 7.7: Special Registers.
* 7.8: GnuCOBOL Statements.
@end menu
@comment *********************************************************************
@comment ** 7.1 PROCEDURE DIVISION USING                                    **
@comment *********************************************************************
@page
@newsection{7.1,PROCEDURE DIVISION USING}
@diagram{PROCEDURE DIVISION Subprogram-Argument,PD-USING,PD-USING,None}
The @code{USING} clause defines the arguments that will be passed to a GnuCOBOL program which is serving as a subprogram.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{BY} and @code{IS} are optional and may be omitted.  The presence or absence of these words have no effect upon the program.
@comment Semantic Specifications:

@item
The
@syntaxidx{USING} clause should only be used on the procedure division header of subprograms (subroutines or user-defined functions).

@item
The calling program will pass zero or more data items, known as arguments, to this subprogram --- there must be exactly as many @var{identifier-1} data items specified on the @code{USING} clause as the maximum number of arguments the subprogram will ever be passed.

@item
If a subprogram does not expect any arguments, it should not have a @code{USING} clause specified on its procedure division header.

@item
The order in which arguments are defined on the @code{USING} clause must correspond to the order in which those arguments will be passed to the subprogram by the calling program.

@item
The identifiers specified on the @code{USING} clause must be defined in the linkage section of the subprogram.  No storage is actually allocated for those identifiers in the subprogram as the actual storage for them will exist in the calling program.

@item
A GnuCOBOL subprogram expects that all arguments to it will be one of two things:
@itemize @bullet
@item
The memory address of the actual data item (allocated in the calling program) that is being passed to the subprogram.

@item
A numeric, full-word, binary value (i.e. @syntaxrefalt{USAGE BINARY-LONG,USAGE}) which is the actual argument being passed to the subprogram.
@end itemize

In the case of the former, the @code{USING} clause on the procedure division header should describe the argument via the
@syntaxidx{BY REFERENCE} clause --- in the latter case, a
@syntaxidx{BY VALUE} specification should be coded.  This allows the code generated by the compiler to properly reference the subprogram arguments at run-time.

@item
@code{BY REFERENCE} is the assumed default for the first @code{USING} argument should no @code{BY} clause be specified for it.  Subsequent arguments will assume the @code{BY} specification of the argument prior to them should they lack a @code{BY} clause of their own.

@item
Changes made by a subprogram to the value of an argument specified on the @code{USING} clause will ``be visible'' to the calling program only if @code{BY REFERENCE} was explicitly specified or implicitly assumed for the argument on the subprogram's procedure division header @i{and} the argument was passed to the subprogram @code{BY REFERENCE} by the calling program.  @xref{Subprogram Arguments}, for additional information on the mechanics of how arguments are passed to subprograms.

@item
The optional @code{SIZE} clause allows you to specify the number of bytes a @code{BY VALUE} argument will occupy, with @code{SIZE DEFAULT} specifying 4 bytes (this is the default if no @code{SIZE} clause is used), @code{SIZE AUTO} specifying the size of the argument in the calling program and @code{SIZE @var{integer-1}} specifying a specific byte count.

@item
The optional @code{UNSIGNED} keyword, legal only if @code{SIZE AUTO} or @code{SIZE @var{integer-1}} are coded, will add the @code{unsigned} attribute to the argument's specification in the C-language function header code generated for the subprogram.  While not of any benefit when the calling program is a GnuCOBOL program, this can improve compatibility with a C-language calling program.

@item
The
@syntaxidx{OPTIONAL} keyword, legal only on @code{BY REFERENCE} arguments, allows calling programs to code
@syntaxidx{OMITTED} for that corresponding argument when they call this subprogram.  @xref{CALL}. for additional information on this feature.
@end enumerate
@comment *********************************************************************
@comment ** 7.2 PROCEDURE DIVISION CHAINING                                 **
@comment *********************************************************************
@page
@newsection{7.2,PROCEDURE DIVISION CHAINING}
@diagram{PROCEDURE DIVISION Main-Program-Argument,PD-CHAINING,PD-CHAINING,None}
The @code{CHAINING} term provides one mechanism a programmer may use to retrieve command-line arguments passed to a program at execution time.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
@code{PROCEDURE DIVISION CHAINING} may only be coded in a main program (that is, the first program executed when a compiled GnuCOBOL compilation unit is executed).  It cannot be used in any form of subprogram.

@item
The @code{CHAINING} clause defines arguments that will be passed to a main program from the operating system.  The argument identifiers specified on the @code{CHAINING} clause will be populated by character strings comprised of the parameters specified to the program on the command line that executed it, as follows:
@enumerate A
@item
When a GnuCOBOL program is executed from a command-line, the complete command line text will be broken into a series of @i{tokens}, where each token is identified as being a word separated from the others in the command text by at least one space.  For example, if the command line was @command{/usr/local/myprog THIS IS A TEST}, there will be five tokens identified by the operating system --- @samp{/usr/local/myprog}, @samp{THIS}, @samp{IS}, @samp{A} and @samp{TEST}.

@item
Multiple space-delimited tokens may be treated as a single token by enclosing them in quotes.  For example, there are only three tokens generated from the command line @command{C:\Pgms\myprog.exe @samp{THIS IS A} TEST} --- @samp{C:\Pgms\myprog.exe}, @samp{THIS IS A} and @samp{TEST}.  When quote characters are used to create multi-word tokens, the quote characters themselves are stripped from the token's value.

@item
Once tokens have been identified, the first one (the command) will be discarded; the rest will be stored into the @code{CHAINING} arguments when the program begins execution, with the 2nd token going to the 1@sup{st} argument, the 3rd token going to the 2nd argument and so forth.

@item
If there are more tokens than there are arguments, the excess tokens will be discarded.

@item
If there are fewer tokens than there are arguments, the excess arguments will be initialized as if the @syntaxrefalt{INITIALIZE @var{identifier-1},INITIALIZE} statement were executed.

@item
All identifiers specified on the @code{CHAINING} clause should be defined as @code{PIC X, PIC A}, group items (which are treated implicitly as @code{PIC X}) or as @code{PIC 9 USAGE DISPLAY}.  The use of @code{USAGE BINARY} (or the like) data items as @code{CHAINING} arguments is not recommended as all command-line tokens will be retained in their original character form as they are moved into the argument data items.

@item
If an argument identifier is smaller in storage size than the token value to be stored in it, the right-most excess characters of the token value will be truncated as the value is moved in.  Any @code{JUSTIFIED RIGHT} clause on such an argument identifier will be ignored.

@item
If an argument is larger in storage size than the token value to be stored in it, the token value will be moved into the argument identifier in a left-justified manner.  unmodified-modified byte positions in the identifier will be space filled, unless the argument identifier is defined as @code{PIC 9 USAGE DISPLAY}, in which case unmodified bytes will be filled with @samp{0} characters from the systems native character set.

This behaviour when the argument is defined as @code{PIC 9} may be unacceptable, as an argument defined as @code{PIC 9(3)} but passed in a value of @samp{1} from the command line will receive a value of @samp{100}, not @samp{001}.  Consider defining ``numeric'' command line arguments as @code{PIC X} and then using the @intrinsicref{NUMVAL} function to determine the proper numeric value.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.3 PROCEDURE DIVISION RETURNING                                **
@comment *********************************************************************
@page
@newsection{7.3,PROCEDURE DIVISION RETURNING}
@diagram{PROCEDURE DIVISION RETURNING,PD-RETURNING,PD-RETURNING,None}
The RETURNING clause on the PROCEDURE DIVISION header documents that the subprogram in which the clause appears will be returning a numeric value back to the program that called it. This is only available for functions as it does not work for programs and has issues depending on the platform (operating system) in use - You must test for this for the specific platform.
@comment Semantic Specifications:
@enumerate
@item
The @code{RETURNING} clause is optional within a subroutine, as not all subroutines return a value to their caller.

@item
The @code{RETURNING} clause is mandatory within a user-defined function, as all such must return a numeric result.

@item
The @var{identifier-1} data item should be defined as a @code{USAGE BINARY-LONG} data item.

@item
Main programs that wish to ``pass back'' a return code value to the operating system when they exit do not use @code{RETURNING} - they do so simply by MOVEing a value to the @code{RETURN-CODE} special register.

@item
This is not the only mechanism that a subprogram may use to pass a value back to its caller.  Other possibilities are:
@enumerate A
@item
The subprogram may modify any argument that is specified as @code{BY REFERENCE} on its @code{PROCEDURE DIVISION} header.  Whether the calling program can actually ``see'' any modifications depends upon how the calling program passed the argument to the subprogram.  @xref{CALL}, for more information.

@item
A data item with the @syntaxref{GLOBAL} attribute specified in its description in the calling program is automatically visible to and updatable by a subprogram nested with the calling program.  @xref{Independent vs Contained vs Nested Subprograms}, for more information on subprogram nesting.

@item
A data item defined with the @syntaxref{EXTERNAL} attribute in a subprogram and the calling program (same name in both programs) is automatically visible to and updatable by both programs, even if those programs are compiled separately from one  another.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.4 PROCEDURE DIVISION Sections and Paragraphs                  **
@comment *********************************************************************
@page
@newsection{7.4,PROCEDURE DIVISION Sections and Paragraphs}
The procedure division is the only one of the COBOL divisions that allows you to create your own sections and paragraphs.  These are collectively referred to as
@define{Procedures}, and the names you create for those sections and paragraphs are called
@define{Procedure Names}.

Procedure names are optional in the procedure division and --- when used --- are named entirely according to the needs and whims of the programmer.

Procedure names may be up to thirty one (31) characters long and may consist of letters, numbers, dashes and underscores.  A procedure name may neither begin nor end with a dash (@samp{-}) or underscore (@samp{_}) character.  This means that @code{Main}, @code{0100-Read-Transaction} and @code{17} are all perfectly valid procedure names.

There are three circumstances under which the use of certain GnuCOBOL statements or options will require the specification of procedures.  These situations are:
@enumerate
@item
When @syntaxref{DECLARATIVES} are specified.

@item
When the @statementref{ENTRY} is being used.

@item
When any procedure division statement that references procedures is used.  These statements are:
@itemize @bullet
@item
@code{ALTER @var{procedure-name}}

@item
@code{GO TO @var{procedure-name}}

@item
@code{MERGE @dots{} OUTPUT PROCEDURE @var{procedure-name}}

@item
@code{PERFORM @var{procedure-name}}

@item
@code{SORT @dots{} INPUT PROCEDURE @var{procedure-name}} and/or @code{SORT @dots{} INPUT PROCEDURE @var{procedure-name}}
@end itemize
@end enumerate
@comment *********************************************************************
@comment ** 7.5 DECLARATIVES                                                **
@comment *********************************************************************
@page
@newsection{7.5,DECLARATIVES}
@diagram{DECLARATIVES,PD-DECLARATIVES,PD-DECLARATIVES,PD-DECLARATIVES}
The @code{DECLARATIVES} area of the procedure division allows the programmer to define a series of ``trap'' procedures (referred to as declarative procedures) capable of intercepting certain events that may occur at program execution time.  The syntax diagram above shows the format of a single such procedure.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{AFTER}, @code{FOR}, @code{ON}, @code{PROCEDURE} and @code{STANDARD} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
@code{EC} and @code{EXCEPTION CONDITION} are interchangeable.
@comment Semantic Specifications:

@item
The declaratives area may contain any number of declarative procedures, but no two declarative procedures should be coded to trap the same event.

@item
The following points apply to the
@syntaxidx{USE BEFORE REPORTING} clause:
@enumerate A
@item
@var{identifier-2} must be a report group.

@item
At run-time, the declaratives procedure will be executed prior to the processing of the specified report group's presentation; within the procedure you may take either of the following actions:
@itemize @bullet
@item
You may adjust the value(s) of any items referenced in @syntaxref{SUM} or @syntaxref{SOURCE} clauses in the report group.

@item
You may execute the @syntaxref{SUPPRESS} statement to squelch the presentation of the specified report group altogether.  Note that you will be suppressing this one specific instance of that group's presentation and not all of them.
@end itemize
@end enumerate
@item
The following points apply to the
@syntaxidx{USE FOR DEBUGGING} clause:
@enumerate A
@item
This clause allows you to define a declarative procedure that will be invoked whenever@dots{}
@itemize @bullet
@item
@dots{}@var{identifier-1} is referenced on any statement.

@item
@dots{}@var{procedure-name-1} is executed.

@item
@dots{}any procedure is executed (@code{ALL PROCEDURES}).
@end itemize
@item
A @code{USE FOR DEBUGGING} declarative procedure will be ignored at @i{compilation} time unless @code{WITH DEBUGGING MODE} is specified in the @syntaxref{SOURCE-COMPUTER} paragraph.  Neither the compiler's
@switchidx{-fdebugging-line} nor
@switchidx{-debug} will activate this feature.

@item
Any @code{USE FOR DEBUGGING} declarative procedures will be ignored at @i{execution} time unless the
@envvarruntimeref{COB_SET_DEBUG} has been set to a value of @samp{Y}, @samp{y} or @samp{1}.

@item
The typical use of a @code{USE FOR DEBUGGING} declarative procedure is to display the
@register{DEBUG-ITEM}, which will be implicitly and automatically created in your program for you if @code{WITH DEBUGGING MODE} is active.

The structure of @code{DEBUG-ITEM} will be as follows:

@example
01  DEBUG-ITEM.
    05 DEBUG-LINE      PIC X(6).
    05 FILLER          PIC X(1) VALUE SPACE.
    05 DEBUG-NAME      PIC X(31).
    05 FILLER          PIC X(1) VALUE SPACE.
    05 DEBUG-SUB-1     PIC S9(4) SIGN LEADING SEPARATE.
    05 FILLER          PIC X(1) VALUE SPACE.
    05 DEBUG-SUB-2     PIC S9(4) SIGN LEADING SEPARATE.
    05 FILLER          PIC X(1) VALUE SPACE.
    05 DEBUG-SUB-3     PIC S9(4) SIGN LEADING SEPARATE.
    05 FILLER          PIC X(1) VALUE SPACE.
    05 DEBUG-CONTENTS  PIC X(31).
@end example

where@dots{}
@table @asis
@item @code{DEBUG-LINE}
@dots{} is the program line number of the statement that triggered the declaratives procedure.

@item @code{DEBUG-NAME}
@dots{} is the procedure name or identifier name that triggered the declaratives procedure.

@item @code{DEBUG-SUB-1}
@dots{} is the first subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.

@item @code{DEBUG-SUB-2}
@dots{} is the second subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.

@item @code{DEBUG-SUB-3}
@dots{} is the third subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.

@item @code{DEBUG-CONTENTS}
@dots{} is a (brief) statement of the manner in which the procedure that triggered the declaratives procedure was executed or the first 31 characters of the value of the identifier whose reference triggered the declaratives procedure (the value after the statement was executed).
@end table
@end enumerate
@item
The
@syntaxidx{USE AFTER STANDARD ERROR PROCEDURE} clause defines a declarative procedure invoked any time a failure is encountered with the specified I/O type (or against the specified file(s)).

@item
The @syntaxref{GLOBAL} option, if used, allows a declarative procedure to be used across the program containing the @statement{USE} and any subprograms nested within that program.

@item
Declarative procedures may not reference any other procedures defined outside the scope of DECLARATIVES.
@end enumerate
@comment *********************************************************************
@comment ** 7.6 Common Clauses on Executable Statements                    **
@comment *********************************************************************
@newsection{7.6,Common Clauses on Executable Statements}
@menu
* 7.6.1: AT END + NOT AT END.
* 7.6.2: CORRESPONDING.
* 7.6.3: INVALID KEY + NOT INVALID KEY.
* 7.6.4: ON EXCEPTION + NOT ON EXCEPTION.
* 7.6.5: ON OVERFLOW + NOT ON OVERFLOW.
* 7.6.6: ON SIZE ERROR + NOT ON SIZE ERROR.
* 7.6.7: ROUNDED.
@end menu
@comment *********************************************************************
@comment ** 7.6.1 AT END + NOT AT END                                      **
@comment *********************************************************************
@newsubsection{7.6.1,AT END + NOT AT END}
@diagram{AT END,PD-AT-END,PD-AT-END,None}
@code{AT END} clauses may be specified on @syntaxref{READ}, @syntaxref{RETURN}, @syntaxref{SEARCH} and @syntaxref{SEARCH ALL} statements.
@enumerate
@item
The following points pertain to the use of these clauses on @syntaxref{READ} and @syntaxref{RETURN} statements:
@enumerate A
@item
The @code{AT END} clause will --- if present --- cause @var{imperative-statement-1} (@pxref{Imperative Statement}) to be executed if the statement fails due to a file status of 10 (end-of-file).  @xref{File Status Codes}, for a list of possible File Status codes.

An @code{AT END} clause @i{will not detect other non-zero file-status values}.

Use a @syntaxref{DECLARATIVES} routine or an explicitly-declared file status field tested after the @code{READ} or @code{RETURN} to detect error conditions other than end-of-file.

@item
A @code{NOT AT END} clause will cause @var{imperative-statement-2} to be executed if the @code{READ} or @code{RETURN} attempt is successful.
@end enumerate

@item
The following points pertain to the use of these clauses on @syntaxref{SEARCH} and @syntaxref{SEARCH ALL} statements:
@enumerate A
@item
An @code{AT END} clause detects and handles the case where either form of table search has failed to locate an entry that satisfies the search conditions being used.

@item
The @code{NOT AT END} clause is not allowed on either form of table search.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.6.2 CORRESPONDING                                            **
@comment *********************************************************************
@page
@newsubsection{7.6.2,CORRESPONDING}
Three GnuCOBOL statements --- @syntaxrefalt{ADD,ADD CORRESPONDING}, @syntaxrefalt{MOVE,MOVE CORRESPONDING} and @syntaxrefalt{SUBTRACT,SUBTRACT CORRESPONDING} support the use of a @code{CORRESPONDING} option:
@verbatim
ADD CORRESPONDING group-item-1 TO group-item-2
MOVE CORRESPONDING group-item-1 TO group-item-2
SUBTRACT CORRESPONDING group-item-1 FROM group-item-2
@end verbatim

This option allows one or more data items within one group item (@var{group-item-1} --- the first named on the statement) to be paired with correspondingly-named (hence the name) in a second group item (@var{group-item-2} --- the second named on the statement).  The contents of @var{group-item-1} will remain unaffected by the statement while one or more data items within @var{group-item-2} will be changed.

In order for @var{data-item-1}, defined subordinate to group item @var{group-item-1} to be a @i{corresponding} match to @var{data-item-2} which is subordinate to @var{group-item-2}, each of the following must be true:
@enumerate
@item
Both @var{data-item-1} and @var{data-item-2} must have the same name, and that name may not explicitly or implicitly be @code{FILLER}.

@item
Both @var{data-item-1} and @var{data-item-2}@dots{}
@enumerate A
@item
@dots{}must exist at the same relative structural ``depth'' of definition within @var{group-item-1} and @var{group-item-2}, respectively

@item
@dots{}and all ``parent'' data items defined within each group item must have identical (but non-@code{FILLER}) names.
@end enumerate
@item
When used with a @code{MOVE} verb@dots{}
@enumerate A
@item
@dots{}one of @var{data-item-1} or @var{data-item-2} (but not both) is allowed to be a group item

@item
@dots{}and it must be valid to move @var{data-item-1} TO @var{data-item-2}.
@end enumerate
@item
When used with @code{ADD} or @code{SUBTRACT} verbs, both @var{data-item-1} and @var{data-item-2} must be numeric, elementary, unedited items.

@item
Neither @var{data-item-1} nor @var{data-item-2} may be a @syntaxref{REDEFINES} or @syntaxref{RENAMES} of another data item.

@item
Neither @var{data-item-1} nor @var{data-item-2} may have an @syntaxref{OCCURS} clause, although either may contain subordinate data items that @i{do} have an @code{OCCURS} clause (assuming rule 3a applies)
@end enumerate

Observe the definitions of data items @samp{Q} and @samp{Y}@dots{}

@example
01  Q.                           01  Y.
    03 X.                            02 A         PIC X(1).
       05 A         PIC 9(1).        02 G1.
       05 G1.                           03 G2.
          10 G2.                           04 B   PIC X(1).
             15 B   PIC X(1).        02 C         PIC X(1).
       05 C.                         02 G3.
          10 FILLER PIC X(1).           03 G5.
       05 G3.                              04 D   PIC X(1).
          10 G4.                        03 G6     PIC X(1).
             15 D   PIC X(1).        02 E         PIC 9(1).
       05 E         PIC X(1).        02 F         PIC X(1).
       05 F         REDEFINES V1     02 G         PIC X(4).
                    PIC X(1).        02 H         OCCURS 4 TIMES
       05 G.                                      PIC X(1).
          10 G6     OCCURS 4 TIMES   66 I         RENAMES E.
                    PIC X(1).        02 J.
       05 H         PIC X(4).           03 K.
       05 I         PIC 9(1).              04 L.
       05 J.                                  05 M.
          10 K.
             15 M   PIC X(1).
@end example

The following are the valid @code{CORRESPONDING} matches, assuming the statement @code{MOVE CORRESPONDING X TO Y} is being executed (there are no valid corresponding matches for @code{ADD CORRESPONDING} or @code{SUBTRACT CORRESPONDING} because every potential match up violates rule #4):

@center A, B, C, G

The following are the @code{CORRESPONDING} match ups that passed rule #1 (but failed on another rule), and the reasons why they failed.

@multitable @columnfractions .1 .9
@headitem Data Item @tab Failure Reason
@item @code{D} @tab Fails due to rule #2b
@item @code{E} @tab Fails due to rule #3b
@item @code{F} @tab Fails due to rule #5
@item @code{G1} @tab Fails due to rule #3a
@item @code{G2} @tab Fails due to rule #3a
@item @code{G3} @tab Fails due to rule #3a
@item @code{G4} @tab Fails due to rule #1
@item @code{G5} @tab Fails due to rule #1
@item @code{G6} @tab Fails due to rule #6
@item @code{H} @tab Fails due to rule #6
@item @code{I} @tab Fails due to rule #5
@item @code{J} @tab Fails due to rule #3a
@item @code{K} @tab Fails due to rule #3a
@item @code{L} @tab Fails due to rule #1
@item @code{M} @tab Fails due to rule #2a
@end multitable
@comment *********************************************************************
@comment ** 7.6.3 INVALID KEY + NOT INVALID KEY                            **
@comment *********************************************************************
@newsubsection{7.6.3,INVALID KEY + NOT INVALID KEY}
@diagram{INVALID KEY,PD-INVALID-KEY,PD-INVALID-KEY,None}
@code{INVALID KEY} clauses may be specified on @syntaxref{DELETE}, @syntaxrefalt{READ,Random READ}, @syntaxref{REWRITE}, @syntaxref{START} and @syntaxref{WRITE} statements.

Specification of an @code{INVALID KEY} clause will allow your program to trap an I/O failure condition (with an I/O error code in the file's @syntaxrefalt{FILE-STATUS,SELECT} field) that has occurred due to a record-not-found condition and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}).

An optional
@syntaxidx{NOT INVALID KEY} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.4 ON EXCEPTION + NOT ON EXCEPTION                          **
@comment *********************************************************************
@newsubsection{7.6.4,ON EXCEPTION + NOT ON EXCEPTION}
@diagram{ON EXCEPTION,PD-ON-EXCEPTION,PD-ON-EXCEPTION,None}
@code{EXCEPTION} clauses may be specified on @syntaxref{ACCEPT}, @syntaxref{CALL} and @syntaxref{DISPLAY} statements.

Specification of an exception clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}).  If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2).  The program may also be terminated, depending upon the type and severity of the error.

An optional
@syntaxidx{NOT ON EXCEPTION} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.5 ON OVERFLOW + NOT ON OVERFLOW                            **
@comment *********************************************************************
@newsubsection{7.6.5,ON OVERFLOW + NOT ON OVERFLOW}
@diagram{ON OVERFLOW,PD-ON-OVERFLOW,PD-ON-OVERFLOW,None}
@code{OVERFLOW} clauses may be specified on @syntaxref{CALL}, @syntaxref{STRING} and @syntaxref{UNSTRING} statements.

An @code{ON OVERFLOW} clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}).  If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2).  The program may also be terminated, depending upon the type and severity of the error.

An optional
@syntaxidx{NOT ON OVERFLOW} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.6 ON SIZE ERROR + NOT ON SIZE ERROR                        **
@comment *********************************************************************
@newsubsection{7.6.6,ON SIZE ERROR + NOT ON SIZE ERROR}
@diagram{ON SIZE ERROR,PD-ON-SIZE-ERROR,PD-ON-SIZE-ERROR,None}
@code{SIZE ERROR} clauses may be included on @syntaxref{ADD}, @syntaxref{COMPUTE}, @syntaxref{DIVIDE}, @syntaxref{MULTIPLY} and @syntaxref{SUBTRACT} statements.

Including an @code{ON SIZE ERROR} clause on an arithmetic statement will allow your program to trap a failure of an arithmetic statement (either generating a result too large for the receiving field, or attempting to divide by zero) and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}).  Field size overflow conditions occur silently, usually without any runtime messages being generated, even though such events rarely lend themselves to generating correct results.  Division by zero errors, when no @code{ON SIZE ERROR} clause exists, will produce an error message (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2) and will also abort the program.

An optional
@syntaxidx{NOT ON SIZE ERROR} clause will cause @var{imperative-statement-2} to be executed if the arithmetic statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.7 ROUNDED                                                  **
@comment *********************************************************************
@newsubsection{7.6.7,ROUNDED}
@diagram{ROUNDED,PD-ROUNDED,PD-ROUNDED,None}
GnuCOBOL provides for control over the final rounding process applied to the receiving fields on all arithmetic verbs.  Each of the arithmetic statements (@syntaxref{ADD}, @syntaxref{COMPUTE}, @syntaxref{DIVIDE}, @syntaxref{MULTIPLY} and @syntaxref{SUBTRACT}) statements allow an optional @code{ROUNDED} clause to be applied to each receiving data item.

The following rules apply to the rounding behaviour induced by this clause.
@enumerate
@item
Rounding only applies when the result being saved to a receiving field with a @code{ROUNDED} clause is a non-integer value.

@item
Absence of a @code{ROUNDED} clause is the same as specifying @code{ROUNDED MODE IS TRUNCATION}.

@item
Use of a @code{ROUNDED} clause without a @code{MODE} specification is the same as specifying @code{ROUNDED MODE IS NEAREST-AWAY-FROM-ZERO}.
@end enumerate

The behaviour of the eight different rounding modes is defined in the following table.  Note that a @samp{@dots{}} indicates the last digit repeats.  The examples assume an integer receiving field.
@table @asis
@item @code{AWAY-FROM-ZERO}
Rounding is to the nearest value of larger magnitude.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -4 @tab +3.499@dots{} @result{} +4
@item -2.500 @result{} -3 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -3 @tab +2.499@dots{} @result{} +3
@end multitable
@item @code{NEAREST-AWAY-FROM-ZERO}
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value with the larger absolute value is selected.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -3 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{NEAREST-EVEN}
Rounding is to the nearest value (larger or smaller).  If two values are equally near, the value whose rightmost digit is @i{even} is selected. This mode is sometimes called ``Banker's rounding''.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{NEAREST-TOWARD-ZERO}
Rounding is to the nearest value (larger or smaller).  If two values are equally near, the value with the smaller absolute value is selected.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -3 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{PROHIBITED}
No rounding is performed.  If the value cannot be represented exactly in the desired format, the @code{EC-SIZE-TRUNCATION} condition (exception code 1005) is set (and may be retrieved via the @syntaxrefalt{ACCEPT,ACCEPT FROM Runtime-Info} statement) and the results of the operation are undefined.
@multitable @columnfractions .5 .5
@item -3.510 @result{} Undefined @tab +3.510 @result{} Undefined
@item -3.500 @result{} Undefined @tab +3.500 @result{} Undefined
@item -3.499@dots{} @result{} Undefined @tab +3.499@dots{} @result{} Undefined
@item -2.500 @result{} Undefined @tab +2.500 @result{} Undefined
@item -2.499@dots{} @result{} Undefined @tab +2.499@dots{} @result{} Undefined
@end multitable
@item @code{TOWARD-GREATER}
Rounding is toward the nearest value whose algebraic value is larger.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -3 @tab +3.510 @result{} +4
@item -3.500 @result{} -3 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +4
@item -2.500 @result{} -2 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +3
@end multitable
@item @code{TOWARD-LESSER}
Rounding is toward the nearest value whose algebraic value is smaller.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +3
@item -3.500 @result{} -4 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -4 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -3 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -3 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{TRUNCATION}
Rounding is to the nearest value whose magnitude is smaller.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -3 @tab +3.510 @result{} +3
@item -3.500 @result{} -3 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@end table
@comment *********************************************************************
@comment ** 7.7 Special Registers                                          **
@comment *********************************************************************
@page
@newsection{7.7,Special Registers}
GnuCOBOL, like other COBOL dialects, includes a number of data items that are automatically available to a programmer without the need to actually define them in the data division.  COBOL refers to such items as registers or special registers.  The special registers available to a GnuCOBOL program are as follows:
@table @asis
@item @code{COB-CRT-STATUS}
PIC 9(4) --- This is the default data item allocated for use by the @statementrefalt{ACCEPT @var{data-item},ACCEPT data-item}, if no @syntaxrefalt{CRT STATUS,SPECIAL-NAMES} clause was specified..

@item @code{DEBUG-ITEM}
Group Item --- A group item in which debugging information generated by a @code{USE FOR DEBUGGING} section in the declaratives area of the procedure division will place information documenting why the @code{USE FOR DEBUGGING} procedure was invoked.  Consult the @syntaxref{DECLARATIVES} documentation for information on the structure of this register.

@item @code{LINAGE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each selected file having a @syntaxrefalt{LINAGE,File/Sort-Description} clause.  If there are multiple files whose file descriptions have @code{LINAGE} clauses, any explicit references to this register will require qualification (using @code{OF file-name}).  The value of this register will be the current logical line number within the page body.  The value of this register cannot be modified.

@item @code{LINE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each report defined in the program (via an @syntaxrefalt{RD,REPORT SECTION}).  If there are multiple reports, any explicit references to this register not made in the report section will require qualification (@code{OF report-name}).  The value of this register will be the current logical line number on the current page.  The value of this register cannot be modified.

@item @code{NUMBER-OF-CALL-PARAMETERS}
@code{BINARY-LONG SIGNED} --- This register contains the number of arguments passed to a subroutine --- the same value that would be returned by the @subpgmref{C$NARG}.  Its value will be zero when referenced in a main program.  This register, when referenced from within a user-defined function, returns a value of one (@samp{1}) if the function has any number of arguments and a zero if it has no arguments.

@item @code{PAGE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each report having an @syntaxrefalt{RD,REPORT SECTION}.  If there are multiple such reports, any explicit references to this register not made in the report section will require qualification ( @code{OF report-name}).  The value of this register will be the current report page number.  The value of this register cannot be modified.

@item @code{RETURN-CODE}
@code{BINARY-LONG SIGNED} --- This register provides a numeric data item into which a subroutine may @syntaxref{MOVE} a value (which will then be available to the calling program) prior to transferring control back to the program that called it, or into which a main program may @code{MOVE} a value before returning control to the operating system.  Many built-in subroutines will return a value using this register.  These values are --- by convention --- used to signify success (usually with a value of 0) or failure (usually with a non-zero value) of the process the program was attempting to perform.  This register may also be modified by a subprogram as a result of that subprogram's use of the @syntaxrefalt{RETURNING,PROCEDURE DIVISION RETURNING} clause.

@item @code{SORT-RETURN}
@code{BINARY-LONG SIGNED} --- This register is used to report the success/fail status of a @syntaxref{RELEASE} or @syntaxref{RETURN} statement.  A value of 0 is reported on success.  A value of 16 denotes failure.  An @syntaxrefalt{AT END,AT END + NOT AT END} condition on a @code{RETURN} is not considered a failure.

@item @code{WHEN-COMPILED}
@code{PIC X(16)} --- This register contains the date and time the program was compiled in the format @samp{mm/dd/yyhh.mm.ss}.  Note that only a two-digit year is provided.
@end table
@comment *   1.3.21: LENGTH OF.
@comment *********************************************************************
@comment ** 1.3.21 LENGTH OF                                                **
@comment *********************************************************************
@comment @newsubsection{1.3.21,LENGTH OF}
@page
@diagram{LENGTH OF,PD-LENGTH-OF,PD-LENGTH-OF,None}
Alphanumeric literals and identifiers may optionally be prefixed with the @code{LENGTH OF} clause.  The compile-time value generated by this clause will be the number of bytes in the alphanumeric literal or the defined size (in bytes) of the identifier.
@enumerate
@item
The reserved word @code{OF} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
Here is an example.  The following two GnuCOBOL statements both display the same result (27):

@example
01  Demo-Identifier          PIC X(27).
...
    DISPLAY LENGTH OF "This is a LENGTH OF Example"
    DISPLAY LENGTH OF Demo-Identifier
@end example

@item
The @code{LENGTH OF} clause on a literal or identifier reference may generally be used anywhere a numeric literal might be specified, with the following exceptions:
@itemize @bullet
@item
As part of the @code{FROM} clause of a @syntaxref{WRITE} or @statementref{RELEASE}.

@item
As part of the @code{TIMES} clause of a @statementref{PERFORM}.
@end itemize
@end enumerate
@comment *********************************************************************
@comment ** 7.8 GnuCOBOL Statements                                       **
@comment *********************************************************************
@page
@newsection{7.8,GnuCOBOL Statements}
@comment The following menu is hidden in html mode because it makes
@comment makeinfo segfault on some Linux distributions, and it is not
@comment actually necessary in html mode.
@iftex
@menu
* 7.8.1:  ACCEPT
@detailmenu
*   7.8.1.1: ACCEPT FROM CONSOLE
*   7.8.1.2: ACCEPT FROM COMMAND-LINE
*   7.8.1.3: ACCEPT FROM ENVIRONMENT
*   7.8.1.4: ACCEPT Data-Item
*   7.8.1.5: ACCEPT FROM DATE/TIME
*   7.8.1.6: ACCEPT FROM Screen-Info
*   7.8.1.7: ACCEPT FROM Runtime-Info
*   7.8.1.8: ACCEPT OMITTED
*   7.8.1.9: ACCEPT FROM EXCEPTION STATUS
@end detailmenu
* 7.8.2:  ADD
@detailmenu
*   7.8.2.1: ADD TO
*   7.8.2.2: ADD GIVING
*   7.8.2.3: ADD CORRESPONDING
@end detailmenu
* 7.8.3:  ALLOCATE
* 7.8.4:  ALTER
* 7.8.5:  CALL
* 7.8.6:  CANCEL
* 7.8.7:  CLOSE
* 7.8.8:  COMMIT
* 7.8.9:  COMPUTE
* 7.8.10: CONTINUE
* 7.8.11: DELETE
* 7.8.12: DISPLAY
@detailmenu
*   7.8.12.1: DISPLAY UPON device
*   7.8.12.2: DISPLAY UPON COMMAND-LINE
*   7.8.12.3: DISPLAY UPON ENVIRONMENT-NAME
*   7.8.12.4: DISPLAY data-item
*   7.8.12.5: DISPLAY data-item (Microsoft v1, 2)
@end detailmenu
* 7.8.13: DIVIDE
@detailmenu
*   7.8.13.1: DIVIDE INTO
*   7.8.13.2: DIVIDE INTO GIVING
*   7.8.13.3: DIVIDE BY GIVING
@end detailmenu
* 7.8.14: ENTRY
* 7.8.15: EVALUATE
* 7.8.15B: EXAMINE
* 7.8.16: EXHIBIT
* 7.8.17: EXIT
* 7.8.18: FREE
* 7.8.19: GENERATE
* 7.8.20: GOBACK
* 7.8.21: GO TO
@detailmenu
*   7.8.21.1: Simple GO TO
*   7.8.21.2: GO TO DEPENDING ON
@end detailmenu
* 7.8.22: IF
* 7.8.23: INITIALIZE
* 7.8.24: INITIATE
* 7.8.25: INSPECT
* 7.8.26: MERGE
* 7.8.27: MOVE
@detailmenu
*   7.8.27.1: Simple MOVE
*   7.8.27.2: MOVE CORRESPONDING
@end detailmenu
* 7.8.28: MULTIPLY
@detailmenu
*   7.8.28.1: MULTIPLY BY
*   7.8.28.2: MULTIPLY GIVING
@end detailmenu
* 7.8.29: OPEN
* 7.8.30: PERFORM
@detailmenu
*   7.8.30.1: Procedural PERFORM
*   7.8.30.2: Inline PERFORM
@end detailmenu
* 7.8.31: READ
@detailmenu
*   7.8.31.1: Sequential READ
*   7.8.31.2: Random READ
@end detailmenu
* 7.8.32: READY TRACE
* 7.8.33: RELEASE
* 7.8.34: RESET TRACE
* 7.8.35: RETURN
* 7.8.36: REWRITE
* 7.8.37: ROLLBACK
* 7.8.38: SEARCH
* 7.8.39: SEARCH ALL
* 7.8.40: SET
@detailmenu
*   7.8.40.1: SET ENVIRONMENT
*   7.8.40.2: SET Program-Pointer
*   7.8.40.3: SET ADDRESS
*   7.8.40.4: SET Index
*   7.8.40.5: SET UP/DOWN
*   7.8.40.6: SET Condition Name
*   7.8.40.7: SET Switch
*   7.8.40.8: SET ATTRIBUTE
*   7.8.40.9: SET LAST EXCEPTION
@end detailmenu
* 7.8.41: SORT
@detailmenu
*   7.8.41.1: File-Based SORT
*   7.8.41.2: Table SORT
@end detailmenu
* 7.8.42: START
* 7.8.43: STOP
* 7.8.44: STRING
* 7.8.45: SUBTRACT
@detailmenu
*   7.8.45.1: SUBTRACT FROM
*   7.8.45.2: SUBTRACT GIVING
*   7.8.45.3: SUBTRACT CORRESPONDING
@end detailmenu
* 7.8.46: SUPPRESS
* 7.8.47: TERMINATE
* 7.8.48: TRANSFORM
* 7.8.49: UNLOCK
* 7.8.50: UNSTRING
* 7.8.51: WRITE
@end menu
@end iftex
@comment *********************************************************************
@comment ** 7.8.1 ACCEPT                                                   **
@comment *********************************************************************
@newsubsection{7.8.1,ACCEPT}
@menu
* 7.8.1.1: ACCEPT FROM CONSOLE
* 7.8.1.2: ACCEPT FROM COMMAND-LINE
* 7.8.1.3: ACCEPT FROM ENVIRONMENT
* 7.8.1.4: ACCEPT data-item
* 7.8.1.5: ACCEPT FROM DATE/TIME
* 7.8.1.6: ACCEPT FROM Screen-Info
* 7.8.1.7: ACCEPT FROM Runtime-Info
* 7.8.1.8: ACCEPT OMITTED
* 7.8.1.9: ACCEPT FROM EXCEPTION STATUS
@end menu
@comment *********************************************************************
@comment ** 7.8.1.1 ACCEPT FROM CONSOLE                                    **
@comment *********************************************************************
@newunit{7.8.1.1,ACCEPT FROM CONSOLE}
@diagram{ACCEPT FROM CONSOLE,PD-ACCEPT-1,PD-ACCEPT-1,None}
This format of the @statement{ACCEPT} is used to read a value from the console window or the standard input device and store it into a data item (@var{identifier-1}).
@enumerate
@comment Syntactical Specifications:

@item
If no @code{FROM} clause is specified, @code{FROM CONSOLE} is assumed.
@comment Semantic Specifications:

@item
The specified @var{mnemonic-name-1} must either be one of the built-in device names @code{CONSOLE}, @code{STDIN}, @code{SYSIN} or @code{SYSIPT}, or a user-defined (@pxref{SPECIAL-NAMES}) mnemonic name @i{attached} to one of those four device names.

@item
Input will be read either from the console window (@code{CONSOLE}) or from the system-standard input (pipe 0 = @code{STDIN}, @code{SYSIN} or @code{SYSIPT}) and will be saved in @var{identifier-1}.

@item
If @var{identifier-1} is a numeric data item, the character value read from the console or standard-input device will be parsed according to the rules for input to the @intrinsicref{NUMVAL}, except that none of the trailing sign formats are honoured.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.2 ACCEPT FROM COMMAND-LINE                               **
@comment *********************************************************************
@page
@newunit{7.8.1.2,ACCEPT FROM COMMAND-LINE}
@diagram{ACCEPT FROM COMMAND-LINE,PD-ACCEPT-2,PD-ACCEPT-2,None}
This format of the @statement{ACCEPT} is used to retrieve information from the program's command line.

@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{ON} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@comment Semantic Specifications:
@item
When you accept from the
@syntaxidx{COMMAND-LINE} option, you will retrieve the entire set of arguments entered on the command line that executed the program, exactly as they were specified.  Parsing that returned data into its meaningful information will be your responsibility.

@item
Using @code{COMMAND-LINE} or @code{ARGUMENT-VALUE} in a *nix based platform and that includes Linux, OSX, BSD and under windows running msys or MinGW etc, the shell process will expand any arguments that have a @samp{*} in the list --- such as @samp{a*}, @samp{abc*.*}, etc. --- and create a list of all files that match the pattern. To avoid this if not wanted, put all such argument within quotes, @i{e.g.}, @code{progundertest "a*" b c d "ef*" "*hg"} and the text within quotes will be passed verbatim to the program (as in the example @command{progundertest}).

@item
By accepting from
@syntaxidx{ARGUMENT-NUMBER}, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the number of arguments found.  Parsing will be conducted according to the following rules:
@enumerate A
@item
Arguments will be separated by treating spaces and/or tab characters as the delimiters between arguments.  The number of such delimiters separating two non-blank argument values is irrelevant.

@item
Strings enclosed in double-quote characters (@samp{"}) will be treated as a single argument, regardless of how many spaces or tab characters (if any) might be embedded within the quotation characters.

@item
On Windows systems, single-quote, or apostrophe, characters (@samp{'}) will be treated just like any other data character and will @i{not} delineate argument strings.
@end enumerate

@item
By accepting from
@syntaxidx{ARGUMENT-VALUE}, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the ``current'' argument.  You specify which argument number is ``current'' via the @code{ARGUMENT-NUMBER} option on the @statementrefalt{DISPLAY,DISPLAY UPON COMMAND-LINE}.  Parsing of arguments will be conducted according to the rules set forth above.

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of an attempt to retrieve an @code{ARGUMENT-VALUE}.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.3 ACCEPT FROM ENVIRONMENT                                **
@comment *********************************************************************
@page
@newunit{7.8.1.3,ACCEPT FROM ENVIRONMENT}
@diagram{ACCEPT FROM ENVIRONMENT,PD-ACCEPT-3,PD-ACCEPT-3,None}
This format of the @statement{ACCEPT} is used to retrieve environment variable values.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{ON} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
By accepting from
@syntaxidx{ENVIRONMENT-VALUE}, you will be asking the GnuCOBOL run-time system to retrieve the value of the environment variable whose name is currently in the
@syntaxidx{ENVIRONMENT-NAME} register.  A value may be placed into the @code{ENVIRONMENT-NAME} register using the @code{ENVIRONMENT-NAME} option of the @statementrefalt{DISPLAY,DISPLAY UPON ENVIRONMENT-NAME}.

@item
A simpler approach to retrieving an environment variables value is to use the
@syntaxidx{ENVIRONMENT} option, where you specify the environment variable whose value is to be retrieved right on the @code{ACCEPT} statement itself.

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to an attempt to retrieve the value of a non-existent environment variable or the successful retrieval of an environment variable's value, respectively.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment ********************************************************************
@comment ** 7.8.1.4 ACCEPT data-item                                **
@comment ********************************************************************
@page
@newunit{7.8.1.4,ACCEPT data-item}
@diagram{ACCEPT data-item,PD-ACCEPT-4,PD-ACCEPT-4,PD-ACCEPT-4}
This format of the @statement{ACCEPT} is used to retrieve data from a working storate item or a formatted console window screen.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{AFTER}, @code{IS}, @code{NUMBER} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{COLUMN}, @code{COL} and @code{POSITION} are interchangeable.

@item
The reserved words @code{TIMEOUT} and @code{TIME-OUT} are interchangeable.
@comment Semantic Specifications:

@item
If @var{identifier-1} is defined in the @syntaxref{SCREEN SECTION}, any @code{AT}, @var{Attribute-Specification}, @code{LOWER}, @code{UPPER} or @code{SCROLL} clauses will be ignored.  In these cases, an implied @syntaxrefalt{DISPLAY,DISPLAY data-item} of @var{identifier-1} will occur before input is accepted.  Coding an explicit @code{DISPLAY identifier-1} before an @code{ACCEPT identifier-1} is redundant and will incur the performance penalty of painting the screen contents twice.

@item
The various @code{AT} clauses provide a means of positioning the cursor to a specific spot on the screen before the screen is read.  One or the other (but not both) may be used, as follows:
@enumerate A
@item
The @code{LINE} and @code{COLUMN} clauses provide one mechanism for specifying the line and column position to which the cursor will be positioned before allowing the user to enter data.  In the absence of one or the other, a value of 1 will be assumed for the one that is missing.  The author's personal preference, however, is to explicitly code both.

@item
The @var{literal-3} or @var{identifier-4} value, if specified, must be a four- or six-digit value with the 1@sup{st} half of the number indicating the line where the cursor should be positioned and the second half indicating the column.  You may code only one of each clause on any @code{ACCEPT}.
@end enumerate

@item
@code{WITH} options (including the various individual @var{Attribute-Specifications}) should be coded only once.

@item
The following @var{Attribute-Specification} clauses are allowed on the @code{ACCEPT} statement; these are the same as those allowed for @code{SCREEN SECTION} data items.  A particular @var{Attribute-Specification} may be used only once in any @code{ACCEPT}:
@itemize @bullet
@item
@syntaxref{AUTO}, @syntaxref{AUTO-SKIP}, @syntaxref{AUTOTERMINATE}, @code{TAB}

@item
@syntaxref{BACKGROUND-COLOR}

@item
@syntaxref{BEEP}, @syntaxref{BELL}

@item
@syntaxref{BEFORE TIME}

@item
@syntaxref{BLINK}

@item
@syntaxref{FOREGROUND-COLOR}

@item
@syntaxref{FULL}, @syntaxref{LENGTH-CHECK}

@item
@syntaxref{HIGHLIGHT}

@item
@syntaxref{LEFTLINE}

@item
@syntaxref{LOWER}

@item
@syntaxref{LOWLIGHT}

@item
@syntaxref{NO UPDATE}

@item
@syntaxref{OVERLINE}

@item
@syntaxref{PROMPT}

@item
@syntaxref{PROTECTED}

@item
@syntaxref{REQUIRED}, @syntaxref{EMPTY-CHECK}

@item
@syntaxref{REVERSE-VIDEO}

@item
@syntaxref{SCROLL DOWN}

@item
@syntaxref{SCROLL UP}

@item
@syntaxref{SIZE}

@item
@syntaxref{SECURE}, @syntaxref{NO-ECHO}

@item
@syntaxref{TIME OUT}

@item
@syntaxref{UPDATE}

@item
@syntaxref{UPPER}

@item
@syntaxref{UNDERLINE}
@end itemize

@item
The
@syntaxidx{SCROLL} option will cause the entire contents of the screen to be scrolled @code{UP} or @code{DOWN} by the specified number of lines before any value is displayed on the screen.  It is syntactically allowable to specify a @code{SCROLL UP} clause as well as a @code{SCROLL DOWN} clause.  In such an instance, it is the last one specified that will be honoured.  If no @code{LINES} specification is made, @code{1 LINE} will be assumed.

@item
The
@syntaxidx{TIMEOUT} option will cause the @code{ACCEPT} to wait no more than the specified number of seconds for input.  The wait count may be specified as a positive integer or a numeric data item with a positive value.

@item
The
@syntaxidx{UPDATE} option will enable the supplied data field to be updated having been displayed on screen prior to data being entered by overwriting, if needed. When this option is @i{not} used the input field is cleared prior to input and this is the default but can be changed by the use of compiler steering command -faccept-with-update that can be input when starting the compiler or included in the configuration file e.g., default.conf used when selected by default @option{-std=default}. For more information see @ref{cobc - The GnuCOBOL Compiler} option switches) and @ref{Compiler Configuration Files}.

@item
This format of the @code{ACCEPT} statement will be terminated by any of the following events:
@enumerate A
@item
When the @key{Enter} key is pressed.

@item
Expiration of the @code{TIMEOUT} timer --- this will be treated as if the @key{Enter} key had been pressed with no data being entered.

@item
When a function key (@key{F@var{n}}) is pressed.

@item
The pressing of the @key{PgUp} or @key{PgDn} keys, if the
@envvarruntimeref{COB_SCREEN_EXCEPTIONS} is set to any non-blank value.

@item
The pressing of the @key{Esc} key if @i{both} the
@envvarruntime{COB_SCREEN_ESC} as well as
@envvarruntime{COB_SCREEN_EXCEPTIONS} are set to any non-blank value.

@item
The pressing of the @key{Up-arrow}, @key{Down-Arrow} or @key{PrtSc} (Print Screen) keys.  These keys are not detectable on Windows systems, however.
@end enumerate

@item
The following apply when @var{identifier-1} is defined in the @code{SCREEN SECTION}:
@enumerate A
@item
Alphanumeric data entered into @var{identifier-1} or any screen data item subordinate to it @i{must} be consistent with the @syntaxref{PICTURE} clause of that item.  This will be enforced at runtime by the @code{ACCEPT} statement.

@item
If @var{identifier-1} or any screen data item subordinate to it are defined as numeric, entered data must be acceptable as @intrinsicref{NUMVAL} input (no decimal points are allowed, however).  The value stored into the screen data item will be as if the input were passed to that function.

@item
If @var{identifier-1} or any screen data item subordinate to it are defined as numeric edited, entered data must be acceptable as @intrinsicref{NUMVAL-C} input (again, no decimal points are allowed).  The value stored into the screen data item will be as if the input were passed to that function.
@end enumerate

@item
The following apply when @var{identifier-1} is @i{not} defined in the @code{SCREEN SECTION}:
@enumerate A
@item
Alphanumeric data entered into @var{identifier-1} @i{should} be consistent with the @syntaxref{PICTURE} clause of that item, although that will not be enforced by the @code{ACCEPT} statement.  You may use @syntaxref{Class Conditions} after the data is accepted to enforce the data type.

@item
If @var{identifier-1} is defined as numeric, entered data must be acceptable as @intrinsicref{NUMVAL} input (no decimal points are allowed, however).  The value stored into @var{identifier-1} will be as if the input were passed to that function.

@item
If @var{identifier-1} is defined as numeric edited, entered data must be acceptable as @intrinsicref{NUMVAL-C} input (again, no decimal points are allowed).  The value stored into @var{identifier-1} will be as if the input were passed to that function.
@end enumerate

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of the screen I/O attempt.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.

After this format of the @code{ACCEPT} statement is executed, the program's @syntaxrefalt{CRT STATUS,SPECIAL-NAMES} identifier will be populated with one of the following:

@anchoridx{CRT STATUS Codes}
@multitable @columnfractions .15 .85
@headitem Code @tab Meaning
@item 0000 @tab @key{ENTER} key pressed
@item 1001--1064 @tab @key{F1}--@key{F64}, respectively, were pressed
@item 2001 @tab @key{PgUp} was pressed
@item 2002 @tab @key{PgDn} was pressed
@item 2003 @tab @key{Up-Arrow} was pressed
@item 2004 @tab @key{Down-Arrow} was pressed
@item 2005 @tab @key{Esc} was pressed
@item 2006 @tab @key{PrtSc} (Print Screen) was pressed
@item 2007 @tab @key{Tab}
@item 2008 @tab @key{Back Tab}
@item 2009 @tab @key{Key Left}
@item 2010 @tab @key{Key Right}
@item 2011 @tab @key{Insert} Key on accept omitted
@item 2012 @tab @key{Delete} Key on accept omitted
@item 2013 @tab @key{Backspace} Key on accept omitted
@item 2014 @tab @key{Home} Key on accept omitted
@item 2015 @tab @key{End} Key on accept omitted
@item 2040-@tab 2095 Exception keys for Mouse Handling
@item 2040 @tab Mouse Move
@item 2041 @tab Left Pressed
@item 2042 @tab Left Released
@item 2043 @tab Left Dbl Click
@item 2044 @tab Mid Pressed
@item 2045 @tab Mid Released
@item 2046 @tab Mid Dbl Click
@item 2047 @tab Right Pressed
@item 2048 @tab Right Released
@item 2049 @tab Right Dbl Click
@item 2050 @tab Shift Move
@item 2051 @tab Shift Left Pressed
@item 2052 @tab Shift Left Released
@item 2053 @tab Shift Left Dbl Click
@item 2054 @tab Shift Mid Pressed
@item 2055 @tab Shift Mid Released
@item 2056-@tab Shift Mid Dbl Click
@item 2057 @tab Shift Right Pressed
@item 2058 @tab Shift Right Released
@item 2059 @tab Shift Right Dbl Click
@item 2060 @tab Ctrl Move
@item 2061 @tab Ctrl Left Pressed
@item 2062 @tab Ctrl Left Released
@item 2063 @tab Ctrl Left Dbl Click
@item 2064 @tab Ctrl Mid Pressed
@item 2065 @tab Ctrl Mid Released
@item 2066 @tab Ctrl Mid Dbl Click
@item 2067 @tab Ctrl Right Pressed
@item 2068 @tab Ctrl Right Released
@item 2069 @tab Ctrl Right Dbl Click
@item 2070 @tab Alt Move
@item 2071 @tab Alt Left Pressed
@item 2072 @tab Alt Left Released
@item 2073-@tab Alt Left Dbl Click
@item 2074 @tab Alt Mid Pressed
@item 2075 @tab Alt Mid Released
@item 2076 @tab Alt Mid Dbl Click
@item 2077 @tab Alt Right Pressed
@item 2078 @tab Alt Right Released
@item 2079 @tab Alt Right Dbl Click
@item 2080 @tab Wheel Up
@item 2081 @tab Wheel Down
@item 2082 @tab Wheel Left
@item 2083 @tab Wheel Right
@item 2084 @tab Shift Wheel Up
@item 2085 @tab Shift Wheel Down
@item 2086 @tab Shift Wheel Left
@item 2087 @tab Shift Wheel Right
@item 2088 @tab Ctrl Wheel Up
@item 2089 @tab Ctrl Wheel Down
@item 2090 @tab Ctrl Wheel Left
@item 2091 @tab Ctrl Wheel Right
@item 2092 @tab Alt Wheel Up
@item 2093 @tab Alt Wheel Down
@item 2094 @tab Alt Wheel Left
@item 2095 @tab Alt Wheel Right
@item @tab Input validation
@item 8000 @tab NO Field
@item 8001 @tab Time Out
@item @tab Other errors
@item 9000 @tab Fatal
@item 9001 @tab Max Field
@end multitable

@item
The actual key pressed to generate a function key (@key{F@var{n}}) will depend on the type of terminal device you're using (PC, Macintosh, VT100, etc.) and what type of enhanced display driver was configured with the version of GnuCOBOL you're using.

For example, on a GnuCOBOL build for a Windows PC using MinGW and ``PDCurses'', @key{F1}--@key{F12} are the actual F-keys on the PC keyboard, @key{F@var{13}}--@key{F@var{24}} are entered by shifting the F-keys, @key{F@var{25}}--@key{F@var{36}} are entered by holding Ctrl while pressing an F-key and @key{F@var{37}}--@key{F@var{48}} are entered by holding Alt while pressing an F-key.  On the other hand, a GnuCOBOL implementation built for Windows using Cygwin and NCurses treats the PCs @key{F@var{1}}--@key{F@var{12}} keys as the actual @key{F@var{1}}--@key{F@var{12}}, while shifted F-keys will enter @key{F@var{11}}--@key{F@var{2}}0.  With Cygwin/NCurses, Ctrl- and Alt-modified F-keys aren't recognized, nor are @key{Shift-F@var{11}} or @key{Shift-F@var{12}}.


Mouse Key codes are populated only if mouse management has been enabled. To enable mouse it is first necessary to set @env{COB_MOUSE_FLAGS} (either externally via terminal command, or internally via @code{SET ENVIRONMENT} to the applicable ?mouse mask? (specifying which activities you wish the program to detect). Here is an example of setting the mask from a COBOL program:

@example
@group
COPY @file{screenio.cpy}.

01  mouse-flags PIC 9(4).

...

    COMPUTE mouse-flags = COB-AUTO-MOUSE-HANDLING
                        + COB-ALLOW-LEFT-DOWN
                        + COB-ALLOW-MIDDLE-DOWN
                        + COB-ALLOW-RIGHT-DOWN

    SET ENVIRONMENT "COB_MOUSE_FLAGS" TO @var{mouse-flags}.

@end group
@end example

@item
Once that has been done, every (extended) ACCEPT, will return a value in COB_CRT_STATUS reflecting mouse activity, when such activity occurs.
The applicable values are shown in screenio.cpy under ?Exception keys for mouse handling?.
If you define a variable in SPECIAL NAMES as follows:
@verbatim
SPECIAL-NAMES.
   CURSOR IS data-name.   *> where data-name is PIC 9(4) or 9(6).
@end verbatim

@item
The cursor or mouse position will be returned as well. The position is expressed as row and column (rrcc or rrrccc).

@item
Numeric keypad keys are not recognizable on Windows MinGW/PDCurses builds of GnuCOBOL, regardless of the number lock settings.  Windows Cygwin/NCurses builds recognize numeric keypad inputs properly.  Although not tested during the preparation of this documentation, I would expect native Windows builds using PDCurses to behave as MinGW builds do and native Unix builds using NCurses to behave as do Cygwin builds.

@item
The optional @code{EXCEPTION-STATUS} clause may be used to detect exceptions from a prior arithmetic verb such as COMPUTE to recover any errors produced. These are recovered using the function @code{EXCEPTION-STATUS}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.5 ACCEPT FROM DATE/TIME                                  **
@comment *********************************************************************
@page
@newunit{7.8.1.5,ACCEPT FROM DATE/TIME}
@diagram{ACCEPT FROM DATE/TIME,PD-ACCEPT-5,PD-ACCEPT-5,None}
This format of the @statement{ACCEPT} is used to retrieve the current system date, time or current day of the week and store it into a data item.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The data retrieved from the system and the format in which it is structured will vary, as follows:
@multitable @columnfractions .3 .5 .2
@headitem Syntax @tab Data Retrieved @tab Format
@item @code{DATE} @tab Current date in Gregorian form @tab yymmdd
@item @code{DATE YYYYMMDD} @tab Current date in Gregorian form @tab yyyymmdd
@item @code{DAY} @tab Current date in Julian form @tab yyddd
@item @code{DAY YYYYDDD} @tab Current date in Julian form @tab yyyyddd
@item @code{DAY-OF-WEEK} @tab Current day within a week where 1 = Monday.., 7 = Sunday @tab d
@item @code{TIME} @tab Time, including hundredths of a second (n) @tab hhmmssnn
@item @code{MICROSECOND-TIME} @tab Time, including micro seconds (u) @tab hhmmssuuuuuu
@end multitable

@item When using one of @option{--std=acu} or @option{--std=acu-strict},
ACCEPT FROM TIME data-item with data-item providing more than 12 digits behaves as if
ACCEPT FROM MICROSECOND-TIME data-item is used (six decimal places for fractional seconds).

@item Consider using the standard @code{FUNCTION FORMATTED-CURRENT-DATE} if you need a
high precision (up to eight decimal places for fractional seconds).

@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.6 ACCEPT FROM Screen-Info                                **
@comment *********************************************************************
@page
@newunit{7.8.1.6,ACCEPT FROM Screen-Info}
@diagram{ACCEPT FROM Screen-Info,PD-ACCEPT-6,PD-ACCEPT-6,None}
This format of the @statement{ACCEPT} is used to retrieve information about the console window or about the user's interactions with it.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{LINES} and @code{LINE-NUMBER} are interchangeable.

@item
The reserved words @code{COLS} and @code{COLUMNS} are interchangeable.
@comment Semantic Specifications:

@item
The following points pertain to the use of the
@syntaxidx{LINES} and
@syntaxidx{COLUMNS} options:
@enumerate A
@item
The
@syntaxidx{LINES} and
@syntaxidx{COLUMNS} options will retrieve the respective components of the size of the console display.

@item
When the console is running in a windowed environment, this will be the sizing of the window in which the program is executing, in terms of horizontal (@code{COLUMNS}) or vertical (@code{LINES}) character counts --- not pixels.

@item
When the system is not running a windowing environment, the physical console screen attributes will be returned.

@item
Values of 0 will be returned if GnuCOBOL was not generated to include screen I/O.

@item
See the documentation on the @subpgmref{CBL_GET_SCR_SIZE} for another way to retrieve this information.
@end enumerate

@item
The
@syntaxidx{ESCAPE KEY} option may be used after the @statementref{ACCEPT FROM Screen-Info} has executed.  The result returned will be the four-digit @syntaxrefalt{CRT STATUS,SPECIAL-NAMES} identifier value.  @xref{CRT STATUS Codes}, for the specific code values.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.7 ACCEPT FROM Runtime-Info                               **
@comment *********************************************************************
@page
@newunit{7.8.1.7,ACCEPT FROM Runtime-Info}
@diagram{ACCEPT FROM Runtime-Info,PD-ACCEPT-7,PD-ACCEPT-7,None}
This format of the @statement{ACCEPT} is used to retrieve run-time information such as the most-recent error exception code and the current user's user name.
@enumerate
@comment Syntactical Specifications:
@item
The following points pertain to the use of the
@syntaxidx{EXCEPTION STATUS} option:
@enumerate A
@item
@var{identifier-1} must be defined as a @code{PIC X(4)} item.

@item
@xref{Error Exception Codes}, for a complete list of the exception codes and their meanings.

@item
An alternative to the use of @code{ACCEPT FROM Runtime-Info} is to use the @intrinsicref{EXCEPTION-STATUS}.
@end enumerate

@item
The following points pertain to the use of the
@syntaxidx{USER NAME} option:
@enumerate A
@item
The returned result is the userid that was used to login to the system with, and not any actual first and/or last name of the user in question (unless, of course, that is the information used as a logon id). It is not the PID or UID numbers but the name associated with the UID under *nix based systems.

@item
@var{identifier-1} should be defined large enough to receive the longest user-name on the system.

@item
If insufficient space is allocated, the returned value will be truncated.

@item
If excess space is allocated, the returned value will be padded with spaces (to the right).
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.8 ACCEPT OMITTED                                         **
@comment *********************************************************************
@page
@newunit{7.8.1.8,ACCEPT OMITTED}
@diagram{ACCEPT OMITTED,PD-ACCEPT-8,PD-ACCEPT-8,None}
This format of the @statement{ACCEPT} will wait for a keyboard event that terminates input; function keys, or Enter/Return, among others. CRT STATUS (COB-CRT-STATUS @syntaxrefalt{CRT STATUS,SPECIAL-NAMES} if not explicitly defined) is set with the keycode, listed in copy/screenio.cpy. It also handles a few other keycode terminations not normally used to complete an extended accept.
@enumerate
@comment Syntactical Specifications:

@item
The following are examples of keycodes that can be used:
@verbatim
COB-SCR-INSERT
COB-SCR-DELETE
COB-SCR-BACKSPACE
COB-SCR-KEY-HOME
COB-SCR-KEY-END
@end verbatim

@item
You can use extended attributes, useful for setting timeouts or positioning.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.9 ACCEPT FROM EXCEPTION STATUS                           **
@comment *********************************************************************
@page
@newunit{7.8.1.9,ACCEPT FROM EXCEPTION STATUS}
@diagram{ACCEPT FROM EXCEPTION STATUS,PD-ACCEPT-9,PD-ACCEPT-9,None}
This format of the @statement{ACCEPT} will receive the status for any exceptions resulting from a previous valid verb.
@enumerate
@comment Syntactical Specifications:

@item
The following is an example of usage:
@verbatim
 In WS:
 01  exception-status  pic 9(4).
..
 In PD:

 ACCEPT unexpected-rounding  FROM EXCEPTION STATUS
 IF unexpected-rounding NOT EQUAL "0000" THEN
    DISPLAY "Unexpected rounding. Code " unexpected-rounding
             UPON SYSERR
 END-IF
@end verbatim
@end enumerate
@comment *********************************************************************
@comment ** 7.8.2 ADD                                                      **
@comment *********************************************************************
@page
@newsubsection{7.8.2,ADD}
@menu
* 7.8.2.1: ADD TO
* 7.8.2.2: ADD GIVING
* 7.8.2.3: ADD CORRESPONDING
@end menu
@comment *********************************************************************
@comment ** 7.8.2.1 ADD TO                                                 **
@comment *********************************************************************
@newunit{7.8.2.1,ADD TO}
@diagram{ADD TO,PD-ADD-1,PD-ADD-1,None}
This format of the @statement{ADD} generates an intermediate arithmetic sum of the values of all @var{identifier-1} and @var{literal-1}) items. The value of each @var{identifier-2} will be replaced, in turn, by the sum of that @var{identifier-2}s value and the intermediate sum.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items while @var{literal-1} must be a numeric literal.

@item
An @var{identifier-1} data item may also be coded as an @var{identifier-2}. Note, however, that the value of such a data item will therefore be included @i{twice} in the result.
@comment Semantic Specifications:

@item
The contents of each @var{identifier-1} will remain unchanged by this statement.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.2.2 ADD GIVING                                             **
@comment *********************************************************************
@page
@newunit{7.8.2.2,ADD GIVING}
@diagram{ADD GIVING,PD-ADD-2,PD-ADD-2,None}
This format of the @code{ADD} statement generates the arithmetic sum of the values of all @var{identifier-1}, @var{literal-1}) and @var{identifier-2} (if any) items and then saves that sum to each @var{identifier-3}.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items while @var{literal-1} must be a numeric literal; @var{identifier-3} may be either a numeric or numeric edited data item.

@item
An @var{identifier-1} or @var{identifier-2} data item may be used as an @var{identifier-3}, if desired.
@comment Semantic Specifications:

@item
The contents of each @var{identifier-1} and @var{identifier-2} will remain unchanged by this statement, unless they happen to also be specified as an @var{identifier-3}.

@item
The current value in each @var{identifier-3} at the start of the statement's execution is irrelevant, since the contents of each @var{identifier-3} will simply be replaced with the computed sum.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-3} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-3} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.2.3 ADD CORRESPONDING                                      **
@comment *********************************************************************
@page
@newunit{7.8.2.3,ADD CORRESPONDING}
@diagram{ADD CORRESPONDING,PD-ADD-3,PD-ADD-3,None}
This format of the @statement{ADD} generates code equivalent to individual @syntaxref{ADD TO} statements for corresponding matches of data items found subordinate to the two identifiers.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
Both @var{identifier-1} and @var{identifier-2} must be group items.

@item
@xref{CORRESPONDING}, for information on how corresponding matches will be found between @var{identifier-1} and @var{identifier-2}.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-3} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-3} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.3 ALLOCATE                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.3,ALLOCATE}
@diagram{ALLOCATE,PD-ALLOCATE,PD-ALLOCATE,None}
The @code{ALLOCATE} statement is used to dynamically allocate memory at run-time.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{INITIALIZED} and @code{INITIALISED} are interchangeable.

@item
If @var{identifier-1} is specified, the RETURNING phrase may be omitted; otherwise, the RETURNING phrase shall be
specified.

@item
If used, @var{arithmetic-expression-1} must be an arithmetic expression with a non-zero positive integer value and the RETURNING  phrase must be specified.

@item
If used, @var{identifier-1} should be an 01-level item defined in working-storage or local-storage with the @syntaxref{BASED} attribute.  It may be an 01 item defined in the linkage section without the @code{BASED} attribute, but using such a data item is not recommended.

@item
If used, @var{identifier-3} should be a @syntaxrefalt{POINTER,USAGE} data item.

@item
The optional
@syntaxidx{RETURNING} clause will return the address of the allocated memory block into the specified @code{USAGE POINTER} @var{identifier-3} data item.  When this option is used, knowledge of the originally-requested size of the allocated memory block will be retained by the program in case a @syntaxref{FREE} statement is ever issued against @var{identifier-3}.

@item
When the @var{identifier-1} option is used in conjunction with
@syntaxidx{INITIALIZED} (or its internationalized alternative @code{INITIALISED}), the allocated memory block will be initialized as if an @syntaxrefalt{INITIALIZE @var{identifier-1} WITH FILLER ALL TO VALUE THEN TO DEFAULT,INITIALIZE} were executed.

@item
When the @code{@var{arithmetic-expression-1} CHARACTERS} option is used, @code{INITIALIZED} will initialize the allocated memory block to binary zeros.  If @code{INITIALIZED} is not used, the initial contents of allocated memory will be left to whatever rules of memory allocation are in effect for the operating system the program is running under.

@item
There are two basic ways in which this statement is used.  The simplest is:

@example
ALLOCATE My-01-Item
@end example

With this form, a block of storage equal in size to the defined size of My-01-Item (which must have been defined with the @code{BASED} attribute) will be allocated.  The address of that block of storage will become the base address of My-01-Item so that it and its subordinate data items become usable within the program.

A second (and equivalent) approach is:

@example
ALLOCATE LENGTH OF My-01-Item CHARACTERS RETURNING The-Pointer
SET ADDRESS OF My-01-Item TO The-Pointer
@end example

@item
With this form My-01-Item can either be defined with the @code{BASED} attribute or be defined in LINKAGE SECTION.
Instead of LENGTH OF My-01-Item you may also use a size smaller to the maximum field size as long as you ensure that the complete field is never used.

@item
Referencing a @code{BASED} data item either before its storage has been allocated or after its storage has been released (via the @statement{FREE}) will lead to ``unpredictable results''.  That's how reference manuals and standards specifications talk about this situation.  In the author's experience, the results are all too predictable: the program aborts from an attempt to reference an unallocated area of memory.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.4 ALTER                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.4,ALTER}
@diagram{ALTER,PD-ALTER,PD-ALTER,None}
The @statement{ALTER} was used in the early years of the COBOL language to edit the object code of a program @strong{at execution time}, changing a @syntaxrefalt{GO TO,Simple GO TO} statement to branch to a spot in the program different than where the @code{GO TO} statement was originally compiled for.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{PROCEED} and @code{TO} (the one @i{after} @code{PROCEED}) are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
@var{procedure-name-1} must contain only a single statement, and that statement must be a simple @code{GO TO}.
@comment Semantic Specifications:

@item
The effect of this statement will be as if the generated machine-language code for the @code{GO TO} statement in @var{procedure-name-1} is changed so that the @code{GO TO} statement now transfers control to @var{procedure-name-2}, rather than to whatever procedure name was specified in the program source code.

@item
Support for the @code{ALTER} verb has been added to GnuCOBOL for the purpose of enabling GnuCOBOL to pass those National Institute of Standards and Technology (NIST) tests for the COBOL programming language that require support for @code{ALTER}.

@item
Because of the catastrophic effect this statement has on program readability and therefore the programmer's ability to debug problems with program logic, the use of @code{ALTER} in new programs is @strong{STRONGLY} discouraged.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.5 CALL                                                     **
@comment *********************************************************************
@page
@newsubsection{7.8.5,CALL}
@diagram{CALL,PD-CALL,PD-CALL,None}
@diagram{CALL Argument,PD-CALL-Arg,PD-CALL-Arg,None}
The @statement{CALL} is used to transfer control to a subroutine.  @xref{Sub-Programming}, for the specifics of using subprograms with GnuCOBOL programs.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{BY}, @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{EXCEPTION} and @code{OVERFLOW} are interchangeable.

@item
The reserved words @code{GIVING} and @code{RETURNING} are interchangeable.
@comment Semantic Specifications:

@item
The expectation is that the subroutine will eventually return control back to the calling program, at which point the @code{CALL}ing program will resume execution starting with the statement immediately following the @code{CALL}.  Subprograms are not required to return to their callers, however, and are free to halt program execution if they wish.

@item
The @var{mnemonic-name-1} /
@syntaxidx{STATIC} /
@syntaxidx{STDCALL} option, if used, affects the linkage conventions that will be used to the subroutine being called, as follows:
@table @asis
@item @code{STATIC}
causes the linkage to the subroutine to be performed in such a way as to require the subroutine to be statically-linked with the calling program.  Note that this enables static-linking to be used on a subroutine-by-subroutine selective basis.

@item @code{STDCALL}
allows system standard calling conventions (as opposed to GnuCOBOL calling conventions) to be used when calling a subroutine.  The definition of what constitutes ``system standard'' may vary from operating system to operating system.  Use of this requires special knowledge about the linkage requirements of subroutines you are intending to @code{CALL}.  Subroutines written in GnuCOBOL do not need this option.

@item @var{mnemonic-name-1}
allows a custom defined calling convention to be used.  Such mnemonic names are defined using the @syntaxrefalt{CALL-CONVENTION,SPECIAL-NAMES} clause.  That clause associates a decimal integer value with @var{mnemonic-name-1} such that the individual bits set on or off in the binary equivalent of the integer affect linkage to the subroutine as described in the following chart.  Those rows of the chart marked with a ``No'' in the @b{Supported} column represent bit positions (switch settings) in the integer value that are currently accepted (to provide compatibility to other COBOL implementations) if coded, but are otherwise unsupported.

Note that bit 0 is the right-most bit in the binary value.

@multitable @columnfractions .03 .15 .33 .33
@headitem Bit @tab Supported @tab Meaning if 0 @tab Meaning if 1
@item 0
@tab No @tab Arguments will be passed in right-to-left sequence @tab Arguments will be passed in left-to-right sequence.
@item 1
@tab No @tab The calling program will flush processed arguments from the argument stack.@tab The called program (subroutine) will flush processed arguments from the argument stack.
@item 2
@tab Yes @tab The
@registerrefalt{RETURN-CODE,Special Registers} will be updated in addition to any @code{RETURNING} or @code{GIVING} data item. @tab The
@registertext{RETURN-CODE} will not be updated (but any @code{RETURNING} or @code{GIVING} data item still will).
@item 3
@tab Yes @tab If @code{CALL @var{literal}} is used, the subroutine will be located and linked in with the calling program at compile time or may be dynamically located and loaded at execution time, depending on compiler switch settings and operating system capabilities.  @tab If @code{CALL @var{literal}} is used, the subroutine can only be located and linked with the calling program at compilation time.
@item 4
@tab No @tab OS/2 ``OPTLINK'' conventions will not be used to CALL the subprogram. @tab OS/2 ``OPTLINK'' conventions will be used to CALL the subprogram.
@item 5
@tab No @tab Windows 16-bit ``thunking'' will not be in effect. @tab Windows 16-bit ``thunking'' will be used to call the subroutine as a DLL.
@item 6
@tab Yes @tab The @code{STDCALL} convention will not be used. @tab The @code{STDCALL} convention, required to use the Microsoft Win32 API,  will be used.
@end multitable

Using the @code{STATIC} option on a @code{CALL} statement is equivalent to using @code{CALL-CONVENTION 8} (only bit 3 set).

Using the @code{STDCALL} option on a @code{CALL} statement is equivalent to using @code{CALL CONVENTION 64} (only bit 6 set).
@end table

@item
The value of @var{literal-1} or @var{identifier-1} is the entry-point of the subprogram you wish to call.

@item
When you call a subroutine using @var{identifier-1}, you are forcing the runtime system to call a dynamically-loadable subprogram.  The contents of @var{identifier-1} will be the entry-point name within that module.  If this is the @i{first} call to any entry-point within the module being made at run-time, the contents of @var{identifier-1} must be the primary entry-point name of the module (which must also match the filename, minus any OS-mandated extension) of the executable file comprising the module).

@item
You can force the GnuCOBOL runtime system to pre-load all dynamically-loaded modules that could ever be called by the program, at the time the program starts executing.  This is accomplished through the use of the
@envvarruntimeref{COB_PRE_LOAD}.  If used, this will only pre-load those modules invoked via @code{CALL @var{literal-1}}, as the runtime contents of @var{identifier-1} cannot be predicted.

@item
If the subprogram being called is a GnuCOBOL program, and if that program had the @syntaxrefalt{INITIAL,IDENTIFICATION DIVISION} attribute specified on its @code{PROGRAM-ID} clause, all of the subprogram's data division data will be restored to its initial state each time the subprogram is executed, regardless of which entry-point within the subprogram is being referenced.

This [re]-initialization behaviour will @i{always} apply to any subprogram's local-storage (if any), regardless of the use (or not) of @code{INITIAL}.

@item
The
@syntaxidx{USING} clause defines a list of arguments that may be passed from the calling program to the subprogram.  The manner in which any given argument is passed to the subroutine depends upon the @code{BY} clause (if any) coded (or implied) for that argument, as follows:
@table @code
@item @plainidx{BY REFERENCE}
passes the @i{address} of the argument to the subprogram.  If the subprogram changes the contents of that argument, the change will be ``visible'' to the calling program.

@item @plainidx{BY CONTENT}
passes the @i{address} of a @i{copy} of the argument to the subprogram.  If the subprogram changes the value of such an argument, the change only affects the copy back in the calling program, not the original version.

@item @plainidx{BY VALUE}
passes the @i{actual numeric value} of the literal or identifiers contents as the argument.  This feature exists to provide compatibility with C, C++ and other languages and would not normally be used when calling GnuCOBOL subprograms.  Only numeric literals or numeric data items should be passed in this manner.
@end table

If an argument lacks a @code{BY} clause, the most-recently encountered @code{BY} specification on that @code{CALL} statement will be assumed.  If the first argument specified on a @code{CALL} lacks a @code{BY} clause, @code{BY REFERENCE} will be assumed.

@item
No more than 251 arguments may be passed to a subroutine, unless the GnuCOBOL compiler was built with a specifically different argument limit specified for it.  If you have access to the GnuCOBOL source code, you may adjust this limit by changing the value of the @code{COB_MAX_FIELD_PARAMS} in the @file{call.c} file (found in the @file{libcob} folder) as well as the last shown @code{#if MAX_CALL_FIELD_PARAMS} statement before you run @command{make} to build the compiler and run-time library.

@item
The
@syntaxidx{RETURNING} clause allows you to specify a numeric data item into which the subroutine should return a numeric value.  If you use this clause on the @code{CALL}, the subroutine should include a @syntaxrefalt{RETURNING,PROCEDURE DIVISION RETURNING} clause on its procedure division header.  Of course, a subroutine may pass a value of any kind back in any argument passed @code{BY REFERENCE}.

@item
The optional @code{ON OVERFLOW} and @code{NOT ON OVERFLOW} clauses (or @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} --- they are interchangeable) may be used to detect and react to the failure or success, respectively, of an attempt to @code{CALL} the subroutine.  Failure, in this context, is defined as the inability to either locate or load the object code of the subroutine at execution time.  @xref{ON OVERFLOW + NOT ON OVERFLOW}, for additional information.

@item
Call also supports using an entry point stored in a @code{PROGRAM-POINTER}, avoiding the dynamic runtime lookup. GnuCOBOL keeps a cache of lookups during a program run. Repeated use of a named function does not suffer much penalty, but @code{PROGRAM-POINTER} will be just that little bit faster. To set a @code{PROGRAM-POINTER} use @code{SET @var{program-reference} TO ENTRY "@var{name}"} (or get the address from an API, and take part in callback programming).

@item
An extension of @code{CALL} allows a call to a @var{Program-Pointer-1} which is preset using @code{SET @var{program-pointer-1} TO ENTRY @var{x}}. Additional the @code{RETURNING} clause may return a data pointer or a @code{PROGRAM-POINTER}
@end enumerate
@comment *********************************************************************
@comment ** 7.8.6 CANCEL                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.6,CANCEL}
@diagram{CANCEL,PD-CANCEL,PD-CANCEL,None}
The @statement{CANCEL} unloads the dynamically-loadable subprogram module containing the entry-point specified as @var{literal-1} or @var{identifier-1} from memory.
@enumerate
@item
If a dynamically-loadable module unloaded by the @statement{CANCEL} is subsequently re-executed, all data division storage for that module will once again be in its initial state.

@item
Whether the
@statement{CANCEL} actually physically unloads a dynamically-loaded module or simply marks it as logically-unloaded depends on the use and value of the
@envvarruntimeref{COB_PHYSICAL_CANCEL}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.7 CLOSE                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.7,CLOSE}
@diagram{CLOSE,PD-CLOSE,PD-CLOSE,PD-CLOSE}
The @statement{CLOSE} terminates the program's access to the specified file(s).
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{FOR} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{REEL} and @code{UNIT} are interchangeable.
@comment Semantic Specifications:

@item
The @code{CLOSE} statement may only be executed against files that have been successfully opened.

@item
A successful @code{CLOSE} will write any remaining unwritten record buffers to the file (similar to an @statementref{UNLOCK}) and release any file locks for the file, regardless of open mode.  A closed file will then be no longer available for subsequent I/O statements until it is once again OPENED.

@item
When a @syntaxref{ORGANIZATION LINE SEQUENTIAL} or @syntaxref{LINE ADVANCING} file is closed, a final delimiter sequence will be written to the file to signal the termination point of the final data record in the file.  This will only be necessary if the final record written to the file was written with the @syntaxrefalt{AFTER ADVANCING,WRITE} option.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.8 COMMIT                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.8,COMMIT}
@diagram{COMMIT,PD-COMMIT,PD-COMMIT,None}
The @statement{COMMIT} performs an @code{UNLOCK} against every currently-open file, but does not close any of the files.
See the @statementref{UNLOCK} for additional details.
@comment *********************************************************************
@comment ** 7.8.9 COMPUTE                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.9,COMPUTE}
@diagram{COMPUTE,PD-COMPUTE,PD-COMPUTE,None}
The @statement{COMPUTE} provides a means of easily performing complex arithmetic operations with a single statement, instead of using cumbersome and possibly confusing sequences of @code{ADD}, @code{SUBTRACT}, @code{MULTIPLY} and @code{DIVIDE} statements.  @code{COMPUTE} also allows the use of exponentiation --- an arithmetic operation for which no other statement exists in COBOL.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@item
The reserved word @code{EQUAL} is interchangeable with the use of @samp{=}.
@comment Semantic Specifications:

@item
Each @var{identifier-1} must be a numeric or numeric-edited data item.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-1} will control how non-integer results will be saved.

@item
@xref{Arithmetic Expressions}, for more information on arithmetic expressions.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined either as having an @var{identifier-3} with an insufficient number of digit positions available to the left of any implied decimal point or attempting to divide by zero.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.10 CONTINUE                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.10,CONTINUE}
@diagram{CONTINUE,PD-CONTINUE,PD-CONTINUE,None}
The @statement{CONTINUE} is a no-operation statement that may be coded anywhere an imperative statement (@pxref{Imperative Statement}) may be coded.
@enumerate
@item
The @code{CONTINUE} statement has no effect on the execution of the program.

@item
This statement (perhaps in combination with an appropriate comment or two) makes a convenient ``place holder'' --- particularly in @syntaxrefalt{ELSE,IF} or @syntaxrefalt{WHEN,EVALUATE} clauses where no code is currently expected to be needed, but a place for code to handle the conditions in question is to be reserved in case it's ever needed.

@item
The optional extension of (AFTER) when used with the @code{CONTINUE} statement pauses execution for a specified length of time.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.11 DELETE                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.11,DELETE}
@diagram{DELETE,PD-DELETE,PD-DELETE,None}
The @statement{DELETE} logically deletes a record from a COBOL file.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{KEY} and @code{RECORD} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
The @code{ORGANIZATION} of @var{file-name-1} cannot be @syntaxref{ORGANIZATION LINE SEQUENTIAL}.

@item
The @var{file-name-1} file cannot be a sort/merge work file (a file described using a @syntaxrefalt{SD,File/Sort-Description}).

@item
For files in the @code{SEQUENTIAL} access mode, the last input-output statement executed against @var{file-name-1} prior to the execution of the @code{DELETE} statement must have been a successfully executed sequential-format @statementrefalt{READ,Sequential READ}.  That @code{READ} will therefore identify the record to be deleted.

@item
If @var{file-name-1} is a @code{RELATIVE} file whose @syntaxrefalt{ACCESS MODE,ORGANIZATION RELATIVE} is either @code{RANDOM} or @code{DYNAMIC}, the record to be deleted is the one whose relative record number is currently the value of the field specified as the files
@syntaxidx{RELATIVE KEY} in its
@statement{SELECT}.

@item
If @var{file-name-1} is an @code{INDEXED} file whose @syntaxrefalt{ACCESS MODE,ORGANIZATION INDEXED} is @code{RANDOM} or @code{DYNAMIC}, the record to be deleted is the one whose primary key is currently the value of the field specified as the
@syntaxidx{RECORD KEY} in the file's @code{SELECT} statement.

@item
The optional @code{INVALID KEY} and @code{NOT INVALID KEY} clauses may be used to detect and react to the failure or success, respectively, of an attempt to delete a record.  @xref{INVALID KEY + NOT INVALID KEY}, for additional information.

@item
No @code{INVALID KEY} or @code{NOT INVALID KEY} clause may be specified for a file who's @code{ACCESS MODE IS SEQUENTIAL}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.12 DISPLAY                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.12,DISPLAY}
@menu
* 7.8.12.1: DISPLAY UPON device
* 7.8.12.2: DISPLAY UPON COMMAND-LINE
* 7.8.12.3: DISPLAY UPON ENVIRONMENT-NAME
* 7.8.12.4: DISPLAY data-item
* 7.8.12.5: DISPLAY data-item (Microsoft)
@end menu
@comment *********************************************************************
@comment ** 7.8.12.1 DISPLAY UPON device                                   **
@comment *********************************************************************
@newunit{7.8.12.1,DISPLAY UPON device}
@diagram{DISPLAY UPON device,PD-DISPLAY-1,PD-DISPLAY-1,None}
This format of the @statement{DISPLAY} displays the specified identifier contents and/or literal values on the system output device specified via the @code{UPON} clause.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{ON} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
If no
@syntaxidx{UPON} clause is specified, @code{UPON CONSOLE} will be assumed.  If the @code{UPON} clause @i{is} specified, @var{mnemonic-name-1} must be one of the built-in output device names @code{CONSOLE}, @code{PRINTER}, @code{STDERR}, @code{STDOUT}, @code{SYSERR}, @code{SYSLIST}, @code{SYSLST} or @code{SYSOUT} or a mnemonic name assigned to one of those devices via the @syntaxref{SPECIAL-NAMES} paragraph.

When displaying upon the @code{STDERR} or @code{SYSERR} devices or to a @var{mnemonic-name-1} attached to one of those two devices, the output will be written to output pipe #2, which will normally cause the output to appear in the console output window.  You may, if desired, redirect that output to a file by appending @kbd{2> filename} to the end of the command that executes the program.  This applies to both Windows (any type) or Unix versions of GnuCOBOL.

When displaying upon the @code{CONSOLE}, @code{PRINTER}, @code{STDOUT}, @code{SYSLIST}, @code{SYSLST} or @code{SYSOUT} devices or to a @var{mnemonic-name-1} attached to one of them, the output will be written to output pipe #1, which will normally cause the output to appear in the console output window.  You may, if desired, redirect that output to a file by appending @kbd{1> filename} or simply @kbd{> filename} to the end of the command that executes the program.  This applies to both Windows (any type) or Unix versions of GnuCOBOL.

@item
The
@syntaxidx{NO ADVANCING} clause, if used, will suppress the carriage-return / line-feed sequence that is normally added to the end of any console display.

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified device.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.12.2 DISPLAY UPON COMMAND-LINE                             **
@comment *********************************************************************
@page
@newunit{7.8.12.2,DISPLAY UPON COMMAND-LINE}
@diagram{DISPLAY UPON COMMAND-LINE,PD-DISPLAY-2,PD-DISPLAY-2,None}
This form of the @statement{DISPLAY} may be used to specify the command-line argument number to be retrieved by a subsequent @statementrefalt{ACCEPT FROM ARGUMENT-VALUE,ACCEPT FROM COMMAND-LINE} or to specify a new value for the command-line arguments themselves.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{ON} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
By displaying a numeric integer value @code{UPON}
@syntaxidx{ARGUMENT-NUMBER}, you will specify which argument (by its relative number) will be retrieved by a subsequent @statement{ACCEPT FROM ARGUMENT-VALUE}.

@item
Executing a @code{DISPLAY UPON COMMAND-LINE} will influence subsequent @code{ACCEPT FROM COMMAND-LINE} statements (which will then return the  value you displayed), but will not influence subsequent @code{ACCEPT FROM ARGUMENT-VALUE} statements --- these will continue to return the original program execution parameters.

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified item.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.12.3 DISPLAY UPON ENVIRONMENT-NAME                         **
@comment *********************************************************************
@page
@newunit{7.8.12.3,DISPLAY UPON ENVIRONMENT-NAME}
@diagram{DISPLAY UPON ENVIRONMENT-NAME,PD-DISPLAY-3-Info,PD-DISPLAY-3-TeX,None}
This form of the @statement{DISPLAY} can be used to create or modify environment variables.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{ON} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
To create or change an environment variable will require two @code{DISPLAY} statements.  The following example sets the environment variable @env{MY_ENV_VAR} to a value of @samp{Demonstration Value}:

@example
DISPLAY "MY_ENV_VAR" UPON ENVIRONMENT-NAME
DISPLAY "Demonstration Value" UPON ENVIRONMENT-VALUE
@end example

@item
Environment variables created or changed from within GnuCOBOL programs will be available to any sub-shell processes spawned by that program (i.e. @syntaxrefalt{CALL 'SYSTEM',SYSTEM}) but will not be known to the shell or console window that started the GnuCOBOL program.

@item
Consider using @syntaxref{SET ENVIRONMENT} in lieu of @code{DISPLAY} to set environment variables as it is much simpler.

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of an attempt to display output to the specified item.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment *************************************************************
@comment ** 7.8.12.4 DISPLAY data-item                              **
@comment *************************************************************
@page
@newunit{7.8.12.4,DISPLAY data-item}
@diagram{DISPLAY data-item,PD-DISPLAY-4,PD-DISPLAY-4,PD-DISPLAY-4}
This format of the @statement{DISPLAY} presents data onto a formatted screen.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{AFTER}, @code{LINE}, @code{LINES}, @code{NUMBER} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{COLUMN} and @code{POSITION} are interchangeable.

@item
The reserved words @code{LINE} and @code{LINES} are interchangeable.
@comment Semantic Specifications:

@item
If @var{identifier-1} is defined in the @syntaxref{SCREEN SECTION}, any @code{AT}, @var{Attribute-Specification} and @code{WITH} clauses will be ignored.  All field definition, cursor positioning and screen control will occur as a result of the screen section definition of @var{identifier-1}.

@item
The reserved word @code{OMITTED} when used, will act to position the cursor or any screen clearance without changing any content of the screen.

@item
The following points apply if @var{identifier-1} is not defined in the screen section:
@enumerate A
@item
The purpose of the @code{AT} clause is to define where on the screen @var{identifier-1} should be displayed.  @xref{ACCEPT data-item}, for additional information.

@item
The purpose of the @code{WITH} clause is to define the visual attributes that should be applied to @var{identifier-1} when it is displayed on the screen as well as other presentation-control characteristics.

@item
The following @var{Attribute-Specification} clauses are allowed on the @code{DISPLAY} statement --- these are the same as those allowed for @code{SCREEN SECTION} data items.  A particular @var{Attribute-Specification} may be used only once in any @code{DISPLAY}:
@itemize @bullet
@item
@syntaxref{BACKGROUND-COLOR}

@item
@syntaxref{BEEP}, @syntaxref{BELL}

@item
@syntaxref{BLANK}

@item
@syntaxref{BLINK}

@item
@syntaxref{ERASE}

@item
@syntaxref{FOREGROUND-COLOR}

@item
@syntaxref{HIGHLIGHT}

@item
@syntaxref{LOWLIGHT}

@item
@syntaxref{OVERLINE}

@item
@syntaxref{REVERSE-VIDEO}

@item
@syntaxref{UNDERLINE}
@end itemize

@item
@xref{ACCEPT data-item}, for additional information on the other @code{WITH} clause options.
@end enumerate

@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of the screen I/O attempt.  @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate

When @code{DISPLAY} is used with Line and column where multiple variables or literals are used before @code{LINE} only the first will be displayed.

If this is needed then the use of @code{CONCATENATE} to built more than one element together prior to the display, @i{e.g.}, @code{DISPLAY FUNCTION CONCATENATE (VARS-1 VARS-2) AT 0201}.

When @code{DISPLAY} is used without line or column controls only one variable or literal may will appear on a line, so the use of the above example should also be employed.

@comment *************************************************************
@comment ** 7.8.12.5 DISPLAY data-item (Microsoft)            **
@comment *************************************************************
@page
@newunit{7.8.12.5,DISPLAY data-item (Microsoft)}
@diagram{DISPLAY data-item,PD-DISPLAY-5,PD-DISPLAY-5,None}
This format of the @statement{DISPLAY} presents data onto a formatted screen using the Microsoft format from v1 and v2 compilers (MsDos).

@comment *********************************************************************
@comment ** 7.8.13 DIVIDE                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.13,DIVIDE}
@menu
* 7.8.13.1: DIVIDE INTO
* 7.8.13.2: DIVIDE INTO GIVING
* 7.8.13.3: DIVIDE BY GIVING
@end menu
@comment *********************************************************************
@comment ** 7.8.13.1 DIVIDE INTO                                            **
@comment *********************************************************************
@newunit{7.8.13.1,DIVIDE INTO}
@diagram{DIVIDE INTO,PD-DIVIDE-1,PD-DIVIDE-1,PD-DIVIDE-MAP}
This format of the @statement{DIVIDE} will divide a numeric value (specified as a literal or numeric data item) into another numeric value (also specified as a literal or numeric data item) and will then replace the contents of one or more receiving data items with the results of that
division.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items and @var{literal-1} must be a numeric literal.

@item
A division operation will be performed for each @var{identifier-2}, in turn.  Each of the results of those divisions will be saved to the corresponding @var{identifier-2} data item(s).

@item
Should any @var{identifier-2} be an integer numeric data item, the result computed when that @var{identifier-2} is divided by @var{literal-1} or @var{identifier-1} will also be an integer --- any remainder from that division will be discarded.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being numeric truncation caused by an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.13.2 DIVIDE INTO GIVING                                    **
@comment *********************************************************************
@page
@newunit{7.8.13.2,DIVIDE INTO GIVING}
@diagram{DIVIDE INTO GIVING,PD-DIVIDE-2,PD-DIVIDE-2,None}
This format of the @statement{DIVIDE} will divide one numeric value (specified as a literal or numeric data item) into another numeric value (also specified as a literal or numeric data item) and will then replace the contents of one or more receiving data items with the results of that division.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items while both @var{identifier-3} and @var{identifier-4} must be numeric (edited or unedited) data items.

@item
Both @var{literal-1} and @var{literal-2} must be numeric literals.

@item
If the
@syntaxidx{REMAINDER} clause is coded, there may be only one @var{identifier-3} specified.

@item
The result obtained when the value of @var{literal-2} or @var{identifier-2} is divided by the value of @var{literal-1} or @var{identifier-1} is computed; this result is then moved into each @var{identifier-3}, in turn, applying the rules defined by the @syntaxref{ROUNDED} clause (if any) for that @var{identifier-3} to the move.

@item
If a @code{REMAINDER} clause is specified, the value of the one and only @var{identifier-3} (as stated earlier, if @code{REMAINDER} is specified there may only be a single @var{identifier-3} coded on the statement) after it was assigned a value according to the previous rule will be multiplied by the value of @var{literal-1} or @var{identifier-1}; that result is then subtracted from the value of @var{literal-2} or @var{identifier-2} and @i{that} result is the value which is moved to @var{identifier-4}.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.13.3 DIVIDE BY GIVING                                      **
@comment *********************************************************************
@page
@newunit{7.8.13.3,DIVIDE BY GIVING}
@diagram{DIVIDE BY GIVING,PD-DIVIDE-3,PD-DIVIDE-3,None}
This format of the @statement{DIVIDE} will divide one numeric value (specified as a literal or numeric data item) by another numeric value (also specified as a literal or numeric data item) and will then replace the contents of one or more receiving data items with the results of that division.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items while both @var{identifier-3} and @var{identifier-4} must be numeric (edited or unedited) data items.

@item
Both @var{literal-1} and @var{literal-2} must be numeric literals.

@item
If the
@syntaxidx{REMAINDER} clause is coded, there may be only one @var{identifier-3} specified.

@item
The result obtained when the value of @var{literal-1} or @var{identifier-1} is divided by the value of @var{literal-2} or @var{identifier-2} is computed; this result is then moved into each @var{identifier-3}, in turn, applying the rules defined by the @syntaxref{ROUNDED} clause (if any) for that @var{identifier-3} to the move.

@item
If a @code{REMAINDER} clause is specified, the value of the one and only @var{identifier-3} (as stated earlier, if @code{REMAINDER} is specified there may only be a single @var{identifier-3} coded on the statement) after it was assigned a value according to the previous rule will be multiplied by the value of @var{literal-2} or @var{identifier-2}; that result is then subtracted from the value of @var{literal-1} or @var{identifier-1} and @i{that} result is the value which is moved to @var{identifier-4}.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point, or an attempt to divide by zero.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.14 ENTRY                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.14,ENTRY}
@diagram{ENTRY,PD-ENTRY,PD-ENTRY,None}
@diagram{ENTRY-Argument,PD-ENTRY-Arg,PD-ENTRY-Arg,None}
The @statement{ENTRY} is used to define an alternate entry-point into a subroutine, along with the arguments that subroutine will be expecting.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{BY} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
You may not use an @statement{ENTRY} in a nested subprogram, nor may you use it in any form of user-defined function.

@item
The
@syntaxidx{USING} clause defines the arguments the subroutine entry-point supports.  This list of arguments must match up against the @code{USING} clause of any @statement{CALL} that will be invoking the subroutine using this entry-point.

@item
Each @var{ENTRY-Argument} specified on the @statement{ENTRY} must be defined in the linkage section of the subroutine in which the @statement{ENTRY} exists.

@item
The @var{literal-1} value will specify the entry-point name of the subroutine.  It must be specified exactly on @code{CALL} statements (with regard to the use of upper- and lower-case letters) as it is specified on the @statement{ENTRY}.

@item
The meaning of
@syntaxidx{REFERENCE},
@syntaxidx{CONTENT} and
@syntaxidx{VALUE} are the same as the equivalent specifications on the @statementref{CALL}.  Whatever specification will be used for an argument on the @code{CALL} to this entry-point should match the specification used in the corresponding @var{ENTRY-Argument}.  The same rules regarding the presence or absence of a @code{BY} clause on a @statement{CALL} apply to the presence or absence of a @code{BY} clause on the corresponding argument of the @statement{ENTRY}.

@item
The @var{GO TO} with the ENTRY FOR is an GnuCOBOL special purpose extension for use with various GnuCobol tools.

@end enumerate
@comment *********************************************************************
@comment ** 7.8.15 EVALUATE                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.15,EVALUATE}
@diagram{EVALUATE,PD-EVALUATE,PD-EVALUATE,None}
@diagram{EVALUATE Selection Subject,PD-EVALUATE-SS,PD-EVALUATE-SS,None}
@diagram{EVALUATE Selection Object,PD-EVALUATE-SO,PD-EVALUATE-SO,None}
The @statement{EVALUATE} provides a means of defining processing that should take place under any number of mutually-exclusive conditions.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
There must be at least one
@syntaxidx{WHEN} clause (in addition to any
@syntaxidx{WHEN OTHER} clause) specified on any @statement{EVALUATE}.

@item
There must be at least one @var{Selection-Subject} specified on the @statement{EVALUATE}.  Any number of additional @var{Selection-Subject} clauses may be specified, using the
@syntaxidx{ALSO} reserved word to separate each from the prior.

@item
Each @code{WHEN} clause (other than the
@syntaxidx{WHEN OTHER} clause, if any) must have the same number of @var{Selection-Object} clauses as there are @var{Selection-Subject} clauses.

@item
When using
@syntaxidx{THRU}, the values on both sides of the @code{THRU} must be the same class (both numeric, both alphanumeric, etc.).

@item
A @var{partial-expression} is one of the following:
@enumerate A
@item
A Class Condition without a leading @var{identifier-1} (@pxref{Class Conditions}).

@item
A Sign Condition without a leading @var{identifier-1} (@pxref{Sign Conditions}).

@item
A Relation Condition with nothing to the left of the relational operator (@pxref{Relation Conditions}).
@end enumerate
@comment Semantic Specifications:

@item
At execution time, each @var{Selection-Subject} on the @statement{EVALUATE} will have its value matched against that of the corresponding @var{Selection-Object} on a @code{WHEN} clause, in turn, until:
@enumerate A
@item
A @code{WHEN} clause has @i{each} of its @var{Selection-Object}(s) successfully matched by the corresponding @var{Selection-Subject}; this will be referred to as the '@i{Selected WHEN clause}'.

@item
The complete list of @code{WHEN} clauses (except for the @code{WHEN OTHER} clause, if any) has been exhausted.  In this case, there is no '@i{Selected WHEN Clause}'.
@end enumerate

@item
If a '@i{Selected WHEN Clause}' was identified:
@enumerate A
@item
The @var{imperative-statement-1} (@pxref{Imperative Statement}) immediately following the '@i{Selected WHEN Clause}' will be executed.  If the '@i{Selected WHEN Clause}' is lacking an @var{imperative-statement-1}, the first @var{imperative-statement-1} found after any following @code{WHEN} clause will be executed.

@item
Once the @var{imperative-statement-1} has been executed, or no @var{imperative-statement-1} was found anywhere after the '@i{Selected WHEN Clause}', control will proceed to the statement following the @code{END-EVALUATE} or, if there is no @code{END-EVALUATE}, the first statement that follows the next period.  If, however, the @var{imperative-statement-1} included a @statement{GO TO}, and that @code{GO TO} was executed, then control will transfer to the procedure named on the @code{GO TO} instead.
@end enumerate

@item
If no '@i{Selected WHEN Clause}' was identified:
@enumerate A
@item
The @code{WHEN OTHER} clause's @var{imperative-statement-other} will be executed, if such a clause was coded.

@item
Control will then proceed to the statement following the @code{END-EVALUATE} or the first statement that follows the next period if there is no @code{END-EVALUATE}.  If,however, the @var{imperative-statement-other} included a @statement{GO TO}, and that @code{GO TO} was executed, then control will transfer to the procedure named on the @code{GO TO} instead.
@end enumerate

@item
In order for a @var{Selection-Subject} to match the corresponding @var{Selection-Object} on a @code{WHEN} clause, at least one of the following must be true:
@enumerate A
@item
The @var{Selection-Object} is
@syntaxidx{ANY}

@item
The implied Relation Condition @code{@var{Selection-Subject} = @var{Selection Object}} is @code{TRUE} --- @xref{Relation Conditions}, for the rules on how the comparison will be made.

@item
The value of the @var{Selection-Subject} falls within the range of values specified by the @code{THRU} clause of the @var{Selection-Object}

@item
If the @var{Selection-Object} is a @var{partial-expression}, then the conditional expression that would be represented by coding @code{@var{Selection-Subject} @var{Selection-Object}} evaluates to @code{TRUE}
@end enumerate

@item
Here is a sample program that illustrates the EVALUATE statement.

@example
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOEVALUATE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Test-Digit                  PIC 9(1).
    88 Digit-Is-Odd VALUE 1, 3, 5, 7, 9.
    88 Digit-Is-Prime VALUE 1, 3, 5, 7.
PROCEDURE DIVISION.
P1. PERFORM UNTIL EXIT
    DISPLAY "Enter a digit (0 Quits): "
        WITH NO ADVANCING
    ACCEPT Test-Digit
    IF Test-Digit = 0
        EXIT PERFORM
    END-IF
    EVALUATE Digit-Is-Odd ALSO Digit-Is-Prime
    WHEN TRUE ALSO FALSE
        DISPLAY Test-Digit " is ODD"
            WITH NO ADVANCING
    WHEN TRUE ALSO TRUE
        DISPLAY Test-Digit " is PRIME"
            WITH NO ADVANCING
    WHEN FALSE ALSO ANY
        DISPLAY Test-Digit " is EVEN"
            WITH NO ADVANCING
    END-EVALUATE
    EVALUATE Test-Digit
    WHEN < 5
        DISPLAY " and it's small too"
    WHEN < 8
        DISPLAY " and it's medium too"
    WHEN OTHER
        DISPLAY " and it's large too"
    END-EVALUATE
END-PERFORM
DISPLAY "Bye!"
STOP RUN
.
@end example

Console output when run (user input follows the colons on the prompts for input):

@example
Enter a digit (0 Quits): 1
1 is PRIME and it's small too
Enter a digit (0 Quits): 2
2 is EVEN and it's small too
Enter a digit (0 Quits): 3
3 is PRIME and it's small too
Enter a digit (0 Quits): 4
4 is EVEN and it's small too
Enter a digit (0 Quits): 5
5 is PRIME and it's medium too
Enter a digit (0 Quits): 6
6 is EVEN and it's medium too
Enter a digit (0 Quits): 7
7 is PRIME and it's medium too
Enter a digit (0 Quits): 8
8 is EVEN and it's large too
Enter a digit (0 Quits): 9
9 is ODD and it's large too
Enter a digit (0 Quits): 0
Bye!
@end example
@end enumerate

@comment *********************************************************************
@comment ** 7.8.15B EXAMINE                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.15B,EXAMINE}
@diagram{EXAMINE,PD-EXAMINE,PD-EXAMINE,None}
The @statement{EXAMINE} is the pre runner for INSPECT which should be used over the pre 1970 Cobol standard EXAMINE, and it is used to count the number of times a specified character appears in a data item and/or to replace a character with another character.
@enumerate

@item
This statement is only available subject to specific dialects being set when running the GnuCOBOL compiler.

@item
In all cases, the description of identifier must be such that its usage is display (explicitly or implicitly).

@item
When identifier represents a non numeric data item, examination starts at the leftmost character and proceeds to the right. Each character in the data item is examined in turn. For purposes of the EXAMINE statement, external floating point items are treated as non numeric data items.

@item
When identifier represents a numeric data item, this data item must consist of numeric characters, and may possess an operational sign. Examination starts at the leftmost character and proceeds to the right. Each character is examined in turn.

@item
If the letter 'S' is used in the PICTURE of the data item description to indicate the presence of an operational sign, the sign is ignored by the EXAMINE statement.

@item
Each literal must consist of a single character belonging to a class consistent with that of the identifier; in addition, each literal may be any figurative constant except ALL. If identifier is numeric, each literal must be an unsigned integer or the figurative constant ZERO (ZEROES, ZEROS).

@item
When Format 1 is used, an integral count is created which replaces the value of a special register called TALLY, whose implicit description is that of an unsigned integer of five digits.

@item
When the ALL option is used, this count represents the number of occurrences of literal-1.

@item
When the LEADING option is used, this count represents the number of occurrences of literal-1 prior to encountering a character other than literal-1.

@item
When the UNTIL FIRST option is used, this count represents all characters encountered before the first occurrence of literal-1.

@item
Whether Format 2 is used, or the REPLACING option of Format 1, the replacement rules are the same. They are as follows:

@item
When the ALL option is used, literal-2 is substituted for each occurrence of literal-1.

@item
When the LEADING option is used, the substitution of literal-2 for each occurrence of literal-1 terminates as soon as a character other than literal-1 or the right hand boundary of the data item is encountered.

@item
When the UNTIL FIRST option is used, the substitution of literal-2 terminates as soon as literal-1 or the right hand boundary of the data item is encountered.
@end enumerate

@comment *********************************************************************
@comment ** 7.8.16 EXHIBIT                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.16,EXHIBIT}
@diagram{EXHIBIT,PD-EXHIBIT,PD-EXHIBIT,None}
The @statement{EXHIBIT} causes an (optionally conditional) display of the literals, and/or identifiers (optionally preceded by the identifier name) specified in the statement for the purposes of debugging.
@enumerate

@item
EXHIBIT is only present to ease migrations, this is an archaic language element in GnuCOBOL (but without the archaic message warning because there is no explicit dialect configuration for that other than the reserved word). Depending on the -std used it will either compile or not. As the standard says about archaic language elements:

    it should not be used in new compilation groups because better programming practices exist

The use of DISPLAY is more portable and allows for the same feature-set (with the exception of CHANGED which GnuCOBOL may not support for a long time and with the need of a literal for NAMED).
This statement can be removed from any later version.

@item
The reserved words @code{NAMED}, @code{CHANGED} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
Each identifier specified in the EXHIBIT statement can be any class of data. TALLY and RETURN-CODE are the only special registers that can be used as identifiers.

@item
Literals and identifiers displayed by the EXHIBIT statement are separated by a space on the displayed line.

@item
Each literal can be any figurative constant other than ALL.

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

@item
Each execution of an EXHIBIT NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by a "=" (equal sign) and its current value. They all appear on a single line on the order in which they appear in the statement.

@item
Each execution of an EXHIBIT CHANGED NAMED statement displays each identifier or literal specified, with each identifier (including any qualifiers and subscripts) followed by a "=" (equal sign) and its current value. They all appear on a single line on the order in which they appear in the statement. However, the display for each identifier (name and value) is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, neither the name nor the value is printed for those identifiers. If none of the identifier values has changed, and no literals are specified, no display takes place (display of a blank line is suppressed).

@item
Each execution of an EXHIBIT CHANGED statement displays the current value of each identifier or literal specified. They all appear on a single line on the order in which they appear in the statement. However, the value display for each identifier is conditional on the value of that identifier having changed since the last execution of the current EXHIBIT statement. If one or more of the identifier values have not changed, the value for those identifiers are not printed and spaces are inserted instead. If none of the identifier values has changed, and no literals are specified, a blank line is displayed  (display of a blank line is not suppressed).

@item
Each execution of an EXHIBIT statement with neither the CHANGED nor the NAMED option displays each identifier or literal specified. They all appear on a single line in the order in which they appear in the statement.

@item
An EXHIBIT statement is the same as an EXHIBIT NAMED statement.

@item
ERASE is a display attribute which got into GnuCOBOL when MS-COBOL support was increased, it is not yet implemented.

@item
The  CHANGED  clause is not yet implemented but recognised by GnuCOBOL.

@item
The  UPON mnemonic-name-1  clause is not yet implemented but recognised by GnuCOBOL.
@end enumerate


@comment *********************************************************************
@comment ** 7.8.17 EXIT                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.17,EXIT}
@diagram{EXIT,PD-EXIT,PD-EXIT,None}
The @statement{EXIT} is a multi-purpose statement; it may provide a common end point for a series of procedures, exit an in-line @code{PERFORM}, paragraph or section or it may mark the logical end of a subprogram, returning control back to the calling program.
@enumerate
@comment Syntactical Specifications:

@item
The @statement{EXIT PROGRAM} is not legal anywhere within a user-defined function.

@item
The @statement{EXIT FUNCTION} cannot be used anywhere within a subroutine.

@item
Neither @code{EXIT PROGRAM} nor @code{EXIT FUNCTION} may be used within a @code{USE GLOBAL} routine in @syntaxref{DECLARATIVES}.
@comment Semantic Specifications:

@item
The following points describe the @statement{EXIT} with none of the optional clauses:
@enumerate A
@item
When this form of an @statement{EXIT} is used, it must be the only statement in the procedure (paragraph or section) in which it occurs.  This is @i{not} enforced in GnuCOBOL.

@item
This usage of the @statement{EXIT} simply provides a common ``GO TO'' end point for a series of procedures, as may be seen in the following example:

@example
01  Switches.
    05 Input-File-Switch PIC X(1).
       88 EOF-On-Input-File VALUE ``Y'' FALSE ``N''.
@dots{}
    SET EOF-On-Input-File TO FALSE.
    PERFORM 100-Process-A-Transaction THRU 199-Exit
        UNTIL EOF-On-Input-File.
@dots{}
100-Process-A-Transaction.
    READ Input-File AT END
        SET EOF-On-Input-File TO TRUE
        GO TO 199-Exit
    END-READ.
    IF Input-Rec of Input-File = SPACES
        GO TO 199-Exit  *> IGNORE BLANK RECORDS!
    END-IF.
    <<@var{process the record just read}>>
199-Exit.
    EXIT.
@end example

@item
In this case, the @statement{EXIT} takes no other run-time action.
@end enumerate

@item
The following points apply to the @code{EXIT PARAGRAPH} and @code{EXIT SECTION} statements:
@enumerate A
@item
If an @statement{EXIT PARAGRAPH} or @statement{EXIT SECTION} resides in a paragraph @i{within} the scope of a procedural @syntaxrefalt{PERFORM,Procedural PERFORM}, control will be returned back to the @code{PERFORM} for evaluation of any @code{TIMES}, @code{VARYING} and/or @code{UNTIL} clauses.

@item
If an @statement{EXIT PARAGRAPH} or @statement{EXIT SECTION} resides @i{outside} the scope of a procedural @code{PERFORM}, control simply transfers to the first executable statement in the next paragraph (@code{EXIT PARAGRAPH}) or section (@code{EXIT SECTION}).

@item
The following shows how the previous example could have been coded without a @code{GO TO} by utilizing an @statement{EXIT PARAGRAPH}.
@example
01  Switches.
    05 Input-File-Switch PIC X(1).
       88 EOF-On-Input-File VALUE ``Y'' FALSE ``N''.
@dots{}
    SET EOF-On-Input-File TO FALSE.
    PERFORM 100-Process-A-Transaction
        UNTIL EOF-On-Input-File.
@dots{}
100-Process-A-Transaction.
    READ Input-File AT END
        SET EOF-On-Input-File TO TRUE
        EXIT PARAGRAPH
    END-READ.
    IF Input-Rec of Input-File = SPACES
        EXIT PARAGRAPH *> IGNORE BLANK RECORDS!
    END-IF.
    <<@var{process the record just read}>>
@end example
@end enumerate

@item
The following points apply to the @code{EXIT PERFORM} and @code{EXIT PERFORM CYCLE} statements:
@enumerate A
@item
The @code{EXIT PERFORM} and @code{EXIT PERFORM CYCLE} statements are intended to be used in conjunction with an in-line @statementrefalt{PERFORM,Inline PERFORM}.

@item
An @statement{EXIT PERFORM CYCLE} will terminate the current iteration of the in-line @code{PERFORM}, giving control to any @code{TIMES}, @code{VARYING} and/or @code{UNTIL} clauses for them to determine if another cycle needs to be performed.

@item
An @statement{EXIT PERFORM} will terminate the in-line PERFORM outright, transferring control to the first statement following the @code{END-PERFORM} (if there is one) or to the next sentence following the @code{PERFORM} if there is no @code{END-PERFORM}.

@item
This last example shows the final modification to the previous examples by using an in-line @code{PERFORM} along with @code{EXIT PERFORM} and @code{EXIT PERFORM CYCLE} statements:

@example
PERFORM FOREVER
    READ Input-File AT END
        EXIT PERFORM
    END-READ
    IF Input-Rec of Input-File = SPACES
        EXIT PERFORM CYCLE *> IGNORE BLANK RECORDS!
    END-IF
    <<@var{process the record just read}>>
END PERFORM
@end example
@end enumerate

@item
The following points apply to the @code{EXIT PROGRAM} and @code{EXIT FUNCTION} statements:
@enumerate A
@item
The @code{EXIT PROGRAM} and @code{EXIT FUNCTION} statements terminate the execution of a subroutine (i.e.  a program that has been CALLed by another) or user-defined function, respectively, returning control back to the calling program.

@item
An @statement{EXIT PROGRAM} returns control back to the statement following the @syntaxref{CALL} of the subprogram.  An @statement{EXIT FUNCTION} returns control back to the processing of the statement in the calling program that invoked the user-defined function.

@item
For @statement{EXIT PROGRAM} usage of @statement{RETURNING} or @statement{GIVING} will provide value defined by indentifer-1 or literal-1 back to the calling routine.

@item
If executed by a main program, neither the @code{EXIT PROGRAM} nor @code{EXIT FUNCTION} statements will take any action.

@item
The COBOL2002 standard has made a common extension to the COBOL language --- the @statementref{GOBACK} --- a standard language element; the @code{GOBACK} statement should be strongly considered as the preferred alternative to both @code{EXIT PROGRAM} and @code{EXIT FUNCTION} for new subprograms.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.18 FREE                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.18,FREE}
@diagram{FREE,PD-FREE,PD-FREE,None}
The @statement{FREE} releases memory previously allocated to the program by the @statementref{ALLOCATE}.
@enumerate
@comment Syntactical Specifications:

@item
The @code{ADDRESS OF} clause is optional and may be omitted.  The presence or absence of this clause has no effect upon the program.
@comment Semantic Specifications:

@item
@var{identifier-1} must have a @syntaxref{USAGE} of @code{POINTER}, or it must be an 01-level data item with the @syntaxref{BASED} attribute.

@item
If @var{identifier-1} is a @code{USAGE POINTER} data item and it contains a valid address, the @statement{FREE} will release the memory block the pointer references.  In addition, any @code{BASED} data items that the pointer was used to provide an address for will become un-based and therefore unusable.  If @var{identifier-1} did not contain a valid address, no action will be taken.

@item
If @var{identifier-1} is a @code{BASED} data item and that data item is currently based (meaning it currently has memory allocated to it), its memory is released and @var{identifier-1} will become un-based and therefore unusable.  If @var{identifier-1} was not based, no action will be taken.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.19 GENERATE                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.19,GENERATE}
@diagram{GENERATE,PD-GENERATE,PD-GENERATE,None}
The @statement{GENERATE} presents data to a report.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The following points apply when @var{identifier-1} is specified:
@enumerate A
@item
@var{identifier-1} must be the name of a @syntaxrefalt{DETAIL,RWCS Lexicon} report group.

@item
If necessary, @var{identifier-1} may be qualified with a report name.

@item
The file in whose @code{FD} a @code{REPORT} clause exists for the report in which @var{identifier-1} is a detail group must be opened for @code{OUTPUT} or @code{EXTEND} at the time the @code{GENERATE} is executed.  @xref{OPEN}, for information on file open modes.

@item
The report in which @var{identifier-1} is a @code{DETAIL} group must have been successfully initiated via the @statementref{INITIATE} and not yet terminated via the @statementref{TERMINATE} at the time the @code{GENERATE} is executed.

@item
If at least one @code{GENERATE} statement of this form is executed against a report, the report is said to be a
@define{detail report}.  If no @code{GENERATE} statements of this form are executed against a report, the report is said to be a
@define{summary report}.
@end enumerate

@item
The following points apply when @var{report-name-1} is specified:
@enumerate A
@item
@var{report-name-1} must be the name of a report having an @code{RD} defined for it in the report section.

@item
There must be at least one @syntaxrefalt{CONTROL,RWCS Lexicon} group defined for @var{report-name-1}.

@item
There cannot be more than one @code{DETAIL} group defined for @var{report-name-1}.

@item
The file in whose @code{FD} a @code{REPORT @var{report-name-1}} clause exists must be open for  @code{OUTPUT} or @code{EXTEND} at the time the GENERATE is executed.

@item
@var{report-name-1} must have been successfully initiated (via @code{INITIATE @var{report-name-1}}) and not yet terminated (via TERMINATE) at the time the @code{GENERATE} is executed.  @xref{OPEN}, for information on file open modes.

@item
The @code{DETAIL} group which is defined for @var{report-name-1} @i{will} be processed but will not actually be presented to any report page.  This will allow summary processing to take place.  If all @code{GENERATE} statements are of this form, the report is said to be a
@define{summary report}.  If at least one @code{GENERATE @var{identifier-1}} is executed, the report is considered to be a
@define{detail report}.
@end enumerate

@item
When the first @code{GENERATE} statement for a report is executed, the contents of all control fields are saved so they may be referenced during the processing of subsequent @code{GENERATE} statements.

@item
When, during the processing of  a subsequent @code{GENERATE}, it is determined that a control field has changed value (ie. a control break has occurred), the appropriate control footing and control heading processing will take place and a snapshot of the current values of all control fields will again be saved.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.20 GOBACK                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.20,GOBACK}
@diagram{GOBACK,PD-GOBACK,PD-GOBACK,None}
The @statement{GOBACK} is used to logically terminate an executing program.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
If executed within a subprogram (i.e. a subroutine or user-defined function), @code{GOBACK} behaves like an @code{EXIT PROGRAM} or @statement{EXIT FUNCTION}, respectively.

@item
If executed within a main program, @code{GOBACK} will act as a @code{STOP RUN} statement.

@item
The optional @code{RETURNING} clause provides the opportunity to return a numeric value to the operating system (technically, an @i{exit status}  The manner in which the exit status value is interrogated by the operating system varies.  Windows can use @code{%ERRORLEVEL%} to query the exit status while Unix shells such as @command{sh}, @command{bash} and @command{ksh} can query the exit status as @code{$?}.  Other Unix shells may have different ways to access the exit status.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.21 GO TO                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.21,GO TO}
@menu
* 7.8.21.1: Simple GO TO
* 7.8.21.2: GO TO DEPENDING ON
@end menu
@comment *********************************************************************
@comment ** 7.8.21.1 Simple GO TO                                          **
@comment *********************************************************************
@newunit{7.8.21.1,Simple GO TO}
@diagram{Simple GO TO,PD-GO-TO-1,PD-GO-TO-1,None}
This form of the @statement{GO TO} unconditionally transfers control in a program to the first executable statement within the specified @var{procedure-name-1}.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{TO} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
If this format of the @statement{GO TO} appears in a consecutive sequence of imperative statements (@pxref{Imperative Statement}) within a sentence, it must be the @i{final} statement in the sentence.
@comment Semantic Specifications:

@item
If a @code{GO TO} is executed within the scope of@dots{}
@enumerate A
@item
...an in-line @syntaxref{PERFORM}, the @code{PERFORM} is terminated as control of execution transfers to @var{procedure-name-1}.

@item
...a procedural @syntaxref{PERFORM}, and @var{procedure-name-1} lies outside the scope of that @code{PERFORM}, the @code{PERFORM} is terminated as control of execution transfers to @var{procedure-name-1}.

@item
...a @statementref{MERGE} @code{OUTPUT PROCEDURE} or within the scope of either an @code{INPUT PROCEDURE} or @code{OUTPUT PROCEDURE} of a @statementrefalt{SORT,File-Based SORT}, and @var{procedure-name-1} lies outside the scope of that procedure, the @code{SORT} or @code{MERGE} operation is terminated as control of execution transfers to @var{procedure-name-1}.  Any sorted or merged data accumulated to that point is lost.
@end enumerate
@item
A @code{GO TO ENTRY} is an GnuCOBOL special purpose extension for use with various GnuCobol tools and is not part of any current ISO standard. See also @code{ENTRY}.
@item
The @code{GO TO ENTRY} format has to be used together with @code{ENTRY FOR GO TO}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.21.2 GO TO DEPENDING ON                                    **
@comment *********************************************************************
@page
@newunit{7.8.21.2,GO TO DEPENDING ON}
@diagram{GO TO DEPENDING ON,PD-GO-TO-2,PD-GO-TO-2,None}
This form of the @statement{GO TO} will transfer control to any one of a number of specified procedure names depending on the numeric value of the identifier specified on the statement.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{TO} is optional and may be omitted.  The presence or absence of this word has no effect upon the program but does help with read-ability.
@comment Semantic Specifications:

@item
The @syntaxref{PICTURE} and/or @syntaxref{USAGE} of the specified @var{identifier-1} must be such as to define it as a numeric, unedited, preferably unsigned integer data item.

@item
If the value of @var{identifier-1} has the value 1, control will be transferred to the 1@sup{st} specified procedure name.  If the value is 2, control will transfer to the 2nd procedure name, and so on.

@item
The @code{GO TO ENTRY ... DEPENDING ON} format has to be used together with @code{ENTRY FOR GO TO}.

If control of execution is transferred to a procedure named on the statement, and the @code{GO TO} is executed within the scope of@dots{}
@enumerate A
@item
...an in-line @syntaxref{PERFORM}, the @code{PERFORM} is terminated as control of execution transfers to the procedure named on the statement.

@item
...a procedural @syntaxref{PERFORM}, and @var{procedure-name-1} lies outside the scope of that @code{PERFORM}, the @code{PERFORM} is terminated as control of execution transfers to the procedure named on the statement.

@item
...a @statementref{MERGE} @code{OUTPUT PROCEDURE} or within the scope of either an @code{INPUT PROCEDURE} or @code{OUTPUT PROCEDURE} of a @statementrefalt{SORT,File-Based SORT}, and @var{procedure-name-1} lies outside the scope of that procedure, the @code{SORT} or @code{MERGE} operation is terminated as control of execution transfers to the procedure named on the statement.  Any sorted or merged data accumulated to that point is lost.
@end enumerate

@item
If the value of @var{identifier-1} is less than 1 or exceeds the total number of procedure names specified on the statement, control will simply fall through into the next statement following the @code{GO TO}.

@item
The following example shows how @code{GO TO ... DEPENDING ON} may be used in a real application situation, and compares it against an alternative --- @syntaxref{EVALUATE}.

@multitable @columnfractions 0.5 0.5
@headitem GO TO DEPENDING ON @tab EVALUATE
@item
@verbatim
    GO TO
      ACCT-TYPE-1
      ACCT-TYPE-2
      ACCT-TYPE-3
    DEPENDING ON Acct-Type.
    <<< Invalid Acct Type >>>
    GO TO All-Done.
Acct-Type-1.
    <<< Handle Acct Type 1 >>>
    GO TO All-Done.
Acct-Type-2.
    <<< Handle Acct Type 2 >>>
    GO TO All-Done.
Acct-Type-3.
    <<< Handle Acct Type 3 >>>
All-Done.
@end verbatim
@tab
@verbatim
EVALUATE Acct-Type
WHEN 1
    <<< Handle Acct Type 1 >>>
WHEN 2
    <<< Handle Acct Type 2 >>>
WHEN 3
    <<< Handle Acct Type 3 >>>
WHEN OTHER
    <<< Invalid Acct Type >>>
END-EVALUATE.
@end verbatim
@end multitable

@item
Current programming philosophy would prefer the use of the @statement{EVALUATE} to that of this form of the @statement{GO TO}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.22 IF                                                      **
@comment *********************************************************************
@page
@newsubsection{7.8.22,IF}
@diagram{IF,PD-IF,PD-IF,None}
The @statement{IF} is used to conditionally execute an imperative statement (@pxref{Imperative Statement}) or to select one of two different imperative statements to execute based upon the @code{TRUE}/@code{FALSE} value of a conditional expression.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{THEN} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
 You cannot use both @code{NEXT SENTENCE} and the @code{END-IF} scope terminator in the same @code{IF} statement.
@comment Semantic Specifications:

@item
If @var{conditional-expression} evaluates to @code{TRUE}, @var{imperative-statement-1} will be executed regardless of whether or not an
@syntaxidx{ELSE} clause is present.  Once @var{imperative-statement-1} has been executed, control falls into the first statement following the @code{END-IF} or to the first statement of the next sentence if there is no @code{END-IF} clause.

@item
If the optional @code{ELSE} clause is present and conditional-expression evaluates to false, then (and only then) @var{imperative-statement-2} will be executed. Once @var{imperative-statement-2} has been executed, control falls into the first statement following the @code{END-IF} or to the first statement of the next sentence if there is no @code{END-IF} clause.

@item
The clause
@syntaxidx{NEXT SENTENCE} may be substituted for either imperative-statement, but not both.  If control reaches a @code{NEXT SENTENCE} clause due to the truth or falsehood of @var{conditional-expression}, control will be transferred to the first statement of the next sentence found in the program (the first statement after the next period).

@code{NEXT SENTENCE} was needed for COBOL programs that were coded according to pre-1985 standards that wish to nest one @statement{IF} inside another.  @xref{Use of VERB/END-VERB Constructs}, for an explanation of why @code{NEXT SENTENCE} was necessary.

Programs coded for 1985 (and beyond) standards don't need it, instead using the explicit scope-terminator @code{END-IF} to inform the compiler where @var{imperative-statement-2} (or @var{imperative-statement-1} if there is no @code{ELSE} clause coded) ends.  New GnuCOBOL programs should be coded to use the @code{END-IF} scope terminator for @code{IF} statements.  @xref{Use of VERB/END-VERB Constructs}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.23 INITIALIZE                                              **
@comment *********************************************************************
@page
@newsubsection{7.8.23,INITIALIZE}
@diagram{INITIALIZE,PD-INITIALIZE,PD-INITIALIZE,None}
The @statement{INITIALIZE} initializes each @var{identifier-1} with certain specific values, depending upon the options specified.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{DATA}, @code{OF}, @code{THEN}, @code{TO} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{INITIALIZE} and @code{INITIALISE} are interchangeable.

@item
The @code{WITH FILLER}, @code{REPLACING} and @code{DEFAULT} clauses are meaningful only if @var{identifier-1} is a group item.  They are accepted if it's an elementary item, but will serve no purpose.  The @code{VALUE} clause is meaningful in both cases.

@item
A @var{category-name-1} and/or @var{category-name-2} may be any of the following:
@table @asis
@item @plainidx{ALPHABETIC}
The @syntaxref{PICTURE} of the data item only contains @code{A} symbols.

@item @plainidx{ALPHANUMERIC}
The @code{PICTURE} of the data item contains only @code{X} or a combination of @code{A} and @code{9} symbols.

@item @plainidx{ALPHANUMERIC-EDITED}
The @code{PICTURE}  of the data item contains only @code{X} or a combination of @code{A} and @code{9} symbols plus at least one @code{B}, @code{0} (zero) or @code{/} symbol.

@item @plainidx{NUMERIC}
The data item is one that is described with a picture less @syntaxref{USAGE} or has a @code{PICTURE} composed of nothing but @code{P}, @code{9}, @code{S} and @code{V} symbols.

@item @plainidx{NUMERIC-EDITED}
The @code{PICTURE} of the data item contains nothing but the symbol @code{9} and at least one of the editing symbols @code{$}, @code{+}, @code{-}, @code{CR}, @code{DB}, @code{.}, @code{,}, @code{*} or @code{Z}.

@item @plainidx{NATIONAL}
The data item is one containing nothing but the @code{N} symbol.

@item @plainidx{NATIONAL-EDITED}
The data item contains nothing but @code{N}, @code{B}, @code{/} and @code{0} symbols.
@end table
@comment Semantic Specifications:

@item
From the sequence of @var{identifier-1} data items specified on the @statement{INITIALIZE}, a list of initialized fields referred to as the @i{field list} in the remainder of this section, will include:
@enumerate A
@item
Every @var{identifier-1} that is an elementary item, including any that may have the @syntaxref{REDEFINES} clause in their descriptions.

@item
Every non-@code{FILLER} elementary item subordinate to @var{identifier-1}, provided that elementary item neither contains a @code{REDEFINES} clause in its definition nor belongs to a group item @i{subordinate to} @var{identifier-1} which contains a @code{REDEFINES} clause in its definition.

@item
If the optional
@syntaxidx{WITH FILLER} clause is included on the @statement{INITIALIZE}, then every FILLER elementary item subordinate to each @var{identifier-1} will be included as well, provided that elementary item neither contains a @code{REDEFINES} clause in its definition nor belongs to a group item @i{subordinate to} @var{identifier-1} which contains a @code{REDEFINES} clause in its definition..
@end enumerate

@item
Once a field list has been determined, each item in that field list will be initialized as if an individual @syntaxref{MOVE} statement to that effect had been coded.  The rules for initialization are as follows:

@item
If no
@syntaxidx{VALUE},
@syntaxidx{REPLACING} or
@syntaxidx{DEFAULT} clauses are coded, each member of the field list will be initialized as if the figurative constant @code{ZERO} (if the field list item is numeric or numeric-edited) or @code{SPACES} (otherwise) were being moved to it.

@item
If a @code{VALUE} clause is specified on the @statement{INITIALIZE}, each qualifying member of the field list having a compile-time @syntaxref{VALUE} specified in its definition will be initialized to that value.  Field list members with @code{VALUE} clauses will qualify for this treatment as follows:
@enumerate A
@item
If the @code{ALL} keyword was specified on the @code{VALUE} clause, all members of the field list with @code{VALUE} clauses will qualify.

@item
If @var{category-name-1} is specified instead of @code{ALL}, only those members of the field list with @code{VALUE} clauses that also meet the criteria set down for the specified @var{category-name} (see the list above) will qualify.

@item
If you need to apply @code{VALUE} initialization to multiple @var{category-name-1} values, you will need to use multiple @code{INITIALIZE} statements.
@end enumerate

@item
If a @code{REPLACING} clause is specified on the @statement{INITIALIZE}, each qualifying member of the field list that was not already initialized by a @code{VALUE} clause, if any, will be initialized to the specified @var{literal-1} or @var{identifier-1} value.

Only those as-yet uninitialized list members meeting the criteria set forth for the specified @var{category-name-2} will qualify for this initialization.

If you need to apply @code{REPLACING} initialization to multiple @var{category-name-2} values, you may repeat the syntax after the reserved word @code{REPLACING}, as necessary.

@item
If a @code{DEFAULT} clause is specified, any remaining uninitialized members of the field list will be initialized according to the default for their class (numeric and numeric-edited are initialized to @code{ZERO}, all others are initialized to @code{SPACES}).

@item
The following example may help your understanding of how the @statement{INITIALIZE} works.  The sample code makes use of the @command{COBDUMP} program to dump the storage that is (or is not) being initialized.  @xref{COBDUMP,COBDUMP,COBDUMP,gnucobsp,GnuCOBOL Sample Programs}, for a source and cross-reference listing of the @command{COBDUMP} program.

@example
IDENTIFICATION DIVISION.
PROGRAM-ID. DemoInitialize.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Item-1.
    05 I1-A VALUE ALL '*'.
       10 FILLER                PIC X(1).
       10 I1-A-1                PIC 9(1) VALUE 9.
    05 I1-B                     USAGE BINARY-CHAR.
    05 I1-C                     PIC A(1) VALUE 'C'.
    05 I1-D                     PIC X/X VALUE 'ZZ'.
    05 I1-E                     OCCURS 2 TIMES PIC 9.
PROCEDURE DIVISION.
000-Main.
    DISPLAY "MOVE HIGH-VALUES TO Item-1"
        PERFORM 100-Init-Item-1
        CALL "COBDUMP" USING Item-1
        DISPLAY " "

    DISPLAY "INITIALIZE Item-1"
        INITIALIZE Item-1
        CALL "COBDUMP" USING Item-1
        PERFORM 100-Init-Item-1
        DISPLAY " "

    DISPLAY "INITIALIZE Item-1 WITH @code{FILLER}"
        MOVE HIGH-VALUES TO Item-1
        INITIALIZE Item-1 WITH @code{FILLER}
        CALL "COBDUMP" USING Item-1
        PERFORM 100-Init-Item-1
        DISPLAY " "

    DISPLAY "INITIALIZE Item-1 ALL TO VALUE"
        MOVE HIGH-VALUES TO Item-1
        INITIALIZE Item-1 ALPHANUMERIC TO VALUE
        CALL "COBDUMP" USING Item-1
        PERFORM 100-Init-Item-1
        DISPLAY " "

    DISPLAY "INITIALIZE Item-1 REPLACING NUMERIC BY 1"
        MOVE HIGH-VALUES TO Item-1
        INITIALIZE Item-1 REPLACING NUMERIC BY 1
        CALL "COBDUMP" USING Item-1
        PERFORM 100-Init-Item-1
        DISPLAY " "

    STOP RUN
    .

100-Init-Item-1.
    MOVE HIGH-VALUES TO Item-1
    .
@end example

When executed, this program produces the following output:

@smallexample
MOVE HIGH-VALUES TO Item-1
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ---->
======== ==== =============================================== ================
00404058    1 FF FF FF FF FF FF FF FF FF                      .........

INITIALIZE Item-1
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ---->
======== ==== =============================================== ================
00404058    1 FF 30 00 20 20 2F 20 30 30                      .0.  / 00

INITIALIZE Item-1 WITH @code{FILLER}
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ---->
======== ==== =============================================== ================
00404058    1 20 30 00 20 20 2F 20 30 30                       0.  / 00

INITIALIZE Item-1 ALL TO VALUE
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ---->
======== ==== =============================================== ================
00404058    1 2A 2A FF 43 5A 5A 20 FF FF                      **.CZZ ..

INITIALIZE Item-1 REPLACING NUMERIC BY 1
<-Addr-> Byte <---------------- Hexadecimal ----------------> <---- Char ---->
======== ==== =============================================== ================
00404058    1 FF 31 01 FF FF FF FF 31 31                      .1.....11
@end smallexample
@end enumerate
@comment *********************************************************************
@comment ** 7.8.24 INITIATE                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.24,INITIATE}
@diagram{INITIATE,PD-INITIATE,PD-INITIATE,None}
The @statement{INITIATE} starts Report-Writer Control System (RWCS) processing for a report.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
Each @var{report-name-1} must be the name of a report having an @syntaxrefalt{RD,REPORT SECTION} defined for it.

@item
The file in whose @syntaxrefalt{FD,File/Sort-Description} a @code{REPORT @var{report-name-1}} clause exists must be open for @code{OUTPUT} or @code{EXTEND} at the time the @statement{INITIATE} is executed.  @xref{OPEN}, for more information on file open modes.

@item
The @statement{INITIATE} will initialize all of the following for each report named on the statement:
@itemize @bullet
@item
All sum counters, if any, will be set to 0

@item
The report's
@registerrefalt{LINE-COUNTER,Special Registers} will be set to 0

@item
The report's
@register{PAGE-COUNTER} will be set to 1
@end itemize

@item
No report content will actually presented to the report file as a result of a successful @statement{INITIATE} --- that will not occur until the first @statementref{GENERATE} is executed.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.25 INSPECT                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.25,INSPECT}
@diagram{INSPECT,PD-INSPECT,PD-INSPECT,None}
The @statement{INSPECT} is used to perform various counting and/or data-alteration operations against strings.
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{INITIAL} is optional and may be omitted.  The presence or absence of this words has no effect upon the program.

@item
If a
@syntaxidx{CONVERTING} clause is specified, neither the
@syntaxidx{TALLYING} nor
@syntaxidx{REPLACING} clauses may be used.

@item
If either the @code{TALLYING} or @code{REPLACING} clauses are specified, the @code{CONVERTING} clause cannot be used.

@item
If both the @code{TALLYING} and @code{REPLACING} clauses are specified, they must be specified in the order shown.

@item
All literals and identifiers must be explicitly or implicitly defined as alphanumeric or alphabetic.

@item
If @var{function-reference-1} is specified, it must be an invocation of an intrinsic function that returns a @i{string} result.  Additionally, only the @code{TALLYING} clause may be specified.

@item
If @var{literal-1} is specified, only the @code{TALLYING} clause may be specified.
@comment Semantic Specifications:

@item
Whichever is specified --- @var{literal-1}, @var{identifier-1} or @var{function-reference-1} --- that item will be referred to in the discussions that follows as the '@i{inspect subject}'.

@item
The three optional clauses control the operation of this statement as follows:
@enumerate A
@item
The @code{CONVERTING} clause replaces one or more individual characters found in the inspect subject with a different character in much the same manner as is possible with the @statementref{TRANSFORM}.

@item
The @code{REPLACING} clause replaces one or more sub strings located in the inspect subject with a different, but equally-sized replacement sub string.  If you need to replace a sub string with another of a @i{different} length, consider using either the @intrinsicref{SUBSTITUTE} or the @intrinsicref{SUBSTITUTE-CASE}.

@item
The @code{TALLYING} clause counts the number of occurrences of one or more strings of characters in the inspect subject.
@end enumerate

@item
The optional @code{INITIAL} clauses may be used to limit the range of characters in the inspect subject that the  @code{CONVERTING}, @code{REPLACING} or @code{TALLYING} instruction in which they occur will apply.  We call this the '@i{target range}' of the inspect subject.  The target range is defined as follows:
@enumerate A
@item
If there is no @code{INITIAL} clause specified, the target range is the entire inspect subject.

@item
Either a @code{BEFORE} phrase, an @code{AFTER} phrase or both may be specified.  They may be specified in any order.

@item
The starting point of the target range will be the first character following the sub string identified by the @code{AFTER} specification.  The ending point will be the last character immediately preceding the sub string identified by the @code{BEFORE} specification.

@item
If no @code{AFTER} is specified, the first character position of the target range will be character position #1 of the inspect subject.

@item
If no @code{BEFORE} is specified, the last character position of the target range will be the last character position of the inspect subject.
@end enumerate

@item
The following points apply to the use of the @code{TALLYING} clause:
@enumerate A
@item
While there will typically be only be a single set of counting instructions on an @code{INSPECT}:

@example
INSPECT Character-String
    TALLYING C-ABC FOR ALL "ABC"
@end example

There could be multiple counting instructions specified:

@example
INSPECT Character-String
    TALLYING C-ABC FOR ALL "ABC"
             C-BCDE FOR ALL "BCDE"
@end example

When there @i{are} multiple instructions, the one specified first will take priority over the one specified second, (and so forth) as the @code{INSPECT} proceeds forward through the inspect subject, character-by-character.

With the above example, if the inspect subject were @code{--ABCDEF----BCDEF--}, the final result of the counting would be that @code{C-ABC} would be incremented by 1 while @code{C-BCDE} would be incremented only once; although the human eye clearly sees two @samp{BCDE} sequences, the @code{INSPECT ... TALLYING} would only ``see'' the second --- the first would have been processed by the first (higher-priority) counting instruction.

@item
Each set of counting instructions contains the following information:
@enumerate a
@item
A target range, specified by the presence of an @code{AFTER INITIAL} and/or @code{BEFORE INITIAL} clause; the rules for specifying target ranges were covered previously.

@item
A Target Sub string --- this is a sequence of characters to be located somewhere in the inspect subject and counted.  Target sub strings may be defined as a literal value (figurative constants are allowed) or by the contents of an identifier.  If the target sub string is specified as a figurative constant, it will be assumed to have a length of one (@samp{1}) character.  The keywords before the literal or identifier control how many target sub strings could be identified from that replacement instruction, as follows:

@code{ALL} --- identifies every possible target sub string that occurs within the target range.  There are three occurrences of @code{ALL 'XX'} found in @code{aXXabbXXccXXdd}.

@code{LEADING} --- identifies only an occurrence of the target sub string found either at the first character position of the target range or immediately following a previously-found occurrence.  There are no occurrences of @code{LEADING 'XX'} found in @code{aXXabbXXccXXdd}, but there is one occurrence of @code{LEADING 'a'} (the first character).

@code{TRAILING} --- identifies only an occurrence of the target sub string found either at the very end of the target range or toward the end, followed by nothing but other occurrences.  There are no occurrences of @code{LEADING 'XX'} found in @code{aXXabbXXccXXdd}, but there are two occurrences of @code{TRAILING 'd'}.

The @code{CHARACTERS} option will match any one single character, regardless of what that character is.
@end enumerate

@item
@var{identifier-2} will be incremented by 1 each time the target sub string is found within the target range of the inspect subject.  The @code{INSPECT} statement @i{will not} zero-out @var{identifier-2} at the start of execution of the @code{INSPECT} --- it is the programmer's responsibility to ensure that all @var{identifier-2} data items are properly initialized to the desired starting values prior to execution of the @code{INSPECT}.
@end enumerate

@item
The following points apply to the use of the @code{REPLACING} clause:
@enumerate A
@item
While there will typically be only be a single set of replacement instructions on an @code{INSPECT}:

@example
INSPECT Character-String
    REPLACING ALL "ABC" BY "DEF"
@end example

There could be multiple replacement instructions:

@example
INSPECT Character-String
    REPLACING ALL "ABC" BY "DEF"
              ALL "BCDE" BY "WXYZ"
@end example

When there @i{are} multiple replacement instructions, the one specified first will take priority over the one specified second, (and so forth) as the @code{INSPECT} proceeds forward through the inspect subject, character-by-character.

With the above example, if the inspect subject were @code{--ABCDEF----BCDEF--}, the final result of the replacement would be @code{--DEFDEF----WXYZF--}.

@item
Each set of replacement instructions contains the following information:
@enumerate a
@item
A target range, specified by the presence of an @code{AFTER INITIAL} and/or @code{BEFORE INITIAL} clause; the rules for specifying target ranges were covered previously.

@item
A Target Sub string --- this is a sequence of characters to be located somewhere in the inspect subject and subsequently replaced with a new value.  Target sub strings, which are specified before the @code{BY} keyword, may be defined as a literal value (figurative constants are allowed) or by the contents of an identifier.  If the target sub string is specified as a figurative constant, it will be assumed to have a length of one (@samp{1}) character.  The keywords before the literal or identifier control how many target sub strings could be identified from that replacement instruction, as follows:

@code{ALL} --- identifies every possible target sub string that occurs within the target range.  There are three occurrences of @code{ALL 'XX'} found in @code{aXXabbXXccXXdd}.

@code{FIRST} --- the first occurrence of the target sub string found within the target range.  The @code{FIRST 'XX'} found in @code{aXXabbXXccXXdd} would be the one found between the @samp{a} and @samp{b} characters.

@code{LEADING} --- an occurrence of the target sub string found either at the first character position of the target range or immediately following a previously-found occurrence.  There are no occurrences of @code{LEADING 'XX'} found in @code{aXXabbXXccXXdd}, but there is one occurrence of @code{LEADING 'a'} (the first character).

@code{TRAILING} --- an occurrence of the target sub string found either at the very end of the target range or toward the end, followed by nothing but other occurrences.  There are no occurrences of @code{LEADING 'XX'} found in @code{aXXabbXXccXXdd}, but there are two occurrences of @code{TRAILING 'd'}.

The @code{CHARACTERS} option will match any one single character.  When you use this option, the replacement sub string (see the next item) must be exactly one character in length.

@item
A Replacement Sub string --- this is the sequence of characters that should replace the target sub string.  Replacement sub strings are specified after the @code{BY} keyword.  They too may be specified as a literal, either with or without an @code{ALL} prefix (again, figurative constants are allowed) or the value of an identifier.  If a figurative constant is coded, the @code{ALL} keyword will be assumed, even if it wasn't specified.  Literals without @code{ALL} will either be truncated or padded with spaces on the right to match the length of the target sub string.  Literals with @code{ALL} or figurative constants will be repeated as necessary to match the length of the target sub string.  Identifiers specified as replacement sub strings must be defined with a length equal to that of the target sub string.
@end enumerate
@end enumerate

@item
When both @code{REPLACING} and @code{TALLYING} are specified:
@enumerate A
@item
The @code{INSPECT} statement will make a single pass through the sequence of characters comprising the inspect subject.  As the pointer to the current inspect target character reaches a point where it falls within the explicit or implicit target ranges specified on the operational instructions of the two clauses, the actions specified by those instructions will become eligible to be taken.  As the character pointer reaches a point where it falls past the end of target ranges, the instructions belonging to those target ranges will become disabled.

@item
At any point in time, there may well be multiple @code{REPLACING} and/or @code{TALLYING} operational instructions  active.  Only one of the @code{TALLYING} and one of the @code{REPLACING} instructions (if any) can be executed for any one character pointer position.  In each case, it will be the first of the instructions in each category that produces a match with its target string specification.

@item
When both a @code{TALLYING} and a @code{REPLACING} instruction have been selected for execution, the @code{TALLYING} instruction will be executed first.  This guarantees that @code{TALLYING} will compute occurrences based upon the @i{initial} value of the inspect subject before any replacements occur.
@end enumerate

@item
The following points apply to the use of the @code{CONVERTING} clause:
@enumerate A
@item
A @code{CONVERTING} clause performs a series of single-character substitutions against a data item in much the same manner as is possible with the @statementref{TRANSFORM}.

@item
Unlike the @code{TALLYING} and @code{REPLACING} clauses, both of which may have multiple operations specified, there may be only one @code{CONVERTING} operation per @code{INSPECT}.

@item
If the length of @var{literal-7} or @var{identifier-8} (the ``from'' string) @i{exceeds} the length of @var{literal-8} or @var{identifier-9} (the ``to'' string), then the ``to'' string will be assumed to be padded to the right with enough spaces to make it the same length as the ``from'' string.

@item
If the length of the ``from'' string @i{is less than} the length of the ``to'' string, then the ``to'' string will be truncated to the length of the ``from'' string.

@item
Each character, in turn, within the ``from'' string will be searched for in the target range of the inspect subject.  Each located occurrence will be replaced by the corresponding character of the ``to'' string.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.26 MERGE                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.26,MERGE}
@diagram{MERGE,PD-MERGE-Info,PD-MERGE-TeX,PD-DUPLICATES}
The @statement{MERGE} merges the contents of two or more files that have each been pre-sorted on a set of specified identical keys.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IN}, @code{IS}, @code{KEY}, @code{ON}, @code{ORDER}, @code{SEQUENCE} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
GnuCOBOL always behaves as if the @code{WITH DUPLICATES IN ORDER} clause is specified, even if it isn't.

While any COBOL implementation's sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.

Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
@comment Semantic Specifications:

@item
The @var{sort-file-1} named on the @statement{MERGE} must be defined using a sort description (@syntaxrefalt{SD,File/Sort-Description}).  This file is referred to in the remainder of this discussion as the @i{merge work file}.

@item
Each @var{file-name-1}, @var{file-name-2} and @var{file-name-3} (if specified) must reference @syntaxref{ORGANIZATION LINE SEQUENTIAL} or @syntaxref{ORGANIZATION SEQUENTIAL} files.  These files must be defined using a file description (@syntaxrefalt{FD,File/Sort-Description}).

@item
The @var{identifier-1} @dots{} field(s) must be defined as field(s) within a record of @var{sort-file-1}.

@item
The record descriptions of @var{file-name-1}, @var{file-name-2}, @var{file-name-3} (if any) and @var{sort-file-1} are assumed to be identical in layout and size.  While the actual data names used for fields in these files' records may differ, the structure of records, @syntaxref{PICTURE} of fields, @syntaxref{USAGE} of fields, size of fields and location of fields within the records should match field-by-field across all files, at least as far as the @code{KEY} fields are concerned.

@item
A common programming technique when using the @statement{MERGE} is to define the records of all files involved as simple elementary items of the form @code{01 record-name PIC X(n).} where n is the record size.  The only file where records are actually described in detail would then be @var{sort-file-1}.

@item
The following rules apply to the files named on the @code{USING} clause:
@enumerate A
@item
None of them may be open at the time the @code{MERGE} is executed.

@item
Each of those files is assumed to be already sorted according to the specifications set forth on the @statement{MERGE}'s
@syntaxidx{KEY} clause.

@item
No two of those files may be referenced on a @syntaxref{SAME RECORD AREA}, @code{SAME SORT AREA} or @code{SAME SORT-MERGE AREA} statement.
@end enumerate

@item
The merging process is as follows:
@enumerate A
@item
As the @statement{MERGE} begins execution, the first record in each of the
@syntaxidx{USING} files is read automatically.

@item
As the @statement{MERGE} executes, the current record from each of the @code{USING} files is examined and compared to each other according to the rules set forth by the @code{KEY} clause and the alphabet (@pxref{Alphabet-Name-Clause}) specified on the
@syntaxidx{COLLATING SEQUENCE} clause.  The record that should be next in sequence will be written to the merge work file and the @code{USING} file from which that record came will be read so that its next record is available.  As end-of-file conditions are reached on @code{USING} files, those files will be excluded from further processing --- processing continues with the remaining files until all the contents of all of them have been exhausted.

@item
After the merge work file has been populated, the merged data will be written to each @var{file-name-3} if the
@syntaxidx{GIVING} clause was specified, or will be processed by utilizing an
@syntaxidx{OUTPUT PROCEDURE}.

@item
When @code{GIVING} is specified, none of the @var{file-name-3} files can be open at the time the @statement{MERGE} is executed.

@item
When an output procedure is used, the procedure(s) specified on the @code{OUTPUT PROCEDURE} clause will be invoked as if by a procedural @syntaxrefalt{PERFORM,Procedural PERFORM} statement with no @code{VARYING}, @code{TIMES} or @code{UNTIL} options specified.  Merged records may be read from the merge work file --- one at a time --- within the output procedure using the @syntaxref{RETURN} statement.

A @statementref{GO TO} that transfers control out of the output procedure will terminate the @statement{MERGE} but allows the program to continue executing from the point where the @statement{GO TO} transferred control to.  Once an output procedure has been ``aborted'' using a @code{GO TO} it cannot be resumed, and the contents of the merge work file are lost.  You may, however, re-execute the @statement{MERGE} itself.  @i{Using a} @statement{GO TO} @i{to prematurely terminate a merge, or re-starting a previously-cancelled merge is not considered good programming style and should be avoided}.

An output procedure should be terminated in the same way a procedural @statement{PERFORM} would be.  Usually, this action will be taken once the @statement{RETURN} indicates that all records in the merge work file have been processed, but termination could occur at @i{any} time --- via an @statementref{EXIT} --- if required.

Neither a file-based @statementrefalt{SORT,File-Based SORT} nor another @statement{MERGE} may be executed within the scope of the procedures comprising the output procedure unless those statements utilize a different sort or merge work file.

@item
Once the output procedure terminates, or the last @var{file-name-3} file has been populated with merged data, the output phase --- and the @statement{MERGE} itself --- is complete.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.27 MOVE                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.27,MOVE}
@menu
* 7.8.27.1: Simple MOVE
* 7.8.27.2: MOVE CORRESPONDING
@end menu
@comment *********************************************************************
@comment ** 7.8.27.1 Simple MOVE                                           **
@comment *********************************************************************
@newunit{7.8.27.1,Simple MOVE}
@diagram{Simple MOVE,PD-MOVE-1,PD-MOVE-1,None}
The Simple @statement{MOVE} moves a specific value to one or more receiving data items.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
The @statement{MOVE} will replace the contents of one or more receiving data items (@var{identifier-2}) with a new value --- the one specified by @var{literal-1} or @var{identifier-1}.

@item
Only numeric data can be moved to a numeric or numeric-edited @var{identifier-2}.  A @code{MOVE} involving numeric data will perform any necessary format conversions that might be necessary due to differing @syntaxref{USAGE} specifications.

@item
The contents of the @var{identifier-1} data item will not be changed, unless that same data item appears as an @var{identifier-2}.  Note that such situations will cause a warning message to be issued by the compiler, if warning messages are enabled.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.27.2 MOVE CORRESPONDING                                    **
@comment *********************************************************************
@page
@newunit{7.8.27.2,MOVE CORRESPONDING}
@diagram{MOVE CORRESPONDING,PD-MOVE-2,PD-MOVE-2,None}
The @statement{MOVE CORRESPONDING} similarly-named items from one group item to another.
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{CORRESPONDING} may be abbreviated as @code{CORR}.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be group items.

@item
@xref{CORRESPONDING}, for a discussion of how corresponding matches between two group items are established.

@item
When corresponding matches are established, the effect of a @code{MOVE CORRESPONDING} on those matches will be as if a series of individual @code{MOVE}s were done --- one for each match.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.28 MULTIPLY                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.28,MULTIPLY}
@menu
* 7.8.28.1: MULTIPLY BY
* 7.8.28.2: MULTIPLY GIVING
@end menu
@comment *********************************************************************
@comment ** 7.8.28.1 MULTIPLY BY                                           **
@comment *********************************************************************
@newunit{7.8.28.1,MULTIPLY BY}
@diagram{MULTIPLY BY,PD-MULTIPLY-1,PD-MULTIPLY-1,None}
The @statement{MULTIPLY BY} computes the product of one or more data items (@var{identifier-2}) and either a numeric literal or another data item.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric un-edited data items; @var{literal-1} must be a numeric literal.

@item
The product of @var{identifier-1} or @var{literal-1} and each @var{identifier-2}, in turn, will be computed and moved to each of the @var{identifier-2} data items, replacing the prior contents.

@item
The value of @var{identifier-1} is not altered, unless that same data item appears as an @var{identifier-2}.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.28.2,MULTIPLY GIVING                                       **
@comment *********************************************************************
@page
@newunit{7.8.28.2,MULTIPLY GIVING}
@diagram{MULTIPLY GIVING,PD-MULTIPLY-2,PD-MULTIPLY-2,None}
The @statement{MULTIPLY GIVING} computes the product of two literals and/or data items and saves that result in one or more other data items.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric un-edited data items; @var{literal-1} and @var{literal-2} must be numeric literals.

@item
The product of @var{identifier-1} or @var{literal-1} and @var{identifier-2} or @var{literal-2} will be computed and moved to each of the @var{identifier-3} data items, replacing their old contents.

@item
Neither the value of @var{identifier-1} nor @var{identifier-2} will be altered, unless either appears as an @var{identifier-3}.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.29 OPEN                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.29,OPEN}
@diagram{OPEN,PD-OPEN,PD-OPEN,PD-OPEN}
The @statement{OPEN} makes one or more files described in your program available for use.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{OTHER} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The @code{SHARING} and @code{WITH LOCK} clauses may not both be specified in the same @statement{OPEN}.
@comment Semantic Specifications:

@item
Any file defined in a GnuCOBOL program must be successfully opened before it or any of its record descriptions may be referenced on:

A @statementref{CLOSE}

A @statementref{DELETE}

A @statementref{READ}

A @statementref{REWRITE}

A @statementref{START}

An @statementref{UNLOCK}

A @statementref{WRITE}

@item
Any attempt to open a file that is already open will fail with a file status of 41 (@pxref{File Status Codes}).

@item
Any open failure (including status 41) may be trapped using @syntaxref{DECLARATIVES} or an error procedure established using the @subpgmref{CBL_ERROR_PROC} built-in subroutine or even just checking the status field defined.  It is up to the programmer to check for bad statuses and respond accordingly such as issue a CLOSE before dealing with the problem.

@item
@anchoridx{File OPEN Modes}The
@syntaxidx{INPUT},
@syntaxidx{OUTPUT},
@syntaxidx{I-O} and
@syntaxidx{EXTEND} open modes inform GnuCOBOL of the manner in which you wish to use the file, as follows:
@table @asis
@item @code{INPUT}
You may only read the existing contents of the file --- only the @code{CLOSE}, @code{READ}, @code{START} and @code{UNLOCK} statements will be allowed.  This enforcement takes place at execution time, not compilation time.

@item @code{OUTPUT}
You may only write new content (which will completely replace any previous file contents) to the file --- only the @code{CLOSE}, @code{UNLOCK} and @code{WRITE} statements will be allowed.  This enforcement takes place at execution time, not compilation time.

@item @code{I-O}
You may perform any operation you wish against the file --- all file I/O statements will be allowed.

@item @code{EXTEND}
You may only write new content (which will be appended after the previously existing file contents) to the file --- only the @code{CLOSE}, @code{UNLOCK} and @code{WRITE} statements will be allowed.  This enforcement takes place at execution time, not compilation time.  You cannot extend an empty file; this will not generate a runtime error, but no output will appear in the file.
@end table

@item
The
@syntaxidx{SHARING} clause informs the GnuCOBOL file runtime modules how you are willing to co-exist with any other GnuCOBOL programs that may attempt to open the same file after your program does.  @xref{File Sharing}, for an explanation of the @code{SHARING} clause.

@item
The
@syntaxidx{WITH LOCK} option will be functional only if your GnuCOBOL build can support it.  GnuCOBOL built for MinGW or native Windows will not, because the Unix @code{fcntl} primitive doesn't exist in those environments.  GnuCOBOL built for Cygwin or Unix will.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.30 PERFORM                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.30,PERFORM}
@menu
* 7.8.30.1: Procedural PERFORM
* 7.8.30.2: Inline PERFORM
* 7.8.30.3: VARYING
@end menu
@comment *********************************************************************
@comment ** 7.8.30.1 Procedural PERFORM                                    **
@comment *********************************************************************
@newunit{7.8.30.1,Procedural PERFORM}
@diagram{Procedural PERFORM,PD-PERFORM-1,PD-PERFORM-1,None}
This format of the @statement{PERFORM} is used to transfer control to one or more procedures, which will return control back when complete.  Execution of the procedure(s) can be done a single time, multiple times, repeatedly until a condition becomes @code{TRUE} or forever (with some way of breaking out of the control of the @code{PERFORM} or of halting program execution within the procedure(s)).
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{WITH} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
The reserved word and phrase @code{FOREVER} and @code{UNTIL EXIT} are interchangeable.
@comment Semantic Specifications:

@item
Both @var{procedure-name-1} and @var{procedure-name-2} must be procedure division sections or paragraphs defined in the same program as the @code{PERFORM} statement.  If @var{procedure-name-2} is specified, it must follow @var{procedure-name-1} in the program's source code.

@item
The
@define{perform scope} is defined as being the statements within @var{procedure-name-1}, the statements within @var{procedure-name-2} and all statements in all procedures defined between them.

@item
@var{literal-1} must be a numeric literal or a reference to a function that returns a numeric value.  The value must be an integer greater than zero.

@item
@var{identifier-1} must be an elementary un-edited numeric data item with an integer value greater than zero.

@item
Without the
@syntaxidx{UNTIL},
@syntaxidx{UNTIL EXIT},
@syntaxidx{TIMES}, @termrefalt{VARYING-Clause,VARYING} or
@syntaxidx{FOREVER} clauses, the code within the perform scope will be executed once, after which control will return to the statement following the @code{PERFORM}.

@item
The @code{FOREVER} option will repeatedly execute the code within the perform scope with no conditions defined for termination of the repetition --- it will be up to the programmer to include an @statementrefalt{EXIT SECTION,EXIT} or @statement{EXIT PARAGRAPH} within the procedure(s) being performed that will break out of the loop.

@item
The @code{TIMES} option will repeat the execution of the code within the perform scope a fixed number of times.  When the @code{PERFORM} statement begins execution, an internal repeat counter (not accessible to the programmer) will be set to the value of @var{literal-1} or the value within @var{identifier-1}.

If the counter has a value greater than zero, the statement(s) within the @code{PERFORM} scope will be executed, after which the counter will be decremented by 1 with each repetition.  Once that counter reaches zero, repetition will cease and control will fall into the next statement following the @code{PERFORM}.

If the @var{identifier-1} option was used, altering the value of that data item within the perform scope will @i{not} affect the repetition count.

@item
The @code{UNTIL @var{conditional-expression-1}} option will repeat the code within the perform scope until the specified conditional expression evaluates to a @code{TRUE} value.

@item
The optional
@syntaxidx{WITH TEST} clause will control whether @code{UNTIL} testing occurs @code{BEFORE} the statements within the perform scope are executed on each iteration (creating the possibility --- if @var{conditional-expression-1} is initially @code{TRUE} --- that the statements within the perform scope will never be executed) or
@syntaxidx{AFTER} (guaranteeing the statements within the perform scope will be executed at least once).

The default, if this clause is absent, is @code{WITH TEST BEFORE}.

This clause may not be coded when the @code{TIMES} clause is used.

@item
The optional @code{@var{VARYING-Clause}} is a mechanism that creates an advanced loop-management mechanism complete with one or more numeric data items being automatically incremented (or decremented) on each loop iteration as well as the termination control of an @code{UNTIL} clause.  @xref{VARYING}, for the details.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.30.2 Inline PERFORM                                        **
@comment *********************************************************************
@page
@newunit{7.8.30.2,Inline PERFORM}
@diagram{Inline PERFORM,PD-PERFORM-2,PD-PERFORM-2,None}
This format of the @statement{PERFORM} is identical in operation to the procedural @code{PERFORM}, except for the fact that the statement(s) comprising the perform scope (@var{imperative-statement-1}) (@pxref{Imperative Statement}) are now specified in-line with the @code{PERFORM} code rather than in procedures located elsewhere within the program.
@comment *********************************************************************
@comment ** 7.8.30.3 VARYING                                               **
@comment *********************************************************************
@page
@newunit{7.8.30.3,VARYING}
@diagram{VARYING,PD-PERFORM-VARYING,PD-PERFORM-VARYING,None}
The @code{VARYING} clause, available on both formats of the @code{PERFORM} statement, is a looping mechanism that allows for the specification of one or more numeric data items that will be initialized to a programmer-specified value and automatically incremented by another programmer-specified value after each loop iteration.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
All identifiers used in a @var{VARYING-Clause} must be elementary, un-edited numeric data items.  All literals must be numeric literals.

@item
The following points describe the sequence of events that take place as a result of the @code{VARYING} portion of the clause:
@enumerate A
@item
When the @code{PERFORM} begins execution, the @code{FROM} value will be moved to @var{identifier}.

@item
If the @code{PERFORM} specifies or implies @code{WITH TEST BEFORE}, @var{conditional-expression-1} will be evaluated and processing of the @code{PERFORM} will halt if the expression evaluates to @code{TRUE}.  If @code{WITH TEST BEFORE} was @i{not} specified or implied, or if the conditional expression evaluated to @code{FALSE}, processing proceeds with step C.

@item
The statements within the perform scope will be executed.  If a @code{GO TO} executed within the perform scope transfers control to a point outside the perform scope, processing of the @code{PERFORM} will halt.

@item
When the statements within the perform scope terminate the loop iteration, by one of:
@itemize @bullet
@item
allowing the flow of execution to attempt to fall past the last statement in the perform scope

@item
executing an @statementrefalt{EXIT PERFORM CYCLE,EXIT}

@item
executing an @statement{EXIT PARAGRAPH} or @statement{EXIT SECTION} when there is only one paragraph (or section) in the perform scope ( this option only applies to a procedural @code{PERFORM})
@end itemize

If @code{WITH TEST AFTER} was specified, control will return back to the @code{PERFORM}, where  @var{conditional-expression-1} will be evaluated, and processing of the @code{PERFORM} will halt if the expression evaluates to @code{TRUE}.  If @code{WITH TEST AFTER} was @i{not} specified, or if the conditional expression evaluated to @code{FALSE}, processing continues with the next step.

@item
The @code{BY} value, if any, will be added to @var{identifier-2}.  If no @code{BY} is specified, it will be treated as if @code{BY 1} had been specified.

@item
Return to step C.
@end enumerate

@item
Most @code{@var{VARYING-Clause}}s have no @code{AFTER} specified.  Those that do, however, are establishing a loop-within-a-loop situation where the process described above in steps (@samp{A}) through (@samp{F}) will take place from the @code{AFTER}, and those six processing steps actually replace step C of the @code{VARYING}.  This ``nesting'' process can continue indefinitely, with each additional @code{AFTER}.
@end enumerate

An example should really help you see this at work.  Observe the following code which defines a two-dimensional (3 row by 4 column) table and a pair of numeric data items to be used to subscript references to each element of the table:

@example
01  PERFORM-DEMO.
    05 PD-ROW             OCCURS 3 TIMES.
       10 PD-COL          OCCURS 4 TIMES
          15 PD           PIC X(1).
01  PD-Col-No             PIC 9 COMP.
01  PD-Row-No             PIC 9 COMP.
@end example

Let's say the 3x4 ``grid'' defined by the above structure has these values:

@example
A B C D
E F G H
I J K L
@end example

This code will display @code{ABCDEFGHIJKL} on the console output window:

@example
PERFORM WITH TEST AFTER
        VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3
          AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4
    DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING
END-PERFORM
@end example

While this code will display @code{AEIBFJCGKDHL} on the console output window:

@example
PERFORM WITH TEST AFTER
        VARYING PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4
          AFTER PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3
    DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING
END-PERFORM
@end example

While we're looking at sample code, this code displays @code{ABCEFG}:

@example
PERFORM
        VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No = 3
          AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No = 4
    DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING
END-PERFORM
@end example

By removing the @code{WITH TEST} clause, the statement is now assuming @code{WITH TEST BEFORE}.  Since testing now happens @i{before} the @statement{DISPLAY} gets executed, when PD-Row-No is 3 and PD-Col-No is 4 the @statement{DISPLAY} won't be executed.

Most COBOL programmers, when using @code{WITH TEST BEFORE} explicitly or implicitly have developed the habit of using @samp{>} rather than @samp{=} on @code{UNTIL} clauses.  This would make the sample code:

@example
PERFORM
        VARYING PD-Row-No FROM 1 BY 1 UNTIL PD-Row-No > 3
          AFTER PD-Col-No FROM 1 BY 1 UNTIL PD-Col-No > 4
    DISPLAY PD (PD-Row-No, PD-Col-No) WITH NO ADVANCING
END-PERFORM
@end example

With this change, @code{ABCDEFGHIJKL} is once again displayed.
@comment *********************************************************************
@comment ** 7.8.31 READ                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.31,READ}
@menu
* 7.8.31.1: Sequential READ
* 7.8.31.2: Random READ
@end menu
@comment *********************************************************************
@comment ** 7.8.31.1 Sequential READ                                       **
@comment *********************************************************************
@newunit{7.8.31.1,Sequential READ}
@diagram{Sequential READ,PD-READ-1,PD-READ-1,None}
This form of the @statement{READ} retrieves the next (or previous) record from a file.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{AT}, @code{RECORD} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The @var{file-name-1} file @i{must} have been defined via an @syntaxrefalt{FD,File/Sort-Description}, not an @code{SD}.
@comment Semantic Specifications:

@item
The @var{file-name-1} file must currently be open for @syntaxrefalt{INPUT,File OPEN Modes} or @code{I-O}.

@item
If @var{file-name-1} is an @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED} file with an @code{ACCESS MODE RANDOM}, this statement cannot be used.

@item
If @var{file-name-1} was specified as @code{ACCESS MODE SEQUENTIAL}, this is the @i{only} format of the @statement{READ} that is available.

@item
If @var{file-name-1} is an @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED} file with @code{ACCESS MODE DYNAMIC}, this statement as well as a random @syntaxrefalt{READ,Random READ} may be used.

@item
The keywords
@syntaxidx{NEXT} and
@syntaxidx{PREVIOUS} specify what ``direction of travel'' the reading process will take through the file.  If neither is specified, @code{NEXT} is assumed.

@item
The @code{PREVIOUS} option is available only for @code{ORGANIZATION INDEXED} files.

@item
When reading any sequential (any organization) or relative file, the ``next'' direction refers to the physical sequence of records in the file.  When reading an indexed file, the ``next'' and ``previous'' directions refer to the sequence of primary or alternate record key values in the file's records, regardless of where the records physically occur within the file.

@item
The minimal statement @code{READ @var{file-name-1}} is perfectly legal according to @i{both} READ formats.  For that reason, when @code{ACCESS MODE DYNAMIC} has been specified and you want to tell the GnuCOBOL compiler that this minimal statement should be treated as a @i{sequential} @code{READ}, you must add either @code{NEXT} or @code{PREVIOUS} to the statement (otherwise it will be treated as a random @code{READ}).

@item
A successful sequential READ will retrieve the next available record from @var{file-name-1}, in either a ``next'' or ``previous'' direction from the most-recently-read record, depending upon the use of the @code{NEXT} or @code{PREVIOUS} option.  The newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file's @code{FD}.  If the optional
@syntaxidx{INTO} clause is present, a copy of the just-retrieved record will be automatically moved to @var{identifier-1}.

@item
When an @code{ORGANIZATION RELATIVE} file has been successfully read, the file's @syntaxrefalt{RELATIVE KEY,ORGANIZATION RELATIVE} field will be automatically populated with the relative record number (ordinal occurrence number) of the record in the file.

@item
The optional @code{LOCK} options may be used to manually control access to the retrieved record by other programs while this program is running.  @xref{Record Locking}, to review the various record locking behaviours.

@item
The optional @code{AT END} clause, if coded, is used to detect and react to the failure of an attempt to retrieve another record from the file due to an end-of-file (i.e. no more records) condition.

@item
The optional @code{NOT AT END} clause, if coded, will check for a file status value of 00.  @xref{File Status Codes}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.31.2 Random READ                                           **
@comment *********************************************************************
@page
@newunit{7.8.31.2,Random READ}
@diagram{Random READ,PD-READ-2,PD-READ-2,None}
This form of the @statement{READ} retrieves an arbitrary record from an @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED} file.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS}, @code{KEY} (on the @code{INVALID} and @code{NOT INVALID} clauses), @code{RECORD} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The @var{file-name-1} file @i{must} have been defined via an @syntaxrefalt{FD,File/Sort-Description}, not an @code{SD}.
@comment Semantic Specifications:

@item
The @var{file-name-1} file must currently be open for @syntaxrefalt{INPUT,File OPEN Modes} or @code{I-O}.

@item
If the @code{ACCESS MODE} of @var{file-name-1} is @code{SEQUENTIAL}, or the @code{ORGANIZATION} of the file is any form of sequential, this format of the @statement{READ} cannot be used.

@item
If the @code{ACCESS MODE} of @var{file-name-1} is @code{RANDOM}, this is the @i{only} format of the @statement{READ} that is available.

@item
If @var{file-name-1} is an @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED} file with @code{ACCESS MODE DYNAMIC}, this statement as well as a sequential @syntaxrefalt{READ,Sequential READ} may be used.

@item
The minimal statement @code{READ @var{file-name-1}} is perfectly legal according to @i{both} READ formats.  For that reason, when @code{ACCESS MODE DYNAMIC} has been specified and you want to tell the GnuCOBOL compiler that this minimal statement should be treated as a @i{random} @code{READ}, you must omit the @code{NEXT} or @code{PREVIOUS} available to the sequential format of the @statement{READ} to ensure the statement @i{will} be treated as a random @code{READ}.

@item
The optional
@syntaxidx{KEY} clause tells the compiler how a record is to be located in the file.

If the @code{KEY} clause is absent, and the file is

@table @code
@item ORGANIZATION RELATIVE
the contents of the field declared as the file's @code{RELATIVE KEY} will be used to identify a record

@item ORGANIZATION INDEXED
the contents of the field declared as the file's @code{RECORD KEY} will be used to identify a record.
@end table

If the @code{KEY} clause @i{is} specified, and the file is

@table @code
@item ORGANIZATION RELATIVE
the contents of @var{identifier-2} will be used as the relative record number of the record to be accessed.  @var{identifier-2} need not be the @syntaxrefalt{RELATIVE KEY,ORGANIZATION RELATIVE} field of the file (although it could be if you wish).

@item ORGANIZATION INDEXED
@var{identifier-2} @i{must} be the @syntaxrefalt{RECORD KEY,ORGANIZATION INDEXED} or one of the file's @code{ALTERNATE RECORD KEY} fields (if any).  The current contents of that field will identify the record to be accessed.  If an alternate record key is used, and that key allows duplicate values, the record accessed will be the @i{first} one having that key value.
@end table

@item
Once read from the file, the newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file's @code{FD}.  If the optional
@syntaxidx{INTO} clause is present, a copy of the just-retrieved record will be automatically moved to @var{identifier-1}.

@item
When an @code{ORGANIZATION RELATIVE} file has been successfully read, the file's @syntaxrefalt{RELATIVE KEY,ORGANIZATION RELATIVE} field will be automatically populated with the relative record number (ordinal occurrence number) of the record in the file.

@item
The optional @code{LOCK} options may be used to manually control access to the retrieved record by other programs while this program is running.  @xref{Record Locking}, to review the various record locking behaviours.

@item
The optional @code{INVALID KEY} and @code{NOT INVALID KEY} clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively.  @xref{File Status Codes}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.32 READY TRACE                                             **
@comment *********************************************************************
@page
@newsubsection{7.8.32,READY TRACE}
@diagram{READY TRACE,PD-READY-TRACE,PD-READY-TRACE,None}
The @statement{READY TRACE} turns procedure or procedure-and-statement tracing on.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
In order for this statement to be functional, tracing code must have been generated into the compiled program using either the
@switchidx{-ftrace} (procedures only) or @switch{-ftraceall} (procedures and statements).

@item
Tracing may be turned off at any point by executing the @statementref{RESET TRACE}.

@item
The
@envvarruntimeref{COB_SET_TRACE} provides another way to control tracing.  If this environment variable is set to a value of @samp{Y} prior to the start of program execution, tracing starts at the point the program begins execution, as if @code{READY TRACE} were the first executed statement.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.33 RELEASE                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.33,RELEASE}
@diagram{RELEASE,PD-RELEASE,PD-RELEASE,None}
The @statement{RELEASE} adds a new record to a sort work file.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
This statement is valid only within the @code{INPUT PROCEDURE} of a file-based @statementrefalt{SORT,File-Based SORT}.

@item
The specified @var{record-name-1} must be a record defined to the sort description (@syntaxrefalt{SD,File/Sort-Description}) of the sort work file being processed by the current sort.

@item
The optional
@syntaxidx{FROM} clause will cause @var{literal-1} or @var{identifier-1} to be automatically moved into @var{record-name-1} prior to writing @var{record-name-1}'s contents to the @var{file-name-1}.  If this clause is not specified, it is the programmer's responsibility to populate @var{record-name-1} with the desired data prior to executing the @code{RELEASE}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.34 RESET TRACE                                             **
@comment *********************************************************************
@page
@newsubsection{7.8.34,RESET TRACE}
@diagram{RESET TRACE,PD-RESET-TRACE,PD-RESET-TRACE,None}
The @statement{RESET TRACE} turns procedure or procedure-and-statement tracing off.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
By default, procedure and procedure-and-statement tracing is off as programs begin execution.  The @statementref{READY TRACE} can be used to turn tracing on.

@item
In order for this statement to be functional, tracing code must have been generated into the compiled program using either the
@switchidx{-ftrace} (procedures only) or
@switchidx{-ftraceall} (procedures and statements).

@item
The
@envvarruntimeref{COB_SET_TRACE} provides another way to control tracing.  If this environment variable is set to a value of @samp{Y} prior to the start of program execution, tracing started at the point the program begins execution, as if @code{READY TRACE} were the first executed statement.  The @code{RESET TRACE} statement, if executed, will then turn off tracing.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.35 RETURN                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.35,RETURN}
@diagram{RETURN,PD-RETURN,PD-RETURN,None}
The @statement{RETURN} reads a record from a sort or merge work file.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{AT} and @code{RECORD} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
The @statement{RETURN} is valid only within the @code{OUTPUT PROCEDURE} of a file-based @syntaxrefalt{SORT,File-Based SORT} or a @statementref{MERGE} statement.

@item
The @var{sort-file-name-1} file must be a sort- or merge work file defined with a @syntaxrefalt{SD,File/Sort-Description}, not an @code{FD}.

@item
A successful @code{RETURN} will retrieve the next available record from @var{sort-file-name-1}.  The newly-retrieved record data will be saved into the 01-level record structure(s) that immediately follow the file's SD.  If the optional
@syntaxidx{INTO} clause is present, a copy of the just-retrieved record will be automatically moved to @var{identifier-1}.

@item
The mandatory @code{AT END} clause is used to detect and react to the failure of an attempt to retrieve another record from the file due to an end-of-file (i.e. no more records) condition.

@item
The optional @code{NOT AT END} clause, if coded, will check checking for a file status value of 00.  @xref{File Status Codes}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.36 REWRITE                                                 **
@comment *********************************************************************
@page
@newsubsection{7.8.36,REWRITE}
@diagram{REWRITE,PD-REWRITE,PD-REWRITE,None}
The @statement{REWRITE} replaces a logical record on a disk file.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{KEY} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
The @var{record-name-1} specified on the statement must be defined as an 01-level record subordinate to the File Description (@syntaxrefalt{FD,File/Sort-Description}) of a file that is currently open for @syntaxrefalt{I-O,File OPEN Modes}.

@item
The optional
@syntaxidx{FROM} clause will cause @var{literal-1} or @var{identifier-1} to be automatically moved into @var{record-name-1} prior to writing @var{record-name-1}'s contents to the @var{file-name-1}.  If this clause is not specified, it is the programmer's responsibility to populate @var{record-name-1} with the desired data prior to executing the @code{REWRITE}.

@item
This statement may not be used with @syntaxref{ORGANIZATION LINE SEQUENTIAL} files.

@item
Rewriting a record does not cause the contents of the file to be physically updated until the next block of the file is read, a @syntaxref{COMMIT} or @statementref{UNLOCK} is issued or that file is closed.

@item
If the file has @syntaxref{ORGANIZATION SEQUENTIAL}:
@enumerate A
@item
The record to be rewritten will be the one retrieved by the most-recently executed @syntaxref{READ} of the file.

@item
If the @code{FD} of the file contains the @code{RECORD CONTAINS} or @code{RECORD IS VARYING} clause, and that clause allows the record size to vary, the size of @var{record-name-1} cannot be altered.
@end enumerate

@item
If the file has @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED}:
@enumerate A
@item
If the file has @code{ACCESS MODE SEQUENTIAL}, the record to be rewritten will be the one retrieved by the most-recently executed @code{READ} of the file.  If the file has @code{ACCESS MODE RANDOM} or @code{ACCESS MODE DYNAMIC}, no @code{READ} is required before a record may be rewritten --- the @code{RELATIVE KEY} or @code{RECORD KEY} definition for the file, respectively, will specify the record to be updated.

@item
If the @code{FD} of the file contains the @code{RECORD CONTAINS} or @code{RECORD IS VARYING} clause, and that clause allows the record size to vary, the size @i{can} be altered.
@end enumerate

@item
The optional @code{LOCK} options may be used to manually control access to the re-written record by other programs while this program is running.  @xref{Record Locking}, to review the various record locking behaviours.

@item
The optional @code{INVALID KEY} and @code{NOT INVALID KEY} clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively.  @xref{File Status Codes}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.37 ROLLBACK                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.37,ROLLBACK}
@diagram{ROLLBACK,PD-ROLLBACK,PD-ROLLBACK,None}
The @statement{ROLLBACK} has the same effect as if an @statementref{UNLOCK} were executed against every open file in the program.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
All locks currently being held for all open files will be released.

@item
@xref{Record Locking}, to review the various record locking behaviours.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.38 SEARCH                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.38,SEARCH}
@diagram{SEARCH,PD-SEARCH,PD-SEARCH,None}
The @statement{SEARCH} is used to sequentially search a table, stopping either once a specific value is located within the table or when the table has been completely searched.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{AT} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
The searching process will be controlled through a
@define{Search Index} --- a data item with a @syntaxref{USAGE} of @code{INDEX}.  The search index is either the @var{index-name-1} identifier specified on the
@syntaxidx{VARYING} clause or --- if no @code{VARYING} is specified --- the @code{USAGE INDEX} data item implicitly created by an @syntaxrefalt{INDEXED BY,OCCURS} clause in the table's definition.

@item
At the time the @code{SEARCH} statement is executed, the current value of the search index data item will define the starting position in the table where the searching process will begin.  Typically, one initializes that index to a value of 1 before starting the @code{SEARCH} via @code{SET @var{search-index} TO 1}.

@item
Each of the @var{conditional-expression-n}s on the @code{WHEN} clause(s) should involve a data element within the table, subscripted using the search index.

@item
The searching process is as follows:
@enumerate A
@item
Each @var{conditional-expression-n} will be evaluated, in turn, until either one evaluates to a value of @code{TRUE} or all have evaluated to @code{FALSE}.

@item
The @var{imperative-statement-n} (@pxref{Imperative Statement}) specified on the @code{WHEN} clause whose @var{conditional-expression-n} evaluated to @code{TRUE} will be executed; after that, the search will be considered complete and control will fall into the first executable statement following the @code{SEARCH}.

@item
If all @var{conditional-expression-n}s evaluated to FALSE:
@itemize @bullet
@item
The search index will be incremented by 1

@item
If the search index now has a value greater than the number of entries in the table, the search is considered to have failed and the @var{imperative-statement-1} on the optional
@syntaxidx{AT END} clause, if any, will be executed.  After that, control will fall into the first executable statement following the @code{SEARCH}.

@item
If the search index now has a value less than or equal to the number of entries in the table, search processing returns back to step A.
@end itemize
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.39 SEARCH ALL                                              **
@comment *********************************************************************
@page
@newsubsection{7.8.39,SEARCH ALL}
@diagram{SEARCH ALL,PD-SEARCH-ALL,PD-SEARCH-ALL,None}
The @statement{SEARCH ALL} performs a binary, or half-interval, search against a sorted table.  This is generally @i{significantly} faster than performing a sequential @code{SEARCH} of a table, especially if the table contains a large number of entries.
@enumerate
@comment Syntactical Specifications:

@item
The reserved word @code{AT} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
To be eligible for searching via @code{SEARCH ALL}:
@enumerate A
@item
The @code{OCCURS} clause of @var{table-name-1} must contain the following elements:
@itemize @bullet
@item
An
@syntaxidx{INDEXED BY} entry to define an implicit search index data item with a @syntaxref{USAGE} of @code{INDEX}.

@item
An
@syntaxidx{ASCENDING KEY} or
@syntaxidx{DESCENDING KEY} clause to specify the field within the table by which all entries in the table are sorted.
@end itemize

@item
Just because the table has one or more @code{KEY} clauses doesn't mean the data is actually @i{in} that sequence in the table --- the actual sequence of the data @i{must} agree with the KEY clause(s)!  A table-based @syntaxrefalt{SORT,Table SORT} can prove very useful in this regard.

@item
No two records in the table may have the same @code{KEY} field values.  If the table has multiple @code{KEY} definitions, then no two records in the table may have the same @i{combination} of @code{KEY} field values.
@end enumerate

@item
If rule @i{A} is violated, the compiler will reject the @code{SEARCH ALL}.  If rules @i{B} and/or @i{C} are violated, there will be no message issued by the compiler, but the run-time results of a @code{SEARCH ALL} against the table will probably be incorrect.

@item
The @var{conditional-expression-1} should involve the @code{KEY} field(s), using the search index (the table's @code{INDEXED BY} index name) as a subscript.

@item
The function of the single, mandatory,
@syntaxidx{WHEN} clause is to compare the key field(s) of the table, as indexed by the search index data item, against whatever literal and/or identifier values you are comparing the key field(s) to in the @var{conditional-expression-1} in order to locate the desired entry in the table.  The search index will be automatically varied in a manner designed to require the minimum number of tests.

@item
The internal processing of the SEARCH ALL statement begins by setting internal ``first'' and ``last'' pointers to the 1@sup{st} and last entry locations of the table.  Processing then proceeds as follows:
@enumerate A
@item
The entry half-way between ``first'' and ``last'' is identified.  We'll call this the ``current'' entry, and will set its table entry location into @var{index-name-1}.

@item
The @var{conditional-expression-1} is evaluated.  This comparison of the key(s) against the target literal/identifier values will have one of three possible outcomes:
@itemize @bullet
@item
If the key(s) and value(s) match, @var{imperative-statement-2} (@pxref{Imperative Statement}) is executed, after which control falls through into the next statement following the @code{SEARCH ALL}.

@item
If the key(s) are LESS THAN the value(s), then the table entry being searched for can only occur in the ``current'' to ``last'' range of the table, so a new ``first'' pointer value is set (it will be set to the ``current'' pointer).

@item
If the key(s) are GREATER THAN the value(s), then the table entry being searched for can only occur in the ``first'' to ``current'' range of the table, so a new ``last'' pointer value is set (it will be set to the ``current'' pointer).
@end itemize

@item
If the new ``first'' and ``last'' pointers are different than the old ``first'' and ``last'' pointers, there's more left to be searched, so return to step @i{A} and continue.

@item
If the new ``first'' and ``last'' pointers are the same as the old ``first'' and ``last'' pointers, the table has been exhausted and the entry being searched for cannot be found; @var{imperative-statement-1} is executed, after which control falls through into the next statement following the @code{SEARCH ALL}.  If there is no @code{AT END} clause coded, control simply falls into the next statement following the @code{SEARCH ALL}.
@end enumerate

@item
The net effect of the above algorithm is that only a fraction of the number of elements in the table need ever be tested in order to decide whether or not a particular entry exists.  This is because the half the remaining entries in the table are discarded each time an entry is checked.

@item
Computer scientists will compare the two techniques implemented by the @code{SEARCH} and @statement{SEARCH ALL}s as follows:

@item
When searching a table with @i{N} entries, a sequential search will need an average of @i{N/2} tests and a worst case of @i{N} tests in order to find an entry and @i{N} tests to identify that an entry doesn't exist.

@item
When searching a table with @i{N} entries,  a binary search will need a worst-case of log2(@i{N}) tests in order to find an entry and log2(@i{N}) tests to identify that an entry doesn't exist (@i{N} = the number of entries in the table), where @i{log2} is the base-2 logarithm function.
@end enumerate

Here's a more practical view of the difference.  Let's say that a table has 1,000 entries in it.  With a sequential search, on average, you'll have to check 500 of them to find an entry and you'll have to look at all 1,000 of them to find that an entry doesn't exist.

With a binary search, express the number of entries as a binary number (1,000 = 1111101000), count the number of digits in the result (which is, essentially, what a logarithm is, when rounded up to the next integer --- the number of digits a decimal number would have if expressed in the logarithm's number base).  In this case, we end up with 10 --- @i{that} is the worst-case number of tests required to find an entry or to identify that it doesn't exist.  That's quite an improvement!
@comment *********************************************************************
@comment ** 7.8.40 SET                                                      **
@comment *********************************************************************
@page
@newsubsection{7.8.40,SET}
@menu
* 7.8.40.1: SET ENVIRONMENT
* 7.8.40.2: SET Program-Pointer
* 7.8.40.3: SET ADDRESS
* 7.8.40.4: SET Index
* 7.8.40.5: SET UP/DOWN
* 7.8.40.6: SET Condition Name
* 7.8.40.7: SET Switch
* 7.8.40.8: SET ATTRIBUTE
* 7.8.40.9: SET LAST EXCEPTION
@end menu
@comment *********************************************************************
@comment ** 7.8.40.1 SET ENVIRONMENT                                        **
@comment *********************************************************************
@newunit{7.8.40.1,SET ENVIRONMENT}
@diagram{SET ENVIRONMENT,PD-SET-1,PD-SET-1,None}
The @statement{SET ENVIRONMENT} provides a straight-forward means of setting environment values from within a program.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The value of @var{literal-1} or @var{identifier-1} specifies the name of the environment variable to set.

@item
The value of @var{literal-2} or @var{identifier-2} specifies the value to be assigned to the environment variable.

@item
Environment variables created or changed from within GnuCOBOL programs will be available to any sub-shell processes spawned by that program (i.e. @code{CALL "SYSTEM"}) but will not be known to the shell or console window that started the GnuCOBOL program.
@end enumerate

This is a much simpler and more readable means of setting environment variables than by using the @statementref{DISPLAY UPON ENVIRONMENT-NAME}.  For example, these two code sequences produce identical results:

@example
DISPLAY "VARNAME" UPON ENVIRONMENT-NAME
DISPLAY "VALUE" UPON ENVIRONMENT-VALUE

SET ENVIRONMENT "VARNAME" TO "VALUE"
@end example
@comment *********************************************************************
@comment ** 7.8.40.2 SET Program-Pointer                                    **
@comment *********************************************************************
@page
@newunit{7.8.40.2,SET Program-Pointer}
@diagram{SET Program-Pointer,PD-SET-2,PD-SET-2,None}
The @statement{SET @var{Program-Pointer}} allows you to retrieve the address of a procedure division code module --- specifically the @code{PROGRAM-ID}, @code{FUNCTION-ID} or an entry-point established via the @statementref{ENTRY}.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The @syntaxref{USAGE} of @var{program-pointer-1} must be @code{PROGRAM-POINTER}.

@item
The @var{literal-1} or @var{identifier-1} value specified must name a primary entry-point name (@code{PROGRAM-ID} of a subroutine or @code{FUNCTION-ID} of a user-defined function) or an alternate entry-point defined via an @code{ENTRY} statement within a subprogram.

@item
Once the address of a procedure division code area has been acquired in this way, the address could be passed to a subroutine (usually written in C) for whatever use it needs it for.  For examples of @code{PROGRAM-POINTER}s at work, see the discussions of the @subpgmref{CBL_ERROR_PROC} and @subpgmref{CBL_EXIT_PROC}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.3 SET ADDRESS                                            **
@comment *********************************************************************
@page
@newunit{7.8.40.3,SET ADDRESS}
@diagram{SET ADDRESS,PD-SET-3,PD-SET-3,None}
The @statement{SET ADDRESS} can be used to work with the addresses of data items rather than their contents.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
When the
@syntaxidx{ADDRESS OF} clause is used @i{before} the @code{TO} you will be using this statement to alter the address of a linkage section or @syntaxref{BASED} data item.  Without that clause you will be assigning an address to one or more data items whose @syntaxref{USAGE} is @code{POINTER}.

@item
When the @code{ADDRESS OF} clause is used @i{after} the @code{TO}, this statement will be identifying the address of @var{identifier-2} as the address to be assigned to @var{identifier-1} or stored in @var{pointer-name-1}.

@item
If the @code{ADDRESS OF} clause is absent after the @code{TO}, the contents of @var{pointer-name-2} will serve as the address to be assigned.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.4 SET Index                                              **
@comment *********************************************************************
@page
@newunit{7.8.40.4,SET Index}
@diagram{SET Index,PD-SET-4,PD-SET-4,None}
This statement assigns a value to a @code{USAGE INDEX} data item.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
Either the @syntaxref{USAGE} of @var{index-name-1} should be @code{INDEX}, or @var{index-name-1} must be identified in a table @code{INDEXED BY} clause.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.5 SET UP/DOWN                                            **
@comment *********************************************************************
@page
@newunit{7.8.40.5,SET UP/DOWN}
@diagram{SET UP/DOWN,PD-SET-5,PD-SET-5,None}
Use this statement to increment or decrement the value of an index or pointer by a specified amount.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The @syntaxref{USAGE} of @var{identifier-1} must be @code{INDEX}, @code{POINTER} or @code{PROGRAM-POINTER}.

@item
The typical usage when @var{identifier-1} is a @code{USAGE INDEX} data item is to increment its value @code{UP} or @code{DOWN} by 1, since an index is usually being used to sequentially walk through the elements of a table.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.6 SET Condition Name                                     **
@comment *********************************************************************
@page
@newunit{7.8.40.6,SET Condition Name}
@diagram{SET Condition Name,PD-SET-6-Info,PD-SET-6-TeX,None}
The @statement{SET @var{Condition Name}} provides one method of specifying the @code{TRUE} / @code{FALSE} value of a level-88 condition name.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
By setting the specified @var{condition-name-1}(s) to a @code{TRUE} or @code{FALSE} value, you will actually be assigning a value to the parent data item(s) to which the condition name data item(s) is(are) subordinate to.

@item
When specifying @code{TRUE}, the value assigned to each parent data item will be the first value specified on the condition name's @code{VALUE} clause.

@item
When specifying @code{FALSE}, the value assigned to each parent data item will be the value specified for the @code{FALSE} clause of the condition name's definition; if any @var{condition-name-1} occurrence lacks a @code{FALSE} clause, the @code{SET} statement will be rejected by the compiler.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.7 SET Switch                                             **
@comment *********************************************************************
@page
@newunit{7.8.40.7,SET Switch}
@diagram{SET Switch,PD-SET-7-Info,PD-SET-7-TeX,None}
This form of the @statement{SET} is used to turn switches on or off.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
Switches are defined using the @syntaxref{SPECIAL-NAMES} paragraph.

@item
Switches may be tested via the @statementref{IF} and a Switch-Status Condition.  @xref{Switch-Status Conditions}, for more information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.8 SET ATTRIBUTE                                          **
@comment *********************************************************************
@page
@newunit{7.8.40.8,SET ATTRIBUTE}
@diagram{SET ATTRIBUTE,PD-SET-8,PD-SET-8,None}
The @statement{SET ATTRIBUTE} may be used to modify one or more attributes of a screen section data item at run-time.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
When making an attribute change to @var{identifier-1}, the change will not become visible on the screen until the screen section data item containing @var{identifier-1} is next accepted (if @var{identifier-1} is an input field) or is next displayed (if @var{identifier-1} is not an input field).

@item
The attributes shown in the syntax diagram are the only ones that may be altered by this statement.  @xref{Data Description Clauses}, for information on their usage.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.40.9 SET LAST EXCEPTION                                     **
@comment *********************************************************************
@page
@newunit{7.8.40.9,SET LAST EXCEPTION}
@diagram{SET ATTRIBUTE,PD-SET-9,PD-SET-9,None}
The @statement{SET LAST EXCEPTION} will set the last program exception status to indicate no exception.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:

@item
The predefined object reference EXCEPTION-OBJECT is set to null, and the last exception status is set to indicate no exception.

@item
This action resets the global exception object completely (FUNCTION EXCEPTION-@{FILE, LOCATION, STATEMENT, STATUS @} ), and will not show anything afterwards), no matter what the last exception was (such as a divide by zero). Use with care.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.41 SORT                                                     **
@comment *********************************************************************
@page
@newsubsection{7.8.41,SORT}
@menu
* 7.8.41.1: File-Based SORT
* 7.8.41.2: Table SORT
@end menu
@comment *********************************************************************
@comment ** 7.8.41.1 File-Based SORT                                        **
@comment *********************************************************************
@newunit{7.8.41.1,File-Based SORT}
@diagram{File-Based SORT,PD-SORT-1-Info,PD-SORT-1-TeX,PD-DUPLICATES}
This format of the @statement{SORT} is designed to sort large volumes of data according to one or more key fields.
@enumerate
@comment Syntactical Specifications:

@item
The reserved words @code{IN}, @code{IS}, @code{KEY}, @code{ON}, @code{ORDER}, @code{SEQUENCE} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{THRU} and @code{THROUGH} are interchangeable.

@item
GnuCOBOL always behaves as if the @code{WITH DUPLICATES IN ORDER} clause is specified, even if it isn't.

While any COBOL implementation's sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.

Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
@comment Semantic Specifications:

@item
The @var{sort-file-1} named on the @statement{SORT} must be defined using a sort description (@syntaxrefalt{SD,File/Sort-Description}).  This file is referred to in the remainder of this discussion as the @i{sort work file}.

@item
If specified, @var{file-name-1} and @var{file-name-2} must reference @syntaxref{ORGANIZATION LINE SEQUENTIAL} or @syntaxref{ORGANIZATION SEQUENTIAL} files.  These files must be defined using a file description (@syntaxrefalt{FD,File/Sort-Description}).  The same file(s) may be used for @var{file-name-1} and @var{file-name-2}.

@item
The @var{identifier-1} @dots{} field(s) must be defined as field(s) within a record of @var{sort-file-1}.

@item
A sort work file is never opened or closed.

@item
The sorting process works in three stages --- the Input Stage, the Sort Stage and the Output Stage.

@item
The following points pertain to the Input Stage:
@enumerate A
@item
The data to be sorted is loaded into the sort work file either by copying the entire contents of the file(s) named on the @code{USING} clause (done automatically by the sort) or by utilizing an input procedure.

@item
When
@syntaxidx{USING} is specified, none of the @var{file-name-1} files may be open at the time the @statement{SORT} is executed.

@item
When an input procedure is used, the procedure(s) specified on the
@syntaxidx{INPUT PROCEDURE} clause will be invoked as if by a procedural @statementrefalt{PERFORM,Procedural PERFORM} with no @code{VARYING}, @code{TIMES} or @code{UNTIL} options specified.  Records will be loaded into the sort work file --- one at a time --- within the input procedure using the @statementref{RELEASE}.  This, by the way, is how you could sort the contents of relative or indexed files.

A @statementref{GO TO} that transfers control out of the input procedure will terminate the @statement{SORT} but allows the program to continue executing from the point where the @statement{GO TO} transferred control to.  Once an input procedure has been ``aborted'' using a @code{GO TO} it cannot be resumed, and the contents of the sort work file are lost.  You may, however, re-execute the @statement{SORT} itself.@footnote{Using a @statement{GO TO} to prematurely terminate a sort, or re-starting a previously-cancelled sort is not considered good programming style and should be avoided.}

An input procedure should be terminated in the same way a procedural @statement{PERFORM} would be.

Neither a another file-based @statement{SORT} nor a @statement{MERGE} may be executed within the input procedure unless those statements utilize a different sort or merge work file.

@item
Once the input procedure terminates, the input phase is complete.

@item
As data is loaded into the sort work file, it is actually being buffered in dynamically-allocated memory.  Only if the amount of data to be sorted exceeds the amount of available sort memory (128 MB) will actual disk files be allocated and utilized.  There is a
@envvarruntimeref{COB_SORT_MEMORY} that you may use to allocate more or less memory to the sorting process.
@end enumerate

@item
The following points pertain to the Sort Stage:
@enumerate A
@item
The sort will take place by arranging the data records in the sequence defined by the @code{KEY} specification(s) on the @statement{SORT} according to the @code{COLLATING SEQUENCE} specified on the @code{SORT} (if any) or --- if none was defined --- the @syntaxrefalt{PROGRAM COLLATING SEQUENCE,OBJECT-COMPUTER}.  Keys may be any supported data type and @syntaxref{USAGE} except for level-78 or level-88 data items.

@item
For example, let's assume we're sorting a series of financial transactions.  The SORT statement might look like this:

@example
SORT Sort-File
    ASCENDING  KEY Transaction-Date
    ASCENDING  KEY Account-Number
    DESCENDING KEY Transaction-Amount
@end example

The effect of this statement will be to sort all transactions into ascending order of the date the transaction took place (oldest first, newest last).  Unless the business running this program is going out of business, there are most-likely many transactions for any given date.  Therefore, within each grouping of transactions all with the same date, transactions will be sub-sorted into ascending sequence of the account number the transactions apply to.  Since it's quite possible there might be multiple transactions for an account on any given date, a third level sub-sort will arrange all transactions for the same account on the same date into descending sequence of the actual amount of the transaction (largest first, smallest last).  If two or more transactions of $100.00 were recorded for account #12345 on the 31@sup{st} of August 2009, those transactions will be retained in the order in which they were loaded into the sort work file.

@item
 Should disk work files be necessary due to the amount of data being sorted, they will be automatically allocated to disk in a folder defined by the
@envvarruntime{TMPDIR},
@envvarruntime{TMP} or
@envvarruntimerefs{TEMP} (checked for existence in that sequence).  These disk files will be automatically purged upon @code{SORT} termination or program execution termination (normal or otherwise).
@end enumerate

@item
The following points pertain to the Output Stage:
@enumerate A
@item
Once the sort stage is complete, a copy of the sorted data will be written to each @var{file-name-2} if the
@syntaxidx{GIVING} clause was specified.  None of the @var{file-name-2} files can be open at the time the sort is executed.

@item
When an output procedure is used, the procedure(s) specified on the
@syntaxidx{OUTPUT PROCEDURE} clause will be invoked as if by a procedural @statementrefalt{PERFORM,Procedural PERFORM} with no @code{VARYING}, @code{TIMES} or @code{UNTIL} options specified.  Records will be retrieved from the sort work file --- one at a time --- within the output procedure using the @statementref{RETURN}.

A @statementref{GO TO} that transfers control out of the output procedure will terminate the @statement{SORT} but allows the program to continue executing from the point where the @statement{GO TO} transferred control to.  Once an output procedure has been ``aborted'' using a @code{GO TO} it cannot be resumed, and the contents of the sort work file are lost.  You may, however, re-execute the @statement{SORT} itself.  USING A @statement{GO TO}@footnote{To prematurely terminate a sort, or re-starting a previously-cancelled sort is not considered good programming style and should be avoided.}

An output procedure should be terminated in the same way a procedural @statement{PERFORM} would be.

Neither a another file-based @statement{SORT} nor a @statement{MERGE} may be executed within the output procedure unless those statements utilize a different sort or merge work file.

@item
Once the output procedure terminates, the sort is complete.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.41.2 Table SORT                                            **
@comment *********************************************************************
@page
@newunit{7.8.41.2,Table SORT}
@diagram{Table SORT,PD-SORT-2,PD-SORT-2,PD-DUPLICATES}
This format of the @statement{SORT} sorts relatively small quantities of data --- namely data contained in a data division table --- according to one or more key fields.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IN}, @code{IS}, @code{KEY}, @code{ON}, @code{ORDER}, @code{SEQUENCE} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
GnuCOBOL always behaves as if the @code{WITH DUPLICATES IN ORDER} clause is specified, even if it isn't.

While any COBOL implementation's sort or merge facilities guarantee that records with duplicate key values will be in proper sequence with regard to other records with different key values, they generally make no promises as to the resulting relative sequence of records having duplicate key values with one another.

Some COBOL implementations provide this optional clause to force their sort and merge facilities to retain duplicate key-value records in their original input sequence, relative to one another.
@comment Semantic Specifications:

@item
The @var{table-name-1} data item must be a table defined in any data division section @i{except} the report or screen sections.

@item
The data within @var{table-name-1} will be sorted in-place (i.e. no sort file is required).

@item
The sort will take place by rearranging the data in @var{table-name-1} into the sequence defined by the @code{KEY} specification(s) on the @statement{SORT}, according to the @code{COLLATING SEQUENCE} specified on the @code{SORT} (if any) or --- if none was defined --- the @syntaxrefalt{PROGRAM COLLATING SEQUENCE,OBJECT-COMPUTER}.  Keys may be any supported data type and @syntaxref{USAGE} except for level-78 or level-88 data items.

@item
If you are sorting @var{table-name-1} for the purpose of preparing the table for use with a @statementref{SEARCH ALL}, care must be taken that the @code{KEY} specifications on the @code{SORT} agree with those in the table's definition.

@item
Although the specification of one or more @code{KEY} clauses is optional, currently, a table sort with no @code{KEY} specification(s) made on the @statement{SORT} is unsupported by GnuCOBOL and will be rejected by the compiler.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.42 START                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.42,START}
@diagram{START,PD-START,PD-START,None}
The @statement{START} defines the logical starting point within a relative or indexed file for subsequent sequential read operations.  It positions an internal logical record pointer to a particular record in the file, but does not actually transfer any of that record's data into the record buffer.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS}, @code{THAN} and @code{TO} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
To use this statement, @var{file-name-1} must be an @syntaxref{ORGANIZATION RELATIVE} or @syntaxref{ORGANIZATION INDEXED} file that must have been defined with an @code{ACCESS MODE DYNAMIC} or @code{ACCESS MODE SEQUENTIAL} in its @statementref{SELECT}.

@item
At the time this statement is executed, @var{file-name-1} must be open in either @code{INPUT} or @syntaxrefalt{I-O,File OPEN Modes} mode.

@item
If @var{file-name-1} is a relative file, @var{identifier-1} must be the defined @code{RELATIVE KEY} of the file.

@item
If @var{file-name-1} is an indexed file, @var{identifier-1} must be the defined @code{RECORD KEY} of the file or any of the @code{ALTERNATE RECORD KEY} fields for the file.

@item
If no @code{FIRST}, @code{LAST} or @code{KEY} clause is specified, @code{KEY IS EQUAL TO @var{xxx}} will be assumed, where @code{@var{xxx}} is the defined @code{RELATIVE KEY} of (if @var{file-name-1} is a relative file) or the defined @code{RECORD KEY} (if @var{file-name-1} is an indexed file).

@item
After successful execution of a @statement{START}, the internal logical record pointer into the @var{file-name-1} data will be positioned to the record which satisfied the actual or implied @code{FIRST}, @code{LAST} or @code{KEY} clause specification, as follows:
@table @code
@item FIRST
the logical record pointer will point to the first record in the file.

@item LAST
the logical record pointer will point to the last record in the file.

@item KEY
(specified or implied), and the relation used is. Warning: Later versions of the compiler may well not use implied, so always specify it and it makes the code easier to read any way.

@item SIZE
WITH @code{SIZE} or @code{LENGTH} arithmetic-expression specifies the number of characters in the key to be used in the positioning process.

@item LENGTH
WITH @code{LENGTH} or @code{SIZE} arithmetic-expression specifies the number of characters in the key to be used in the positioning process.

@code{SIZE} and @code{LENGTH} are interchangeable and mean exactly the same.


@table @asis
@item @code{EQUAL TO}, @code{GREATER THAN} or @code{GREATER THAN OR EQUAL TO} (or equivalent)
the logical record pointer will be specified to the @i{first} record satisfying the relation condition; to identify this record. The file's contents are searched in a first-to-last (in sequence of the key implied by the @code{KEY} clause), provided the relation is
@item @code{LESS THAN}, @code{LESS THAN OR EQUAL TO} or @code{NOT GREATER THAN} (or equivalent)
the logical record pointer will be specified to the @i{last} record satisfying the relation condition; to identify this record. The file's contents are searched in a last-to-first (in sequence of the key implied by the @code{KEY} clause)
@end table
@end table


The next sequential @statement{READ} will read the record that is pointed to by the logical record pointer.

@item
The optional @code{INVALID KEY} and @code{NOT INVALID KEY} clauses may be used to detect and react to the failure or success, respectively, by detecting non-zero (typically 23 = key not found = record not found) and 00 file status codes, respectively.  @xref{File Status Codes}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.43 STOP                                                    **
@comment *********************************************************************
@page
@newsubsection{7.8.43,STOP}
@diagram{STOP,PD-STOP,PD-STOP,None}
The @statement{STOP} suspends program execution.  Some options will allow program execution to resume while others return control to the operating system.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{STATUS} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words
@syntaxidx{RETURNING} and
@syntaxidx{GIVING} are interchangeable.
@comment Semantic Specifications:

@item
The
@syntaxidx{RUN} clause halts the program without displaying any special message to that effect.

@item
The @var{literal-3} clause displays the specified text on the @code{SYSOUT}/@code{STDOUT} device, waits for the user to press the Enter key and then --- once the key has been pressed --- allows the program to continue execution.

@item
The optional @code{RETURNING} clause provides the opportunity to return a numeric value to the operating system (an @dfn{exit status}).  The manner in which the exit status may be interrogated by the operating system varies, but Windows can use @code{%ERRORLEVEL%} to query the exit status while Unix shells such as sh, bash and ksh can query the exit status as @code{$?}.  Other Unix shells may have different ways to access return code values.

@item
The
@syntaxidx{STATUS} clause provides another means of returning an exit status.  Using the @code{STATUS} clause is functionally equivalent to using the @code{RETURNING} clause.

@item
Using the @code{STATUS} clause without a @var{literal-2} or @var{identifier-2} will return an exit status of 0 if the
@syntaxidx{NORMAL} keyword is used or a 1 if
@syntaxidx{ERROR} was specified.

@item
Your program will @i{always} return an exit status, even if no @code{RETURNING} or @code{STATUS} clause is specified.  In the absence of the use of these clauses, the value in the
@registerrefalt{RETURN-CODE,Special Registers} at the time the
@statement{STOP} is executed will be used as the exit status.

@item
Any programmer-defined exit procedure (established via the @subpgmref{CBL_EXIT_PROC}) will be executed by @code{STOP RUN}, but not by @code{STOP @var{literal-3}}.

@item
Valid return code values can be in the range -2147483648 to +2147483647.

@item
The three code snippets below are all equivalent.  They show different ways in which a GnuCOBOL program may be coded to pass an exit status value of 16 back to the operating system and then halt.

@enumerate
@item
@example
STOP RUN RETURNING 16
@end example

@item
@example
MOVE 16 TO RETURN-CODE
STOP RUN
@end example

@item
@example
STOP RUN WITH ERROR STATUS 16
@end example
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.44 STRING                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.44,STRING}
@diagram{STRING,PD-STRING,PD-STRING,None}
The @statement{STRING} is used to concatenate all or a part of one or more strings together, forming a new string.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{BY}, @code{ON} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
All literals and identifiers (except for @var{identifier-4}) must be explicitly or implicitly defined with a @syntaxref{USAGE} of @code{DISPLAY}.   Any of the identifiers may be group items.

@item
The
@syntaxidx{POINTER} data item --- @var{identifier-4} --- must be a non-edited elementary integer numeric data item with a value greater than zero.

@item
Each @var{literal-1} / @var{identifier-1} will be referred to as a source item.  The receiving data item is @var{identifier-3}.

@item
The @statement{STRING}'s processing is based upon a
@define{current character pointer}.  The initial value of the current character pointer will be the value of @var{identifier-4} at the time the @code{STRING} statement began execution.  If no @code{POINTER} clause is coded, a value of 1 (meaning ``the 1@sup{st} character position'') will be assumed for the current character pointer's initial value.

@item
For each source item, the contents of the sending item will be copied --- character-by-character --- into @var{identifier-3} at the character position specified by the current character pointer.  After each character is copied, the current character pointer will be incremented by 1 so that it points to the position within @var{identifier-3} where the @i{next} character should be copied.

@item
The
@syntaxidx{DELIMITED BY} clause specifies how much of each source item will be copied into @var{identifier-3}.  @code{DELIMITED BY SIZE} (the default if no @code{DELIMITED BY} clause is specified) causes the @i{entire} contents of the source item to be copied into @var{identifier-3}.

@item
Using @code{DELIMITED BY @var{literal-2}} or @code{DELIMITED BY @var{identifier-2}} causes only the contents of the source item up to but not including the character sequence specified by the literal or identifier to be copied.

@item
@code{STRING} processing will cease when one of the following occurs:
@enumerate A
@item
The initial value of the current character pointer is less than 1 or greater than the number of characters in @var{identifier-3}, or@dots{}

@item
The value of the current character pointer exceeds the size of @var{identifier-3} at the point the STRING statement wants to copy a character into @var{identifier-3}, or@dots{}

@item
All sending items have been fully processed
@end enumerate

@item
If event @i{A} occurs, @var{identifier-3} will remain unchanged.

@item
The occurrence of either event @i{A} or @i{B} triggers what is referred to as an
@define{overflow condition}.

@item
The @var{identifier-3}) is neither automatically initialized (to spaces or any other value) at the start of a @code{STRING} statement nor will it be space-filled should the total number of sending item characters copied into it be less than its size.  You may explicitly initialize @var{identifier-3} yourself via the @syntaxref{INITIALIZE} or @syntaxref{MOVE} statements before executing the @code{STRING} if you wish.

@item
The optional @code{ON OVERFLOW} and @code{NOT ON OVERFLOW} clauses may be used to detect and react to the occurrence or not, respectively, of an overflow condition.  @xref{ON OVERFLOW + NOT ON OVERFLOW}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.45 SUBTRACT                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.45,SUBTRACT}
@menu
* 7.8.45.1: SUBTRACT FROM
* 7.8.45.2: SUBTRACT GIVING
* 7.8.45.3: SUBTRACT CORRESPONDING
@end menu
@comment *********************************************************************
@comment ** 7.8.45.1 SUBTRACT FROM                                         **
@comment *********************************************************************
@newunit{7.8.45.1,SUBTRACT FROM}
@diagram{SUBTRACT FROM,PD-SUBTRACT-1-Info,PD-SUBTRACT-1-TeX,None}
This format of the @statement{SUBTRACT} generates the arithmetic sum of all arguments that appear before the @code{FROM} (@var{identifier-1} or @var{literal-1}) and subtracts that sum from each @var{identifier-2}.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items.

@item
@var{literal-1} must be a numeric literal.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.45.2 SUBTRACT GIVING                                       **
@comment *********************************************************************
@page
@newunit{7.8.45.2,SUBTRACT GIVING}
@diagram{SUBTRACT GIVING,PD-SUBTRACT-2-Info,PD-SUBTRACT-2-TeX,None}
The @statement{SUBTRACT GIVING} generates the arithmetic sum of all arguments that appear before the @code{FROM} (@var{identifier-1} or @var{literal-1}), subtracts that sum from the contents of @var{identifier-2} and then replaces the contents of the identifiers listed after the
@syntaxidx{GIVING} (@var{identifier-3}) with that result.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be numeric unedited data items.

@item
@var{literal-1} must be a numeric literal.

@item
@var{identifier-3} must be a numeric (edited or unedited) data item.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.45.3 SUBTRACT CORRESPONDING                                **
@comment *********************************************************************
@page
@newunit{7.8.45.3,SUBTRACT CORRESPONDING}
@diagram{SUBTRACT CORRESPONDING,PD-SUBTRACT-3,PD-SUBTRACT-3,None}
The @statement{SUBTRACT CORRESPONDING} generates code equivalent to individual @code{SUBTRACT FROM} statements for corresponding matches of data items found subordinate to the two identifiers.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{IS} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
Both @var{identifier-1} and @var{identifier-2} must be group items.

@item
@xref{CORRESPONDING}, for information on how corresponding matches will be found between @var{identifier-1} and @var{identifier-2}.

@item
The optional @syntaxref{ROUNDED} clause available to each @var{identifier-2} will control how non-integer results will be saved.

@item
The optional @code{ON SIZE ERROR} and @code{NOT ON SIZE ERROR} clauses may be used to detect and react to the failure or success, respectively, of an attempt to perform a calculation.  In this case, failure is defined as being an @var{identifier-2} with an insufficient number of digit positions available to the left of any implied decimal point.  @xref{ON SIZE ERROR + NOT ON SIZE ERROR}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.46 SUPPRESS                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.46,SUPPRESS}
@diagram{SUPPRESS,PD-SUPPRESS,PD-SUPPRESS,None}
The @statement{SUPPRESS} causes the presentation of a report group to be suppressed.
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{PRINTING} is optional and may be omitted.  The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:

@item
This statement may only appear within a @code{USE BEFORE REPORTING} procedure (in @syntaxref{DECLARATIVES}).

@item
@code{SUPPRESS} only prevents the presentation of the report group within whose @code{USE BEFORE REPORTING} procedure the statement occurs.

@item
This statement must be executed each time presentation of the report group is to be suppressed.

@item
When a report group's presentation is suppressed, none of the following operations for the report will take place:
@enumerate A
@item
Actual presentation of the report group in question.

@item
Processing of any @syntaxref{LINE} clauses within the report group in question.

@item
Processing of the @syntaxref{NEXT GROUP} clause (if any) within the report group in question.

@item
Any modification to the
@registerrefalt{LINE-COUNTER,Special Registers}.

@item
Any modification to the
@register{PAGE-COUNTER}.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.8.47 TERMINATE                                               **
@comment *********************************************************************
@page
@newsubsection{7.8.47,TERMINATE}
@diagram{TERMINATE,PD-TERMINATE,PD-TERMINATE,None}
The @statement{TERMINATE} causes the processing of the specified report(s) to be completed.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
Each @var{report-name-1} must be the name of a report having an @syntaxrefalt{RD,REPORT SECTION} defined for it.

@item
The specified report name(s) must be currently initiated (via @syntaxref{INITIATE}) and cannot yet have been terminated.

@item
The @statement{TERMINATE} will present each @code{CONTROL FOOTING} (if any), in reverse sequence of the control hierarchy, starting with the most minor up to @code{FINAL} (if any).  During the presentation of these groups and the processing of any @code{USE BEFORE REPORTING} procedures for those groups, the prior set of control data item values will be available, as though a control break had been detected at the most major control data name.

@item
During the presentation of the @code{CONTROL FOOTING} groups, any necessary @code{PAGE FOOTING} and @code{PAGE HEADING} groups will be presented as well.

@item
Finally,the @code{REPORT FOOTING} group, if any, will be presented.

@item
If an @code{INITIATE} is followed by a @code{TERMINATE} with no intervening @syntaxref{GENERATE} statements (all pertaining to the same report, of course), no report groups will be presented to the output file.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.48 TRANSFORM                                               **
@comment *********************************************************************
@page
@newsubsection{7.8.48,TRANSFORM}
@diagram{TRANSFORM,PD-TRANSFORM,PD-TRANSFORM,None}
The @statement{TRANSFORM} scans a data item performing a series of mono-alphabetic substitutions, defined by the arguments before and after the @code{TO} clause.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
Both @var{literal-1} and/or @var{literal-2} must be alphanumeric literals.

@item
All of @var{identifier-1}, @var{identifier-2} and @var{identifier-3} must either be group items or alphanumeric data items.  Numeric data items with a @syntaxref{USAGE} of @code{DISPLAY} are accepted, but will generate warning messages from the compiler.

@item
The @code{TRANSFORM} statement will replace characters within @var{identifier-1} that are found in the string specified @i{before} the @code{TO} keyword with the corresponding characters from the string specified @i{after} the @code{TO} keyword.

@item
Usage of word CHARACTERS has no effect on operations other than for appearance.

@item
This statement exists within GnuCOBOL to provide compatibility with COBOL programs written to pre-1985 standards.  The @statement{TRANSFORM} was made obsolete in the 1985 standard of COBOL, having been replaced by the @code{CONVERTING} clause of the @statementref{INSPECT}.  New programs should be coded to use @code{INSPECT CONVERTING} rather than @code{TRANSFORM}.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.49 UNLOCK                                                  **
@comment *********************************************************************
@page
@newsubsection{7.8.49,UNLOCK}
@diagram{UNLOCK,PD-UNLOCK,PD-UNLOCK,None}
This statement synchronizes any as-yet unwritten file I/O buffers to the specified file (if any) and releases any record locks held for records belonging to @var{file-name-1}.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{RECORD} and @code{RECORDS} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
If @var{file-name-1} is a Sort/Merge work file, no action will be taken.

@item
Not all GnuCOBOL implementations support locking.  Whether they do or not depends upon the operating system they were built for and the build options that were used when GnuCOBOL was generated.  When a program using one of those GnuCOBOL implementations issues an UNLOCK, it will ignored.  There will be no compiler message issued.  Buffer syncing, if needed, will still occur.

@item
For GnuCOBOL UNLOCK is implied in GnuCOBOL on file close so there's no use to do it afterwards. A CLOSE will always trigger syncing the file to disk, too.

@item
Doing UNLOCK before a close, will explicit unlock any records with a lock when running on INDEXED files, for other files it will release any locks on the file if it wasn't opened for exclusive locking and will trigger syncing to disk (not done for any INDEXED file).

@item
When using Linux and for that matter most *nix platforms, the system maintains it's own cache and buffers for file processing so there can and most likely will be a short delay before all data is written out to disk.

@item
@xref{Record Locking}, for additional information on record locking.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.50 UNSTRING                                                **
@comment *********************************************************************
@page
@newsubsection{7.8.50,UNSTRING}
@diagram{UNSTRING,PD-UNSTRING,PD-UNSTRING,None}
The @statement{UNSTRING} parses a string, extracting any number of sub strings from it.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{BY}, @code{IN} and @code{ON} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.
@comment Semantic Specifications:

@item
@var{identifier-1} through @var{identifier-5} must be explicitly or implicitly defined with a @syntaxref{USAGE} of @code{DISPLAY}.   Any of those identifiers may be group items.

@item
Both @var{literal-1} and @var{literal-2} must be alphanumeric literals.

@item
Each of @var{identifier-6}, @var{identifier-7} and @var{identifier-8} must be elementary non-edited integer numeric items.

@item
At the time the @statement{UNSTRING} begins execution, @var{identifier-7} must have a value greater than 0.

@item
@var{identifier-1} will be referred to as the @i{source string} and each @var{identifier-4} will be referred to as a @i{destination field} in the following discussions.

@item
 The @statement{UNSTRING}'s processing is based upon a @i{current character pointer}, the initial value of which will be the value of @var{identifier-7} at the time the @code{UNSTRING} statement began execution.  If no @code{POINTER} clause is coded, a value of 1 (meaning ``the 1@sup{st} character position'') will be assumed for the current character pointer's initial value.

@item
The source string will be parsed into sub strings starting from the current character pointer position.  Sub strings are identified by using the various delimiter strings specified on the
@syntaxidx{DELIMITED BY} clause as inter-sub string separators.

@item
Using the
@syntaxidx{ALL} option allows a delimiter sequence to be an arbitrarily long sequence of occurrences of the delimiter literal whereas its absence treats each occurrence as a separate delimiter.  When multiple delimiters are specified, they will be looked for in the source string in the sequence in which they are coded.

@item
Two consecutive delimiter sequences will identify a null sub string.

@item
Identified sub strings will be moved into each destination field in the sequence they are identified; values moved into a destination field will be truncated if the sub string length exceeds the destination field length, or padded with spaces if the destination field length exceeds the sub string length.  Both truncation and padding will be controlled by the presence or absence of a @syntaxref{JUSTIFIED} clause on the destination field.

@item
Each destination field may have an optional
@syntaxidx{DELIMITER} clause.  If a @code{DELIMITER} clause is specified, @var{identifier-5} will have the delimiter character string used to identify the sub string for the destination field moved into it.  If a destination field was not altered (because an insufficient number of sub strings were identified), @var{identifier-5} for that destination field will also be unchanged.

@item
Each destination field may have an optional
@syntaxidx{COUNT} clause.  If a @code{COUNT} clause is specified, @var{identifier-6} will have the size of the sub string (in characters) for the destination field moved into it.  If a destination field was not altered (because an insufficient number of sub strings were identified), @var{identifier-6} for that destination field will also be unchanged.

@item
If a @code{TALLYING} clause is coded, @var{identifier-8} will be incremented by 1 each time a destination field is populated.

@item
None of @var{identifier-4}, @var{identifier-5}, @var{identifier-6}, @var{identifier-7} or @var{identifier-8} are initialized by the @statement{UNSTRING}.  You need to do that yourself via a @syntaxref{MOVE} or @statementref{INITIALIZE}.

@item
@code{UNSTRING} processing will cease when one of the following occurs:
@enumerate A
@item
The initial value of the current character pointer is less than 1 or greater than the number of character positions in @var{identifier-1}, or@dots{}

@item
All destination fields have been fully processed
@end enumerate

@item
If event @i{A} occurs, none of the destination field contents (or the contents of their @code{DELIMITER} or @var{COUNT} identifiers) will be changed.

@item
An @i{overflow} condition exists if either event @i{A} occurs, or if event @i{B} occurs with at least one character position in @var{identifier-1} not having been processed.

@item
The optional @code{ON OVERFLOW} and @code{NOT ON OVERFLOW} clauses may be used to detect and react to the occurrence or not, respectively, of an overflow condition.  @xref{ON OVERFLOW + NOT ON OVERFLOW}, for additional information.
@end enumerate

The following sample program illustrates the @statement{UNSTRING} statement.

@example
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOUNSTRING.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Full-Name                   PIC X(40).
01  Parsed-Info.
    05 Last-Name                PIC X(15).
    05 First-Name               PIC X(15).
    05 MI                       PIC X(1).
    05 Delim-LN                 PIC X(1).
    05 Delim-FN                 PIC X(1).
    05 Delim-MI                 PIC X(1).
    05 Count-LN                 BINARY-CHAR.
    05 Count-FN                 BINARY-CHAR.
    05 Count-MI                 BINARY-CHAR.
    05 Tallying-Ctr             BINARY-CHAR.
PROCEDURE DIVISION.
P1. PERFORM UNTIL EXIT
      DISPLAY "Enter Full Name (null quits):"
          WITH NO ADVANCING
      ACCEPT Full-Name
      IF Full-Name = SPACES
        EXIT PERFORM
      END-IF
      INITIALIZE Parsed-Info
      UNSTRING Full-Name
        DELIMITED BY ", "
                  OR ","
                  OR ALL SPACES
        INTO Last-Name
                 DELIMITER IN Delim-LN
                 COUNT IN Count-LN
             First-Name
                 DELIMITER IN Delim-FN
                 COUNT IN Count-FN
             MI
                 DELIMITER IN Delim-MI
                 COUNT IN Count-MI
        TALLYING Tallying-Ctr
    DISPLAY "First-Name=" First-Name
            " Delim='"    Delim-FN
            "' Count="    Count-FN
    DISPLAY "MI        =" MI "              "
            " Delim='"    Delim-MI
            "' Count="    Count-MI
    DISPLAY "Last-Name =" Last-Name
            " Delim='"    Delim-LN
            "' Count="    Count-LN
    DISPLAY "Tally=     " Tallying-Ctr
  END-PERFORM
  DISPLAY "Bye!"
  STOP RUN   .
@end example

The following is sample output from the program:

@example
Enter Full Name (null quits):Cutler, Gary L
First-Name=Gary            Delim=' ' Count=+004
MI        =L               Delim=' ' Count=+001
Last-Name =Cutler          Delim=',' Count=+006
Tally=     +003
Enter Full Name (null quits):Snoddgrass,Throckmorton,P
First-Name=Throckmorton    Delim=',' Count=+012
MI        =P               Delim=' ' Count=+001
Last-Name =Snoddgrass      Delim=',' Count=+010
Tally=     +003
Enter Full Name (null quits):Munster   Herman
First-Name=Herman          Delim=' ' Count=+006
MI        =                Delim=' ' Count=+000
Last-Name =Munster         Delim=' ' Count=+007
Tally=     +002
Enter Full Name (null quits):
Bye!
@end example
@comment *********************************************************************
@comment ** 7.8.51 WRITE                                                   **
@comment *********************************************************************
@page
@newsubsection{7.8.51,WRITE}
@diagram{WRITE,PD-WRITE,PD-WRITE,None}
The @statement{WRITE} writes a new record to an open file.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{ADVANCING}, @code{AT}, @code{KEY}, @code{LINE}, @code{LINES} and @code{WITH} are optional and may be omitted.  The presence or absence of these words has no effect upon the program.

@item
The reserved words @code{END-OF-PAGE} and @code{EOP} are interchangeable.
@comment Semantic Specifications:

@item
The @var{record-name-1} specified on the statement must be defined as an 01-level record subordinate to the File Description (@syntaxrefalt{FD,File/Sort-Description}) of a file that is currently open for @syntaxrefalt{OUTPUT,File OPEN Modes}, @code{EXTEND} or @code{I-O}.

@item
The optional
@syntaxidx{FROM} clause will cause @var{literal-1} or @var{identifier-1} to be automatically moved into @var{record-name-1} prior to writing @var{record-name-1}'s contents to the appropriate file.  If this clause is not specified, it is the programmer's responsibility to populate @var{record-name-1} with the desired data prior to executing the @code{WRITE}.

@item
The optional @code{LOCK} options may be used to manually control access to the just-written record by other programs while this program is running.  @xref{Record Locking}, to review the various record locking behaviour.

@item
The optional @code{INVALID KEY} and @code{NOT INVALID KEY} clauses may be used when writing to relative or indexed files to detect and react to the failure (non-zero file status code) or success (00 file status code), respectively, of the statement.  @xref{File Status Codes}, for additional information.

@item
When @code{WRITE} is used against an @syntaxref{ORGANIZATION LINE SEQUENTIAL} file, with or without the @syntaxref{LINE ADVANCING} option, an end-of-record delimiter character sequence will be written to the file to signify where one record ends and the next record begins.  This delimiter sequence will be either of the following:
@itemize @bullet
@item
A line-terminator sequence consisting of an ASCII carriage-return/line-feed character sequence (@code{X'0D0A'}) if you are running a MinGW or native Windows build of GnuCOBOL

@item
A line-terminator sequence consisting of an ASCII line-feed character (@code{X'0A'}) if you are running a Cygwin, Linux, Unix or OSX build of GnuCOBOL
@end itemize

@item
The following points pertain to the use (or not) of the @code{ADVANCING} clause:
@enumerate A
@item
Using this clause with any organization other than @code{ORGANIZATION LINE SEQUENTIAL} will either be rejected outright by the compiler (relative or indexed files) or may introduce unwanted characters into the file (@syntaxref{ORGANIZATION SEQUENTIAL}).

@item
If no @code{ADVANCING} clause is specified on a @code{WRITE} to a line-advancing file, @code{AFTER ADVANCING 1 LINE} will be assumed; on other than line-advancing files, @code{BEFORE ADVANCING 1 LINE} will be assumed.

@item
When
@syntaxidx{BEFORE ADVANCING} is used (or implied), the record is written to the file before the @code{ADVANCING} action writes line-terminator characters to the file.

@item
If
@syntaxidx{AFTER ADVANCING} is used (or implied), the @code{ADVANCING} action writes line-terminator characters to the file and then the record data is written to the file.

@item
The @code{ADVANCING n LINES} clause will introduce the specified number of line-terminator character sequences into the file either before the written record (@code{AFTER ADVANCING}) or after the written record (@code{BEFORE ADVANCING}).

@item
If the @syntaxrefalt{LINAGE,File/Sort-Description} clause is @i{absent} from the file's @code{FD}:
@enumerate a
@item
The
@syntaxidx{ADVANCING PAGE} clause will introduce an ASCII formfeed character into the file either before the written record (@code{AFTER PAGE}) or after the written record (@code{BEFORE PAGE}).

@item
Management of areas on the printed page such as top-of page headers, bottom-of-page footers, dealing with ``full page'' situations and the like are the complete responsibility of the programmer.
@end enumerate
@item
If the LINAGE clause is @i{present} in the file's @code{FD}:
@enumerate a
@item
The @code{ADVANCING PAGE} clause will introduce the appropriate number of line-terminator character sequences into the file either before the written record (@code{AFTER ADVANCING}) or after the written record (@code{BEFORE ADVANCING}) so as to force the printer to automatically advance to a new sheet of paper when the file prints.  No formfeed characters will be generated when @code{LINAGE} is specified --- instead, it is assumed that the printer to which the report will be printed will be loaded with special forms that conform to the specifications defined by the @code{LINAGE} clause.

@item
Management of areas on the printed page such as top-of page headers, bottom-of-page footers, dealing with ``full page'' situations and the like are now the joint responsibility of the programmer and the GnuCOBOL run-time library, which provides tools such as the
@registerrefalt{LINAGE-COUNTER,Special Registers} and the
@syntaxidx{END-OF-PAGE} clause to deal with page formatting issues.

@item
The @code{AT END-OF-PAGE} clause will be triggered, thus executing @var{imperative-statement-1} (@pxref{Imperative Statement}), if the @statement{WRITE} introduces a data line or line-feed character into the file at a line position within the Page Footer area defined by the @code{LINAGE} clause.  The @code{NOT AT END-OF-PAGE} clause will be triggered (thus executing @var{imperative-statement-2}) if no end-of-page condition occurred during the @code{WRITE}.
@end enumerate
@end enumerate
@end enumerate
@iftex
@sp 3
@center ------------------------------------------------------------
@center End of Chapter 7 --- PROCEDURE DIVISION
@end iftex