4.4 – UFB
The UFB (undefined file buffer) function returns a Boolean value
that indicates whether the last file operation gave the file
buffer an undefined status.
Syntax:
UFB( file_variable )
The 'file_variable' is the name of the file variable associated
with the file whose buffer is being tested.
The file can be in any mode before UFB is called; execution of
UFB does not change the file mode.
UFB tests the effect of the last I/O operation done to the file.
UFB returns FALSE if a successful GET, FIND, FINDK, RESET, or
RESETK operation has filled the file buffer. GET, FIND, FINDK,
RESET, and RESETK procedure calls that do not fill the file
buffer set UFB to TRUE.
UFB also returns TRUE after DELETE, EXTEND, LOCATE, PUT,
REWRITE, TRUNCATE, and UPDATE procedures have left the contents
of the file buffer unknown.
Assigning a new value to the file buffer with an assignment
statement does not change the value of UFB.
See the "HP Pascal Language Reference Manual" for a complete
description of the UFB function.
4.5 – UNLOCK
The UNLOCK procedure releases the current file component for
access by other processes.
Syntax:
UNLOCK( file_variable [[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file whose component is to be unlocked.
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 must be in inspection mode before UNLOCK is called; it
remains in inspection mode after UNLOCK has executed.
If the component at which the file pointer is positioned has
been locked, the UNLOCK procedure releases it.
5 – Text File
Text file manipulation routines apply only to text files (including INPUT, OUTPUT, and ERR).
5.1 – EOLN
The EOLN function tests for the end-of-line marker within a text
file and returns a Boolean value.
Syntax:
EOLN [[( file_variable )]]
The 'file_variable' is the name of a file variable associated
with a text file. If you omit the name of the file, the default
is INPUT.
The file must be in inspection mode and EOF must return FALSE
before EOLN is called. EOLN leaves the file in inspection mode.
The Boolean EOLN function returns TRUE when the file pointer is
positioned after the last character in a line. When the EOLN
function returns TRUE, the file buffer contains a blank
character.
The EOLN function returns FALSE when the last component in the
line is read into the file buffer. Another character must be
read to cause EOLN to return TRUE and to cause the file buffer
to be positioned at the end-of-line marker following the last
character of the line. If you use the EOLN function on a
nontext file, an error occurs.
See the "HP Pascal Language Reference Manual" for a complete
description of the EOLN function.
5.2 – LINELIMIT
The LINELIMIT procedure stops execution of the program after a
specified number of lines has been written into a TEXT file.
Syntax:
LINELIMIT( file_variable, n [[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the TEXT file to which the limit applies.
The 'n' is a positive integer expression that indicates the
number of lines that can be written to the file before execution
terminates.
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 LINELIMIT is called; the file
mode does not change after LINELIMIT has been executed.
VSI Pascal first uses environment-specific means to determine if
there is a default line limit. If there is not
environment-specific default, there is no default line limit.
You can use a call to LINELIMIT to override the default.
After the number of lines written into the file has reached the
line limit, program execution terminates unless the WRITELN
procedure that exceeded the line limit includes the ERROR :=
CONTINUE parameter.
See the "HP Pascal Language Reference Manual" for a complete
description of the LINELIMIT procedure.
5.3 – PAGE
The PAGE procedure skips from the current page to the next page
of a TEXT file.
Syntax:
PAGE( file_variable [[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with a TEXT file.
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 must be in generation mode before the PAGE procedure is
called; the mode does not change as a result of the procedure's
execution.
Execution of the PAGE procedure clears the record buffer, if it
contains data, by performing a WRITELN procedure, and then
advances the output to a new page of the specified TEXT file.
The next component written to the file begins on the first line
of a new page. You can use this procedure only on TEXT files.
If you specify a file of any other type, an error occurs.
The value of the page eject component that is output to the file
depends on the carriage control format for that file. When
CARRIAGE or FORTRAN is enabled, the page eject record is
equivalent to the carriage control character '1'. When LIST,
NOCARRIAGE, or NONE is enabled, the page eject record is a
single form feed character.
See the "HP Pascal Language Reference Manual" for a complete
description of the PAGE procedure.
5.4 – READLN
The READLN procedure reads lines of data from a TEXT file.
Syntax:
READLN [[( [[file_variable,]] {variable-identifier
[[:radix-specifier]]},... [[, ERROR := error-recovery]]) ]];
The 'file_variable' is the name of the file variable associated
with the TEXT file to be read. If you omit the name of the
file, the default is INPUT.
The 'variable-identifier' is the name of the variable into which
a file component will be read; multiple identifiers are
separated by commas. If you do not specify any variable name,
READLN skips a line in the specified file.
The 'radix-specifier' is one of the format values BIN, OCT, or
HEX. These values, when used on a variable identifier, read the
variable in binary, octal, or hexadecimal, respectively. You
can use a radix specifier only when reading from a TEXT file.
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 must be in inspection mode before READLN is called; it
remains in that mode after the procedure's execution.
The READLN procedure reads values from a TEXT file. After
reading values for all the listed variables, the READLN
procedure skips over any characters remaining on the current
line and positions the file at the beginning of the next line.
The values need not all be on a single line; READLN continues
until values have been assigned to all the specified variables,
even if this process results in the reading of several lines of
the input file.
EOLN returns TRUE after a READLN procedure only if the new line
is empty.
See the "HP Pascal Language Reference Manual" for a complete
description of the READLN procedure.
5.5 – WRITELN
The WRITELN procedure writes a line of data to a text file.
Syntax:
WRITELN [[( [[file_variable,]] {expression},...
[[, ERROR := error-recovery]] )]]
The 'file_variable' is the name of the file variable associated
with the text file to be written. 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 by commas. The
expressions can be of any ordinal, real, or string type and are
written with a default field width.
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 must be in generation mode before WRITELN is called; it
remains in that mode after WRITELN has been executed.
The WRITELN procedure writes the specified values into the TEXT
file, inserts an end-of-line marker after the end of the current
line, and then positions the file at the beginning of the next
line.
You can specify a carriage-control character as the first item
in an output line. When you use carriage-control characters,
make sure that the file is open with either the CARRIAGE or
FORTRAN option.
If you specify a carriage format but use an invalid carriage
control character, the first character in the line is ignored.
The output appears with the first character truncated.
See the "HP Pascal Language Reference Manual" for a complete
description of the WRITELN procedure.
6 – Direct Access
Direct access procedures are generally legal only on files opened for direct access. In some cases, procedures apply to keyed access files as well.
6.1 – DELETE
The DELETE procedure deletes the current file component. DELETE
can be used only on files with relative or indexed organization
that have been opened for direct or keyed access; it cannot be
used on files with sequential organization.
Syntax:
DELETE( file_variable[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file from which a component is to be deleted.
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 must be in inspection mode before DELETE is called; the
mode does not change after the procedure's execution.
When the DELETE procedure is called, the current component, as
indicated by the file buffer, must already have been locked by a
successful FIND, FINDK, GET, RESET, or RESETK procedure before
it can be deleted. After deletion, the component is unlocked
and the UFB function returns TRUE.
See the "HP Pascal Language Reference Manual" for a complete
description of the DELETE procedure.
6.2 – FIND
The FIND procedure positions a file at a specified component.
The file must be open for direct access and must contain
fixed-length components.
Syntax:
FIND( file_variable, component-number
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with a file that is open for direct access.
The 'component-number' is a positive integer expression that
indicates the component at which the file is to be positioned.
If the component number is zero or negative, a run-time error
occurs.
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 FIND procedure allows direct access to the components of a
file. You can use the FIND procedure to move forward or
backward in a file.
After execution of the FIND procedure, the file is positioned at
the specified component. The file buffer variable assumes the
value of the component, and the file mode is set to inspection.
If the file has relative organization, the current file
component is locked. If there is no file component at the
selected position, the file buffer is undefined (UFB becomes
TRUE) and the mode becomes undefined. After any call to FIND,
the value of EOF is undefined.
You can use the FIND procedure only when reading a file that was
opened by the OPEN procedure. If the file is open because of a
default open (that is, with EXTEND, RESET, or REWRITE), a call
to FIND results in a run-time error because the default access
method is sequential.
See the "HP Pascal Language Reference Manual" for a complete
description of the FIND procedure.
6.3 – LOCATE
The LOCATE procedure positions a random-access file at a
particular component so that the next PUT procedure can modify
that component.
Syntax:
LOCATE( file_variable, component-number
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file to be positioned.
The 'component-number' is a positive integer expression
indicating the relative component number of the component to be
found.
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 LOCATE is called. The mode
is set to generation after the procedure's execution.
The LOCATE procedure positions the file so that the next PUT
procedure writes the contents of the file buffer into the
selected component. After LOCATE has been performed, UFB
returns TRUE and EOF is undefined.
See the "HP Pascal Language Reference Manual" for complete
information on the LOCATE procedure.
6.4 – UPDATE
The UPDATE procedure writes the contents of the file buffer into
the current component.
Syntax:
UPDATE( file_variable[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file whose component is to be updated.
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 must be in inspection mode before UPDATE is called; it
remains in that mode after the procedure's execution.
The UPDATE procedure is legal for files that have been opened
for random access ("direct" or "keyed"). The current component
must already have been locked by a successful FIND, FINDK, GET,
RESET, or RESETK procedure before the contents of the file
buffer can be rewritten into it. After the update has taken
place, the component is unlocked and UFB returns TRUE.
See the "HP Pascal Language Reference Manual" for complete
information on the UPDATE procedure.
7 – Keyed Access
Keyed access procedures are legal only on files opened for keyed access.
7.1 – FINDK
The FINDK procedure searches the index of an indexed file opened
for keyed access and locates a specific component.
Syntax:
FINDK( file_variable, key-number, key-value[[, match-type]]
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file to be searched.
The 'key-number' is a positive integer expression that indicates
the key position.
The 'key-value' is an expression that indicates the key to be
found. It must be assignment compatible with the key field in
the specified key position.
The 'match-type' is an identifier that indicates the
relationship between the key value in the FINDK procedure call
and key value of a component.
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.
When you establish key fields with the KEY attribute, you assign
each one a key number from 0 to 254. Key number 0 represents
the mandatory primary key of the file. Separate indexes are
built for each key number in the file.
The key value and the match type provide information about the
key to be found. The key value must be assignment compatible
with the key fields of the key number being searched. The match
type must be EQL (equal to the key value), NXT (the next key in
the collating sequence after the key value), or NXTEQL (the next
or equal key in the collating sequence after the key value).
If the FINDK procedure was used on an ascending collating
sequence, NXT and NXTEQL would be equivalent to GTR and GEQ. If
a descending collating sequence was used, it would be the same
as LSS and LEQ. The match type is optional; if omitted, it
defaults to EQL.
The FINDK procedure can be called for any indexed file opened
for keyed access, regardless of the file's mode. If the
component described exists, the file buffer is filled with that
component; UFB and EOF both become FALSE. The mode is set to
inspection and the component is automatically locked. If no
component is found to match the description, UFB becomes TRUE
and EOF is undefined. The mode is set to undefined.
See the "HP Pascal Language Reference Manual" for complete
information on the FINDK procedure.
7.2 – RESETK
The RESETK procedure, like the RESET procedure, readies a file
for reading.
Syntax:
RESETK( file_variable, key-number[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the input file.
The 'key-number' is a positive integer expression that indicates
the key position.
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 RESETK is called to set the
mode to inspection.
RESETK can be applied only to indexed files opened for random
access by key. You assign a key number from 0 to 254 to each
key field of a file component with the KEY attribute. The file
is searched for the component with the lowest value in the
specified key number. This component becomes the current
component in the file and is locked. The value of the current
component is copied into the file buffer; EOF and UFB are set to
FALSE. If the component does not exist, EOF and UFB become
TRUE.
Note that a RESETK procedure on key number 0 is equivalent to a
RESET procedure.
See the "HP Pascal Language Reference Manual" for complete
information on the RESETK procedure.