Queue and Scratch Management Commands › PUT SCRATCH

PUT SCRATCH

Purpose

Stores or replaces a scratch record in the scratch area.

Syntax

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

 ►─── FROM scratch-data-location-variable ────────────────────────────────────►

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

 ►──┬──────────────────────────────────────────────┬──────────────────────────►
    └─ RECORD ID scratch-record-id ──┬───────────┬─┘
                                     └─ REPLACE ─┘

 ►─┬────────────────────────────────────────────────────────────┬─────────────►
   └─ RETURN RECORD ID into return-scratch-record-id-variable ──┘

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

Parameters

AREA ID scratch-area-id

Specifies the area in the scratch area where the record will be stored.

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.

FROM scratch-data-location-variable

Specifies the location of the data to be stored in the queue record.

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 that contains the data to be stored in the scratch record.

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

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

LENGTH scratch-data-length

Specifies the length, to be specified in bytes, of the buffer area that contains the data to be stored in the scratch record.

Scratch-data-length is either 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 LENGTH scratch-data-length is specified, the length of the location is the length of scratch-data-location-variable.

RECORD ID scratch-record-id

Assigns an id to the scratch record being stored.

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.

The scratch record id can subsequently be used to retrieve or delete the associated scratch record.

The scratch record id is stored as a binary fullword.

REPLACE

Replaces the scratch record identified by scratch-record-id with the scratch record being stored.

RETURN RECORD ID into return-scratch-record-id-variable

Returns a system-assigned scratch record id to the location specified by return-scratch-record-id-variable.

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

Return-scratch-record-id-variable cannot be defined as a doubleword binary field.

The scratch record id can subsequently be used to retrieve or delete the associated scratch record.

The system assigns a scratch record id if one is not specified in the RECORD ID parameter.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

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

Example

The following example illustrates the use of the PUT SCRATCH command:

PUT SCRATCH AREA ID 'CUSTAREA' FROM CUSTWORK LENGTH REC-LENGTH
RETURN RECORD ID INTO REC-ID.

More information:

Error Handling