 |
Compaq COBOL
Reference Manual
With COUNT phrase:
DISPLAY "Enter two dates in a row: " NO ADVANCING.
ACCEPT INMESSAGE.
MOVE 1 TO PTR.
PERFORM DISPLAY-TWO 2 TIMES.
GO TO DISPLAYED-TWO.
DISPLAY-TWO.
MOVE SPACES TO THEDATE.
MOVE 0 TO FIELD-COUNT MONTH-COUNT DAY-COUNT YEAR-COUNT.
UNSTRING INMESSAGE
DELIMITED BY "-" OR "/" OR ALL " "
INTO THEMONTH DELIMITER IN HOLD-DELIM COUNT MONTH-COUNT
THEDAY DELIMITER IN HOLD-DELIM COUNT DAY-COUNT
THEYEAR DELIMITER IN HOLD-DELIM COUNT YEAR-COUNT
WITH POINTER PTR
TALLYING IN FIELD-COUNT.
INSPECT THEDATE REPLACING ALL " " BY "0".
DISPLAY THEDATE " " PTR " " FIELD-COUNT
" : " MONTH-COUNT "-" DAY-COUNT "-" YEAR-COUNT.
DISPLAYED-TWO.
EXIT.
|
Results
Enter two dates in a row: 6/13/87 8/15/87
870613 09 03 : 01-02-02
870815 21 03 : 01-02-02
Enter two dates in a row: 10 15 87-1 1 88
871015 10 03 : 02-02-02
880101 21 03 : 01-01-02
Enter two dates in a row: 6/13/87-12/31/87
870613 09 03 : 01-02-02
871231 21 03 : 02-02-02
Enter two dates in a row: 6/13/87-12/31
870613 09 03 : 01-02-02
001231 21 02 : 02-02-00
Enter two dates in a row: 6/13/87/12/31/87
870613 09 03 : 01-02-02
871231 21 03 : 02-02-02
|
6.8.42 USE
Function
The USE statement specifies Declarative USE procedures to handle
input/output exceptions and errors. It can also specify procedures to
be executed before the program processes a specific report group.
file-name
is the name of a file connector described in a file description entry
in a Data Division. It cannot refer to a sort or merge file.
group-data-name
is the name of a report group in a report group description entry in a
Data Division. It must not appear in more than one USE statement.
Syntax Rules
All Formats
- A USE statement can be used only in a sentence immediately after a
section header in the Procedure Division declaratives area. It must be
the only statement in the sentence. The rest of the section can contain
zero, one, or more paragraphs to define the USE procedures.
- The USE statement itself does not execute. It defines the
conditions that cause execution of the USE procedure.
Format 1
- The ERROR and EXCEPTION syntax are equivalent and interchangeable.
Format 2
- Of the four Report Writer Procedure Division verbs (SUPPRESS,
GENERATE, INITIATE, or TERMINATE), only the SUPPRESS statement can
appear in a USE BEFORE REPORTING procedure. A PERFORM statement in a
USE BEFORE REPORTING procedure must not have GENERATE, INITIATE, or
TERMINATE statements in its range.
The USE procedure must not alter
the value of any control data item.
General Rules
All Formats
- At run time, two special precedence rules apply for the selection
of a USE procedure when a program is contained within another program.
In applying these rules, only the first qualifying USE procedure is
selected for execution. The order of precedence for the selection of a
USE procedure is as follows:
- First, select the applicable USE procedure within the program
containing the statement that caused the qualifying condition.
- If a USE procedure is not found in the program using the previous
rule, the Run-Time System searches all programs directly or indirectly
containing that program for a USE GLOBAL procedure. This search
continues until the Run-Time System either: (a) finds an applicable USE
GLOBAL procedure, or (b) finds the outermost containing program, if
there is no applicable USE GLOBAL procedure. Either condition
terminates the search.
- A Declarative USE procedure cannot refer to a non-Declarative
procedure. However, only the PERFORM statement can transfer execution
control from:
- A Declarative USE procedure to another Declarative USE procedure
- A non-Declarative procedure to a Declarative USE procedure
- After a USE procedure executes, control returns to the next
executable statement in the invoking routine, if one is defined.
Otherwise, control transfers according to the rules for Explicit and
Implicit Transfers of Control.
- A program must not execute a statement in a USE procedure that
would cause execution of a USE procedure that had been previously
executed and had not yet returned control to the routine that invoked
it.
Format 1
- A USE procedure executes automatically:
- After the system's input-output exception processing completes
- When an invalid key or at end condition results from an
input-output statement that has no INVALID KEY or AT END clause
- If there is an applicable USE AFTER EXCEPTION procedure, it
executes whenever an input or output condition occurs that would result
in a nonzero value in the first character of a FILE STATUS data item.
However, it does not execute if: (a) the condition is invalid key and
there is an INVALID KEY phrase, or (b) the condition is at end, and
there is an AT END phrase.
- One input-output exception cannot cause more than one USE AFTER
EXCEPTION procedure to execute.
- More than one USE AFTER EXCEPTION procedure can relate to an
input-output operation when there is one procedure for
file-name and another for the applicable open mode. In this
case, only the procedure for file-name executes. This rule
applies only to USE procedures in the same program.
- If no applicable USE procedures are found in the local program,
then containing programs are searched upwards for: (a) USE GLOBAL
procedures for the file, and then (b) for USE GLOBAL procedures for the
input-output type.
- A USE AFTER EXCEPTION procedure specifying an open mode applies to
an input-output operation only when all of the following are true:
- The open mode (INPUT, OUTPUT, I-O, or EXTEND) specified in the USE
AFTER EXCEPTION procedure is identical to the open mode in effect (that
is, the open mode established by the OPEN statement).
- The file is open or in the process of being opened.
- There is no file-name declarative procedure for that file
within the same program.
- If an input-output error occurs for a file that is not open or not
in the process of being opened, the only applicable USE procedure is a
file-name USE procedure.
Format 2
- The Report Writer Control System (RWCS) executes the USE BEFORE
REPORTING procedure before it processes the named
group-data-name report group. Only during the processing of
the report group does the RWCS change prior values, execute control
breaks, adjust LINE-COUNTER and PAGE-COUNTER, and present the report
group.
Additional References
Example
***************************************************************
* This example assumes that SELECT and FD statements exist
* for FILE1-SEQ, FILE1-RAN, FILE1-DYN and FILE1-EXT.
* All three USE procedures are local to the program
* that hosts this fragment.
* At run-time if there is an exception on opening FILE1-RAN
* or FILE1-DYN, FILE1-ERR section can be invoked.
* If there is an exception on opening FILE1-SEQ, INPUT-ERR
* section can be invoked. Since there is no USE procedure
* declared for the EXTEND mode or for FILE1-EXT,
* an exception on opening that file will cause an abnormal
* termination of the program. Also, since FILE1-SEQ in the
* fragment is not opened for OUTPUT mode, the OUTPUT-ERR USE
* procedure is not eligible to be invoked here.
***********************************************************
PROCEDURE DIVISION.
DECLARATIVES.
INPUT-ERR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
INP-1.
DISPLAY "INVOKED USE PROCEDURE FOR INPUT".
OUTPUT-ERR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT.
OUT-1.
DISPLAY "INVOKED USE PROCEDURE FOR OUTPUT".
FILE1-ERR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON FILE1-RAN, FILE1-DYN.
FILE1-1.
DISPLAY "INVOKED USE PROCEDURE FOR FILES".
END DECLARATIVES.
MAIN-PROGRAM SECTION.
P0. DISPLAY "***ENTERED USE TEST PROGRAM FRAGMENT***".
OPEN INPUT FILE1-SEQ.
OPEN OUTPUT FILE1-RAN.
OPEN I-O FILE1-DYN.
OPEN EXTEND FILE1-EXT.
...
|
6.8.43 WRITE
Function
The WRITE statement releases a logical record to an output or
input-output file. It can also position lines vertically on a logical
page.
rec-name
is the name of a logical record described in the Data Division File
Section. The logical record cannot be in a sort-merge file description
entry.
src-item
is the identifier of the data item that contains the data.
advance-num
is an integer or the identifier of an unsigned data item described as
an integer. Its value can be zero.
top-of-page-name
is a mnemonic-name equated to C01 in the SPECIAL-NAMES paragraph of the
Environment Division. It represents top-of-page and is equivalent to
the PAGE phrase.
stment
is an imperative statement executed when the relevant condition
(end-of-page or invalid key) occurs.
stment2
is an imperative statement executed when the relevant condition (not at
end-of-page or not invalid key) occurs.
Syntax Rules
- Format 1 must be used for sequential files.
- Format 2 must be used for relative and indexed files.
- If the file description entry containing rec-name has a
LINAGE clause, the WRITE statement cannot have an ADVANCING
top-of-page-name phrase.
- If there is an END-OF-PAGE phrase, the file description entry
containing rec-name must have a LINAGE clause.
- The words END-OF-PAGE and EOP are equivalent.
- In Format 2, there must be an INVALID KEY phrase if there is no
applicable USE AFTER EXCEPTION procedure for the file.
- To use the ALLOWING option, the program must include these entries:
- LOCK-HOLDING clause of the I-O-CONTROL paragraph
- ALLOWING option of the OPEN statement
- If src-item is a function-identifier, it must reference an
alphanumeric function. When src-item is not a
function-identifier, rec-name and src-item must not
reference the same storage area.
- The ADVANCING PAGE and END-OF-PAGE phrase cannot be used in the
same WRITE statement.
- ADVANCING cannot be used with LINE SEQUENTIAL (Alpha).
- The ALLOWING clause is Compaq standard file-sharing syntax, and
cannot be used for a file connector that has had X/Open standard
file-sharing syntax (WITH [NO] LOCK or LOCK MODE) specified.
General Rules
All Files
- The record is no longer available in rec-name after a
WRITE statement successfully executes. However, if the associated
file-name is in a SAME RECORD AREA clause, the record is available in
rec-name. In this case, the record is also available in the
record areas of other file-names in the same SAME RECORD AREA clause.
- The FROM Phrase section lists the rules for the FROM phrase.
- For mass storage files, the WRITE statement does not affect the
File Position Indicator.
- The WRITE statement updates the value of the FILE STATUS data item
for the file.
- A file's maximum record size is set when it is created. It cannot
be changed later.
- On a mass storage device, the number of characters required to
store a logical record in a file depends on file organization and
record type. (See Technical Notes.)
- WRITE statement execution releases a logical record to the I-O
system.
- The ALLOWING NO OTHERS option can be used only in a Compaq standard
manual record-locking environment. To create a manual record-locking
environment, the program must open file-name with an ALLOWING option
and specify the APPLY LOCK-HOLDING phrase of the I-O-CONTROL paragraph.
If you use manual locking (APPLY LOCK-HOLDING), then the ALLOWING NO
OTHERS clause on the WRITE statement is required.
- The ALLOWING NO OTHERS option locks the current record. No other
concurrent access stream can access this record until it is unlocked.
However, on Tru64 UNIX systems, for indexed files the WRITE
statement with the ALLOWING clause does not acquire a record lock.
<>
- If there is an applicable USE AFTER EXCEPTION procedure, it
executes whenever an input or output condition occurs that would result
in a nonzero value in the first character of a FILE STATUS data item.
However, it does not execute if: (a) the condition is invalid key, and
(b) there is an INVALID KEY phrase.
See the rules for the INVALID
KEY phrase, Section 6.6.10.
- The number of character positions in the record to be written must
not be less than the lowest or greater than the highest number of
character positions allowed by the RECORD VARYING clause. In either
case, the WRITE statement is unsuccessful and the following occurs:
- The WRITE operation does not take place.
- The contents of the record area remain unaffected.
- The I-O status of the file is set to a value that indicates the
cause of the condition.
Sequential or Line Sequential (Alpha) Files
- The file must be open in the OUTPUT or EXTEND mode when the WRITE
statement executes. (See Table 6-15.)
- The sequence of records in a sequential file is set by the order of
WRITE statement executions that create the file. The relationship does
not change, except when records are added to the end of the file.
- For a sequential file open in the extend mode, the WRITE statement
adds records to the end of the file as if the file were open in the
output mode. If the file has records, the first record written after
execution of an OPEN statement with the EXTEND phrase is the successor
of the file's last record.
- When a program tries to write beyond a sequential file's externally
defined boundaries (for example,attempting to write to a full disk
device), an exception condition exists as follows:
- The contents of the record area are unaffected.
- The value of the FILE STATUS data item for the file indicates a
boundary violation.
- If a USE AFTER EXCEPTION procedure applies to the file, it executes.
- If there is no applicable USE AFTER EXCEPTION procedure, the
program terminates abnormally.
- If the end of a reel/unit is recognized, and the WRITE does not
exceed the externally defined file boundaries:
- A reel/unit swap occurs.
- The Current Volume Pointer points to the file's next reel/unit.
- If the program reaches the end of the logical page during execution
of a WRITE statement with the END-OF-PAGE phrase, stment
executes. The LINAGE clause associated with the file specifies the
logical end.
- An end-of-page condition is reached when a WRITE statement with the
END-OF-PAGE phrase causes printing or spacing in the footing area of
the page body.
This condition occurs when the WRITE statement
causes the LINAGE-COUNTER to equal or exceed the value in the LINAGE
clause FOOTING phrase. stment then executes after
rec-name is written to the file.
If this statement does
not occur and the NOT END-OF-PAGE is specified, rec-name is
written to the file, file status is updated, and control is transferred
to stment2.
- An automatic page overflow condition occurs when the page body
cannot fully accommodate a WRITE statement (with or without the
END-OF-PAGE phrase).
This condition occurs when WRITE statement
execution would cause the LINAGE-COUNTER to exceed the number of lines
in the page body specified in the LINAGE clause. When this happens, the
line is presented on the logical page before or after (depending on the
phrase) device positioning. The device is positioned to the first line
that can be written on the next logical page (as described in the
LINAGE clause). stment then executes after rec-name
is written to the file.
- If there is no LINAGE clause FOOTING phrase, the WRITE statement
operates as if the FOOTING phrase value was beyond the limits of the
page. That is, the end-of-page condition occurs after the specified
number of lines per page are written. No space is reserved for a
footing.
- If there is a FOOTING phrase, and a WRITE statement would cause the
LINAGE-COUNTER to exceed both the number of lines in a logical page and
the value in the LINAGE clause FOOTING phrase, the WRITE statement
operates as if there were no FOOTING phrase.
Relative Files
- The file must be open in the OUTPUT, I-O, or EXTEND mode when the
WRITE statement executes. (See Table 6-15.)
- When a relative file with sequential access mode is open in the
output mode, the WRITE statement releases a record to the I-O system.
The first record has a relative record number of 1. Subsequent records
have relative record numbers of 2, 3, 4, and so on. If rec-name
has an associated RELATIVE KEY data item, the WRITE places the
relative record number of the released record into it.
- When a relative file with sequential access mode is open in the
extend mode, the WRITE statement releases a record to the I-O system.
The first record has a relative record number one greater than the
highest relative record number existing in the file. Subsequent records
have consecutively higher relative record numbers. If rec-name
has an associated RELATIVE KEY data item, the WRITE statement
places the relative record number of the released record into it.
- When a relative file with random or dynamic access mode is open in
the output mode, the program must place a value in the RELATIVE KEY
data item before executing the WRITE statement. The value is the
relative record number to associate with the record in
rec-name. The WRITE statement releases the record to the I-O
system.
- When a relative file is open in the I-O mode and the access mode is
random or dynamic, the program must place a value in the RELATIVE KEY
data item before executing the WRITE statement. The value is the
relative record number to associate with the record in
rec-name. Executing a Format 2 WRITE statement releases the
record to the I-O system.
- The invalid key condition exists when:
- The access mode is random or dynamic, and the RELATIVE KEY data
item specifies a record that already exists in the file.
- The program tries to write a record beyond the externally defined
file boundaries.
- The number of significant digits in the relative record number is
larger than the size of the relative key data item described for the
file.
- When the program detects an invalid key condition, WRITE statement
execution is unsuccessful. The following results occur:
- The contents of the current record area are not affected.
- The WRITE statement sets the FILE STATUS data item for the file to
indicate the cause of the condition.
- Program execution continues according to the rules for the invalid
key condition.
See the rules for the INVALID KEY phrase,
Section 6.6.10.
Indexed Files
- The file must be open in the OUTPUT, I-O, or EXTEND mode when the
WRITE statement executes. (See Table 6-15.)
- Executing a Format 2 WRITE statement releases a record to the I-O
system. The contents of the record keys enable later record access
based on any defined key.
- When the file description entry has a RECORD KEY IS clause, the
prime record key value is unique unless the DUPLICATES phrase is
specified. When a program later accesses these records sequentially,
the retrieval order is the same as the order in which they were written
in the program.
- The program must set the value of the prime record key data item
before executing the WRITE statement.
- If the file is open in the sequential access mode, the program must
release records in ascending or descending order of prime record key
values, depending on the sort order specified in the RECORD KEY clause.
If the file is open in the extend mode, the first released record must
have a prime record key value that logically follows the last record in
the file according to the prime key sort order.
- If the file is open in the random or dynamic access mode, the
program can release records in any order.
- When the file description entry has an ALTERNATE RECORD KEY clause,
the alternate record key value is unique unless the program specifies
the DUPLICATES phrase. When a program later accesses these records
sequentially, the retrieval order is the same as the order in which
they were written in the program.
- The invalid key condition occurs for any of the following:
- The file is open in the sequential access mode and in the
OUTPUT or EXTEND mode, and the prime record key value does not
logically follow the prime record key value of the previous record.
- The file is open in the OUTPUT, EXTEND, or I-O mode, the prime
record key value duplicates an existing record's prime record key
value, and the program does not specify duplicates on the prime record
key.
- The file is open in the OUTPUT, EXTEND, or I-O mode, and the value
of an alternate record key (for which duplicates are not allowed)
duplicates the value of the corresponding data item in an existing
record.
- The program tries to write a record beyond the externally defined
file boundaries.
- When the program detects an invalid key condition, WRITE statement
execution is unsuccessful. The following results occur:
- The contents of the current record area are not affected.
- The WRITE statement sets the FILE STATUS data item for the file to
indicate the cause of the condition.
- Program execution continues according to the rules for the invalid
key condition.
See the rules for the INVALID KEY phrase,
Section 6.6.10.
Technical Notes
- WRITE statement execution can result in these FILE STATUS data item
values:
File
Status |
File
Organization |
Access
Method |
Meaning |
|
00
|
All
|
All
|
Write is successful
|
|
02
|
Ind
|
All
|
Created duplicate primary or alternate key
|
|
21
|
Ind
|
Seq
|
Attempted key value not in prime key sort order (invalid key)
|
|
22
|
Ind, Rel
|
All
|
Duplicate key (invalid key)
|
|
24
|
Ind, Rel
|
All
|
Boundary violation (relative or indexed files) or relative record
number is too large for relative key data item (invalid key)
|
|
34
|
Seq
|
Seq
|
Boundary violation (sequential files)
|
|
44
|
All
|
All
|
Boundary violation. An attempt was made to write a record that is
larger than the largest or smaller than the smallest record allowed
|
|
48
|
All
|
All
|
File not open, or incompatible open mode
|
|
92
|
Ind, Rel
|
All
|
Record locked by another process
|
|
30
|
All
|
All
|
All other permanent errors
|
In order to detect "device full" (file status 34) on a sequential WRITE
operation, each WRITE needs to be followed by a call to SYS$FLUSH to
ensure that an attempt has been made to write any buffered records to
disk. For more information, at the OpenVMS system prompt, type
Additional References
|
|
** About PDF files: The PDF files on this Web site can be read online or printed using Adobe® Acrobat® Reader. If you do not
have this software installed on your system, you may download it from the Adobe Web site.
|
 |
|
|
|
