The VSI Pascal I/O model provides an extensive set of predeclared routines. These routines allow you to establish files with sequential, relative, or indexed organization and process them by sequential, direct, or keyed access.
1 – General
1.1 – OPEN
The OPEN procedure opens a file and allows you to specify file
characteristics.
Syntax:
OPEN( file_variable
,[[file_name]]
,[[history]]
,[[record_length]]
,[[access_method]]
,[[record_type]]
,[[carriage_control]]
,[[organization]]
,[[disposition]]
,[[file_sharing]]
,[[user_action]]
,[[default_file_name]]
,[[ERROR := error_recovery]] )
OPEN( FILE_VARIABLE := file_variable
[[,FILE_NAME := file_name]]
[[,HISTORY := history]]
[[,RECORD_LENGTH := record_length]]
[[,ACCESS_METHOD := access_method]]
[[,RECORD_TYPE := record_type]]
[[,CARRIAGE_CONTROL := carriage_control]]
[[,ORGANIZATION := organization]]
[[,DISPOSITION := disposition]]
[[,SHARING := file_sharing]]
[[,USER_ACTION := user_action]]
[[,DEFAULT := default_file_name]]
[[,ERROR := error_recovery]] )
Before the OPEN procedure is called, the file is in undefined
mode; its mode does not change after OPEN has been executed.
You cannot use OPEN on a file variable that is already open.
If you use INPUT or OUTPUT, VSI Pascal implicitly opens them
just before their first use. VSI Pascal implicitly opens INPUT
with a history of READONLY. If you choose, you can explicitly
open INPUT or OUTPUT; to do this, call the OPEN procedure at any
point in your compilation unit before you use the first I/O
routine on that file.
Because the RESET, REWRITE, and EXTEND procedures implicitly
open files, you need not always use the OPEN procedure. RESET,
REWRITE, and EXTEND impose the same defaults as OPEN, except
where noted (in the HISTORY parameter).
You must use the OPEN procedure to create a TEXT file with
fixed-length components, to create a file with relative or
indexed organization, to open a file for direct or keyed access,
or to specify a line length other than the default for a line in
a TEXT file.
See the "HP Pascal Language Reference Manual" for the complete
description of the OPEN procedure.
1.1.1 – File Variable
The 'file_variable' is the only required parameter. It is the name of the file variable associated with the file that HP Pascal is to open.
1.1.2 – File Name
The 'file_name' is a character-string expression containing the external file name. VSI Pascal determines the default file name according to the environment in which you are programming.
1.1.3 – History
The 'history' is a value that indicates whether the file exists or if VSI Pascal must create the file. If you specify OLD and if VSI Pascal cannot find the file, an error occurs. If you specify READONLY, you can only read from the file; if you attempt to write to the file, an error occurs. If you specify UNKNOWN, VSI Pascal looks for an existing file but creates a new file if there is no existing file. If you specify OLD or UNKNOWN and if the attempt to open the file generates a file protection error, VSI Pascal tries again using READONLY. NEW is the default for OPEN/REWRITE openings, while OLD is the default for EXTEND/RESET openings.
1.1.4 – Record Length
The 'record-length' is a positive integer that specifies the
maximum size in bytes for a line in a TEXT file or a file of
type FILE OF VARYING. ("Record" length is equivalent to
"component" length.) The default is 255 bytes. For all other
types of files, VSI Pascal ignores this parameter.
If you do not specify a length for an existing file, VSI Pascal
uses the length specified at the file's creation.
If you use OPEN to create a sequentially organized file with
variable-length components, VSI Pascal records the maximum
length of each component in the file only if you specify a value
for the record_type field.
1.1.5 – Access Method
The 'access_method' is a value that specifies the component access method to use. The possible values include SEQUENTIAL, DIRECT, and KEYED. The DIRECT access method is equivalent to random access by relative component number. The KEYED access method is equivalent to random access by key. The default is SEQUENTIAL.
1.1.6 – Record Type
The 'record_type' is a value that indicates the component
format. ("Record" format and "component" format are
equivalent.) The available values are FIXED (fixed-length
components), VARIABLE (variable-length components), STREAM
(stream component format with either carriage return,
combination carriage return and line feed, or form feed
delimiters), STREAM_CR (stream component format with carriage
return delimiters), and STREAM_LF (stream component format with
line feed delimiters).
VARIABLE is the default for new TEXT and VARYING OF CHAR, while
FIXED is the default for other new files.
1.1.7 – Carriage Control
The 'carriage_control' is a value that indicates the carriage control format for the file. The value LIST indicates single spacing between components. The values CARRIAGE and FORTRAN are equivalent and indicate that the first character of every output line is a carriage control character. The values NONE and NOCARRIAGE indicate that the file has no carriage control. LIST id the default for TEXT and VARYING OF CHAR files, while NONE is the default for all other file types.
1.1.8 – Organization
The 'organization' is a value that specifies the file
organization. If you are accessing an existing file, the
specified organization must match the organization of the
existing file; if it does not, an error occurs. The choices for
this parameter are SEQUENTIAL, RELATIVE, and INDEXED. The
default is SEQUENTIAL. The parameter choices are as follows:
o SEQUENTIAL file organization specifies that file components
are stored one after the other, in the order in which they
were entered into the file. VSI Pascal supports this
organization for files on disk. This is the only
organization supported for files on magnetic tape, on
terminals, on card readers, and on line printers.
o RELATIVE file organization consists of a series of
fixed-length component positions (cells) numbered
consecutively from 1 to n. The numbered, fixed-length cells
enable VSI Pascal to calculate the component's physical
position in the file. The cell numbers are called relative
component numbers. VSI Pascal supports this organization on
disk files only.
o INDEXED file organization specifies that, in addition to the
stored components, there exists at least a primary key and
possibly alternate keys (first alternate key, second
alternate key, and so forth). VSI Pascal uses the primary
key to store components and uses a program-specified key or
keys to retrieve data. VSI Pascal supports this
organization on disk files only.
1.1.9 – Disposition
The 'disposition' is a value that indicates what VSI Pascal should do with the file after you close the file. If SAVE is specified, the file is retained. If DELETE is specified, the file is deleted. If PRINT is specified, the file is printed on a line printer and is retained. If PRINT_DELETE is specified, the file is deleted after it is printed. If SUBMIT is specified, the file is submitted to a queue or placed in a background process and is retained. If SUBMIT_DELETE is specified, the file is deleted after being processed. SAVE is the default for external files. DELETE is the default for internal files.
1.1.10 – Sharing
The 'sharing' is a value that specifies whether other programs can access the file while it is open. A value of READONLY indicates that other programs can read but not write to the file. This is the default value for files with HISTORY := READONLY. READWRITE indicates that other programs can read and write to the file when it is open. A value of NONE denies any access to the file while it is open. This is the default value for all other histories.
1.1.11 – User Action
The 'user_action' is the name of a user-written routine that VSI Pascal calls to open the file (instead of allowing VSI Pascal to open the file with the OPEN procedure). You can use a user-action routine to open the file using environment-specific capabilities of the I/O system underlying HP Pascal.
1.1.12 – Default
The 'default' is a string expression containing default file specification information. For instance, you can use this value to set a default directory specification.
1.1.13 – Error Recovery
The 'error_recovery' specifies the action the program should take if an error occurs during execution of the routine. By default, after the first error, the error message is printed and execution is stopped.
1.2 – CLOSE
The CLOSE procedure closes an open file.
Syntax:
CLOSE( file_variable
,[[disposition]]
,[[user_action]]
,[[ERROR := error_recovery]] )
CLOSE( FILE_VARIABLE := file_variable
[[,DISPOSITION := disposition]]
[[,USER_ACTION := user_action]]
[[,ERROR := error_recovery]] )
Except for the file variable parameter, all other parameters are
optional. If the nonpositional parameter names are not used, as
in the first syntax, the parameters must be in the order
specified. If nonpositional parameter names are used, as in the
second syntax, the parameters can be specified in any order.
1.2.1 – File Variable
The 'file_variable' is the name of the file variable associated with the file that VSI Pascal is to close.
1.2.2 – Disposition
The 'disposition' is a value that indicates what VSI Pascal should do with the file after you close the file. If SAVE is specified, the file is retained. If DELETE is specified, the file is deleted. If PRINT is specified, the file is printed on a line printer and is retained. If PRINT_DELETE is specified, the file is deleted after it is printed. If SUBMIT is specified, the file is submitted to a queue or placed in a background process and is retained. If SUBMIT_DELETE is specified, the file is deleted after being processed. SAVE is the default for external files. DELETE is the default for internal files. The disposition value in the CLOSE procedure supersedes a disposition value in the OPEN procedure.
1.2.3 – User Action
The 'user_action' is a routine name that VSI Pascal calls to close the file. You can use a user-action routine to close the file using environment-specific capabilities.
1.2.4 – Error Recovery
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. Execution of the CLOSE procedure causes the system to close the file and, if the file is internal, to delete it. Each file is automatically closed when control passes from the block in which it is declared. You cannot close a file that has not been opened (either explicitly by the OPEN procedure, or implicitly by the EXTEND, RESET, or REWRITE procedure). If you attempt to close a file that was never opened, an error occurs. The file can be in any mode (inspection, generation, or undefined) before the CLOSE procedure is called. Execution of CLOSE sets the mode to undefined.
2 – Seq Access Input
The sequential access input procedures are procedures used on files opened for sequential access, but they can also be used on files opened for direct and keyed access.
2.1 – GET
The GET procedure advances the file position and reads the next
component of the file into the file buffer variable. If the
file has relative or indexed organization, the component is also
locked to prevent access by other processes.
Syntax:
GET( file_variable [[,ERROR := error-recovery]] );
The 'file_variable' is the name associated with the input 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.
Before the GET procedure is used for the first time to read one
or more file components, the file must be in inspection mode and
prepared for reading input. Depending on the access method
specified when the file was opened, you can prepare the file for
input in the following ways:
o If the file is open for sequential access, call the RESET
procedure. RESET sets the mode to inspection, advances the
file position to the first component, and assigns the
component's value to the file buffer variable.
o If the file is open for direct access, call either the RESET
or the FIND procedure to position the file.
o If the file is open for keyed access, call the FINDK, RESET,
or RESETK procedure to position the file.
As a result of the GET procedure, the file remains in inspection
mode, and the file position advances to the next component. If
a component is found other than the end-of-file marker, the
component is locked, EOF is set to FALSE, the file buffer
variable takes on the value of the component, and UFB is set to
FALSE. If a component is not found or the end of the file is
reached, EOF and UFB are set to TRUE. If the GET procedure
fails, UFB is set to TRUE and EOF becomes undefined.
See the "HP Pascal Language Reference Manual" for the complete
description of the GET procedure.
2.2 – READ
The READ procedure reads one or more file components into a
variable.
Syntax:
READ( [[file_variable,]] {variable-identifier
[[:radix-specifier]]},... [[, ERROR := error-recovery]] );
The 'file_variable' is the name associated with the input file.
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.
The 'radix-specifier' is one of the format values BIN, OCT, or
HEX. These values, when used on a variable identifier, will
read the variable in binary, octal, or hexadecimal radix
respectively. You can use a radix specifier only when reading
from a TEXT file.
The 'error-recovery' is 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 READ is called. The
file remains in inspection mode after execution of a READ
procedure.
By definition, the READ procedure for a nontext file performs an
assignment statement, a GET procedure, and an UNLOCK procedure
for each variable.
The READ procedure reads from the file until it has found a
value for each variable in the list. The first value read is
assigned to the first variable in the list, the second value
read is assigned to the second variable, and so on. The values
and the variables must be of assignment-compatible types.
Reading stops if an error occurs.
For a TEXT file, more than one component (character) can be read
into a single variable. For example, many characters can be
read into a string or converted into a numeric variable. The
READ procedure repeats the assignment, GET, and UNLOCK process
until it has read a sequence of characters that represent a
legal value for the next variable in the parameter list. The
procedure continues to read components from the file until it
has assigned a value to each variable in the list.
See the "HP Pascal Language Reference Manual" for a complete
description of the READ procedure.
2.3 – RESET
The RESET procedure readies a file for reading.
Syntax:
RESET( file_variable [[, file_name]]
[[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the input file. You do not need this argument if the file
was opened with the OPEN procedure.
The 'file_name' represents the string expression to be
associated with the 'file_variable'. If the file was previously
opened with the OPEN procedure, 'file_name' is ignored.
The 'error-recovery' represents 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 you call RESET; a call to
RESET sets the file to inspection mode. If the file is an
external file and is not already open, RESET opens it using the
same defaults as the OPEN procedure. You cannot use RESET to
create a file.
After execution of RESET, the file is positioned at the first
component, and the file buffer variable contains the value of
this component. If the file is not empty, EOF and UFB return
FALSE and the first component is locked to prevent access by
other processes. If the file is empty, EOF and UFB return TRUE.
If the file does not exist, RESET does not create it, but
returns an error at run time.
You should call RESET before reading any file with sequential
organization except the predeclared file INPUT. The RESET
procedure removes the end-of-file marker from any file connected
to a terminal device (including INPUT), thus allowing reading
from the file to continue. If you call RESET for the
predeclared file OUTPUT, an error occurs.
A call to RESET on a relative file opened for direct access
positions the file at its first existing component.
A call to RESET on an indexed file opened for keyed access
positions the file at the first component relative to the
primary key.
See the "HP Pascal Language Reference Manual" for a complete
description of the RESET procedure.
3 – Seq Access Output
The sequential access output procedures apply primarily to files opened for sequential access; but can also be used on direct and keyed access files.
3.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.
3.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.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.
3.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.
4 – Misc
The miscellaneous routines are generally used when dealing with sequential access files. In some cases, they can be used on direct or keyed access files.
4.1 – EOF
The EOF (end of file) function indicates whether the file
pointer is positioned after the last component in a file by
returning a Boolean value.
Syntax:
EOF[[( file_variable )]]
The 'file_variable' is the name of the file variable associated
with the input file. If you omit the name of the file, the
default is INPUT.
The file can be in either inspection or generation mode before
EOF is called; however, end-of-file must be defined. The input
operations GET, RESET, and FINDK are guaranteed to leave
end-of-file defined. The file mode does not change after EOF
has been executed.
EOF returns TRUE when the file pointer is positioned after the
last component in the file, and returns FALSE up to and
including the time when the last component of the input file is
read into the file buffer. You must attempt to retrieve another
file component after the last to determine whether the file is
positioned at end-of-file.
When EOF is tested for a file with relative organization opened
for direct access, the result is TRUE if the file is in
inspection mode and the last GET or RESET operation positioned
the file beyond the last existing component. If the file is in
generation or undefined mode, the result of EOF is undefined.
When EOF is tested for a file with indexed organization opened
for keyed access, the result is TRUE if the file is in
inspection mode and the last FINDK, GET, RESET, or RESETK
operation positioned the file beyond the last component with the
current key number. Successful attempts at FINDK, GET, RESET,
and RESETK cause EOF to be FALSE. If the file is not in
inspection mode, EOF is undefined.
If you attempt to read a file after EOF becomes TRUE, an error
occurs.
See the "HP Pascal Language Reference Manual" for a complete
description of the EOF function.
4.2 – STATUS
The STATUS function indicates the status of a file following the
last operation performed on it.
Syntax:
STATUS( file_variable )
The 'file_variable' is the name of the file variable associated
with the file to be tested.
The file can be in any mode before STATUS is called; unless an
error occurs, STATUS does not change the file mode upon
execution.
The STATUS function returns integer codes indicating the
previous operation's effect on the file. If the operation is
successful, 0 is returned. If end-of-file is encountered, -1 is
returned. If an error is encountered, a positive integer is
returned. (The actual number is environmental specific and
indicates the exact error that occured.)
A test by the STATUS function on a TEXT file causes delayed
device access to occur, thus filling the file buffer with the
next file component. Therefore, EOF, EOLN, UFB, and STATUS
never return an error code following a successful STATUS
function call.
See the "HP Pascal Language Reference Manual" for a complete
description of the STATUS function.
4.3 – TRUNCATE
The TRUNCATE procedure indicates that the current file component
and all components following it are to be deleted. TRUNCATE can
only be used on a file that has sequential organization.
Syntax:
TRUNCATE( file_variable [[, ERROR := error-recovery]] );
The 'file_variable' is the name of the file variable associated
with the file to be truncated.
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 TRUNCATE is called.
After the procedure has been executed, the mode is set to
generation so that you can write to the file.
After the appropriate components have been deleted, the file
remains positioned at the new end-of-file, but the file buffer
itself is undefined. Thus, EOF and UFB are both set to TRUE.
See the "HP Pascal Language Reference Manual" for a complete
description of the TRUNCATE procedure.
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.