HP 3000 Manuals

WRITE Statement [ HP COBOL II/XL Reference Manual ] MPE/iX 5.0 Documentation

HP COBOL II/XL Reference Manual

WRITE Statement

The WRITE statement releases a logical record. To use the WRITE
statement for a sequential file, the file must be opened in the OUTPUT or
EXTEND mode. To use the WRITE statement with an indexed, relative, or
random file, the file must be opened in either OUTPUT, I-O mode, or
EXTEND for access mode sequential.

For sequential files, the WRITE statement may additionally be used for
vertical positioning of lines within a logical page (refer to the LINAGE
clause in the File Description Entry of the DATA DIVISION in Chapter 7
).

Syntax

There are two formats for the WRITE statement:

Parameters

record-name-1 the name of a logical record in the FILE SECTION
of the DATA DIVISION. It may be qualified.
Record-name-1 must not reference the same storage
area as identifier-1. Additionally for random
access files, record-name-1 must not be part of a
SORT file.

identifier-1 the name of a data item described within the DATA
DIVISION,[REV BEG] or a function-identifier. If
it is a function, it must be an alphanumeric
function. If it is not a function,[REV END]
identifier-1 and record-name-1 must not reference
the same storage area.

identifier-2 the name of an elementary integer data item. The
value of the data item must be greater than or
equal to zero.

integer-1 a nonnegative integer.

mnemonic-name-1 a name related to the functions, TOP, NO SPACE
CONTROL, and C01 through C16. This relation is
provided by the SPECIAL-NAMES clause to the
CONFIGURATION SECTION of the ENVIRONMENT
DIVISION.

END-OF-PAGE and EOP equivalent.

imperative-statement-1 each one or more imperative statements.
and imperative-
statement-2,

Description

The rules stated below apply to both formats of the WRITE statement.

The successful execution of a WRITE statement releases a logical record
number of character positions defined by the logical description of that
record in the program.

If the file's records are longer than the data being written to it, the
file is padded with blanks or zeros, depending upon whether the file is
an ASCII or binary file, respectively. If the file's records are shorter
than the data being written to it, the data being written is truncated.

Whether execution of the WRITE statement was successful or not, the FILE
STATUS data item, if any, is updated following the execution of the WRITE
statement. Refer to Chapter 6 , under "FILE STATUS Clause", for valid
status keys.[REV BEG] For more information on handling I/O errors, see
"Input-Output Error Handling Procedures" .[REV END]

The logical record released by the execution of the WRITE statement is no
longer available in memory unless the associated file is named in a SAME
RECORD AREA clause, or the execution of the WRITE statement was
unsuccessful because of a boundary violation (for sequential files) or an
INVALID KEY condition (for relative, indexed or random access files).

The logical record is also available to the program as a record of other
files referenced in that SAME RECORD AREA clause.

FROM Phrase

The results of executing a WRITE statement using the FROM phrase is
equivalent to executing the statement,

MOVE identifier-1 TO record-name-1

and then executing the same WRITE statement without the FROM phrase.

Unlike the record area for record-name-1, the data in identifier-1 always
remains in memory and is available after execution of the WRITE
statement, regardless of whether a SAME RECORD AREA clause was used for
any file in which identifier-1 names a data item.

Note that the maximum record size of a file is established at the time
the file is created, and must not subsequently be changed.

WRITE Statement - Format 1

A format 1 WRITE statement, used for sequential files only, allows you to
use vertical positioning of a line within a logical page.

This is done through the ADVANCING and END-OF-PAGE phrases.

Either or both of these phrases may be used in a format 1 WRITE
statement. However, if the END-OF-PAGE phrase is used, the LINAGE clause
must appear in the file description entry for the associated file. Also,
if the LINAGE phrase is present in the file's description, and the
ADVANCING phrase is used, it cannot be used in the form ADVANCING
mnemonic-name-1.

If neither phrase is used, automatic advancing equivalent to AFTER
ADVANCING 1 LINE is provided.

Whenever the execution of a given format 1 WRITE statement cannot be
fully accommodated within the current page body, an automatic page
overflow condition occurs. If neither the ADVANCING nor the END-OF-PAGE
phrase is specified, and a page overflow condition occurs, the WRITE
statement uses an implicit AFTER ADVANCING PAGE to position the data on
the next logical page.

ADVANCING Phrase.

When the ADVANCING phrase is used in a format 1 WRITE statement, the line
to be written is presented to the page either before or after the
representation of the page is advanced. Whether it is presented before
or after advancing the logical page is determined by the use of the
BEFORE or AFTER keyword, respectively.

The amount of advancement of the logical page is determined by integer-1,
identifier-2, PAGE, and mnemonic-name-1 as follows:

* Integer-1 causes the representation of the logical page to be
advanced the number of lines equal to the value of integer.

* Identifier-2 causes the representation of the logical page to be
advanced the number of lines equal to the current value of the
data item represented by identifier-2.

* PAGE causes the logical page to be advanced to the next logical
page. If the record to be written is associated with a file whose
description includes a LINAGE clause, the repositioning is to the
first line that can be written on the new logical page as
specified by the LINAGE clause. If the record to be written is
associated with a file whose description does not contain a LINAGE
clause, the repositioning is to the first line of the next logical
page.

If PAGE is specified for a device to which it has no meaning, advancing
is provided that is equivalent to ADVANCING 1 LINE.

* If mnemonic-name-1 is specified, the file receiving the record
must not contain a LINAGE clause in its description and must be a
line printer device file. Mnemonic-name-1 can be equivalent to
TOP, in which case it is equivalent to specifying PAGE for a file
whose description does not contain a LINAGE clause.

Mnemonic-name-1 may also be equivalent to one of C01 to C16, or NO SPACE
CONTROL.

The C01 through C16 options are related to the VFU (Vertical Form Unit)
holes punched into a paper tape of a line printer. For an HP line
printer, C01 through C16 have the following meanings:

c01: Page eject (skip to top of next page).
c02: Skip to the bottom of the form.
c03: Single spacing with automatic page eject.
c04: Single space on the next odd-numbered line with automatic
page eject.
c05: Triple space with automatic page eject.
c06: Space a half page with automatic page eject.
c07: Space one quarter of a page with automatic page eject.
c08: Space one sixth of a page with automatic page eject.
c09: Space to the bottom of the form.
c10: User option.
c11: User option.
c12: User option.
c13: User option.
c14: User option.
c15: User option.
c16: User option.

NOTE The C13 through C16 options may not be functionally operable on all
printer devices; for example, printer devices that only provide 12
VFU channels.

END-OF-PAGE Phrase.

The END-OF-PAGE phrase can be used only in conjunction with the LINAGE
clause of a sequential file description entry.

To clarify the following description, the concept of a logical page is
illustrated below:

Two conditions may occur that cause the execution of the END-OF-PAGE
phrase.

The first occurs when a footing area has been defined using integer-2 or
data-name-2 of the LINAGE Clause. In this case, when a WRITE statement
using the END-OF-PAGE phrase is executed, and this execution causes
printing or spacing within the footing area, an end-of-page condition
occurs. This is controlled by the value of the LINAGE-COUNTER for the
associated file. Thus, when LINAGE-COUNTER equals or exceeds the value
of integer-2 or the data item specified by data-name-2, an end-of-page
condition occurs. The data is written into the footing area, and the
imperative-statement-1 of the END-OF-PAGE phrase is executed.

NOTE An end-of-page condition does not automatically cause the next line
of data to be written on the next logical page; it is your
responsibility to control this using the LINAGE-COUNTER of the
file, the ADVANCING phrase, or the automatic page overflow
condition.

The second condition that causes the execution of an END-OF-PAGE phrase
is an automatic page overflow. An automatic page overflow occurs when
the LINAGE-COUNTER for the file associated with the WRITE statement
exceeds integer-1 or the data item referenced by data-name-1. In this
case, if an ADVANCING phrase using the BEFORE keyword is present in the
WRITE statement, the record is written the specified number of lines
below the end of the page body, and the device used to contain the
logical pages is repositioned to the first line that can be written on
the next logical page. If an ADVANCING phrase is specified (implicitly
or explicitly) that uses the AFTER keyword, the device used to contain
the logical pages is repositioned to the first line that can be written
on the next logical page, and the record is written.

No matter whether ADVANCING BEFORE or ADVANCING AFTER is specified,
when the record has been written, control is transferred to the
imperative-statement-1 of the END-OF-PAGE phrase.

If integer-2 or the data item referenced by data-name-2 of the LINAGE
clause is not specified (thus, no footing area has been defined), or if
integer-2 or the data item referenced by data-name-2 is equal to
integer-1 or the data item referenced by data-name-1 of the LINAGE
clause, no end-of-page condition distinct from a page overflow is
detected. Thus, an end-of-page condition is, in this case, equivalent to
a page overflow condition.

Bounds Overflow.

When an attempt is made to write beyond the boundaries of a sequential
file, an exception condition exists. The contents of the record area
specified by record-name-1 are unaffected by such a condition and the
following actions take place:

* The FILE STATUS data item, if any, of the associated file is set
to indicate a boundary violation.

* If a USE AFTER STANDARD EXCEPTION declarative is specified
(explicitly or implicitly) for the file, the associated procedure
is executed. If no USE statement is specified for the file, the
program aborts, supplying a file error message.
[REV BEG]

For more information on handling I/O errors, see "Input-Output Error
Handling Procedures" .[REV END]

Multiple Reel/Unit Files.

After an end-of-reel condition has been recognized for a multiple reel
labeled tape, the WRITE statement performs the standard ending reel or
unit procedure, requests a reel or unit swap, and then performs the
standard reel or unit label procedure. The record is then written
according to the specifications of the WRITE statement.

Print Files.

A print file is organized like a sequential organization file and has
carriage control. The carriage control option cannot be changed after
the file is created.

The three ways to create a print file are:

1. Use the MPE :BUILD command with the carriage control option CCTL.
For example:

:BUILD filename;CCTL
2. Use the MPE :FILE command to cause COBOL to create a print file.
For example:

:FILE filename;CCTL
3. Cause the compiler to enable the CCTL option. The following
conditions cause the compiler to enable the CCTL option:
a. The SELECT...ASSIGN clause includes the device name
parameter CCTL.
b. The SELECT...ASSIGN clause specifies the actual file
$STDLIST.
c. The WRITE statements include the BEFORE/AFTER ADVANCING
clause.
d. A file equation for the actual file specifies CCTL.

You can disable CCTL by any of the following:

1. Avoiding the conditions that enable CCTL (see above).
2. Specifying NOCCTL in the file equation.
3. Using a disc file that did not have CCTL when it was built.

When CCTL is enabled, the compiler does the following:

1. Enables the file for CCTL operations when it is opened.
2. Writes the following two control records to the file, before the
firs data record (even if the file is opened in EXTEND mode).
a. Record one contains an ASCII "A" (%101) in the first byte,
which sets the printer spacing mode to PRE-SPACE, the COBOL
default. PRE-SPACE is equivalent to AFTER ADVANCING.
b. Record two contains an ASCII "C" (%103) in the first byte,
which sets the printer to the single-space option, without
automatic page eject. This allows you to control the page
size.
3. Prepends to each record a character that contains carriage control
code. This character is transparent so you need not allow space
for it when you define the record.

Carriage Control Codes.

The carriage control codes that COBOL uses are defined within the MPE
FWRITE intrinsic. They are written in the first byte of each data record
or passed through the control parameter. The carriage control codes and
their meanings are shown in Table 9-7 .

Table 9-7. Carriage Control Codes and Their Meanings

--------------------------------------------------------------------------------------------
| | |
| Code | Meaning |
| | |
--------------------------------------------------------------------------------------------
| | |
| %2n | Space n lines (no automatic page eject). The number n is in the range 0 |
| | through %77 (63). |
| | |
--------------------------------------------------------------------------------------------
| | |
| %3n | Channel options C01 through C16. The number n is in the range 0 through %17 |
| | (15). |
| | |
--------------------------------------------------------------------------------------------
| | |
| %61 | Eject a page (go to the top of the next page; equivalent to TOP). |
| | |
--------------------------------------------------------------------------------------------
| | |
| %100 | Set printer spacing mode to POST-SPACE (equivalent to BEFORE ADVANCING). |
| | |
--------------------------------------------------------------------------------------------
| | |
| %101 | Set printer spacing mode to PRE-SPACE (equivalent to AFTER ADVANCING). |
| | |
--------------------------------------------------------------------------------------------
| | |
| %103 | No automatic page eject. |
| | |
--------------------------------------------------------------------------------------------
| | |
| %320 | No space control. |
| | |
--------------------------------------------------------------------------------------------

If a file has carriage control due to the MPE :FILE command or disc
label, but has no ADVANCING clause, you must put a carriage control code
in the first byte of each record yourself.

If a file has at least one ADVANCING clause, then all other WRITE
statements for that file are treated as if AFTER ADVANCING 1 were
specified.

WRITE Statement - Format 2

A format 2 WRITE statement can be used for random access, relative, or
indexed files.

In a format 2 WRITE statement, if no applicable USE statement has been
issued for the referenced file, the INVALID KEY phrase of the WRITE
statement must be used.

Also, the INVALID KEY phrase must always be used when a format 2 WRITE
statement is issued for a random access file.

Random Access Files.

When a format 2 WRITE statement is issued for a random access file, the
contents of the ACTUAL KEY data item associated with the file are used in
an implicit seek to find the record into which the data specified by
record-name-1 is to be written. If the address specified by the ACTUAL
KEY data item is invalid, an INVALID KEY condition exists, no data
is written, the data in the record area is unaffected, and the
imperative-statement-1 in the INVALID KEY phrase is executed.

The address can be invalid for one of three reasons, as follows:

* It contains a negative value.

* It is greater than the highest possible relative record number in
the file.

* The value moved to the ACTUAL KEY data item contains more than
nine digits.

Relative Files.

When a format 2 WRITE statement is issued for a relative file, and the
file is open for output in sequential mode, the first execution of a
WRITE statement for the file releases a record to that file, assigning a
relative record number of 1 to it. Subsequent WRITE statements assign
relative record numbers of 2,3,4, and so on as records are released to
the file. If the RELATIVE KEY data item has been specified in the file
control entry for the associated file, it is updated during each
execution of the WRITE statement to indicate the relative record number
of the record being written.

If a relative file is open in random or dynamic access mode, regardless
of whether it is open for output only or input-output operations, your
program must set the value of the relative key data item to specify where
the record is to be placed in the file.

Provided that the relative key data item is a valid relative key, the
data in the record area is released to the file.

INVALID KEY Conditions For a Relative File.

An INVALID KEY condition exists for a relative file when an attempt is
made to write beyond the externally defined boundaries of the file, or
when the file is in dynamic or random access mode and the RELATIVE KEY
data item specifies a record that already exists in the file.

When this condition occurs, execution of the WRITE statement is
unsuccessful, the contents of the record area are unaffected, and the
FILE STATUS data item, if any, is updated to indicate the cause of the
condition.

If the INVALID KEY phrase was specified in the WRITE statement, control
passes to the imperative statement appearing in the phrase. If no
INVALID KEY phrase was specified, then a USE procedure must have been
specified (either implicitly or explicitly), and is executed.

If both a USE procedure and an INVALID KEY phrase are specified, the USE
procedure is ignored.
[REV BEG]

For more information on handling I/O errors, see "Input-Output Error
Handling Procedures" .[REV END]

Indexed Files.

A format 2 WRITE statement for an indexed file uses the primary record
key data item to write records to the file; therefore, the value of the
primary record key must be unique within the records of the file unless
the DUPLICATES phrase has been used in the RECORD KEY clause of the
ENVIRONMENT DIVISION.

If alternate record keys have been specified, they must also be unique
within the file unless the DUPLICATES phrase has been used in the
ALTERNATE RECORD KEY clause of the ENVIRONMENT DIVISION.

If the DUPLICATES phrase is used, then after records containing duplicate
keys have been written to the file, if they are later accessed
sequentially, they are retrieved in the same order as they were written.

NOTE A WRITE statement for an indexed file open in sequential access
mode must write records to the file in ascending order of prime
record key values.

A WRITE statement for an indexed file in random or dynamic access mode
writes a record to the file in whatever order your program specifies.

When a WRITE statement is successfully executed for an indexed file, all
keys of the record are used in such a way that subsequent access of the
record may be made based upon any of the specified record keys.

INVALID KEY Conditions For Indexed Files.

There are three conditions under which an INVALID KEY condition can occur
for an indexed file WRITE statement:

* When the file is open for output in sequential access mode, and
the value of the prime record key is not greater than the value of
the prime record key of a previous record.

* When the file is open for output or input-output operations in any
access mode, and the value of the primary or an alternate record
key for which duplicates are not allowed, equals the value of the
corresponding record key of a record already existing in the file.

* When an attempt is made to write beyond the externally defined
boundaries of the file.

In any case, when an INVALID KEY condition occurs, execution of the WRITE
statement is unsuccessful, the record area is unaffected, and the FILE
STATUS data item, if any, associated with the file is set to a value that
indicates the cause of the condition.

If an INVALID KEY phrase was specified in the WRITE statement, control is
transferred to the imperative statement appearing in the phrase, and any
USE procedure specified for the file is ignored.

If no INVALID KEY phrase was specified, then a USE procedure must have
been specified, implicitly or explicitly, and that procedure is executed.
[REV BEG]

For more information on handling I/O errors, see "Input-Output Error
Handling Procedures" .[REV END]

MPE/iX 5.0 Documentation