|
HP OpenVMS Systems Documentation |
|
HP Pascal for OpenVMS
|
| Previous | Contents | Index |
The READLN procedure reads lines of data from a TEXT file.
READLN [[( [[file_variable,]] {variable-identifier [[:radix-specifier]]},...
[[, ERROR := error-recovery]] )]];
|
file_variable
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.variable-identifier
The name of the variable into which a value will be read; multiple identifiers must be separated with commas. If you do not specify any variable names, READLN skips a line in the specified file.radix-specifier
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.error-recovery
The action to be taken if an error occurs during execution of the routine.
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.
When applied to several variables, READLN performs the following sequence:
READ( file_variable, {variable-identifier},... );
READLN( file_variable );
|
EOLN returns TRUE after a READLN procedure only if the new line is empty.
You can use the READLN procedure to read integers, real numbers, Booleans, constants of enumerated types. the file must be separated as for the READ procedure. The rules governing the reading of values from text files are presented with the READ procedure.
Consider the following example:
TYPE
String = PACKED ARRAY[1..20] OF CHAR;
VAR
Names : TEXT;
Pres, Veep : String;
{In the executable section:}
READLN( Names, Pres, Veep );
|
This program fragment declares and reads the file Names, which contains the following characters:
John F. Kennedy Lyndon B. Johnson Lyndon B. Johnson <EOLN> Hubert H. Humphrey <EOLN> Richard M. Nixon Spiro T. Agnew <EOLN> <EOLN> <EOF> |
The READLN procedure reads the values 'John F. Kennedy ' for Pres and 'Lyndon B. Johnson ' for Veep. It then skips to the next line, ignoring the remaining characters on the first line. Subsequent execution of the procedure assigns the value 'Hubert H. Humphrey ' to Pres and the space detected as the end-of-line marker to Veep. A third call to the procedure reads 'Richard M. Nixon ' into Pres and 'Spiro T. Agnew ' into Veep. The procedure then skips past the end-of-line marker to the beginning of the next line. If you call READLN again, EOF becomes TRUE, and EOLN becomes undefined.
The READLN procedure is implemented as one or more READ calls followed by a READLN call. A STATUS call after a READLN procedure tests if the file was properly positioned, not whether the last READ was successful. To test if READLN successfully read data, replace the call to READLN with an explicit call to READ to read the line, then call STATUS to test the results of the READ, and finally call READLN to advance the file buffer variable for the next READLN.
The RESET procedure puts a file into inspection mode, in which it can be read.
|
RESET( file_variable [[, file_name]] [[, ERROR := error-recovery]] |
file_variable
The name of the file variable associated with the input file.file_name
String expression for the file name to be associated with the file_variable. If the file is already open, an error is signaled.error-recovery
The action to be taken if an error occurs during execution of the routine.
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.
A call to RESET on a sequential file positions the file 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 must 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), which allows reading from the file to
continue. If you call RESET for the predeclared files OUTPUT or ERR, 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.
Consider the following example:
VAR
f : FILE OF INTEGER;
{In the executable section:}
OPEN( f , 'file.dat', ACCESS_METHOD := DIRECT );
RESET( f );
|
The OPEN call opens the file variable f for direct access. The RESET call positions the file at the first component and is necessary whether the file is new or old. After execution of the OPEN and RESET procedures, you can use the FIND procedure for direct access to the components of the file. For example:
RESET( Weights ); |
If the file variable Weights is already open, this procedure call prepares it for reading and assigns the value of the first file component to Weights^. If the file is not open, RESET causes HP Pascal to open the file by default. If Weights is an external file, its file history will be OLD. If Weights does not exist, an error occurs.
The RESETK procedure puts an indexed file into inspection mode, in which it can be read. RESETK can be applied only to indexed files opened for random access by key.
|
RESETK( file_variable, key-number[[, ERROR := error-recovery]] ); |
The name of the file variable associated with the input file.file_variable
The file can be in any mode before RESETK is called to set the mode to inspection.
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.
Consider the following example:
RESETK( Book_Index, 0 ); |
This procedure searches the file Book_Index for the component with the lowest value in the primary key. If this component exists, it becomes the current file component and is locked. The function calls UFB( Book_Index ) and EOF( Book_Index ) returns FALSE. If the procedure was unable to find the component, UFB( Book_Index ) and EOF( Book_Index ) return TRUE.
The REWRITE procedure puts a file into generation mode in which it can be written.
|
REWRITE( file_variable [[, file_name]] [[, ERROR := error-recovery]] |
file_variable
The name of the file variable associated with the output file.file_name
String expression for the file name to be associated with the file_variable. If the file is already open, an error is signaled.error-recovery
The action to be taken if an error occurs during execution of the routine.
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 sequential files 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.
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.
Consider the following example:
REWRITE( Storms ); |
If the file variable Storms is already open, this REWRITE procedure prepares the file for writing, clears it of old data, and sets the file position to the beginning of the file. If Storms is not open, a new version is created with the same defaults as for the OPEN procedure.
Consider the following example:
VAR
Ratings : FILE OF INTEGER;
{In the executable section:}
OPEN( Ratings, 'cars.dat', HISTORY := OLD, RECORD_TYPE := FIXED );
REWRITE( Ratings );
|
The OPEN procedure opens the file variable Ratings, which is associated with the file cars.dat. The REWRITE procedure discards the current contents of the file f and sets the file position to the beginning of the file. After execution of this procedure, EOF( Ratings ) returns TRUE.
The STATUS function indicates the status of a file following the last operation performed on it. The LOCATE procedure does not perform an operation, but sets internal data in the run-time library for use by future operations. Therefore, this procedure does not affect the result of the STATUS function.
|
STATUS(file_variable ) |
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 one of the following integer codes that
indicate the previous operation's effect on the file:
The name of the file variable associated with the file to be tested.
file_variable
| Code | Description |
|---|---|
| 0 | Successful operation |
| -1 | End-of-file encountered |
| Positive integer 1 | Error encountered |
A test by the STATUS function on a TEXT file causes delayed device access to occur, which fills 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.
Consider the following example:
RESET( File1, ERROR := CONTINUE ); IF STATUS( File1 ) > 0 THEN WRITELN( 'Cannot access first record' ) ELSE IF STATUS( File1 ) < 0 THEN WRITELN( 'File is empty' ) ELSE READ( File1 ); |
If the RESET procedure encounters either an error condition or an end-of-file, an appropriate error message is displayed. If the STATUS function indicates that the RESET procedure was successful, the first record is read from the file.
The TRUNCATE procedure indicates that the current file component and all components following it are to be deleted. You can only use TRUNCATE on a file that has sequential organization.
|
TRUNCATE( file_variable [[, ERROR := error-recovery]] ); |
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.
Consider the following example:
The name of the file variable associated with the file to be truncated.
file_variable
error-recovery
The action to be taken if an error occurs during execution of the
routine.
TRUNCATE( Master_File ); |
This procedure deletes components from Master_File, beginning with the current component and continuing until EOF returns TRUE. When the operation is complete, EOF( Master_File ) and UFB( Master_File ) are TRUE, and new data can be written at the end of Master_File.
The UFB (Undefined File Buffer) function returns a Boolean value to indicate whether the last file operation gave the file buffer an undefined status.
|
UFB( file_variable ) |
The file can be in any mode before UFB is called, the execution of UFB
does not change the file mode.
UFB tests the effect of the last I/O operation on 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 due to the data not being
present in the file set UFB to TRUE. GET, FIND, FINDK, RESET, and
RESETK procedure calls that could not examine the file leave UFB in an
unknown state. You must use the STATUS builtin to determine if the GET,
FIND, FINDK, RESET, and RESETK procedure calls were able to examine the
contents of the file. 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. Consider the following example:
The name of the file variable associated with the file whose buffer is
being tested.
file_variable
FIND( Supplies, December ); IF NOT UFB( Supplies ) THEN Inventory := Inventory - Supplies^; |
If the variable December has a value of 12, the FIND procedure attempts to find the twelfth component of the file Supplies. If the FIND procedure is successful, Supplies^ assumes the value of this component and UFB( Supplies ) is FALSE. If, however, the FIND procedure is unable to find the twelfth component of the file, UFB( Supplies ) returns TRUE. In this example, the value of Supplies^ is subtracted from the value of Inventory only if the FIND procedure is successful.
The UNLOCK procedure releases the current file component for access by other processes.
|
UNLOCK( file_variable [[, ERROR := error-recovery]] ); |
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.
Consider the following example:
The name of the file variable associated with the file whose component
is to be unlocked.
file_variable
error-recovery
The action to be taken if an error occurs during execution of the
routine.
UNLOCK( Sales_File ); |
The UNLOCK procedure releases the contents of the current component.
On the error-processing parameter ( Section 9.7)
The UPDATE procedure writes the contents of the file buffer into the
current component.
9.8.23 UPDATE Procedure
|
UPDATE( file_variable[[, ERROR := error-recovery]] ); |
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.
Consider the following example:
The name of the file variable associated with the file whose component
is to be updated.
file_variable
error-recovery
The action to be taken if an error occurs during execution of the
routine.
UPDATE( October_Sales ); |
This procedure writes the file buffer contents (October_Sales^) back into the current file component October_Sales. The component is then unlocked and UFB( October_Sales) returns TRUE.
| Previous | Next | Contents | Index |