Queue and Scratch Management Commands › GET SCRATCH

GET SCRATCH

Purpose

Transfers the contents of a scratch record to a specified location in a dialog's record buffers.

Syntax

►►─── GET SCRATCH ────┬────────────────────────────┬──────────────────────────►
                      └─ AREA ID scratch-area-id ──┘

 ►──┬─ DELETE ◄ ─┬──── INTO return-scratch-data-location-variable ────────────►
    └─ KEEP ─────┘

 ►──┬──────────────────────────────────────────┬──────────────────────────────►
    ├─ TO end-scratch-data-location-variable ──┤
    └─ MAX LENGTH scratch-data-max-length ─────┘

 ►──┬─ CURRENT ──────────────────────┬────────────────────────────────────────►
    ├─ FIRST ────────────────────────┤
    ├─ LAST ─────────────────────────┤
    ├─ NEXT ◄ ───────────────────────┤
    ├─ PRIOR ────────────────────────┤
    └─ RECORD ID scratch-record-id ──┘

 ►──┬─────────────────────────────────────────────────────────────┬───────────►
    └── RETURN LENGTH into scratch-data-actual-length-variable ───┘

 ►──┬────────────────────┬────── . ───────────────────────────────────────────►◄
    └─ error-expression ─┘

Parameters

AREA ID scratch-area-id

Specifies an area in the scratch area to be retrieved.

Scratch-area-id is either the name of a variable data field that contains a scratch area id or the 1- to 8-character scratch area id itself, enclosed in single quotation marks.

If scratch-area-id is not specified, a null scratch area id (that is, eight blanks) is assumed.

DELETE

Deletes the record from the scratch area after it is passed to the requesting task.

If the record is truncated, the truncated data may be lost permanently.

DELETE is the default when you specify neither DELETE or KEEP.

KEEP

Retains the record in the scratch area after it is passed to the requesting task.

INTO return-scratch-data-location-variable

Specifies the location to which the requested scratch record is transferred.

Return-scratch-data-location-variable is the name of a variable data field in the dialog's record buffers.

TO end-scratch-data-location-variable

Specifies the end of the buffer area allocated for the requested scratch record.

End-scratch-data-location-variable is the name of a dummy byte field or the name of a variable data field that contains a data item not associated with the requested scratch record.

The field specified by end-scratch-data-location-variable must immediately follow the last byte of the buffer area allocated for the requested scratch record.

MAX LENGTH scratch-data-max-length

Specifies the length of the buffer area allocated for the requested scratch record.

Scratch-data-max-length is the name of a variable data field that contains the length or the length itself, expressed as a numeric constant.

If neither TO end-scratch-data-location-variable nor MAX LENGTH scratch-data-max-length is specified, the length of the location is the length of return-scratch-data-location-variable.

CURRENT

Obtains the record that is current of the scratch area specified by scratch-area-id.

FIRST

Obtains the first record in the scratch area specified by scratch-area-id.

LAST

Obtains the last record in the scratch area specified by scratch-area-id.

NEXT

Obtains the record that follows the current record of the scratch area specified by scratch-area-id.

NEXT is the default when you specify no other scratch record to be obtained.

If currency is not established, NEXT is equivalent to FIRST.

PRIOR

Obtains the record that precedes the current record of the scratch area specified by scratch-area-id.

If currency is not established, PRIOR is equivalent to LAST.

RECORD ID scratch-record-id

Obtains the record identified by scratch-record-id.

Scratch-record-id is either the name of a variable data field that contains the scratch record id or the scratch record id itself, expressed as a numeric constant.

RETURN LENGTH into scratch-data-actual-length-variable

Returns the untruncated length of the obtained scratch record to the location specified by scratch-data-actual-length-variable.

Scratch-data-actual-length-variable is the name of a numeric field in the dialog's record buffers.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

If the scratch record is larger than the allocated buffer area, the record is truncated as necessary.

If autostatus is not in use, a dialog's error-status field indicates the outcome of a GET SCRATCH command:

Example

The following example illustrates the use of the GET SCRATCH command to copy the last record in scratch area CUSTAREA to a location in the dialog's record buffers identified by CUSTWORK. The record is retained in the scratch area for later access:

GET SCRATCH AREA ID 'CUSTAREA' KEEP LAST
INTO CUSTWORK MAX LENGTH REC-LENGTH.

More information:

Error Handling