Data Manipulation Language Statements › PUT SCRATCH (DC/UCF)

PUT SCRATCH (DC/UCF)

The PUT SCRATCH statement stores or replaces a scratch record in the DDLDCSCR area of the data dictionary. For new records, PUT SCRATCH generates an index entry in a scratch area associated with the issuing task. If the scratch area does not already exist, the system allocates it dynamically in the storage pool.

Syntax

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

 ►── FROM (scratch-data-location) ─┬─ TO (end-scratch-data-location) ───────┬─►
                                   └─ LENGTH (scratch-data-location-length)─┘

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

 ►─┬─────────────────────────────────────────────┬─ ; ────────────────────────►◄
   └─ RETURN RECORD ID INTO (scratch-record-id) ─┘

Parameters

AREA ID (scratch-area-id)

Specifies the 1- to 8-character ID of the scratch area associated with the record being allocated. Scratch-area-id is either the symbolic name of a user-defined field that contains the ID or the ID itself enclosed in single quotation marks. If AREA ID is not specified, an area ID of eight blanks is assumed.

FROM (scratch-data-location)

Specifies the data to be stored in the scratch record. Scratch-data-location is the symbolic name of a user-defined program variable-storage entry that contains the data.

TO (end-scratch-data-location)

Indicates the end of the data area to be stored in the scratch record and is specified following the last data-item entry in scratch-data-location. End-scratch-data-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the scratch data being stored.

LENGTH (scratch-data-location-length)

Defines the length, in bytes, of the data area. Scratch-data-location-length is the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.

RECORD ID (scratch-record-id)

Specifies the ID of the scratch record being stored. Scratch-record-id is either the symbolic name of a user-defined FIXED BINARY(31) field that contains the ID or the ID itself expressed as a numeric constant.

REPLACE

Specifies that the scratch record identified by scratch-record-id replaces an existing scratch record. If REPLACE is specified and the scratch record identified by scratch-record-id does not exist, the record is stored and a status value of 0000 is returned.

RETURN RECORD ID INTO (scratch-record-id)

Requests that the system return the automatically assigned ID of a scratch record to the program. Return-scratch-record-id is the symbolic name of a user-defined field into which the system will place the 4-byte scratch record ID.

Example

The following statement replaces the scratch record identified by SCR_REC_ID with data in the WORK_PROC_AREA field:

PUT SCRATCH
  FROM (WORK_PROC_AREA) LENGTH (125)
  RECORD ID (SCR_REC_ID) REPLACE;

Status Codes

Upon completion of the PUT SCRATCH function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000

The request to add a scratch record has been serviced successfully.

4305

The requested scratch record ID cannot be found.

4307

An I/O error has occurred during processing.

4317

The request to replace a scratch record has been serviced successfully.

4322

The request to add a scratch record cannot be serviced because the specified scratch record already exists in the scratch area and REPLACE has not been specified.

4331

The parameter list is invalid.

4332

The derived length of the specified scratch record is either zero or negative.