BSCAN statement

Syntax

BSCAN ID.variable [ , rec.variable ] [FROM [ file.variable [ , record ] 
[USING indexname] [RESET] [BY seq] 
{THEN statements [ELSE statements] | ELSE statements}

Description

Use the BSCAN statement to scan the leaf nodes of a B-tree file (type 25) or of a secondary index. The record ID returned by the current scan operation is assigned to ID.variable. If you specify rec.variable, the contents of the record whose ID is ID.variable is assigned to it.

file.variable specifies an open file. If file.variable is not specified, the default file is assumed (for more information on default files, see the OPEN statement). If the file is neither accessible nor open, the program terminates with a run-time error message.

record is an expression that evaluates to a record ID of a record in the B-tree file. If the USING clause is used, record is a value in the specified index. record specifies the relative starting position of the scan.

record need not exactly match an existing record ID or value. If it does not, the scan finds the next or previous record ID or value, depending on whether the scan is in ascending or descending order. For example, depending on how precisely you want to specify the starting point at or near the record ID or value SMITH, record can evaluate to SMITH, SMIT, SMI, SM, or S.

If you do not specify record, the scan starts at the leftmost slot of the leftmost leaf, or the rightmost slot of the rightmost leaf, depending on the value of the seq expression. The scan then moves in the direction specified in the BY clause.

indexname is an expression that evaluates to the name of a secondary index associated with the file.

RESET resets the internal B-tree scan pointer. If the scanning order is ascending, the pointer is set to the leftmost slot of the leftmost leaf; if the order is descending, the pointer is set to the rightmost slot of the rightmost leaf. If you do not specify seq, the scan is done in ascending order. If you specify record in the FROM clause, RESET is ignored.

seq is an expression that evaluates to A or D; it specifies the direction of the scan. "A", the default, specifies ascending order. "D" specifies descending order.

If the BSCAN statement finds a valid record ID, or a record ID and its associated data, the THEN statements are executed; the ELSE statements are ignored. If the scan does not find a valid record ID, or if some other error occurs, any THEN statements are ignored, and the ELSE statements are executed.

Any file updates executed in a transaction (that is, between a BEGIN TRANSACTION statement and a COMMIT statement) are not accessible to the BSCAN statement until after the COMMIT statement has been executed.

The STATUS function returns the following values after the BSCAN statement is executed:

0

The scan proceeded beyond the leftmost or rightmost leaf node. ID.variable and rec.variable are set to empty strings.

1

The scan returned an existing record ID, or a record ID that matches the record ID specified by record.

2

The scan returned a record ID that does not match record. ID.variable is either the next or the previous record ID in the B-tree, depending on the direction of the scan.

3

The file is not a B-tree (type 25) file, or, if the USING clause is used, the file has no active secondary indexes.

4

indexname does not exist.

5

seq does not evaluate to A or D.

6

The index specified by indexname needs to be built.

10

An internal error was detected.

If NLS is enabled, the BSCAN statement retrieves record IDs in the order determined by the active collation locale; otherwise, BSCAN uses the default order, which is simple byte ordering that uses the standard binary value for characters; the Collate convention as specified in the NLS.LC.COLLATE file for the current locale is ignored.

Example

The following example shows how you might indicate that the ELSE statements were executed because the contents of the leaf nodes were exhausted:

BSCAN ID,REC FROM FILE,MATCH USING "PRODUCT" BY "A" 
THEN
   PRINT ID,REC
END ELSE
   ERR = STATUS()
   BEGIN CASE
      CASE ERR = 0
         PRINT "Exhausted leaf node contents."
      CASE ERR = 3
         PRINT "No active indices, or file is not 
type 25."
      CASE ERR = 4
         PRINT "Index name does not exist."
      CASE ERR = 5
         PRINT "Invalid BY clause value."
      CASE ERR = 6
         PRINT "Index must be built."
      CASE ERR = 10
         PRINT "Internal error detected."
   END CASE
   GOTO EXIT.PROGRAM:
END