ADAPL: write

write

Syntax

WRITE facsname

WRITE facsname UPDATE

WRITE facsname NEXT

WRITE facsname NEXT UPDATE

Meaning

The WRITE instruction (without NEXT) writes the earlier READ record to the dataset referred to by facsname. The current values of the database variables (FACS-)declared for the dataset are written to the record on disk: these values may be the existing values as you READ them from the record earlier or new/changed values which you added by assigning new values to the database variables. Any existing values in the target record appearing in tags which have not been declared in the ADAPL FACS definition remain unchanged. The database table referred to by facsname must first be opened before you can write to it.

UPDATE prevents the lock from being automatically removed from the record. Without this option, the lock will automatically be removed after a successful WRITE.

WRITE...NEXT creates a new record in the dataset (with an automatically assigned record number), containing the current values of the database variables: typically you've assigned some new values to one or more database variables, to make up the new record, but it is important to realize that if you've READ some record in the same FACS database earlier in your adapl then there might very well be database variables which still contain values from that earlier record if you haven't assigned all database variables (as declared in the FACS definition) a new value, resulting in a new record that contains more data than you were after! Therefore you must always empty the FACS buffer for the current database, using the CLEAR function, before you start assigning values to database variables for a new record.
After a successful WRITE NEXT the priref of the new record will immediately be available through the FACS database variable (tag alias) you've created for it. A WRITE NEXT will not place a lock on the record just created, unless the UPDATE option is used.

With the UPDATE option, the found record is locked while it is being written. Another way to lock the record is to use LOCK facsname before writing or deleting. It’s important though to lock a record prior to each type of WRITE operation or DELETE, and unlock it afterwards, via LOCK facsname and UNLOCK facsname respectively. This prevents a record being kept locked unintentionally after editing, which would make it impossible for others to edit it again.

So for a WRITE without the NEXT option, a record must first have been read with READ...UPDATE (to lock it after reading it), or the record must have been read with READ and then explicitly locked with LOCK facsname.

If you assign a record number to a link reference field in an internally linked record, a WRITE of this record will automatically update the reciprocally mirrored record too.

If you change a preferred name or perferred term record to a non-preferred term or name record (by fillling the Use field or its link reference field and perform a WRITE) then, if feedback databases have been set up in the relevant thesaurus or people database definition, all links in the relevant catalogue records (the feedback databases) to now non-preferred term or name records will automatically be changed into links to their respective preferred term or name records.

After a successful WRITE, the status variable &E will be set to 0.

Any storage adapl set for the database table into which you perform a FACS WRITE will be executed, except when the FACS write is executed in a storage adapl itself (to prevent an infinite chain of executions of the same storage adapl).

Note that when you use this function in a storage adapl, it will be skipped when you import records using the Collections import Test run option because a write is not executed during a test run. If you also mark the Save after successful test checkbox, this function will still be executed though when the virtually imported records are actually saved.