HP 3000 Manuals HP 3000 Manuals
FWRITE
INTRINSIC NUMBER 3
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 Figure 4-5, 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 Figure 4-14 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.
_________________________________________________________________________
| |
| $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; |
_________________________________________________________________________
Figure 4-14. FWRITE Example
_____________________________________________________________________
| |
| 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; |
_____________________________________________________________________
Figure 4-14. FWRITE Example (continued)