The sequential access output procedures apply primarily to files opened for sequential access; but can also be used on direct and keyed access files.
1 – EXTEND
The EXTEND procedure opens an existing file, positions the file
buffer after the last component, and prepares it for writing.
It is commonly used to append to a file.
Syntax:
EXTEND( file_variable [[, file_name]]
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the output file.
The 'file_name' is the name of the file to be associated with
the 'file_variable'. If the file was opened with the OPEN
procedure, the 'file_name' is ignored.
The 'error-recovery' is the action to be taken if an error
occurs during execution of the routine.
The file can be in any mode before EXTEND is called to set the
mode to generation. If the file is an external file and is not
already open, EXTEND opens it using the defaults for the OPEN
procedure.
After execution of EXTEND, the file is positioned after the last
component, and EOF and UFB return TRUE. If the file does not
exist, EXTEND does not create it, but returns an error at run
time.
A call to EXTEND on a relative file opened for direct access
positions the file after its last existing component.
A call to EXTEND on an indexed file opened for random access by
key positions the file after the last component relative to the
primary key.
See the "HP Pascal Language Reference Manual" for a complete
description of the EXTEND procedure.
2 – PUT
The PUT procedure adds a new component to a file.
Syntax:
PUT( file_variable [[, ERROR := error-recovery]] );
The 'file_variable' specifies the name of the file variable
associated with the output file.
The 'error-recovery' is the action to be taken if an error
occurs during execution of the routine.
Before executing the first PUT procedure on a file opened for
sequential access, you must execute an EXTEND, REWRITE or
TRUNCATE procedure to set the file to generation mode. EXTEND,
REWRITE and TRUNCATE set EOF to TRUE, thus preparing the file
for output. (TRUNCATE is legal only on files with sequential
organization.) If the file has indexed organization, the
components to be written must be ordered by the primary key.
Before executing the first PUT statement on a file opened for
direct access, you must execute an EXTEND, REWRITE or LOCATE
procedure to position the file.
The PUT procedure writes the value of the file buffer variable
at the end of the specified sequential-file or direct-access
file. You can use LOCATE to position a direct-access file and
then use PUT to write the value of the file buffer variable at
that position. After execution of the PUT procedure, the value
of the file buffer variable becomes undefined (UFB returns
TRUE). EOF remains TRUE and the file remains in generation
mode.
You can call the PUT procedure for a keyed-access file,
regardless of the file's mode (inspection, generation, or
undefined). PUT causes the file buffer variable to be written
to the file at the position indicated by the key. If the
component has more than one key, the file buffer variable is
inserted in each index at the appropriate location. After
execution of PUT, a keyed-access file is in generation mode.
See the "HP Pascal Language Reference Manual" for a complete
description of the PUT procedure.
3 – REWRITE
The REWRITE procedure readies a file for output.
Syntax:
REWRITE( file_variable [[, file_name]]
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the output file.
The 'file_name' is a string expression to be associated with the
file_variable. Files opened with REWRITE and the 'file_name'
stay resident on the disk after the program exits. However, if
the file was opened with the OPEN procedure, the 'file_name' is
ignored.
The 'error-recovery' specifies the action to be taken if an
error occurs during execution of the routine. By default, after
the first error, the error message is printed and execution is
stopped.
The file can be in any mode before REWRITE is called to set the
mode to generation. If the file variable has not been opened,
REWRITE creates and opens it using the same defaults as the OPEN
procedure.
The REWRITE procedure truncates a file to length zero and sets
EOF and UFB to TRUE. You can then write new components into the
file with the PUT, WRITE, and WRITELN procedures (WRITELN is
defined only for text files). After the file is open,
successive calls to REWRITE truncate the existing file to a
length of zero; they do not create new versions of the file.
To update an existing file with sequential organization, you
must either use the EXTEND procedure, use the TRUNCATE
procedure, or copy the contents to another file, specifying new
values for the components you need to update.
When applied to a file with relative or indexed organization,
REWRITE deletes the contents of the file and sets the file
position to the beginning of an empty file.
See the "HP Pascal Language Reference Manual" for a complete
description of the REWRITE procedure.
4 – WRITE
The WRITE procedure assigns data to an output file.
Syntax:
WRITE( [[file_variable, ]]{expression},...
[[,ERROR := error-recovery]] )
The 'file_variable' is the name of the file variable associated
with the output file. If you omit the name of the file, the
default is OUTPUT.
The 'expression' is an expression whose value is to be written;
multiple output values must be separated with commas. An output
value must have the same type as the file components; however,
values written to a TEXT file can also be expressions of any
ordinal, real, or string type.
The 'error-recovery' specifies the action to be taken if an
error occurs during execution of the routine. By default, after
the first error, the error message is printed and execution is
stopped.
The file (unless it is a random-access by key file) must be in
generation mode before WRITE is called; it remains in that mode
after WRITE has executed.
By definition, a WRITE statement to a nontext file performs an
assignment to the file buffer variable and a PUT statement for
each output value. For nontext files, the types of the output
values must be assignment compatible with the component type of
the file.
See the "HP Pascal Language Reference Manual" for a complete
description of the WRITE procedure.