Storage, Scratch, and Queue Management › Using Queue Records

Using Queue Records

CA IDMS queue management functions allow you to store, retrieve, and delete queue records. Queue records, which are stored in the dictionary, are available to all tasks running under CA IDMS and to batch programs with an operating mode of DC-BATCH.

Queue records are saved across a system shutdown/startup and recovered across a system crash; however, currencies are lost when the system crashes or is shut down.

In a data sharing environment, queues can be shared between members of a data sharing group.

Queue Record Storage

CA IDMS stores queue records in the DDLDCRUN area of the dictionary. Each queue record is a member record in a set owned by a queue header record. All records associated with one queue header are referred to collectively as a queue. You can direct records to queues defined at system generation, to queues defined through the DDDL compiler, to program-defined queues, or to null queues.

Sharing Queues Between CA IDMS Systems

In a data sharing environment, queues can be shared between CA IDMS systems that are members of a sharing group. The benefit of a shared queue is that it can be read and updated by programs executing on any member of the group. Whether or not a specific queue is shared, is determined by specifications made by the CA IDMS system administrator. Programs accessing queues are not sensitive to whether or not a queue is shared, since the DML syntax is the same in either case.

How You Can Use Queue Management

You can use CA IDMS queue management functions to do the following:

• Store a queue record and assign an ID to uniquely identify the record
• Retrieve a queue record and place it in a variable-storage area associated with the issuing task
• Delete a record from a specified queue
• Delete an entire queue

Steps to Store a Queue Record

To store a queue record, perform the following steps:

1. Initialize the appropriate fields in program variable storage.
2. Issue a PUT QUEUE command that specifies the variable-storage location of the data to be stored.

Steps to Retrieve a Queue Record

To retrieve a queue record, perform the following steps:

1. Issue a GET QUEUE command that specifies the appropriate queue ID and indicates the variable-storage location in which the queue record is to be placed.

   If there is any chance that the length of the retrieved record exceeds the length of its allocated variable storage, you should do the following:

   Include the KEEP parameter of the GET QUEUE statement to ensure that the record is not deleted when it is retrieved.

   • Check for a status of 4419 (DC-TRUNCATED-DATA).
2. Check for a status of 4405 (DC-REC-NOT-FOUND), which indicates that you have retrieved all queue records for the specified queue ID.
3. Perform the IDMS-STATUS routine if neither 4405 nor 4419 is returned.

'Queue record currency'. CA IDMS maintains currency for each queue by task. If several tasks are accessing a queue concurrently, CA IDMS maintains currency separately for each task. Access to a queue record can be by queue ID, by position within the queue, or by relationship of the specified record to the current record of the queue.

Steps to Delete a Queue Record

To delete a queue record, issue either of the following commands:

• A GET QUEUE command that specifies the DELETE parameter. CA IDMS copies the record's data to the appropriate variable-storage area and deletes the record.
• A DELETE QUEUE command that specifies one of the following:
  • That the current occurrence of the queue record is to be erased
  • That the entire queue should be deleted

Implicit Deletion of Queue Records

CA IDMS saves the next and prior currencies following a DELETE QUEUE function so that you can still access the next and prior records in the queue. When all records associated with a given queue have been deleted, CA IDMS deletes the header record as well. Queue records are also deleted implicitly if the associated queue header record is deleted.

Deleting Queues

Queues can also be deleted at system startup or at run time:

• At system startup -- Each queue is assigned a retention period; the retention period specifies the number of days that CA IDMS will retain the queue. At system startup, CA IDMS deletes queues that have exceeded their retention periods.
• At run time -- The DCMT VARY QUEUE command can be used to delete unwanted queues at run time.

  For more information on DCMT commands, see CA IDMS System Operations Guide.

Queue Record Locks

Because queues are shared among tasks, CA IDMS must ensure that two tasks do not update a queue record concurrently, causing unexpected alteration of data. Additionally, if a task terminates abnormally, CA IDMS must ensure that the queue can be restored to its state before the failure. To accomplish this, CA IDMS handles queues in the following manner:

• When a task stores or retrieves a queue record, CA IDMS places an implicit exclusive lock on that record, thereby preventing it from being retrieved or updated by other tasks.
• All records locked by CA IDMS remain locked until the task terminates or until your program issues a COMMIT TASK statement. COMMIT TASK causes some or all of the locks to be released, as specified.
• Queue currencies and locks are not passed from one task to the next on a terminal. Each task is responsible for reestablishing any required currencies.

Avoiding Task Waits for Queue Access

Only one task can access a queue record at a time; other tasks attempting access must wait until the current task is complete. Therefore, you should ensure that queue access is short lived. There should be no long waits, such as pseudoconverses, embedded within queue access code.

Retrieving Queue Records

The program excerpt below retrieves and displays queue records. This program uses a pageable map in order to display an unlimited number of queue records.

The program retrieves all occurrences in the DISPQ queue. This queue lists the employee's ID and last name, and the date and time that each queue record was established.

 WORKING-STORAGE SECTION.
 01  TC                         PIC X(8).
     88 GETOUT                  VALUE 'QOUT'.
 01  SWITCHES.
     05 FIRST-PAGE-SW           PIC X  VALUE 'N'.

        88 LESS-THAN-A-PAGE     VALUE 'N'.
 01  GETQUE2                    PIC X(8) VALUE 'QOUT'.
 01  CURR-TIME                  PIC X(11).
 01  CURR-DATE                  PIC S9(7) COMP-3.
 01  MESSAGES.
     05 DIS-QUE-MESS            PIC X(20) VALUE
        'QUEUE TESTQ DISPLAYED'.
     05 DIS-QUE-MESS-END        PIC X.
 01  TESTQ                   PIC X(6) VALUE 'TESTQ'.
 01  TEST-QUEUE.
     05 Q-ID              PIC 9(4).
     05 Q-LNAME           PIC X(15).
     05 Q-TIME            PIC X(11).
     05 Q-DATE            PIC 9(5).
     05 TEST-QUEUE-END     PIC X.
 01  QUEMAP-REC.
     05  ID                      PIC 9(4).
     05  LNAME                   PIC X(15).
     05  QTIME                   PIC X(11).
     05  QDATE                   PIC 9(5).
     05  MAP-DATE                PIC 9(5).
     05  MAP-TIME                PIC X(11).
 PROCEDURE DIVISION.
 MAIN-LINE.
     BIND MAP QUEMAP01.
     BIND MAP QUEMAP01 RECORD QUEMAP-REC.
     ACCEPT TASK CODE INTO TC.
     IF GETOUT ENDPAGE
               DC RETURN.
     GET TIME INTO CURR-TIME EDIT
         DATE INTO CURR-DATE.
     MOVE CURR-TIME TO MAP-TIME.
     MOVE CURR-DATE TO MAP-DATE.
     STARTPAGE SESSION QUEMAP01 NOWAIT BACKPAGE BROWSE
        ON DC-SECOND-STARTPAGE NEXT SENTENCE.
*
     PERFORM A100-GET-QUEUE-REC THRU A100-EXIT
              UNTIL DC-REC-NOT-FOUND.
     IF LESS-THAN-A-PAGE
        MAP OUT USING QUEMAP01
          NEWPAGE RESUME
          MESSAGE IS DIS-QUE-MESS TO DIS-QUE-MESS-END.
*
     DC RETURN NEXT TASK CODE GETQUE2.
*

 A100-GET-QUEUE-REC.
     GET QUEUE ID TESTQ NEXT KEEP
         INTO TEST-QUEUE TO
              TEST-QUEUE-END
         ON DC-REC-NOT-FOUND GO TO A100-EXIT.
     MOVE Q-ID        TO ID.
     MOVE Q-LNAME     TO LNAME.
     MOVE Q-TIME      TO QTIME.
     MOVE Q-DATE      TO QDATE.
     MAP OUT USING QUEMAP01
         DETAIL NEW
         ON DC-FIRST-PAGE-SENT
           MOVE 'Y' TO FIRST-PAGE-SW.
 A100-EXIT.
     EXIT.