KEEP LONGTERM (DC/UCF)

Data Manipulation Language Statements › KEEP LONGTERM (DC/UCF)

KEEP LONGTERM (DC/UCF)

The KEEP LONGTERM statement establishes longterm record locks and/or monitors access to records between tasks. Longterm database locks are used in pseudo-conversational transactions and can be shared or exclusive:

Longterm shared locks allow other run units to access the locked record but prevent run units from updating the record as long as the lock is maintained.
Longterm exclusive locks prevent other run units from accessing the locked record. However, run units executing on the logical terminal associated with the issuing task are not restricted from accessing the locked record. Therefore, subsequent tasks in a transaction can access the locked record and complete the database processing required by the transaction.

If a record has been locked with a KEEP LONGTERM or KEEP request, restrictions exist on the type of lock that can be placed on that record by other run units. These restrictions are based on existing locks and whether the requesting run unit is executing on the same logical terminal as the run unit that originally placed the lock on the record. The following table illustrates these restrictions.

Locks in effect	Locks allowed for other run units	Locks disallowed for other run units
Shared	Shared and longterm shared	Exclusive and longterm exclusive
Exclusive	None	Shared, exclusive, longterm shared, and longterm exclusive
Longterm shared	For all run units: shared and longterm shared For run units on the same terminal: exclusive and longterm exclusive	For run units on other terminals: exclusive and longterm exclusive
Longterm exclusive	For run units on the same terminal: shared, exclusive, longterm shared, and longterm exclusive	For run units on other terminals: shared, exclusive, longterm shared, longterm exclusive

Tasks can monitor database activity associated with a specified record during a pseudo-converse and, if desired, can place a longterm lock on the record being monitored. A subsequent task can then make inquiries about that database activity for the record and take the appropriate action.

The DC/UCF system maintains information on database activity by using five bit flags, each of which is either turned on (binary 1) or turned off (binary 0). This information is returned to the program as a numeric value. The bit assignments, the corresponding numeric value returned to the program, and a description of the associated database activity follow:

Numeric value	Bit assignment	Description
16	X'00000010'	The record was physically deleted.
8	X'00000008'	The record was logically deleted.
4	X'00000004'	The record's prefix was modified; that is, a set operation (for Example, CONNECT or DISCONNECT) occurred involving the record.
2	X'00000002'	The record's data was modified.
1	X'00000001'	The record was obtained.

To determine the action or combination of actions that has occurred, you can compare the numeric value returned to the program with an appropriate constant. For example:

If the returned value is 0, no database activity occurred for the specified record.
If the returned value is 2, the record's data was modified.
If the returned value is 2 or greater, the record was altered in some way.
If the returned value is 8 or greater, the record was deleted.

The maximum possible value is 31, indicating that all the above actions occurred for the specified record.

You may prefer to monitor database activity across a pseudo-converse rather than to set longterm locks. Monitoring does not restrict access to database records, sets, or areas by other run units; however, it does enable a program to test a record for alterations made by other run units. The presence of longterm locks can prevent other run units from accessing locked records for an undesirable amount of time if, during a pseudo-converse, the terminal operator fails to enter a response. If longterm locks are used, you may want to release them at specified intervals.

Note: For more information about the use of timeout intervals, see the CA IDMS System Generation Guide.

Syntax

►►─── KEEP LONGTERM ( ─┬─ ALL ─────────┬─ ) ──────────────────────────────────►
                       └─ longterm-id ─┘

 ►─┬─ NOTIFY CURRENT ─┬─ RECORD (record-name) ─┬───────────────────────────┬;─►◄
   │                  ├─ SET (set-name) ───────┤                           │
   │                  └─ AREA (area-name) ─────┘                           │
   ├┬─ SHARE ─────┬─ CURRENT ─┬─ RECORD (record-name) ─┬─┬──────────────┬──┤
   │└─ EXCLUSIVE ─┘           ├─ SET (set-name) ───────┤ ├─ WAIT ◄ ─────┤  │
   │                          └─ AREA (area-name) ─────┘ ├─ NOWAIT ─────┤  │
   │                                                     └─ NODEADLOCK ─┘  │
   ├─ upgrade-specification ───────────────────────────────────────────────┤
   ├─ TEST ─┬──────────────────────────────────────────────┬───────────────┤
   │        └─ RETURN NOTIFICATION INTO (return-location) ─┘               │
   └─ RELEASE ─────────────────────────────────────────────────────────────┘

Expansion of upgrade-specification

►►─┬─────────────────────────────────────────────────────────────────────────►─
   └ UPGRADE ─┬  SHARE ─────┬┬────────────────────────────────────────────┬──
              └  EXCLUSIVE ─┘└ RETURN NOTIFICATION INTO (return-location) ┘

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

Parameters

LONGTERM (ALL)/ (longterm-id)

Specifies the 1- to 16-character identifier that will be used in subsequent KEEP LONGTERM requests to upgrade or release a longterm lock or to make inquiries about database activity associated with the specified record. Longterm-id is either the symbolic name of a user-defined field that contains the longterm ID, or the ID itself enclosed in single quotation marks.

ALL is used only with the RELEASE parameter (described below) to request that the system release all longterm locks kept for the logical terminal associated with the current task.

NOTIFY CURRENT RECORD (record-name)/SET (set-name) /AREA (area-name)

Monitors database activity associated with the current occurrence of the named record type or the current record of the named set or area. When NOTIFY CURRENT is specified, the system initializes a preallocated location in the program to contain information on database activity for the specified record.

SHARE/EXCLUSIVE CURRENT RECORD (record-name)/SET (set-name)/AREA (area-name)

Specifies that the current occurrence of the named record type or the current record of the named set or area will receive a longterm shared (SHARE) or longterm exclusive (EXCLUSIVE) lock.

upgrade-specification

Upgrades a previous KEEP LONGTERM NOTIFY CURRENT request by placing a shared (SHARE) or exclusive (EXCLUSIVE) longterm lock on the record identified by longterm-id.

WAIT

Requests the issuing task to wait for the existing lock to be released. If the wait would cause a deadlock, the system terminates the task abnormally. WAIT is the default.

NOWAIT

Requests the issuing task not to wait for the existing lock to be released.

NODEADLOCK

Requests the issuing task to wait for the existing lock to be released, unless to do so would cause a deadlock. If the wait would cause a deadlock, the system returns control to the task.

RETURN NOTIFICATION INTO (return-location)

Returns information on database activity for that record. Return-location is the symbolic name of a user-defined FIXED BINARY(31) field that contains the program variable-storage entry of the data area to which the system will return the information.

TEST RETURN NOTIFICATION INTO (return-location)

Requests that the system return information on database activity associated with the record identified by longterm-id to a previously allocated location in the program's storage. Return-location is the symbolic name of a user-defined FIXED BINARY(31) field that contains the program variable-storage entry of the data area to which the system will return the information.

TEST must specify a longterm lock ID that matches the longterm lock ID specified in a previous KEEP LONGTERM NOTIFY CURRENT request.

RELEASE

Releases the longterm lock for the record identified by longterm-id or all record locks (ALL) owned by the logical terminal associated with the current task. RELEASE also releases the information associated with a previous KEEP LONGTERM NOTIFY request.

Example

The steps below illustrate the use of the KEEP LONGTERM statement:

Begin monitoring database activities for the current occurrence of the EMPLOYEE record by coding:
```
KEEP LONGTERM (KEEP_ID)
  NOTIFY CURRENT RECORD (EMPLOYEE);
```
Return statistics of database activities for the record identified by KEEP_ID into STAT_VALUE by coding:
```
KEEP LONGTERM (KEEP_ID) TEST RETURN NOTIFICATION
       INTO (STAT_VALUE);
```
Depending on the value returned to STAT_VALUE, you may want to put a longterm shared lock on the EMPLOYEE record identified by KEEP_ID by coding:
```
KEEP LONGTERM (KEEP_ID) UPGRADE SHARE;
```
Upon processing, release all longterm locks by coding:
```
KEEP LONGTERM (ALL) RELEASE;
```

Status Codes

Upon completion of the KEEP LONGTERM function, the ERROR-STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000: The request has been serviced successfully.
5101: The NODEADLOCK option has been specified; however, to wait would cause a deadlock. Control has returned to the issuing task.
5102: Unable to obtain storage for the required KEEP LONGTERM control blocks.
5105: Either the requested record type cannot be found or currency has not been established.
5113: The required area control block was not found in the DMCL.
5121: Either the requested longterm ID cannot be found or the KEEP LONGTERM request was issued by a nonterminal task.
5123: The specified area cannot be found.
5131: The parameter list is invalid.
5147: The KEEP LONGTERM area has not been readied.
5148: The run unit associated with the KEEP LONGTERM request has not been bound.
5149: The NOWAIT option has been specified; however, a wait is required.
5151: A lock manager error occurred during the processing of the KEEP LONGTERM request.
5159: An error occurred in transferring the KEEP LONGTERM request to IDMSKEEP.
5160: The requested KEEP LONGTERM lock ID was already in use with a different page group.
5161: The requested KEEP LONGTERM lock ID was already in use with a different BDKey format.