HP OpenVMS Systems Documentation

HP Pascal for OpenVMS
Language Reference Manual

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.

file_variable

The name of the file variable associated with the file from which a component is to be deleted.

error-recovery

The action to be taken if an error occurs during execution of the routine.

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.

Consider the following example:

DELETE( Accounts_Payable );

This procedure call deletes the current component. When the component has been deleted, it is unlocked and UFB( Accounts_Payable ) returns TRUE. A run-time error occurs if the current component of Accounts_Payable is not locked.

For More Information:

• On file organizations ( Section 9.1)
• On component access ( Section 9.3)
• On the UFB function ( Section 9.8.21)
• On the error-processing parameter ( Section 9.7)

The EOF function indicates whether the file pointer is positioned after the last component in a file by returning a Boolean value.

file_variable

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 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 try 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 try to read a file after EOF becomes TRUE, an error results.

Consider the following example:

Coupons := 0;
WHILE NOT EOF DO
    BEGIN
    READLN( Coupon_Amount );
    Coupons := Coupons + Coupon_Amount;
    END;

This example calculates the total value of the coupons contained in the file INPUT. The loop is performed while the EOF function returns FALSE.

For More Information:

• On component access ( Section 9.3)
• On the error-processing parameter ( Section 9.7)
• On retrieval of file components ( Section 9.5.3)

The EOLN function tests for the end-of-line marker within a text file and returns a Boolean value.

file_variable

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.

Consider the following example:

WHILE NOT EOF( Master_File ) DO
    BEGIN
    WHILE NOT EOLN( Master_File ) DO
        BEGIN
        READ( Master_File, x );
        IF NOT (x IN ['A'..'Z','a'..'z','0'..'9'])
        THEN
             Err := Err + 1;
        END;
    READLN( Master_File );
    END;

This example scans the characters on each line of a TEXT file called Master_File and checks for characters that are neither digits nor letters. If a nonnumeric or nonalphabetic character is encountered in the file, the counter Err is incremented by 1. The loop is executed until the last component in the file is read.

For More Information:

On TEXT files ( Section 9.5)

9.8.5 EXTEND Procedure

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.

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 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.

Consider the following example:

VAR
   f : FILE OF INTEGER;
{In the executable section:}

OPEN( File_Variable := f,
      File_Name     := 'sample.dat',
      History       := OLD,
      Organization  := Relative,
      Access_Method := Direct; );

EXTEND( f );
F^ := 20;
PUT( f );

These statements open an existing relative file named sample.dat. The file will be positioned after the last record in the file. Subsequent PUT statements will append new components to the end of the file.

For More Information:

• On component access ( Section 9.3)
• On default values for the OPEN procedure ( Section 9.8.11)
• On the error-processing parameter ( Section 9.7)

The FIND procedure positions a file at a specified component. The file must be open for direct access and must contain fixed-length components.

file_variable

The name of a file variable associated with a file that is open for direct access.

component-number

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.

error-recovery

The action to be taken if an error occurs during execution of the routine.

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.

Consider the following example:

FIND( Albums, Current + 2 );

If the value of Current is 6, this procedure causes the file position to move to the eighth component; the file buffer variable Albums^ assumes the value of the component. If no eighth component exists, Albums^ is undefined and UFB (Albums) returns TRUE.

For More Information:

• On component access ( Section 9.3)
• On the UFB function ( Section 9.8.21)
• On the error-processing parameter ( Section 9.7)

The FINDK procedure searches the index of an indexed file opened for keyed access and locates a specific component.

   FINDK( file_variable, key-number, key-value[[, match-type]]
      [[, ERROR := error-recovery]] );

file_variable

The name of the file variable associated with the file to be searched.

key-number

A positive integer expression that indicates the key position.

key-value

An expression that indicates the key to be found; it must be assignment compatible with the key field in the specified key position.

match-type

An identifier that indicates the relationship between the key value in the FINDK procedure call and the key value of a component.

error-recovery

The action to be taken if an error occurs during execution of the routine.

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 one of the following identifiers:

• EQL---equal to the key value
• NXT---the next key in the collating sequence after the key value
• 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.

Consider the following example:

FINDK( Book_Index, 1, 35, NXTEQL );

Assuming key number 1 is ascending, this procedure searches the index for key number 1 in the file Book_Index until it finds the first component whose key value is greater than or equal to 35. If the component matching the description in the FINDK statement is found, UFB( Book_Index ) and EOF( Book_Index ) return FALSE, and the component is locked. If the component cannot be found, UFB( Book_Index ) returns TRUE, and EOF( Book_Index ) is undefined. Book_Index must be an indexed file opened for keyed access.

For More Information:

• On indexed files ( Section 9.1.3)
• On random access by key ( Section 9.3.2)
• On the UFB function ( Section 9.8.21)
• On the error-processing parameter ( Section 9.7)

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.

file_variable

The name of the file variable associated with the input file.

error-recovery

The action to be taken if an error occurs during execution of the routine.

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:

• 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.
• If the file is open for direct access, call either the RESET or the FIND procedure to position the file.
• If the file is open for keyed access, call the FINDK, RESET, or RESETK procedure to position the file.

RESET( Books );
New_Rec := Books^;
GET( Books );

Figure 9-10 File Position After GET Procedure

By using the GET procedure repeatedly, you can read sequentially through a file. When called for a file with relative organization, GET skips any nonexistent components to find the next component.

When you reach the end of the file and EOF returns TRUE, a GET procedure results in a run-time error.

Consider the following example:

GET( Phones );

This example reads the next component of the file Phones into the file buffer variable Phones^. Prior to executing GET, the value of EOF (Phones) must be FALSE; if it is TRUE, an error occurs.

For More Information:

• On component access ( Section 9.3)
• On the UFB function ( Section 9.8.21)
• On the error-processing parameter ( Section 9.7)

The LINELIMIT procedure stops execution of the program after a specified number of lines has been written into a TEXT file.

file_variable

The name of the file variable associated with the TEXT file to which this limit applies.

n

A positive integer expression that indicates the number of lines that can be written to the file before execution terminates.

error-recovery

The action to be taken if an error occurs during execution of the routine.

The file can be in any mode before LINELIMIT is called; the file mode does not change after LINELIMIT has been executed.

HP Pascal first uses environment-specific means to determine if there is a default line limit. If there is no 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.

Consider the following example:

LINELIMIT( Debts, 100 );

Execution of the program terminates after 100 lines have been written into the text file Debts.

HP Pascal determines the default line limit by translating an environment variable or logical name as a string of decimal digits. If the environment variable or logical name has not been defined, there is no default line limit. You can override the default by calling the LINELIMIT procedure.

For More Information:

• On TEXT files ( Section 9.5)
• On the error-processing parameter ( Section 9.7)

The LOCATE procedure positions a random-access file at a particular component so that the next PUT procedure can modify that component.

file_variable

The name of the file variable associated with the file to be positioned.

component-number

A positive integer expression that indicates the relative component number of the component to be found.

error-recovery

The action to be taken if an error occurs during execution of the routine.

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. Because the LOCATE procedure does not perform an I/O operation, the value returned by the STATUS procedure is unaffected by LOCATE.

Consider the following example:

LOCATE( Accounts_Receivable, 63 );
Accounts_Receivable^ := Next_Account;
PUT( Accounts_Receivable );

The LOCATE procedure positions the file Accounts_Receivable before relative component number 63. The call UFB( Accounts_Receivable ) now returns TRUE and EOF( Accounts_Receivable ) is undefined. The assignment statement loads the file buffer with the contents of file position 63. The PUT operation writes the file buffer into file component number 63. UFB( Accounts_Receivable ) remains TRUE.

For More Information:

• On relative files ( Section 9.1.2)
• On random access by relative component number ( Section 9.3.2)
• On the UFB function ( Section 9.8.21)
• On the error-processing parameter ( Section 9.7)