FREADC

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

 

     I           IV     LA    IV 

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

FREADC reads a logical record in chronological sequence. Chronological sequence means the sequence in which the records were originally written to the data file.

When FREADC is executed, the key file is not accessed. This read is similar to the standard FREAD for non-KSAM files except that FREADC skips any data records that are marked for deletion. Following execution, the chronological pointer remains positioned at the same record.

FUNCTIONAL RETURN

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

PARAMETERS

filenum

integer by value (required)

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

target

logical away (required)

An array to which the record is to be transfered. This array should be large enough to hold all 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 negative, it signifies the length in bytes; if zero, no transfer occurs.

If tcount is less than the size of the record, only the first tcount words are transfered from the record. If tcount is larger than the physical record size, 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.

USING FREADC

This intrinsic allows you to read the records in the data file in the order in which they are physically stored in the file. The end-of-data is encountered following the last record in the file. If any records have been marked for deletion (refer to the FREMOVE intrinsic), these records are not read; otherwise, this intrinsic reads the data from the data file exactly as it was stored.

Following execution of FREADC, the chronological pointer remains positioned at the record just read, unless it is followed by another call to FREADC. In a series of calls to FREADC, the pointer is advanced automatically so you can read the file in chronological sequence without resetting the pointer for each record.

Because FUPDATE only checks the logical pointer, you cannot update a record located by FREADC or FREADDIR. To update a record located by its chronological record number, you must precede the call to FUPDATE with a call to FPOINT. Unlike FREADC or FREADDIR, FPOINT sets the logical pointer as well as the chronological pointer.

In Title not available, the FREADC intrinsic is used to read the data from the KSAM data file in chronological order. Compare this order to the sequential order by primary key in which the same file is read by FREAD. (Refer to Title not available for an example showing the chronological record number printed in association with each record listed in sequential key order.)

SHARED ACCESS

Because FREADC is a chronological pointer-dependent procedure, you must call one of the procedures that position the pointer before calling FREADC. (Refer to Table 4-2 “Positioning the Pointers” for a list of the pointer-dependent and pointer-independent procedures.) When access is shared, it is essential that you lock the file before calling the procedure that positions the pointer, and then leave the file locked while it is being read by FREADC. This insures that no other user changes the information in the record.

For example, the following sequence of calls guarantees that you will read the file in chronological sequence starting with a specified record number:

 

   FLOCK <----------- lock file 

   FPOINT <------------- position the chronological pointer 

     FREADC loop <----------------- read records in chronological sequence 

   FUNLOCK <--------------- unlock file

Figure 4-9 FREADC Example

 



$CONTROL MAIN=JEXAMPL4 

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

<<*                                                       *>> 

<<*                  EXAMPLE 4                            *>> 

<<*      READ A KSAM FILE CHRONOLOGICALLY                 *>> 

<<*                                                       *>> 

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

INTEGER FILNUM; 

INTEGER LENGTH; 

INTEGER ERRORCODE; 

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

ARRAY MESSAGE (0:35); 

ARRAY INPUT(0:39); 

ARAY OUTPUT(*)=INPUT; 

INTRINSIC FOPEN,FCLOSE,FREADC,FCHECK,FERRMSG,PRINT,TERMINATE; 

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

<<*  OPEN THE KSAM FILE  *>> 

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

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

IF FILNUM=0 

THEN BEGIN 

       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 

       PRINT(MESSAGE,-21,0); 

       FCHECK(FILNUM,ERRORCIDE); <<GET THE ERROR NUMBER>> 

       FERRMSG(ERRORCODE,MESSAGE,LENGTH):<<GET MESSAGE STRING>> 

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

       TERMINATE; 

     END; 

L1; 

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

<<*    READ KSAM ACCORDINGTO CHRONOLOGICAL ORDER     *>> 

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

FREADC(FILNUM,INPUT,-72); 

IF > 

THEN BEGIN <<END OF FILE>> 

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

       IF <> 

       THEN BEGIN 

             MOVE MESSAGE:="CANNOT CLOSE KSAM FILE"; 

             PRINT(MESSAGE,-22,0); 

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

             FFERRMSG(ERRORCODE,MESSAGE,LENGTH);<<GET MESSAGE STRING>>> 

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

           END; 

       TERMINATE; 

    END; 

IF < 

THEN BEGIN 

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

       PRINT(MESSAGE,-37,0); 

       TERMINATE; 

     END; 

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

<<* WRITE THE DATA JUST READ FROM KSAM FILE     *>> 

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

PRINT(OUTPUT,-72,0); 

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

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

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

GO TO L1; 

END; 



Output from Program Execution:





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

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

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

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

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

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

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

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

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

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



 END OF PROGRAM