HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

The FIELD statement dynamically associates string variables with all or parts of a record buffer. FIELD statements do not move data. Instead, they permit direct access through string variables to sections of a specified record buffer.

Format

#chnl-exp, int-exp AS str-var[ , int-exp AS str-var ]...

Syntax Rules

• Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#). A file must be open on the specified channel or HP BASIC signals an error.
• Int-exp specifies the number of characters in str-var. However, a subsequent int-exp cannot depend on the return string from a previous int-exp. For example, the following statement is illegal because the second int-exp depends on the return string A$:

  FIELD #1%, 1% AS A$, ASCII(A$) AS B$

Remarks

• A FIELD statement is executable. You can change a buffer description at any time by executing another FIELD statement. For example:

  FIELD #1%, 40% AS whole_field$ FIELD #1%, 10% AS A$, 10% AS B$, 10% AS C$, 10% AS D$

  
  The first FIELD statement associates the first 40 characters of a buffer with the variable whole_field$. The second FIELD statement associates the first 10 characters of the same buffer with A$, the second 10 characters with B$, and so on. Later program statements can refer to any of the variables named in the FIELD statements to access specific portions of the buffer.
• You cannot define virtual array strings as string variables in a FIELD statement.
• A variable named in a FIELD statement cannot be used in a COMMON or MAP statement, as a parameter in a CALL or SUB statement, or in a MOVE statement.
• Attempting to access an element of a virtual array in a virtual file that has associated FIELD variables, causes BASIC to signal "Illegal operation" (ERR=141).
• If you name an array in a FIELD statement, you cannot use MAT statements in the following format:

  MAT array-name1 = array-name2 MAT array-name1 = NUL$

  
  where array-name1 is named in a FIELD statement. This causes HP BASIC to signal a compile-time error.

Example

FIELD #8%, 2% AS U$, 2% AS CL$, 4% AS X$, 4% AS Y$ LSET U$ = CVT%$(U%) LSET CL$ = CVT%$(CL%) LSET X$ = CVTF$(X) LSET Y$ = CVTF$(Y) U% = CVT$%(U$) CL% = CVT$%(CL$) X = CVT$F(X$) Y = CVT$F(Y$)

The FIND statement locates a specified record in a disk file and makes it the current record for a GET, UPDATE, or DELETE operation. FIND statements are valid on RMS sequential, relative, and indexed files.

Format

Syntax Rules

• Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
• If you specify a lock-clause, it must follow the position-clause. If the lock-clause precedes the position-clause, HP BASIC signals an error.
• If you specify the REGARDLESS lock-clause, you cannot specify another lock-clause in the same FIND statement.

Remarks

• Position-clause
  • Position-clause specifies the position of a record in a file. HP BASIC signals an error if you specify a position-clause and the channel is not associated with a disk file. If you do not specify a position-clause, FIND locates records sequentially. Sequential record access is valid on all files.
  • The RFA position-clause allows you to randomly locate records by specifying the record file address (RFA) of a record. You specify the disk address of a record, and RMS locates the record at that address. All file organizations can be accessed by RFA.
    Rfa-exp in the RFA position-clause is a variable of the RFA data type that specifies the record's file address. Note that an RFA expression can only be a variable of the RFA data type or the GETRFA function. Use the GETRFA function to find the RFA of a record.
  • The RECORD position-clause allows you to randomly locate records in relative and sequential fixed files by specifying the record number.
    • Rec-exp in the RECORD position-clause specifies the number of the record you want to locate. It must be between 1 and the number of the record with the highest number in the file.
    • When you specify a RECORD clause, chnl-exp must be a channel associated with an open relative or sequential fixed file.
  • The KEY position-clause allows you to randomly locate records in indexed files by specifying a key of reference, a relational test, and a key value.
  • An RFA value is valid only for the life of a specific version of a file. If a new version of a file is created, the RFA values may change.
  • Attempting to access a record with an invalid RFA value results in a run-time error.
• Lock-clause
  • Lock-clause allows you to control how a record is locked to other access streams, to override lock checking when accessing shared files that may contain locked records, or to specify what action to take in the case of a locked record.
  • The type of lock you impose on a record remains in effect until you explicitly unlock it with a FREE or UNLOCK statement, until you close the file, or until you perform a GET, FIND, UPDATE or DELETE on the same channel (unless you specified UNLOCK EXPLICIT).
  • The REGARDLESS lock-clause specifies that the FIND statement can override lock checking and locate a record locked by another program.
  • When you specify a REGARDLESS lock-clause, HP BASIC does not impose a lock on the retrieved record.
  • The ALLOW lock-clause lets you control how a record is locked to other users and access streams. The file associated with the specified channel must have been opened with the UNLOCK EXPLICIT clause or HP BASIC signals the error "Illegal record locking clause."
  • The ALLOW allow-clause can be one of the following:
    • ALLOW NONE denies access to the record. This means that other access streams cannot retrieve the record unless they bypass lock checking with the GET REGARDLESS clause.
    • ALLOW READ provides read access to the record. This means that other access streams can retrieve the record but cannot use the DELETE or UPDATE statements on the record.
    • ALLOW MODIFY provides read and write to the record. This means that other access streams can use the GET, FIND, DELETE, and UPDATE statements on the record.
  • If you do not open a file with the ACCESS READ clause or specify an allow-clause, locking is imposed as follows:
    • If the file associated with the specified channel was opened with UNLOCK EXPLICIT, HP BASIC imposes the ALLOW NONE lock on the retrieved record and the next GET or FIND operation does not unlock the previously locked record.
    • If the file associated with the specified channel was not opened with UNLOCK EXPLICIT, HP BASIC locks the retrieved record and unlocks the previously locked record.
  • The WAIT lock-clause accepts an optional int-exp. Int-exp represents a timeout value in seconds. Int-exp must be from 0 through 255 or HP BASIC signals a warning message.
    • WAIT followed by a timeout value causes RMS to wait for a locked record for a given period of time.
    • WAIT followed by no timeout value indicates that RMS should wait indefinitely for the record to become available.
    • If you specify a timeout value and the record does not become available within that period, HP BASIC signals the run-time error "Keyboard wait exhausted" (ERR=15). VMSSTATUS and RMSSTATUS then return RMS$_TMO. For more information about the RMSSTATUS and VMSSTATUS functions, see this chapter and the HP BASIC for OpenVMS User Manual.
    • If you attempt to wait for a record that another user has locked, and consequently that user attempts to wait for the record you have locked, a deadlock condition occurs. When a deadlock condition persists for a period of time (as defined by the SYSGEN parameter DEADLOCK_WAIT), RMS signals the error "RMS$_DEADLOCK" and HP BASIC signals the error "Detected deadlock error while waiting for GET or FIND" (ERR=193).
    • If you specify a WAIT clause followed by a timeout value that is less than the SYSGEN parameter DEADLOCK_WAIT, HP BASIC signals the error "Keyboard wait exhausted" (ERR=15) even though a deadlock condition may exist.
• Key-clause
  • In a key-clause, int-exp1 is the target key of reference. It must be an integer in the range of zero to the highest-numbered key for the file. The primary key is #0, the first alternate key is #1, the second alternate key is #2, and so on. Int-exp1 must be preceded by a number sign (#) or HP BASIC signals an error.
  • When you specify a key-clause, the specified channel must be a channel associated with an open indexed file.
• Rel-op
  • Rel-op is a relational operator that specifies how key-exp is to be compared with int-exp1 in the key-clause.
    • EQ means "equal to"
    • NXEQ means "next or equal to"
    • GE means "greater than or next" (a synonym for NXEQ)
    • NX means "next"
    • GT means "greater than" (a synonym for NX)
  • A successful random FIND operation by key locates the first record whose key satisfies the key-clause comparison:
    • With an exact key match (EQ), a successful FIND locates the first record in the file that equals the key value specified in key-exp. However, if the characters specified by a str-exp key expression are less than the key length, characters specified by str-exp are matched approximately rather than exactly. For example, if you specify ABC and the key length is six characters, HP BASIC locates the first record that begins with ABC. If you specify ABCABC, HP BASIC locates only a record with the key ABCABC. If no match is possible, HP BASIC signals the error "Record not found" (ERR=155).
    • If you specify a next or equal to record key match (NXEQ), a successful FIND locates the next record that equals the key length specified in int-exp or str-exp. If no exact match exists, HP BASIC locates the next record in the key sort order. If the keys are in ascending order, the next record will have a greater key value. If the keys are in descending order, the next record will have a lesser key value.
    • If you specify a greater than or equal to key match (GE), the behavior is identical to that of next or equal to (NXEQ). (Likewise, the behavior of GT is identical to NX.) However, the use of GE in a descending key file may be confusing, because GE will retrieve the next record in the key sort order, but the next record will have a lesser key value. For this reason, it is recommended that you use NXEQ in new program development, especially if you are using descending key files.
    • If you specify a next key match (NX), a successful FIND locates the first record that follows the relational operator in the sort order. If no such record exists, HP BASIC signals the error "Record not found" (ERR=155).
• Key-exp
  • Int-exp2 specifies an integer value to be compared with the key value of a record.
  • Str-exp specifies a string value to be compared with the key value of a record. Str-exp can contain fewer characters than the key of the record you want to locate, but cannot be a null string.
    Str-exp cannot contain more characters than the key of the record you want to locate. If str-exp does contain more characters than the key, BASIC signals "Key size too large" (ERR = 145).
  • Decimal-exp in the key-clause specifies a packed decimal value to be compared with the key value of a record.
  • Quadword-exp in the key-clause specifies a record or group exactly 8 bytes long to be compared with the key value of a record.
• The file on the specified channel must have been opened with ACCESS MODIFY, ACCESS READ, or SCRATCH before your program can execute a FIND operation.
• FIND does not transfer any data to the record buffer. To access the contents of a record, use the GET statement.
• A successful sequential FIND operation updates both the current record pointers and next record pointers.
  • For sequential files, a successful FIND operation locates the next sequential record (the record pointed to by the next record pointer) in the file, changes the current record pointer to the record just found, and the next record pointer to the next sequential record. If the current record pointer points to the last record in a file, a sequential FIND operation causes HP BASIC to signal "Record not found" (ERR=155).
  • For relative files, a successful FIND operation locates the record that exists with the next higher record number (or cell number), makes it the current record, and changes the next record pointer to the current record pointer plus 1.
  • For indexed files, a successful FIND operation locates the next existing logical record in the current key of reference, makes this the current record, and changes the next record pointer to the current record pointer plus 1.
• A successful random access FIND operation by RFA or by record changes the current record pointer to the record specified by rfa-exp or int-exp, but leaves the next record pointer unchanged.
• A successful random access FIND operation by key changes the current record pointer to the first record whose key satisfies the key-clause comparison and leaves the next record pointer unchanged.
• When a random access FIND operation by RFA, record, or key is not successful, HP BASIC signals "Record not found" (ERR=155). The values of the current record pointer and next record pointer are undefined.
• You should not use a FIND statement on a terminal-format or virtual array file.

Example

DECLARE LONG rec-num MAP (cusrec) WORD cus_num & STRING cus_nam=20, cus_add=20, cus_city=10, cus_zip=9 OPEN "CUS_ACCT.DAT" FOR INPUT AS #1, & RELATIVE FIXED, & ACCESS MODIFY & MAP cusrec INPUT "Which record number would you like to delete";rec_num FIND #1, RECORD rec_num, WAIT DELETE #1 CLOSE #1 END

The FIX function truncates a floating-point value at the decimal point and returns the integer portion represented as a floating-point value.

Format

Syntax Rules

None

Remarks

• The FIX function returns the integer portion of a floating-point value, not an integer value.
• HP BASIC expects the argument of the FIX function to be a real expression. When the argument is a real expression, HP BASIC returns a value of the same floating-point size. When the argument is not a real expression, HP BASIC converts the argument to the default floating-point size and returns a value of the default floating-point size.
• If real-exp is negative, FIX returns the negative integer portion. For example, FIX(--5.2) returns --5.

Example

DECLARE SINGLE result result = FIX(-3.333) PRINT FIX(24.566), result

Output

24 -3

The FNEND statement is a synonym for the END DEF statement. See the END statement for more information.

Format

The FNEXIT statement is a synonym for the EXIT DEF statement. See the EXIT statement for more information.

Format

The FOR statement repeatedly executes a block of statements, while incrementing a specified control variable for each execution of the statement block. FOR loops can be conditional or unconditional, and can modify other statements.

Format

Syntax Rules

• Num-unsubs-var must be a numeric, unsubscripted variable. Num-unsubs-var cannot be a record field.
• Num-unsubs-var is the loop variable. It is incremented each time the loop executes.
• In unconditional FOR loops, num-exp1 is the initial value of the loop variable; num-exp2 is the maximum value.
• In conditional FOR loops, num-exp1 is the initial value of the loop variable, while the cond-exp in the WHILE or UNTIL clause is the condition that controls loop iteration.
• Num-exp3 in the STEP clause is the value by which the loop variable is incremented after each execution of the loop.

Remarks

• There is a limit to the number of inner loops you can contain within a single outer loop. This number varies according to the complexity of the loops. If you exceed the limit, HP BASIC signals an error message.
• An inner loop must be entirely within an outer loop; the loops cannot overlap.
• You cannot use the same loop variable in nested FOR loops. For example, if the outer loop uses FOR I = 1 TO 10, you cannot use the variable I as a loop variable in an inner loop.
• The default for num-exp3 is 1 if there is no STEP clause.
• You can transfer control into a FOR loop only by returning from a function invocation, a subprogram call, a subroutine call, or an error handler that was invoked in the loop.
• The starting, incrementing, and ending values of the loop do not change during loop execution.
• The loop variable can be modified inside the FOR loop.
• HP BASIC converts num-exp1, num-exp2, and num-exp3 to the data type of the loop variable before storing them.
• When an unconditional FOR loop ends, the loop variable contains the value last used in the loop, not the value that caused loop termination.
• During each iteration of a conditional loop, HP BASIC tests the value of cond-exp before it executes the loop.
  • If you specify a WHILE clause and cond-exp is false (value zero), HP BASIC exits from the loop. If the cond-exp is true (value nonzero), the loop executes again.
  • If you specify an UNTIL clause and cond-exp is true (value nonzero), HP BASIC exits from the loop. If the exp is false (value zero), the loop executes again.
• When FOR is used as a statement modifier, HP BASIC executes the statement until the loop variable equals or exceeds num-exp2 or until the WHILE or UNLESS condition is satisfied.
• Each FOR statement must have a corresponding NEXT statement or HP BASIC signals an error. (This is not the case if the FOR statement is used as a statement modifier.)

Examples

Example 1

!Unconditional DECLARE LONG course_num, STRING course_nam FOR I = 3 TO 12 STEP 3 INPUT "Course number";course_num INPUT "Course name";course_nam NEXT I

Output

Course number? 221 Course name? Botany Course number? 231 Course name? Organic Chemistry Course number? 237 Course name? Life Science II Course number? 244 Course name? Programming in HP BASIC

Example 2

!Unconditional Statement Modifier DECLARE INTEGER counter PRINT "This is an unconditional statement modifier" FOR counter = 1 TO 3 END

Output

This is an unconditional statement modifier This is an unconditional statement modifier This is an unconditional statement modifier

Example 3

!Conditional Statement Modifier DECLARE INTEGER counter, & STRING my_name INPUT "Try and guess my name";my_name FOR counter = 1 UNTIL my_name = "HP BASIC" PRINT "You guessed it!"

Output

Try and guess my name? VAX PASCAL Try and guess my name? VAX SCAN Try and guess my name? HP BASIC You guessed it!