FREADDIR

Reads a logical record located by its chronological record number from a KSAM file to the user's stack.

 

                IV   LA   IV     DV 

   FREADDIR(filenum,target,tcount,recnum);

The FREADDIR intrinsic reads a specific logical record, or a portion of such a record, from a KSAM file to the user's data stack. The particular record read is specified by its chronological record number. This number is determined by the order in which the record was written to the file; it is not the logical record number determined by ascending key sequence. When the file has fixed-length records, recnum is the actual record number counting from the first record in the file. When the file has variable-length records, recnum is a word pointer to the first word in the record counting from the first word in the file, word zero.

After FREADDIR has been executed, the chronological record pointer remains positioned at the record just read. FREADDIR does not change the position of the logical record pointer.

PARAMETERS

filenum

integer by value (required)

A word identifier supplying the file number of the file to be read.

target

logical array (required)

An array to which the record is to be transferred. This array should be large enough to hold all of the information to be transferred.

tcount

integer by value (required)

An integer specifying the number of words or bytes to be transferred. If this value is positive, it signifies words; if negative, it signifiesbytes; and if it is zero, no transfer occurs.

If tcount is less than the size of the record, only the first tcount words or bytes are read from the record. If tcount is larger than the size of the logical record, the transfer is limited to the length of the logical record.

recnum

double by value (required)

A double-word integer indicating the relative chronological record number (or word number for variable-length records) to which the chronological pointer is positioned. Chronological record numbering for fixed-length records starts with zero or one, as specified in ksamparam or by FIRSTREC in BUILD.

CONDITION CODES

CCE: The specified information was read.
CCG: The end-of-data was encountered during reading.
CCL: The information was not read because an error occurred.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FREADDIR

You can use the FREADDIR intrinsic to position to a particular record in chronological sequence and then read that record. Following execution, the record pointer remains positioned at the same record. This intrinsic is similar in effect to the pair of intrinsics FPOINT and FREADC, with one exception: FREADDIR does not skip records marked for deletion. You might use FREADDIR to read one record and then reposition the pointer; you might use FPOINT and FREADC to position to a particular record and then continue reading in chronological order from that position.

You can use the FGETINFO intrinsic to determine the relative chronological number of the record most recently accessed. This number is returned in the FGETINFO parameter recpt. The example in Title not available determines the chronological record of each record as it is read in sequence by primary key value. The chronological record number is printed, and then FREADDIR uses this number to read the record to which it points. The output shows the chronological record number followed by the record to which it points. To see these records listed in chronological order, refer to the output in example 4-9 illustrating FREADC.

Note that execution of those intrinsics that position the KSAM data file by means of the chronological record pointer (FPOINT, FREADC, FREADDIR), do not access the key file. This type of access only affects the data file. It is, therefore, much faster than those intrinsics that use key sequence to position the data file and must access the key file.

Figure 4-10 FREADDIR Example

 



$CONTROL MAIN=JEXAMPL6 

<<******************************************************>> 

<<*                                                    *>> 

<<*                   EXAMPLE 6                        *>> 

<<*   READ A KSAM FILE BY CHRONOLOGICAL RECORD NUMBER  *>> 

<<*                                                    *>> 

<<******************************************************>> 

INTEGER FILNUM; 

INTEGER ERRORCODE; 

INTEGER LENGTH; 

BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; 

ARRAY MESSAGE(0:35); 

ARRAY INPUT(0:39); 

ARRAY OUTPUT(*)=INPUT; 

DOUBLE RECPTR; 

INTRINSIC FOPEN,FCLOSE,FREAD,FGETINFO,FREADDIR, 

          PRTNT,TERMINATE,DASCII,FCHECK,FERRMSG; 

<<*************************>> 

<<* OPEN THE KSAM FILE    *>> 

<<*************************>> 

FILNUM,=FOPEN(FILNAME,3); <<OPEN THE KSAM FILE>> 

IF FILNUM=0 

THEN BEGIN <<CANNOT OPEN KSAM FILE>> 

       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 

       PRINT(MESSAGE,-21,0); 

       FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> 

       FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>> 

       PRINT(MESSAGE,-LENGTH,0); <<PRTNTOUT ERROR MESSAGE>> 

       TERMINATE; 

     END; 

<<*****************************************************>> 

<<*              READ KSAM SEQUENTIALLY               *>> 

<<****************#************************************>> 

L1: 

FREAD(FILNUM,INPUT,-72); 

IF > 

THEN BEGIN 

        FCLOSE(FILNUM,0,0); <<CLOSE THE KSAM FILE>> 

        IF <> THEN 

            BEGIN 

            MOVE MESSAGE:="CANNOT CLOSE THE KSAM FILE"; 

            PRINT(MESSAGE,-22,0); 

            FCHECK(FILNUM,ERRORCOOE); <<GET ERROR NUMBER>> 

            FFRRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>> 

            PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> 

          END; 

        TERMINATE; 

      END; 

IF < 

THEN BEGIN 

       MOVE MESSAGE:="ERROR OCCURRED WHILE READING KSAM FILE"; 

       PRINT(MESSAGE,-37,0); 

       FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> 

       FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>> 

       PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> 

                TERMINATE; 

              END; 

      <<*****************************************************>> 

      <<* TO FIND OUT RECORD NUMBER OF THE RECORD JUST READ *>> 

      <<*****************************************************>> 

      FGETINFO(FINUM,,,,,,,,RECPTR); 

           MOVE MESSAGE:="RECORD# = "; 

           DASCII(RECPTR,10,MESSAGE(5)); 

           PRINT(MESSAGE,-14,0); 

      <<**********************************************>> 

      <<* READ THE KSAM FILE BY USING RECORD NUMBER  *>> 

      <<**********************************************>> 

      FREADDIR(FILNUM,INPUT,-72,RECPTR); 

      IF <> 

      THEN BEGIN 

             MOVE MESSAGE:="ERROR OCCURRED DURING FREADDIR"; 

             PRINT(MESSAGE,-30,0); 

             FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> 

             FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>>> 

             PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> 

             TERMINATE; 

           END; 

      <<***********************************************>> 

      <<* WRITE THE DATA JUST READ BY FREADDIR        *>> 

      <<***********************************************>> 

      PRINT(OUTPUT,-72,0); 

      <<**********************************>> 

      <<* GO BACK TO GET ANOTHER RECORD  *>> 

      <<**********************************>> 

      GO TO L1; 

      END; 





Output from Program Execution: 



RECORD# = 4 

CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053 

RECORD# = 3 

ECKSTEIN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050 

RECORD# = 2 

HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022 

RECORD# = 1 

NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087 

RECORD# = 5 

PASBY LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE CA. 94102 

RECORD# = 7 

ROBERT GERRY 259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871 

RECORD# = 6 

SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053 

RECORD# = 8 

TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234 

RECORD# = 10 

WESTER ELDER 287-4598 1256 KINGFISHER ST. SUNNYVALE CA. 43098 

RECORD# = 9 

WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234 



 END OF PROGRAM

FREADDIR

Technical documentation

» Table of Contents

PARAMETERS

CONDITION CODES

SPECIAL CONSIDERATIONS

USING FREADDIR