CONTROL FILES

When a DS is going to be accessed under the Concurrent Queued or Exclusive Queued environment, it must first have a CF established.  Each CF is associated with one and only one DS, and serves to coordinate accesses to that DS during concurrent access by multiple users.

Note that a CF is never referenced in a RELATE statement, or in an ACCOPN call, so no changes need to be made to an existing PM or host language programs after a CF is defined.

A CF is created by the DEFINE command.  Once a CF has been defined for a DS, the user need not declare it for use.  ACCENT R automatically uses it whenever the DS is used.

NOTES:  The CF determines whether or not ACCENT R’s 4th Generation tools treat the DS and DI in Concurrent Queued environment.

SEE ALSO:  Control Files

Using The Control File

The following DBL commands work with Control Files:  COPY, LIST, MODIFY, REMOVE, and DIRECTORY.

Example

The examples below show how the commands (listed above) may be used with CF’s.

The DIRECTORY command lists all CF’s in the DBL, and each listing shows the name of the associated DS.  The DS listings in response to a DIRECTORY command will also name the associated CF.

*DIRECTORY

Type Name

DBL   CFTEST

SD    SCHEME

DS    GOODDATA SD SCHEME CF CTROL

CF    CTROL DS GOODDATA

CF entries in the DBL can be accessed through the DBL ACCESS form of the GET statement or the DBL ACCESS form of the ACCGET subroutine call in the Host Language Interface (HLI).  The following structure applies to a CF record in the DBL:

STRUCTURE FOR CF RECORD ID = 'CF'

ENTRY_TYPE

ENTRY_NAME

CREATE_TIME

CHANGE_TIME

SAVE_STATUS

SD_CHECKSUM

DS_NAME

A DS cannot be deleted or renamed if there is an associated CF.  The CF must first be removed with the REMOVE CF command or REMOVE ENTRY FOR CF command.

Example

The following DS Library commands do not work with CF’s:

When a CF must be established for a DS, that CF provides a place to store information about whether a DS has been updated without the DI being active.

When a DS does not have a CF, this information is stored in the DBL.  However, if the DS is used outside the DBL, or if the DBL is “read only”, the information in the DBL is not kept current.  Under these circumstances, the DI might be reformed even though it does not need to be, or conversely, it might be used when it is not current.

When a CF is available, that information should always be accurate, since invoking the DS automatically invokes the CF.

The CF must already be formed before the Simultaneous Update PM that uses them is invoked.  Otherwise, an error message will appear:

DS ds_name MUST HAVE AN ASSOCIATED CF

Locking Resources

Every program requires a certain number of ENQ/DEQ locks in order to reserve the DS's and processing resources that it uses.  The number of locks allowed to each user is determined by the System Manager when the user name is defined in the authorization  file with the parameter ENQLM.  When a user accesses ACCENT R, the number of ENQ/DEQ locks allotted to him is stored in the system field @QUEUE_QUOTA.  The user can quickly ascertain his ENQ/DEQ quota by displaying @QUEUE_QUOTA.  If the number of locks used in a PM exceeds the user’s @QUEUE_QUOTA, a quota error results.

The number of locks required by each element in the program is explained below.

Data Sets

For a PM running under the Concurrent Queued environment, the number of locks required is dependent on the status of the GET, PUT, APPEND, and DELETE operations that are specified in the PM.  One lock is needed for each operation that has a status of shared, exclusive, or shared group 1 (refer to the earlier discussion of ENABLE/DISABLE QUEUE DEBUG for definitions of these terms).  Since there are four possible operations, as many as four locks may be needed to reserve a DS for use.  The status of each operation is displayed in a QUEUE DEBUG message when the DS is queued by the user.

Data Indexes

Two locks are required to activate a DI for use in the PM.

Control Files

Two locks are required to reserve a CF for use.  A DS must have an associated CF in order to operate under the Concurrent Queued environment.  Refer to the preceding discussion, "Control Files," for more information.

Additional locks are required to queue requests for records in a DS.  A LOCK statement takes one lock.  This lock is released when a FREE statement is issued.

A simple GET statement requires a minimum of three locks to retrieve a record.  The number of locks needed depends on the record size.  ENABLE QUEUE TRACE can be used to find out how many locks a PM is using.

A block is freed when a FREE statement is executed or when a subsequent GET retrieves another block.

A GET MULTIPLE statement requires the greatest number of locks, because the retrieved records are not automatically released with the subsequent execution of another GET MULTIPLE statement.  As a result the locks used to retrieve records accumulate until a FREE statement is issued or until the PM terminates.

A quota error is most likely to occur when a GET MULTIPLE statement is used to retrieve several big records without a FREE statement.  For an application that needs to hold many big records at one point, it is suggested that a LOCK statement be used instead of a GET MULTIPLE statement.

SEE ALSO:  ENQ/DEQ Locks - User Authorization File (OpenVMS Manual)

Avoiding Deadlocks & Bottlenecks

A deadlock occurs when two or more users are waiting for resources being held by each other, and each is preventing the other from gaining access.  The simplest example of a deadlock occurs when User A has DS D1 and is waiting for DS D2, while User B has DS D2 and is waiting for DS D1.  Neither user can proceed until the other gives up and releases all resources.  More complex deadlocks can occur involving 3 or more users and 3 or more DS's.

ACCENT R attempts to prevent situations that could result in a deadlock.  At the DS level, it gathers all DS’s to be queued and queues them in the same order for all users.  ACCENT R also dequeues all DS’s used by a PM when it terminates.  If all users who are sharing access to a DS invoke it as a DS in a PM, deadlocks cannot occur at the DS level.

At the record level, the applications programmer must shoulder part of the responsibility for preventing deadlocks.  Since deadlocks are a rare occurrence, the best approach is usually to back out of a deadlock situation, and try again.

Time interrupts are designed to allow users to exit from a deadlock and try again.  A PM can handle possible deadlocks by using a small @RECORD_WAIT value and checking the value of @AUX.  If @AUX is set to “BUSY”, a FREE should be executed.  The PM should then attempt again to retrieve the record.  When doing CREATEs, set @RECORD_WAIT to a value large enough to give the system a chance to retry if it is not successful in adding the record on the first attempt.

The chances of a deadlock occurring can be reduced by having all users who access a given DS queue records in the same order.  In many applications, there is a logical order for accessing records that is definable.

Records should also be retrieved in the same order by all users using the GET statement with the MULTIPLE option.  This order can be alphabetical, record number, or any other logical order, so long as everyone uses the same order.

It has been found that a major bottle-neck while running several applications with Simultaneous Update is the access to the DBL files.  To avoid this problem, the DBL should be used for read-only purposes.  In other words, avoid creating or modifying objects that are stored in the DBL file, such as PM’s, CM’s, SD’s, while running in Simultaneous Update mode.