READU

READU

Top  Previous  Next

 

The READU statement reads a record from a previously opened file, setting an update lock.

 

 

Format

 

READU var {ENCODING name} FROM file.var, record.id {ON ERROR statement(s)}

{LOCKED statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

 

where

 

varis the name of a variable to receive the dynamic array read from the file.

 

file.varis the file variable associated with the file.

 

record.idevaluates to the id of the record to be read.

 

statement(s)are statements to be executed depending on the outcome of the READU operation.

 

At least one of the THEN and ELSE clauses must be present unless the OPTIONAL.THEN.ELSE setting of the $MODE compiler directive is enabled.

 

 

The optional ENCODING element to this statement sets the character encoding to be used, overriding any encoding set in the VOC F-type record or when the file was opened. This is relevant only to directory files and is ignored for other file types. A null string as the encoding name is equivalent to not having the ENCODING clause at all. To disable the default encoding, the encoding name should be specified as "NULL".

 

The THEN clause is executed if the READU is successful. The specified record is read into the named variable and an update lock is set. See Locks for full details of QM's locking mechanism.

 

The LOCKED clause is executed if the file or record is locked by another process. The STATUS() function will return the user id of a process holding a lock that is blocking this action or zero if the lock table is full. If the LOCKED clause is omitted and the file or record is locked, the program will wait for the lock to be released.

 

The ELSE clause is executed if the READU fails because no record with the given id is present on the file. If the PICK.READ mode of the $MODE directive is used var will be left unchanged, otherwise it will be set to a null string for a normal file or an empty collection for a data collection file. The STATUS() function will indicate the cause of the error.

 

The ON ERROR clause is executed for serious fault conditions such as errors in a file's internal control structures. The STATUS() function will return an error number. If no ON ERROR clause is present, an abort would occur.

 

Example

 

READU ITEM FROM STOCK, ITEM.ID LOCKED

  DISPLAY "Record is locked by user " : STATUS()

END THEN

  ...processing statements...

  WRITE ITEM TO STOCK, ITEM.ID

END ELSE

  DISPLAY "Record " : ITEM.ID : " not found"

  RELEASE STOCK, ITEM.ID

END

 

This program fragment reads a record from the a file previously opened to file variable. STOCK into variable ITEM, setting an update lock on the record. If successful, the processing statements are executed. If the record is not found, a message is displayed and the record is unlocked. The locked clause displays an error message if the record is locked by another user.