Queue Debug

Queue Debug

PURPOSE: The QUEUE DEBUG option controls whether DS level and record-level access attempts are traced and corresponding messages displayed at the terminal.

SYNTAX

{ENABLE; DISABLE} QUEUE DEBUG [IF; UNLESS clause]

ENABLE

causes tracing of all attempts by the program to access either the DS or a record, and displays the appropriate message at the terminal.

DISABLE

turns off tracing and messages. This is the default state.

IF; UNLESS

specifies a condition for the option to be enabled or disabled.

Example

The following illustration shows the messages that are displayed when a PM is executed with QUEUE DEBUG enabled. Assume the user’s PM, called REVENUE, relates a DS called SALES_DBM2 which is currently used by another person, user JOHN.MKT. The PM relates the SALES_DBM2 DS with: FOR UPDATE ALLOWING GET PUT.

*ENABLE QUEUE DEBUG

*USE PM REVENUE

>> Queuing DS file SALES_DBM2

>>>> GET is shared; PUT is shared; APPEND is exclusive;

DELETE is exclusive

>>>> Queue request blocked - resource not available

Waiting for DS file SALES_DBM2 in use by PID 1838 User JOHN.MGR

.

.

>>>> Queue request unblocked - request satisfied

.

.

>>>> Dequeuing DS file SALES_DBM2

The first three messages are generated by ENABLE QUEUE DEBUG, then the next one by the system field @DS_MESSAGE. ENABLE QUEUE DEBUG continues to trace the queue status of resources used by the PM and display the appropriate messages, until the PM is terminated.

NOTES: QUEUE DEBUG generates the same messages (1-6) as QUEUE TRACE for DS access attempts. In addition, QUEUE DEBUG generates these additional messages when attempts are made to access records:

(7) GET is {E}; PUT is {E}; APPEND is {E}; DELETE is {E}

(8) Queue request satisfied

(9) Queuing all records in {N} for {E} access

(10) Queuing file block {O}:{O} in {N} for {E} access

(11) Dequeuing all records in {N}

(12) Dequeuing file block {O}:{O} in {N}

(13) {N} was not queued due to duplicate relates

(14) {M} has record queuing without file queuing

Key: {N}= Data Set {O} = block number

{E}= Status of operation {M} = Data Index of Control File

Message (7) is displayed along with Message (1) when a program running in the Concurrent Queued environment submits a request for a DS. {E} represents the status of the operations GET, PUT, APPEND, and DELETE. The possible statuses are: shared, shared group 1, exclusive, and not queued. They are determined by the FOR and ALLOWING clauses used in the RELATE statement of the PM.

An operation is said to be shared if it is specified in both the FOR clause and ALLOWING clause of the user’s PM. An operation is shared group 1 when it is not specified in either the FOR or the ALLOWING clause. It is not queued when it is specified in the ALLOWING clause but not in the FOR clause. It is exclusive when it is specified in the FOR clause but not in the ALLOWING clause. These operation statuses can be summarized as follows:

STATUS	Specified in FOR clause	Specified in ALLOWING clause
Shared	yes	yes
Shared group 1	no	no
Exclusive	yes	no
Not queued	no	yes

The information given by this message helps users determine how many ENQ/DEQ locks are required by their programs. One lock is required for each operation that has a status of shared, shared group 1, or exclusive.

Message (8) is displayed immediately below Message (7) if the request for a DS is granted when it is initially submitted. If the request cannot be granted because the DS is being used by another program, message (2) will be displayed instead. When the request is finally granted, message (3) will then be displayed on the screen.

Message (9) is issued when a LOCK statement is executed in the user’s program to lock all records in a DS. The status indicated by {E} would be exclusive or shared.

Message (10) is issued when a block (or blocks) of records is retrieved for use by the present program; the {O}’s are integers representing block numbers.

Message (11) is issued when a FREE statement is used to release all records reserved or locked by the user’s program.

Message (12) is issued when a block of records is released because the next block is reserved or locked.

Message (13) is issued when a DS is related more than once in a PM. When this happens, only one request for the DS will be queued, and this message will be issued for the duplicate requests. If one of the requests is for update, the DS will be queued for update.

Message (14) is displayed when a CF or DI file is used for a program operating under the Concurrent Queued environment. CF’s are used as an end-of-file pointer for multiple users accessing a DS in the Concurrent Queued environment.

When records have been queued and locked using GET…LOCKED…MULTIPLE, returning to any one of these records with another GET…LOCKED…MULTIPLE statement will cause QUEUE DEBUG to display a message showing the records being re-queued. However, additional machine resources are not being used.

In addition to the messages generated by ENABLE QUEUE TRACE and ENABLE QUEUE DEBUG, ACCENT R displays out the corresponding @WAIT_MESSAGE, @DS_MESSAGE, and @RECORD_MESSAGE for programs running in Concurrent Queued environment, if these system fields have not been disabled.

SEE ALSO: QUEUE TRACE, Control Files (later in this chapter).