BKSTART

Positions a KSAM file to a particular record based on a key value.

  CALL BKSTART(filenum,status[,keyvalue[,keylocation [,relation ]]])

By calling BKSTART, you can position the record pointer to any record in the file based on the value of a key in that record. The key can be the primary key or any alternate key, since BKSTART also allows you to select the key for positioning and for subsequent sequential reads. If you want to read all the keys in a key sequence, you can use BKSTART to position the pointer to the record with the lowest key value in the selected key.

Parameters

filenum

A numeric variable containing the file number that identifies the file. This number was returned by the last call to BKOPEN. It should not be altered unless the file is closed with a successful call to BKCLOSE. (Required parameter)

status

A four-character string variable to which is returned a code that indicates whether or not the call to BKSTART was successful and if not, why not. The first character is set to zero when the call succeeds, to another value when it fails. (Required parameter)

keyvalue

A string or numeric expression whose value is compared to a key value in this record. The record pointer is positioned to the first record with a key value that bears the relation specified by relation to the value in keyvalue. If the value is a string, its logical length is used for the comparison; otherwise, the physical or dimensioned length is used. The length of this value must be less than or equal to the length of the key as specified when the file was created. If keyvalue is a null string (""), the file is positioned to the beginning of the first logical record according to the value of the key in keylocation. (Optional Parameter)

Default: If omitted, the value assumed for keyvalue is the lowest value for the specified key type.

keylocation

A numeric expression whose value indicates the starting character location in each record of the key used for positioning by BKSTART. The characters in a record are counted starting with one. If set to zero, the primary key is assumed. (Optional parameter)

Default: If omitted, the primary key is assumed.

relation

A numeric expression whose value specifies the relation between the specified keyvalue and the value of the key at keylocation. The record pointer is positioned to the first record with a key value satisfying this relation:

0: The value of the record key is equal to keyvalue
1: The value of the record key is greater than keyvalue
2: The value of the record key is greater than or equal to keyvalue (default).
>2: Any value greater than 2 is treated as if it were 2. (Optional parameter)
Default: If omitted, the relation is assumed to be 2, record key is greater than or equal to the keyvalue.

Operation Notes

After calling BKSTART, you should check the status parameter to determine if the procedure was executed successfully. If successful, the record pointer is positioned at the beginning of the first record with a value at keylocation that has the relation specified in relation to the value specified in keyvalue.

If default values are assumed for all three optional parameters, the pointer is positioned to the record with the lowest value for its type in the primary key location.

If the relation specified is equality (relation = 0), then a record must be located that has the same key value as that specified in the BKSTART call. When the record is found, the pointer is positioned to it. If duplicate values are allowed for the key, then the pointer is positioned at the first record with the particular key value.

When the specified relation is greater than (relation = 1), the file is searched until a record is found with a key value greater than the specified key value. The search passes over any record with a key value equal to the specified value. This relation allows you to retrieve items by an approximate key. Thus, if you specify a key value of "R", a call to BKSTART will position the pointer to the first record with a key value that starts with the letter R. A subsequent series of calls to BKREAD allows you to read the remaining records in the file or, by including a test, to read only the records beginning with R.

When the specified relation is greater than or equal to (relation = 2), BKSTART looks for a record containing a value equal to the specified value. If found, it positions the pointer to that record. If not found, it continues looking and positions the pointer to the first record that is greater than the specified value. This type of search can be used to locate records by generic key. A generic, or partial, key is a value that matches characters at the beginning of the key, but not necessarily the end.

Whenever a record cannot be found with a key that satisfies the relation and value specified, the value 23 for invalid key is returned to status.

BKSTART allows you to specify a key other than the primary key assumed by BKREAD. Called prior to a series of calls to BKREAD, it prepares for a sequential read of the file in alternate key order. For example, assuming a file with an alternate key in location 21, the following call positions the pointer to the first record in that key sequence:

 

     100 DIM A$(10),S$(4) 

     150 A$=" " <------------------- assign null string to keyvalue 

     160 L=21 <-------------------- assign alternate key location to keylocation 

     170 CALL BKSTART(F,S$,A$,21)

The default for relation is 2 (greater than or equal to) and need not be specified except for documentation purposes.

Figure B-10 “Positioning Pointer to Least-Valued Record with BKSTART” illustrates the use of BKSTART with default values for all optional parameters. Specified in this minimal form, it positions to the least valued primary key.

Figure B-10 Positioning Pointer to Least-Valued Record with BKSTART

 

  1080 REM ******************************************************* 

  1090 REM * POSITION TO LEAST VALUED PRIMARY KEY * 

  1100 REM ******************************************************* 

  1110 REM 

  1120 REM F IS THE FILE NUMBER OF A KSAM FILE 

  1130 REM OPENED BY A CALL TO BKOPEN 

  1140 REM 

  1150 CALL BKSTART(F,S$) 

  1160 REM 

  1170 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 

  1180 REM 

  1190 IF S$[1;1]<>"0" THEN DO 

  1200 REM N$ CONTAINS THE NAME OF THE KSAM FILE 

  1210 REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL 

  1220 PRINT "UNABLE TO POSITION FILE TO LEAST VALUED PRIMARY KEY" 

  1230 PRINT "ERROR ";S$[1;1]," DETAIL";S$[2] 

  1240 CALL BKERROR,(S$,M$) 

  1250 PRINT M$ 

  1260 GOTO 3620 

  1270 DOEND 

  1280 REM 

  1290 REM THE PROGRAM CONTINUES 

  1300 REM

The example in Figure B-11 “Positioning Pointer to Particular Record with BKSTART” positions the record pointer to a record containing a specific key value. The value is 23; it is located starting in the second character of each record. The value for relation is zero indicating that the key must contain exactly the value 23, not a value larger than 23.

Figure B-11 Positioning Pointer to Particular Record with BKSTART

 

1920 REM 

1930 REM *************************************** 

1940 REM * POSITION A KSAM FILE * 

1950 REM *************************************** 

1960 REM 

1970 REM F IS THE FILE NUMBER OF A KSAM FILE 

1989 REM OPENED BY A CALL TO BKOPEN 

1990 REM 

2000 REM AN ASSUMPTION HAS BEEN MADE THAT THE POSITIONING TO BE 

2010 REM DONE IS TO THE RECORD WRITTEN IN THE WRITE EXAMPLE, 

2020 REM AND THAT THE DESIRED KEY STARTS AT CHARACTER 2. 

2060 REM 

2070 CALL BKSTART(F,S$,"23",2,0) 

2080 REM 

2090 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 

2100 REM 

2110 IF S$[1;1]<>"0" THEN DO 

2120 REM N$ CONTAINS THE NAME OF THE KSAM FILE 

2130 REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL 

2140 PRINT "UNABLE TO START ";N$;" ERROR ";S$[1;1];" DETAIL ";S$[2] 

2150 CALL BKERROR(S$,M$) 

2160 PRINT M$ 

2170 GOTO 3620 

2180 DOEND 

2190 REM 

2200 REM THE PROGRAM CONTINUES 

2210 REM

BKSTART

Technical documentation

» Table of Contents

» Index

Parameters

Operation Notes