UPDATE.RECORD batch mode

UPDATE.RECORD  -  Batch Mode

Top  Previous  Next

 

UPDATE.RECORD runs in batch mode of the command line includes one or more field/value specifications.

 

If the EXCLUSIVE keyword is used, UPDATE.RECORD will obtain exclusive access to the file by acquiring the file lock. If another user holds a record lock or the file lock when the command is issued, UPDATE.RECORD will terminate with an error message unless the WAIT keyword has been used, in which case a message is displayed and it repeats the attempt to lock the file at five second intervals.

 

For each record to be processed, UPDATE.RECORD first locks and reads the record. If another user has the record locked and the WAIT keyword has been used, UPDATE.RECORD will wait for the record to become available. If the WAIT keyword was not used, the record id is added to a list of locked records. If either the INQUIRING or REPORTING keywords was used, a message is output showing the id of the record that could not be locked.

 

If the specified record does not exist in the file and the CREATING keyword has been used, a new, empty record is created to which the amendments are then applied. If the CREATING keyword is not present, the record id is added to a list of missing records

 

Once the record has been successfully locked, UPDATE.RECORD performs each of the specified amendments in the order in which they appear on the command line. Each amendment may draw on the result of preceding amendments. Note in particular, that use of the DELETING option will result in new field positions for all later fields. The record id may be changed by specifying the target as field 0 or a dictionary item such as @ID that refers to field 0. Any I-type or EVAL expressions after the change of record id will see the new id in @ID.

 

The field specification may be a numeric field position or the name of a D-type item from the dictionary or the VOC. The value specification may be:

 

A number or a quoted string.

 

The name of an A, D, I or S-type dictionary or VOC item identifying the field from which data is to be copied. If this is an I-type item or an A/S-type item with a correlative expression, it must have been compiled prior to use by UPDATE.RECORD.

 

The keyword EVAL followed by an I-type expression in single or double quotes. This expression will be compiled by UPDATE.RECORD and evaluated to determine the new value of the field.

 

UPDATE.RECORD honours dictionary conversion specifications for both the source and target data items. Where the new value for a field is derived via a dictionary name, the value is first converted to its external form. Where the field to be updated is identified via a dictionary name, the new value is converted to its internal form prior to storing in the record. If the value specification is followed by the CONV keyword and a quoted conversion specification, this will overrule any conversion specified in the dictionary. UPDATE.RECORD will report a warning message if the conversion generates an error when applied to value.

 

The REPORTING keyword causes UPDATE.RECORD to produce a detailed report of each amendment made, including the record id together with the old and new values of each field amended. This report can be directed to a specific print unit using the LPTR keyword.

 

In the absence of the REPORTING and INQUIRING keywords or if the report is directed to a print unit rather than the display, UPDATE.RECORD displays a progress report in the form of a series of asterisks.

 

On completion of the update, UPDATE.RECORD may create two entries in the $SAVEDLISTS file. If one or more records could not be updated because they were locked by other users, a select list named &LOCK.userno& is created containing a list of such records. If one or more records specified for update did not exist in the file and the CREATING keyword was not used, a select list named &MISS.userno& is created containing a list of the missing record ids. UPDATE.RECORD deletes any old versions of these lists at the start of the update.

 

Note that the database locking system is of a voluntary nature. Both the file and record level locking performed by UPDATE.RECORD only prevent other users acquiring the locks. A program that does not use locks correctly may still be able to access the file during the update.

 

On completion of the update, @SYSTEM.RETURN.CODE will be set to the number of records updated. If the command terminates due to a command line error, @SYSTEM.RETURN.CODE will be negative.

 

 

Examples

 

UPDATE.RECORD STOCK 01-1745 IN.STOCK,0

 

This update amends field IN.STOCK of record 01-1745 in the STOCK file to be zero.

 

 

UPDATE.RECORD SALES ALL TOTAL.SOLD, EVAL "TOTAL.SOLD + THIS.MONTH" THIS.MONTH,0 EXCLUSIVE REPORTING LPTR 2

 

This update processes all records from the SALES file, adding the current value of the THIS.MONTH field into the TOTAL.SOLD field, resetting THIS.MONTH to zero. The EXCLUSIVE keyword ensures that the file is not updated by other users during the amendment. A detailed report of the changes is sent to print unit 2.

 

 

UPDATE.RECORD PAYROLL INQUIRING SALARY,EVAL "SALARY * 1.05"

 

This update processes entries of the PAYROLL file specified in response to a record id prompt, increasing the value of SALARY by 5%.

 

 

UPDATE.RECORD STOCK FROM 2 5,"12/9/96" CONV "D2/"

 

This update uses select list 2 to identify records of the STOCK file in which field 5 is to be set to the internal form of the date 12/9/96.

 

 

The Report

 

The REPORTING keyword causes UPDATE.RECORD to generate a detailed report of its actions. This can be used as a simple audit trail of the changes made to the file and also contains information that enables recovery from an incorrect amendment.

 

The report shows the start of the amendment for a given record, the changes made to each field and the termination of the update at the point when the record has been written back to the file. Missing records and records which have been created by UPDATE.RECORD are highlighted in this report.

 

A command such as

 

UPDATE.RECORD STOCK FROM 2 OLD.VALUE,VALUE VALUE,EVAL "VALUE*1.1" CREATING

 

might produce a report including the following lines

 

Start of update of record '01-1268'

 Field OLD.VALUE was '' now '90'

 Field VALUE was '90', now '99'

 Completed update of record '01-1268'

Record '01-6723' locked by another user.

Creating record '01-7491'

 Field OLD.VALUE was '75' now '80'

 Field VALUE was '80', now '88'

 Completed update of record '01-7491'

 

This example shows the report entries for update of a record found in the file, a record that was not updated because it was locked by another user and a record that was created by UPDATE.RECORD.

 

If the CREATING option was not used, record 01-7491 would have produced the following report line

 

Record '01-7491' not found.