FWRITE

Write a logical record from the user's stack to a KSAM file.

 

              IV   LA   IV   LV 

   FWRITE(filennum,target,tcount,control);

The FWRITE intrinsic writes a logical record from the user's stack to the KSAM file. The record contents are contained in the array target in the user's program and include all key values. FWRITE uses the primary key value to update the key file so that the new record is in sequence by primary key value. Any alternate keys are also entered into their appropriate positions in the key file. No separate key specification is required since all the key values are contained in the record to be written.

Following execution of FWRITE, the logical record pointer is positioned at the next sequential record in key sequence or at the end-of-file if the record is the last in sequence. The particular key is the current key being used when FWRITE is called.

If sequential processing was specified for the file in the flagword of ksamparam when the file was opened by FOPEN, then the records must be written in ascending order by primary key. If duplicate keys are not allowed, any record with a key duplicating a key in an existing record is not written and a CCL condition code is returned.

When the physical bounds of either the data file or the key file prevent further writing (all allowable extents are filled), an end-of-file condition code (CCG) is returned to the user's program.

If the file was opened for shared access (aoptions bits 8,9 = 11), then you must dynamically lock the file with FLOCK before calling FWRITE. Note that the file must also have been opened for dynamic locking (aoptions bit 10 = 1).

PARAMETERS

filenum

integer by value (required)

A word identifier supplying the file number of the file to be written on.

target

logical array (required)

Contains the record to be written.

tcount

integer by value (required)

An integer specifying the number of words or bytes to be written to the record. If this value is positive, it signifies words; if it is negative, it signifies bytes; if it is zero, no transfer occurs. If tcount is less than the recsize parameter associated with the record, only the first tcount words or bytes are written.

If tcount is larger than the recsize value, the write request is refused and condition code CCL is returned.

control

logical by value (required)

A logical value representing a carriage control code. This parameter has no meaning for KSAM files but must be included for compatibility. Whatever value is specified will be ignored.

CONDITION CODES

CCE: Request granted.
CCG: The physical bounds of the file prevented further writing; all disc extents are filled.
CCL: Request denied because an error occurred, such as: an input/output error occurred; a duplicate key value occurred when duplicates are not allowed; tcount does not include all keys; or sequential processing was specified in the flagword of ksamparam in FOPEN and the primary key is not the next in ascending order.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

USING FWRITE

The FWRITE intrinsic writes records from an array in your program to a KSAM file. All the key information is contained in this target array. The record is written to the data file and the keyfile is updated to reflect the primary key and any alternate keys in the new record.

Depending on how the file was opened, you can write records at random regardless of primary key order, or you may be constrained to write records in sequential order by primary key value. The examples in this manual use the file JEXAMFIL that is created for writing at random. If you refer to Title not available, the flagword of the ksamparam parameter is set to the binary value 0000000000000010. Bit 14, indicating that record numbers start with 1, is the only bit set. If bit 13 had also been set to 1 then all records written to the file would have to be in ascending order by primary key value. In such a case, the chronological order of records and the sequential order would be the same.

When you write a record to a KSAM file, FWRITE either overwrites any records previously written to the file or else writes new records following existing records. The choice is made when you open the file. If you set bits 12 through 15 of the aoptions parameter of FOPEN to the binary value 0001 (octal or decimal 1), then all records written to the file before this open are deleted and FWRITE writes records to a cleared file. If you set bits 12 through 15 of aoptions to 0010 or 0011 (octal or decimal 2 or 3), then any previously written data is saved. The example in Title not available deletes any data written to file JEXAMFIL before it was opened. The file will have no data other than that written by this program. If, after closing the file, you want to open it to write more data without deleting existing data, then you must set the aoptions access type (bits 12-15) to 0010 or 0011.

SHARED ACCESS

When access is shared, it is essential that you lock the file before writing new records. This means opening the file with dynamic locking allowed and calling FLOCK before calling FWRITE. You should also unlock the file with FUNLOCK after writing the records.

Figure 4-14 FWRITE Example

 



$CONTR0L MAIN=EXAMPLE9 

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

<<*                                                    *>> 

<<*                     EXAMPLE  9                     *>> 

<<*           WRITE TO EXISTING KSAM FILE              *>> 

<<*                                                    *>> 

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

INTEGER FILNUM; 

INTEGER ERRORCODE; 

INTEGER LENGTH; 

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

ARRAY MESSAGE(0:35); 

ARRAY INPUT(0:39); 

ARRAY OUTPUT(*)=INPUT; 

INTRINSIC FOPEN,FCLOSE,FWRITE,READ,PRINT,FCHECK,FERRMSG; 

INTRINSIC TERMINATE; 

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

<<* OPEN THE KSAM FILE   *>> 

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

FILNUM:=FOPEN(FILNAME,3,2); <<OPEN FILE FOR WRITE>> 

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); <<PRINTOUT ERROR MESSAGE>> 

       TERMINATE; 

     END; 

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

<<* READ DATA FROM $STDIN DEVICE   *>> 

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

L1; 

READ(INPUT,-72); <<READ ONE RECORD FROM $STDIN>> 

IF > 

THEN BEGIN <<END OF FILE ON $STDIN>> 

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

       IF <> THEN 

         BEGIN <<CANNOT CLOSE THE KSAM FILE>> 

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

           PRINT(MESSAGE,-29,0); 

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

           FERRMSG(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 INPUT"; 

       PRINT(MESSAGE,-34,0); 

       TERMINATE; 

     END; 

PRINT(OUTPUT,-72,0); <<ECHO CHECK>> 

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

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

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

FWRITE(FILNUM,OUTPUT,-72,0); 

IF <> 

THEN BEGIN <<ERROR OCCURRED WHILE WRITING KSAM>> 

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

       PRINT(MESSAGE,-38,0); 

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

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

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

       TERMINATE; 

     END; 

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

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

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

GO TO L1; 

END;