GETRFA

Return a record’s RFA

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

GETRFA:new_rfa|new_grfa

Arguments

new_rfa

The returned RFA. (a6)

new_grfa

The returned global RFA (GRFA). (a10)

Discussion

The GETRFA qualifier returns the record’s RFA or GRFA after the operation has been performed.

In some cases an RFA is returned even following an error; $ERR_KEYNOT and $ERR_TOOBIG generated by a READ or READS still transfer a data record and its RFA.

See the warning in Error trapping for information about inconsistencies that may occur after an I/O error is encountered.

Using GRFAs can help you implement optimistic locking. (See Optimistic locking technique for more information.) Using the GETRFA qualifier with a GRFA enables a READ or READS statement to read a record along with its CRC. If you save off the GRFA that is returned, a subsequent READ or READS with the RFA qualifier can attempt to reacquire the same record. If a record has changed between reads, it will still be read, but a “Record not same” error (RECNOT) will result because the CRC no longer matches. To retrieve the CRC portion of the GRFA, use the %GETCRC routine.

GETRFA:grfa is supported on the READ, READS, and WRITE statements for stream, sequential, relative, block, and ISAM files; on the WRITES statement for stream, sequential, relative, and block files; on the STORE statement for ISAM files; and on the FIND statement only if the file being accessed is configured with stored GRFA. Note that when you get the GRFA from one of these statements, the CRC portion will be ignored by FIND without stored GRFA, by UNLOCK, and by the deprecated POSRFA routine when you try to use it there.

The following built-in types are available when declaring an RFA or GRFA variable.

• D_RFA_TYPE (defined as a6)
• D_GRFA_TYPE (defined as a10)

See also

• FIND statement
• READ statement
• READS statement
• STORE statement
• WRITE statement
• RFA qualifier
• Record locking
• Record file addresses (RFAs)

Examples

The following routines illustrate the use of GRFA to implement optimistic locking. A record is read from an ISAM file and then parts are updated. The new record is then written back to the file after it has been determined not to have changed. If the record has changed, the update is attempted again after notifying the user. A brief record lock only occurs when the on-disk record before the WRITE is the same as it was before the update.

.define RECORD_UPDATED          ,1
.define RECORD_NOT_UPDATED      ,2
.define USER_CANCEL             ,0
.define USER_RETRY              ,1
.define RECSIZ                  ,256
function optimistic_update      ,i
    ch                          ,n
    rec                         ,a
    key                         ,a
record
    grfa        ,D_GRFA_TYPE    ;Or a10
    tmprec      ,a RECSIZ
proc
    read(ch, rec, key, GETRFA:grfa, LOCK:Q_NO_LOCK)
    xcall update_totals(rec)
    read(ch, tmprec, RFA:grfa, WAIT:Q_WAIT) [$ERR_RECNOT=was_changed]
    write(ch, rec)                      ;Update and unlock the record
    freturn(RECORD_UPDATED)
was_changed,
    rec = tmprec                        ;Note: The lock has been released
    freturn(RECORD_NOT_UPDATED)         ; as a result of the error
end
subroutine process_record
    ch                  ,n
    rec                 ,a
    key                 ,a
record
    st                  ,i1
proc
    while (%optimistic_update(ch, rec, key) .eq. RECORD_NOT_UPDATED)
      begin
        xcall notify_user(rec, key, st)
          if (st .eq. USER_CANCEL)
            exitloop
          sleep 1
      end
    xreturn
end