FREAD

Reads a logical record in key sequence from a KSAM file to the user's stack.

     I            IV    LA    IV

   lgth:=FREAD(filenum,target,tcount);

FREAD reads a logical record in sequential order by key value. The primary key determines key sequence unless a prior call to FFINDN (or FFINDBYKEY or FREADBYKEY) has specified an alternate key. If the file is opened without KSAM access (FOPEN aoptions bit 3=1), then FREAD reads the data file as if it were not a KSAM file.

The record read by FREAD depends on the current position of the logical record pointer.

FUNCTIONAL RETURN

The FREAD intrinsic returns a positive integer value to lgth showing the length of the information transferred. If the tcount parameter in the FREAD call is positive, the positive value returned represents a word count; if the tcount parameter is negative, the positive value returned represents a byte count.

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 the length in words; if it is negative, it signifies the length in bytes; 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 physical record, transfer is limited to the length of the physical record.

CONDITION CODES

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

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FREAD

The FREAD intrinsic reads the record at which the logical record pointer is currently positioned. When a file is opened, this pointer is positioned to the beginning of the first record in primary key sequence. That is, it is positioned to the record containing the lowest value in those bytes containing the primary key.

Following each FREAD , the record pointer remains positioned at the record just read. Any subsequent FREAD call positions the pointer to the next sequential record in ascending key sequence. Also, if an FREAD call is followed by an FUPDATE and another FREAD, the pointer is advanced before the second FREAD.

A key other than the primary key can be selected as the basis of the sequential read by executing FFINDN, FFINDBYKEY, or FREADBYKEY before executing the FREAD intrinsic.

When the logical end-of-data is encountered during reading, the CCG condition code is returned to your process. The end-of-data occurs when the last logical record of the file is passed . Note that the last logical record of a KSAM file is the record containing the maximum key value in the key on which the key sequence is based.

SHARED ACCESS

In order to be sure that you are reading the record you want, you should call either FLOCK or FCONTROL with control code 7 before calling FREAD. FLOCK prevents other users from changing or deleting the record until the file is unlocked with FUNLOCK. FCONTROL with control code 7 clears the data and key block buffers so that the record must be read directly from the file, and also transfers the latest control information from the file to the extra data segment. Because the logical pointer is part of this control information, you can be sure that is is set correctly by calling FCONTROL with code 7.

FCONTROL uses less overhead than FLOCK, but it cannot prevent other users from modifying the record you want to read while you are calling FCONTROL. FLOCK, on the other hand, fully protects the information to be read from changes by other users but requires more time.

Because FREAD is a pointer-dependent procedure, you must call one of the procedures that position the pointer before calling FREAD. When you are reading the file in sequential key order, it is important to lock the file before calling the procedure that positions the pointer, and to leave it locked while you are reading the file. This insures that the pointer is not moved by another user between the call that positions the pointer and FREAD or between sequential FREAD calls. (Refer to Table 4-2 “Positioning the Pointers” for a list of the pointer-independent and pointer-dependent procedures.)

For example, the following sequence of calls guarantees that you will read the file in sequential order starting with a specified key:

 

   FLOCK 
   FFINDBYKEY <----------------------------sets logical pointer
      FREAD loop <------------------read records in key sequence
   FUNLOCK

Note that FREAD advances the record pointer only if it is followed by another FREAD (or an FUPDATE followed by another FREAD). A single call to FREAD leaves the pointer at the record just read; a subsequent call to FREAD causes the pointer to be positioned to the next record in key sequence. This permits sequential reading of the file without calling a pointer-independent procedure before each FREAD. Also, in order to allow sequential updates, the pointer is advanced for each FREAD in an FUPDATE/FREAD sequence with no other intervening calls (see FUPDATE discussion).

In the example in Figure 4-7 FREAD Example, FREAD is used first to read the KSAM file in sequence by primary key. When the end of data is reached, the program uses FFINDBYKEY to specify an alternate key and FREAD then reads the file in sequence by that altemate key. When the end of data is reached again, the file is closed. (Note that this program is opened for exclusive access so that locking is not necessary).

Figure 4-7 FREAD Example

 

$CONTROL MAIN=JEXAMPL2 
<<*********************************************************>> 
<<*                                                       *>> 
<<*                    EXAMPLE 2                          *>> 
<<*          READ A KSAM FILE SEQUENTIALLY                *>> 
<<*                                                       *>> 
<<*********************************************************>> 
INTEGER      FILNUM;   
INTEGER ERRORCODE,LENGTH;   
BYTE ARRAY   FILNAME(0:9):="JEXAMFIL ";   
ARRAY          MESSAGE(0:35); 
ARRAY          INPUT(0:39); 
ARRAY          OUTPUT(*)=INPUT; 
BYTE ARRAY    KEYVALUE(0:7:="000-0000";   
INTEGER       KEYLENGTH"=8;   
INTEGER       KEYLOCATION:21;   
INTEGER       RELOP:2;   
INTRINSIC   FOPEN,FCLOSE,  FREAD,FFINDBYKEY  ,READ,PRINT, 
            FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE; 
<<*************************>> 
<<* OPEN THE KSAM FILE    *>> 
<<*************************>> 
FILENUM:=FOPEN(FILNAME,3,200); <<OPEN KSAM FILE FOR EXCLUSIVE READ-ONLY ACCESS>> 
IF FILNUM=0 
THEN BEGIN           <<CANNOT OPEN KSAM FILE>> 
       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 
       PRINT(MESSAGE,-21,0); 
       FCHECK(FILNUM,ERRORCODE);          <<GET THE ERROR NUMBER>> 
       FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> 
       PRINT(MESSAGE,-LENGTH,0);    <<PRINT ERROR MESSAGE>> 
       TERMINATE; 
     END; 
MOVE MESSAGE:="LIST IN LAST NAME SEQUENCE"; 
PRINT(MESSAGE,-26,0); 
<<**********************************>> 
<<* READ KSAM IN NAME SEQUENCE     *>> 
<<**********************************>> 
L1: 
FREAD(FILNUM,INPUT,-72);   <<READ SEQUENTIALLY
                               BY PRIMARY KEY>> 
IF   > 
THEN GO TO L2;                   <<GO TO ALTERNATE KEY ORDER>> 
IF < 
THEN BEGIN 
       MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; 
       PRINT(MESSAGES,-34,0); 
       TERMINATE; 
     END; 
<<***********************************************>> 
<<* WRITE THE DATA JUST READ FROM KSAM FILE     *>> 
<<***********************************************>> 
PRINT(OUTPUT,-72,0); 
<<***********************************>> 
<<* GO BACK TO GET ANOTHER RECORD   *>> 
<<***********************************>> 
GO TO L1; 
<<*********************************************************>> 
<<* READ DATA FROM KSAM FILE IN TELEPHONE # SEQUENCE      *>> 
<<*********************************************************>> 
L2:   
FFINDNYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP);   
MOVE MESSAGE:="LIST IN TELEPHONE NO. SEQUENCE";   
PRINT(MESSAGE,-30,0);   
L3:   
FREAD(FILNUM,INPUT,-72);   <<READ SEQUENTIALLY
                                 BY ALTERNATE KEY>> 
IF > 
THEN BEGIN <<END OF FILE>> 
       FCLOSE(FILNUM,0,0); <<CLOSE THE KSAM FILE>> 
       IF <> THEN 
         BEGIN <<CLOSE UNSUCCESSFUL>> 
            MOVE MESSAGE:"CANNOT CLOSE THE KSAM FILE": 
            PRINT(MESSAGE,-29,0); 
            FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> 
            FERRMSG(ERRORCODE,MESSAGE,LENSTH;<<GET MESSAGE STRING>> 
            PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> 
          END; 
        TERMINATE; 
      END; 
IF < 
THEN BEGIN 
       MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; 
       PRINT(MESSAGE,-34,0); 
       TERMINATE; 
     END; 
<<***********************************************>> 
<<* WRITE THE DATA JUST READ FROM KSAM FILE     *>> 
<<***********************************************>> 
PRINT(OUTPUT,-72,0); 
IF <> 
THEN BEGIN <<ERROR OCCURRED WHILE PRINTING OUTPUT>> 
       MOVE MESSAGE,="ERROR OCCURRED WHILE PRINTING OUTPUT"; 
       PRINT(MESSAGE,-36,0); 
       FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> 
       FERRMSG(ERRORCODE,MESSAGE,LENGTH),<<GET MESSAGE STRING>> 
       PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> 
       TERMINATE; 
     END; 
<<************************************>> 
<<* GO BACK TO GET ANOTHER RECORD    *>> 
<<************************************>> 
GO TO L3; 
END; 

Output from Program Execution: 

LIST IN LAST NAME SEQUENCE   
CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053   
ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050   
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022   
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087   
PASBY LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE CA. 94102   
ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871   
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053   
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234   
WESTER ELDER 287-4598 1256 KINGFISHER SUNNYVALE CA. 43098   
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234  
LIST IN TELEPHONE NO. SEQUENCE   
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022   
ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871   
WESTER ELDER 267-4598 1256 KINGFISHER SUNNYVALE CA. 43098   
ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050   
SEELY HENRY 293-4220 1144 LEBERTY EL CERRITO CA. 94053   
PASBY LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE CA. 94102   
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234   
CARDIN RICK 578-7018 11100 WOLFE CUPERTINO CA. 94O53   
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087   
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234   

END OF PROGRAM