READU

The READU statement allows a program to read a record from a previously opened file into a variable. It respects record locking and locks the specified record for update.

COMMAND SYNTAX

READU variable1 FROM {variable2,} expression {SETTING setvar} {ON ERROR statements} {LOCKED statements} THEN|ELSE statements

SYNTAX ELEMENTS

variable1 is the identifier into which the record will be read.

variable2, if specified, should be a jBC variable that has previously been opened to a file using the OPEN statement. If variable2 is not specified then the default file is assumed.

The expression should evaluate to a valid record key for the file.

If the SETTING clause is specified and the read fails, setvar will be set to one of the following values:

Incremental File Errors

If ON ERROR is specified, the statements following the ON ERROR clause will be executed for any of the above Incremental File Errors except error 128.

NOTES

If the record could not be read because another process already had a lock on the record then one of two actions is taken. If the LOCKED clause was specified in the statement then the statements dependant on it are executed. If no LOCKED clause was specified then the statement blocks (hangs) until the lock is released by the other process. The SYSTEM(43) function can be used to determine which port has the lock.

If the statement fails to read the record then any statements associated with the ELSE clause will be executed. If the statement successfully reads the record then the statements associated with any THEN clause are executed. Either or both of THEN and ELSE clauses must be specified with the statement.

The lock taken by the READU statement will be released by any of the following events:

• The record is written to by the same program with WRITE, WRITEV or MATWRITE statements.
• The record is deleted by the same program with the DELETE statement.
• The record lock is released explicitly using the RELEASE statement.
• The program stops normally or abnormally.

See also: WRITE, WRITEU, MATWRITE, MATWRITEU, RELEASE, DELETE

For more detailed information on record locking, see the article The Keys to Record Locking.

EXAMPLES

OPEN "Customers" ELSE ABORT 201, "Customers"
OPEN "DICT Customers" TO DCusts ELSE
    ABORT 201, "DICT Customers"
END
LOOP
    READU Rec FROM DCusts, "Xref" LOCKED
        CRT "Xref locked by port ":SYSTEM(43):" - retrying"
        SLEEP 1; CONTINUE ;* Restart LOOP
    END THEN
        READ DataRec FROM Rec ELSE
            ABORT 202, Rec
        END
        BREAK ;* Leave the LOOP
    END ELSE
        ABORT 202, "Xref"
    END
REPEAT

jBC