Enscribe Programmer's Guide

After doing so, you can obtain the address of the physical record that was actually used by issuing
this procedure call:
item := 202;
error := FILE_GETINFOLIST_ (filenum, item, 1, primary^key, 8);
Random Access by Primary Key
You access individual records randomly within a relative file by using FILE_SETPOSITION_ calls
to explicitly identify the desired record by primary key (relative record number).
CALL FILE_SETPOSITION_ (filenum,38F); ! sets next-rec.ptr=38
CALL WRITE (filenum, buffer, write^count); ! writes to rec 38
Note that this sequence assumes that record 38 is currently empty. If you attempt to WRITE data
to a record that is not empty, the operation fails with an error 10 (file/record already exists).
CALL FILE_SETPOSITION_ (filenum, 76F); !sets next-rec.ptr=76
CALL READ (filenum, buffer, read^count); ! reads record 76
Note that this sequence assumes that record 76 actually contains data. If record 76 is empty, the
READ call accesses the next record higher than 76 that does contain data.
Updating Records
To update a record, the particular physical record being accessed must already contain data.
FILE_WRITE64_/WRITE cannot write to an occupied physical record. Conversely,
FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITEUPDATE and
WRITEUPDATEUNLOCK cannot write to an empty physical record.
After positioning to the particular record you wish to update, read the record using
FILE_READUPDATE64_, FILE_READUPDATELOCK64_, READUPDATE or READUPDATELOCK to
verify that it contains data.
FILE_READ64_, FILE_READLOCK64_, READ and READLOCK always access the next higher nonempty
record in the current access path, simply ignoring empty records. Consequently, they might or
might not access the particular record that you positioned to. FILE_READUPDATE64_,
FILE_READUPDATELOCK64_, READUPDATE and READUPDATELOCK, however, always access
whatever record is pointed to by the current-record pointer. The use of these procedures (instead
of FILE_READ64_, FILE_READLOCK64_, READ or READLOCK) therefore ensures that you are indeed
examining the content of the particular record that you positioned to regardless of whether it
contains data or is empty.
Having determined that the desired record contains data, you then need to change the desired
data fields in your application buffer and write the revised record back to the disk using
FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITEUPDATE or
WRITEUPDATEUNLOCK.
Referring to the sample data file illustrated in “Sample Relative File” (page 147), this sequence of
TAL statements updates the content of record 18:
CALL FILE_SETPOSITION_ (filenum, 18F); ! set next-record
! pointer = 18
CALL READUPDATE (filenum, buffer, read^count, count^read);
IF count^read > 0 THEN
BEGIN
buffer := changed^record;
CALL WRITEUPDATE (filenum, buffer, write^count);
END
ELSE ... ! the specified record is empty;
! update not performed
Accessing Relative File 149