Database Access Commands › Navigational DML › KEEP LONGTERM

KEEP LONGTERM

Purpose

Sets or releases long-term record locks, and monitors database activity across run units.

Information on database activity can be returned to a specified location in a dialog's record buffers.

Syntax

►►── KEEP LONGterm ────┬─ ALL ─────────┬──────────────────────────────────────►
                       └─ longterm-id ─┘

 ►─┬─ NOTIFY CURrent ───┬─ record-name ─┬───────────────┬─────────────────────►
   │                    ├─ set-name ────┤               │
   │                    └─ area-name ───┘               │
   ├─ TEST RETurn notification into return-location ────┤
   ├─ RELease ──────────────────────────────────────────┤
   └─ lock-options ─────────────────────────────────────┘

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

Expansion of Lock-Options

►►─┬┬─ SHAre ─────┬───┬─ record-name ─┬─────────────────────────────────────┬─►
   │└─ EXClusive ─┘   ├─ set-name    ─┤                                     │
   │                  └─ area-name   ─┘                                     │
   └─ UPgrade ─┬─ SHAre     ─┬┬────────────────────────────────────────────┬┘
               └─ EXClusive ─┘└─ REturn notification into return-location ─┘

 ►───────┬─ WAIT ─────────┬───────────────────────────────────────────────────►◄
         ├─ NOWAIT────────┤
         └─ NODEADLOCK ◄ ─┘

Parameters

ALL

(Only with the RELEASE parameter) Requests release of all long-term locks associated with the current task.

longterm-id

Either the name of a 1- to 16-character variable EBCDIC data field that contains a lock identifier or the 1- to 16-character identifier itself, enclosed in single quotation marks.

Longterm-id can be used by a subsequent KEEP LONGTERM command to upgrade or release the long-term lock or to inquire about the status of database activity for the object record.

NOTIFY CURrent

Initializes a preallocated area in the dialog's record buffer with the information written by DC/UCF on the database activity for the record identified by longterm-id.

record-name

Specifies monitoring of database activity for the record that is current of record type.

set-name

Specifies monitoring of database activity for the record that is current of set.

area-name

Specifies monitoring of database activity for the record that is current of area.

TEST RETurn notification into

Requests that information on database activity for the record identified by longterm-id be returned to the location in the dialog's record buffers specified by return-location.

In order to specify RETURN NOTIFICATION, a previous KEEP LONGTERM command must have included the NOTIFY CURRENT option.

return-location

The name of a binary fullword variable data field.

RELease

Releases either the long-term lock for the record identified by longterm-id or all long-term record locks associated with the current task.

All long-term locks that have not been released by the time the application terminates are released when the user signs off from DC/UCF with a BYE, SIGNON, or SIGNOFF command.

lock-options

Identifies the lock options.

Expanded syntax for lock-options is shown above immediately following the KEEP LONGTERM syntax.

error-expression

Specifies the status codes that are returned to the dialog.

SHAre

Places a long-term shared lock on the object record.

EXClusive

Places a long-term exclusive lock on the object record.

Note: The shared or exclusive lock is placed only if the area in which the record is located is readied in an update usage mode.

UPGRADE

Upgrades a longterm lock placed on the record identified by longterm-id during execution of a previous process.

REturn notification into

Clause requesting that information on database activity for the record identified by longterm-id be returned to the location in the dialog's record buffers specified by return-location.

WAIT

(Applies only to SHARE/EXCLUSIVE and UPGRADE) Places the run unit in a wait state if the lock cannot be placed immediately due to an existing lock on the record.

If waiting causes a deadlock, the requesting run unit terminates abnormally.

NOWAIT

(Applies only to SHARE/EXCLUSIVE and UPGRADE) Does not place the run unit in a wait state if the lock cannot be placed immediately due to an existing lock on the record. Control returns to the requesting run unit. The KEEP LONGTERM request is not executed.

NODEADLOCK

(Applies only to SHARE/EXCLUSIVE and UPGRADE) Places the run unit in a wait state. If waiting causes a deadlock, control returns to the requesting run unit and the KEEP LONGTERM request is not executed.

NODEADLOCK is the default when neither WAIT, NOWAIT, or NODEADLOCK is specified.

If WAIT or NODEADLOCK is specified, the run unit waits to place the lock only if the following conditions apply:

• The object record already holds an exclusive lock assigned by a concurrently executing run unit.
• The run unit that assigned the existing lock has readied the area in which the object record is located in an update usage mode.
• The run unit issuing the KEEP LONGTERM request has readied the area in which the object record is located in an update usage mode.

Control returns to the requesting run unit unless all of the above conditions apply.

Usage

Considerations

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

Further Considerations

When the database performs an action on an object record, one of five bit flags is turned on by the runtime system. If no bit is turned on, no database activity has occurred. The following table shows the bit assignments, their corresponding hexadecimal and decimal values, and the database activity they represent.

Information about database activity that occurred for an object record is returned to a dialog as a decimal value. The action or combination of database actions taken can be determined by comparing the returned decimal value listed above to a constant. For example:

• If the returned value is 0, no database activity occurred for the record.
• If the returned value is 2, the record's data was modified.
• If the returned value is 6, both the record's data and the record's prefix were modified.
• If the returned value is 8 or greater, the record was deleted.
• If the returned value is 31 (the maximum possible value), all of the above actions occurred for the object record.

Examples

The following examples illustrate the use of KEEP LONGTERM to set locks and to monitor database activity:

Example 1: Setting and upgrading a lock

The following example illustrates the use of KEEP LONGTERM to set an exclusive lock on the current CUSTOMER record in one process and then to upgrade the lock to shared after the record is modified in a subsequent process:

Process A
    .
    .
    .

KEEP LONGTERM LOCK-ID EXCLUSIVE CUSTOMER.
    .
    .
    .


Process B

    .
    .
    .

MODIFY CUSTOMER.
KEEP LONGTERM LOCK-ID UPGRADE SHARE.
    .
    .
    .

By upgrading the lock to shared, other concurrently executing run units are allowed to access the CUSTOMER record after it has been modified.

Example 2: Monitoring database activity

The following example illustrates the use of KEEP LONGTERM to request monitoring of database activity for the current CUSTOMER record in one process and then, in a subsequent process, to test whether the record was deleted:

Process A
    .
    .
    .

OBTAIN CALC CUSTOMER.
KEEP LONGTERM LOCK-ID NOTIFY CURRENT CUSTOMER.
    .
    .
    .

Process B

    .
    .
    .

KEEP LONGTERM LOCK-ID TEST RETURN NOTIFICATION INTO DB-ACTIV.
IF DB-ACTIV GE 8
THEN
    INVOKE 'ORDCHECK'.
    .
    .
    .

More information:

Error Handling