There are several sources of information or methods you can use when debugging queued tasks:

• Look at the audit trail log. The QTI process puts entries in the audit trail log for certain kinds of errors. (See Compaq ACMS for OpenVMS Managing Applications for more information.) Because the QTI is an agent program and uses the Systems Interface to submit tasks to an ACMS application, error messages in the audit trail log are likely to be Systems Interface messages. Therefore, you might want to learn enough about the Systems Interface to understand these messages. See Compaq ACMS for OpenVMS Systems Interface Programming for more information about the ACMS Systems Interface.
• Check the Software Event Log. In some cases, there is an entry there.
• Use the following techniques to isolate problems:
  • Queue the queued task element, then use the ACMSQUEMGR SHOW ELEMENT command to examine the element in the queue.
  • Use the ACMS$DEQUEUE_TASK service to dequeue the task. By dequeuing the task yourself, you can look at the workspace contents of the queued task element.
  • Run the task interactively. For example, write a test task that calls the task that would have been invoked by the QTI. The test task can fill in the necessary arguments to be passed to the called task.
• Check the accessibility of each entity that is involved in the queue and dequeue operation. Specifically, check the ACMSQDF.DAT file, the queue file, and the access control list on the task. Check the privileges of the QTI process and the enqueuing process to make sure that these two processes have the necessary privileges and access rights to the entities just listed.

ACMS lets you back up task queue files without having to stop the QTI or programs that call the ACMS$QUEUE_TASK and ACMS$DEQUEUE_TASK services. To enable a program that calls a queuing service to continue processing while you back up a task queue file, have the program check for the return status of ACMS$_QUEENQSUS, ACMS$_QUEDEQSUS, or both. The ACMS$QUEUE_TASK service returns the ACMS$_QUEENQSUS status if the enqueue operations for that task queue file are suspended. The ACMS$DEQUEUE_TASK service returns the status ACMS$_QUEDEQSUS if the dequeue operations for that task queue file are suspended.

If a queuing service returns one of these statuses, the program can set a timer and then retry the call. For example, if the ACMS$QUEUE_TASK service returns the ACMS$_QUEENQSUS status, the program could wait for 10 seconds and then retry the call. The program would continue to retry the call every 10 seconds until the ACMS$QUEUE_TASK service completed successfully.

See Compaq ACMS for OpenVMS Managing Applications for information on how to back up a task queue file.

9.10 Queuing Example

This section shows an example of a car rental reservation application that uses the ACMS queuing facility. The purpose of the application is to process the customer's account when the customer returns the rental car. Because there might be peak periods when many customers return their cars at the same time, the application accepts the necessary reservation information from a customer, then queues that information to be processed at a later, less busy time. The example consists of:

• A C routine that gets reservation information from the terminal user, starts a distributed transaction, calls a task, performs error handling, and commits or rolls back the distributed transaction
• A task that validates the reservation information entered by the terminal user and calls a procedure to enqueue a task
• A COBOL procedure used in the processing step of the task to enqueue a task
• A queued task that is called by the QTI process

Figure 9-2 shows how these items work together.

Figure 9-2 A Queuing Example

The following is the flow of events leading up to and including the example:

1. The application manager does the following:
   • Defines queue security
   • Uses the UDU to define agent privileges for the QTI
   • Uses the ACMSQUEMGR CREATE command to create the queue VR_QUEUE and the error queue
   • Enables RMS journaling for the queue file and the error queue file
   • Sets ACMSGEN parameters for the QTI
   • Starts the QTI process
   • Starts the VR_QUEUE queue with the error queue
2. The VR_AGENT agent gets information from the terminal user, starts a distributed transaction, and calls the VR_FAST_CHECKIN_TASK
3. The VR_FAST_CHECKIN_TASK validates the information entered by the terminal user, and queues the task VR_COMP_FAST_CHKIN_TASK to the queue VR_QUEUE
4. The QTI process dequeues VR_COMP_FAST_CHKIN_TASK and submits the task to the application
5. VR_COMP_FAST_CHKIN_TASK runs

Example 9-5 shows the main part and the process_this_transaction subroutine of the C agent that uses the $START_TRANSW system service to start a distributed transaction, and calls the VR_FAST_CHECKIN_TASK. See Compaq ACMS for OpenVMS Systems Interface Programming for a detailed explanation of the complete agent code.

Example 9-5 C Agent that Starts a Distributed Transaction

/**************************************************************/ /* */ /* Version: 01 */ /* Edit dates: 06-MAR-90 */ /* Authors: DIGITAL */ /* */ /**************************************************************/ /**************************************************************/ /* F U N C T I O N A L D E S C R I P T I O N */ /* */ /* */ /* VR_AGENT is an ACMS agent program that acts like an ATM */ /* where you type in your reservation number and odometer */ /* reading, drop the keys in a slot, and walk away. The */ /* system bills you later for the amount you owe. The */ /* agent uses QIOs to get the data, starts a distributed */ /* transaction, then calls a task to do the work. The task */ /* consists of a nonparticipating step that validates the */ /* reservation number, a step that queues a task to do the */ /* actual checkin work, and a step that writes a history */ /* record. If the task succeeds, the agent commits the */ /* transaction. If the task fails, the agent aborts the */ /* the transaction and notifies the user of the problem. */ /* The agent is also responsible for handling errors, such */ /* as transaction timeouts. */ /* */ /**************************************************************/ /**************************************************************/ /* */ /* C O P Y R I G H T */ /* */ /* */ /* COPYRIGHT (c) 1991 BY */ /* DIGITAL EQUIPMENT CORPORATION, MAYNARD */ /* MASSACHUSETTS. ALL RIGHTS RESERVED. */ /* */ /* THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND */ /* MAY BE USED AND COPIED ONLY IN ACCORDANCE WITH */ /* THE TERMS OF SUCH LICENSE AND WITH THE */ /* INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS */ /* SOFTWARE OR ANY OTHER COPIES THEREOF MAY NOT */ /* BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY */ /* OTHER PERSON. NO TITLE TO AND OWNERSHIP OF */ /* THE SOFTWARE IS HEREBY TRANSFERRED. */ /* */ /* THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO */ /* CHANGE WITHOUT NOTICE AND SHOULD NOT BE */ /* CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT */ /* CORPORATION. DIGITAL EQUIPMENT CORPORATION */ /* ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT */ /* MAY APPEAR IN THIS SOFTWARE. */ /* */ /* DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE */ /* OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT */ /* THAT IS NOT SUPPLIED BY DIGITAL. */ /* */ /**************************************************************/ /* . */ /* . */ /* . */ /* . */ main () /**********************************************************************/ /* */ /* Get Procedure information to see if the application is running. */ /* */ /* While the application is up and running prompt user for */ /* reservation ID and odometer reading. */ /* */ /* If the user enters the data, process the fast checkin transaction.*/ /* */ /* If the user aborts, notify the user that the transaction was not */ /* processed. */ /* */ /**********************************************************************/ { for (;;) { status = initialization (); check_status(status); status = ACMS$GET_PROCEDURE_INFO(&submitter_id, &task_name_desc, &appl_name_desc, &task_info_list); while (status & STS$M_SUCCESS) { status = get_data (); if (status & STS$M_SUCCESS) status = process_this_transaction(); else if (status == RMS$_EOF) status = report_user_abort(); check_status(status); status = ACMS$GET_PROCEDURE_INFO(&submitter_id, &task_name_desc, &appl_name_desc, &task_info_list); } if (status == ACMS$_NOSUCH_PKG) status = application_not_running(); check_status(status); status = termination (); check_status(status); } } */ . */ */ . */ */ . */ */ . */ process_this_transaction() /********************************************************************/ /* */ /* Start Transaction. Call the task. Commit if successful. */ /* Abort if failure. Retry if timed out. Notify user whether */ /* transaction succeeded or failed. */ /* */ /********************************************************************/ { short retry, trans_completed; retry = 0; trans_completed = FALSE; while ((trans_completed == FALSE) && (retry < MAX_RETRY)) { status = SYS$START_TRANSW (0,0,&iosb,0,0,tid); if (status & STS$M_SUCCESS) status = iosb.status; check_status(status); status = call_return_task(); if (status & STS$M_SUCCESS) { status = SYS$END_TRANSW (0,0,&iosb,0,0,tid); if (status & STS$M_SUCCESS) status = iosb.status; check_status(status); trans_completed = TRUE; } else { if ((status == ACMS$_TRANSTIMEDOUT) || (status == ACMS$_SRVDEAD) || (status == RDB$_DEADLOCK) || (status == RDMS$_DEADLOCK) || (status == RDB$_LOCK_CONFLICT) || (status == RDMS$_LCKCNFLCT) || (status == RDMS$_TIMEOUT)) ++retry; else retry = MAX_RETRY; status = SYS$ABORT_TRANSW (0,0,&iosb,0,0,tid); if (status & STS$M_SUCCESS) status = iosb.status; check_status(status); } } if (trans_completed == FALSE) status = notify_failure(); else status = notify_success(); return status; }

If the distributed transaction fails because of an error that can be handled, such as server deadlock or transaction timeout, the agent retries the distributed transaction up to five times. Example 9-6 shows the task definition called by the C agent.

Example 9-6 VR_FAST_CHECKIN_TASK Definition

REPLACE TASK AVERTZ_CDD_TASK:VR_FAST_CHECKIN_TASK USE WORKSPACES VR_FAST_CHECKIN_WKSP, VR_RESERVATIONS_WKSP, VR_RENTAL_CLASSES_WKSP, VR_VEHICLES_WKSP, VR_TRANS_WKSP, VR_VEHICLE_RENTAL_HISTORY_WKSP, VR_HIST_WKSP; TASK ARGUMENTS ARE VR_FAST_CHECKIN_WKSP WITH ACCESS READ; ! TASK MUST BE COMPOSABLE TO BE CALLED AS PART OF A DISTRIBUTED ! TRANSACTION BLOCK WORK WITH DISTRIBUTED TRANSACTION NO I/O ! ! Retrieve the reservation record, using the reservation number/ID ! entered by the customer and passed by the vr_agent agent. ! PROCESSING WITH NONPARTICIPATING SERVER CALL PROCEDURE VR_FIND_RES_PROC IN VR_READ_SERVER USING VR_FAST_CHECKIN_WKSP, VR_RESERVATIONS_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "G") THEN MOVE VR_FAST_CHECKIN_WKSP.ACTUAL_RETURN_DATE TO VR_VEHICLE_RENTAL_HISTORY_WKSP.ACTUAL_RETURN_DATE, VR_FAST_CHECKIN_WKSP.RETURN_ODOMETER_READING TO VR_VEHICLE_RENTAL_HISTORY_WKSP.RETURN_ODOMETER_READING; ELSE CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! RETRIEVE THE VEHICLE AND VEHICLE_RENTAL_HISTORY RECORDS ! PROCESSING WITH NONPARTICIPATING SERVER CALL PROCEDURE VR_FIND_VE_VRH_PROC IN VR_READ_SERVER USING VR_RESERVATIONS_WKSP, VR_VEHICLES_WKSP, VR_VEHICLE_RENTAL_HISTORY_WKSP, VR_RENTAL_CLASSES_WKSP, VR_TRANS_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "B") THEN CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! QUEUE THE TASK TO BE RUN LATER ! PROCESSING CALL PROCEDURE VR_ENQ_FAST_CHECKIN IN VR_QUEUE_SERVER USING VR_FAST_CHECKIN_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "G") THEN MOVE "FASTCHIN" TO VR_HIST_WKSP.TRANS_TYPE, VR_VEHICLES_WKSP.VEHICLE_ID TO VR_HIST_WKSP.VEHICLE_ID; ELSE CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! WRITE A RECORD OF A SUCCESSFUL CHECK IN TO THE HISTORY DATABASE ! PROCESSING CALL PROCEDURE VR_WRITE_HIST_RECORD_PROC IN VR_LOG_SERVER USING VR_HIST_WKSP, VR_RESERVATIONS_WKSP; END BLOCK; END DEFINITION;

Because the VR_FAST_CHECKIN_TASK is joining a distributed transaction started by the agent, the root block step must use the TRANSACTION phrase.

The first processing step in VR_FAST_CHECKIN_TASK uses the reservation ID, obtained from the customer by the agent, to retrieve the reservation record. The second processing step retrieves the car history record. Because the first two processing steps perform read-only operations, neither step participates in the distributed transaction. Both steps use the NONPARTICIPATING SERVER phrase.

The third processing step calls the VR_ENQ_FAST_CHECKIN procedure to queue the VR_COMP_FAST_CHKIN_TASK.

The final processing step writes a record of the transaction into the database. If the procedure completes successfully, the task ends, and the agent calls the transaction services to commit the distributed transaction. Example 9-7 shows the COBOL procedure that the VR_FAST_CHECKIN_TASK calls to enqueue a task.

Example 9-7 Enqueuing Routine

IDENTIFICATION DIVISION. ************************************************************** PROGRAM-ID. VR-ENQ-FAST-CHECKIN. * * * Version: 01 * * Edit: 00 * * Edit dates: 16-OCT-1990 * * Authors: DIGITAL * * Called From: AGENT * * * ************************************************************** ************************************************************** * F U N C T I O N A L D E S C R I P T I O N * * * * This routine is called by the VR_FAST_CHECKIN_TASK. * * The VR_FAST_CHECKIN_WKSP is initialized by the VR_AGENT. * * The VR_COMP_FAST_CHKIN_TASK uses the information in the * * workspace to complete the checkin database functions. * * * ************************************************************** ************************************************************** * * * C O P Y R I G H T * * * * COPYRIGHT (c) 1990 BY * * DIGITAL EQUIPMENT CORPORATION, MAYNARD * * MASSACHUSETTS. ALL RIGHTS RESERVED. * * * * THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND * * MAY BE USED AND COPIED ONLY IN ACCORDANCE WITH * * THE TERMS OF SUCH LICENSE AND WITH THE * * INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS * * SOFTWARE OR ANY OTHER COPIES THEREOF MAY NOT * * BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY * * OTHER PERSON. NO TITLE TO AND OWNERSHIP OF * * THE SOFTWARE IS HEREBY TRANSFERRED. * * * * THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO * * CHANGE WITHOUT NOTICE AND SHOULD NOT BE * * CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT * * CORPORATION. DIGITAL EQUIPMENT CORPORATION * * ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT * * MAY APPEAR IN THIS SOFTWARE. * * * * DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE * * OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT * * THAT IS NOT SUPPLIED BY DIGITAL. * * * ************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. ************************************************************** DATA DIVISION. ****************************************************************** WORKING-STORAGE SECTION. * * Return status to pass status to ACMS * 01 RET-STAT PIC S9(9) COMP. * * Task name * 01 TASK PIC X(24) VALUE IS "VR_COMP_FAST_CHKIN_TASK". * * Application Name * 01 APPL PIC X(7) VALUE IS "VR_APPL". * * * Queue Name * * Queue name cannot contain trailing spaces. * 01 QNAM PIC X(8) VALUE IS "VR_QUEUE". * * Flag - 0 = NOHOLD - the queued task is free to run * 1 = HOLD - the queued task is stored but may not run * 01 FLAG PIC 9(9) COMP VALUE IS 0. * * A list of workspace descriptors is sent to the queue service. * For this task, only 1 workspace is required (VR_FAST_CHECKIN_WKSP). * 1 is the number of workspaces in the list, QTE_WS_DESC is the * descriptor being sent, so the address of the address of * QTE_WS_DESC is stored. * 01 WS_DESC_LIST. 05 DES_LIST_CNT PIC S9(9) COMP VALUE 1. 05 QTE_WS_DESC_PTR POINTER VALUE IS REFERENCE QTE_WS_DESC. * * Each workspace must be described by a desriptor. 16 is the number * of bytes in the workspace VR_FAST_CHECKIN_WKSP so its address is * stored in the descriptor. * 01 QTE_WS_DESC. 05 FAST_CHECKIN_WS_SIZE PIC S9(9) COMP VALUE IS 16. 05 FAST_CHECKIN_PTR USAGE IS POINTER. ********************************************************************* LINKAGE SECTION. * COPY "VR_FAST_CHECKIN_WKSP" FROM DICTIONARY. * ********************************************************************** PROCEDURE DIVISION USING VR_FAST_CHECKIN_WKSP GIVING RET-STAT. ********************************************************************** MAIN-SECTION. SET RET-STAT TO SUCCESS. SET FAST_CHECKIN_PTR TO REFERENCE OF VR_FAST_CHECKIN_WKSP. CALL "ACMS$QUEUE_TASK" USING BY DESCRIPTOR QNAM, BY DESCRIPTOR TASK, BY DESCRIPTOR APPL, BY REFERENCE WS_DESC_LIST, BY REFERENCE FLAG GIVING RET-STAT. EXIT-PROGRAM. EXIT PROGRAM.

Example 9-8 shows the definition of the VR_COMP_FAST_CHKIN_TASK.

Example 9-8 VR_COMP_FAST_CHKIN_TASK Definition

! ! This task is queued by the VR_FAST_CHECKIN_TASK which in turn ! is called by an ACMS agent. The agent obtains information from ! the user and sends it to the VR_FAST_CHECKIN_TASK. The ! VR_FAST_CHECKIN_TASK passes the information to the task. ! REPLACE TASK AVERTZ_CDD_TASK:VR_COMP_FAST_CHKIN_TASK USE WORKSPACES VR_FAST_CHECKIN_WKSP, VR_RESERVATIONS_WKSP, VR_RENTAL_CLASSES_WKSP, VR_VEHICLES_WKSP, VR_TRANS_WKSP, VR_VEHICLE_RENTAL_HISTORY_WKSP, VR_HIST_WKSP, VR_CONTROL_WKSP; TASK ARGUMENTS ARE VR_FAST_CHECKIN_WKSP WITH ACCESS READ; ! QTI STARTS A DISTRIBUTED TRANSACTION BEFORE BEGINNING THIS TASK. ! THIS TASK JOINS THE DISTRIBUTED TRANSACTION. SHOULD THE TASK FAIL ! FOR ANY REASON, THE QTI ABORTS THE DISTRIBUTED TRANSACTION AND STARTS ! A NEW DISTRIBUTED TRANSACTION SO THAT IT CAN TRANSFER THE FAILED ! QUEUED TASK RECORD ONTO AN ERROR QUEUE, IF ONE EXISTS. BLOCK WITH TRANSACTION NO I/O ! ! FIND THE RESERVATION RECORD. ! PROCESSING WITH NONPARTICIPATING SERVER CALL PROCEDURE VR_FIND_RES_PROC IN VR_READ_SERVER USING VR_FAST_CHECKIN_WKSP, VR_RESERVATIONS_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "G") THEN MOVE VR_FAST_CHECKIN_WKSP.ACTUAL_RETURN_DATE TO VR_VEHICLE_RENTAL_HISTORY_WKSP.ACTUAL_RETURN_DATE, VR_FAST_CHECKIN_WKSP.RETURN_ODOMETER_READING TO VR_VEHICLE_RENTAL_HISTORY_WKSP.RETURN_ODOMETER_READING; ELSE CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! RETRIEVE THE VEHICLE AND VEHICLE_RENTAL_HISTORY RECORDS. ! PROCESSING WITH NONPARTICIPATING SERVER CALL PROCEDURE VR_FIND_VE_VRH_PROC IN VR_READ_SERVER USING VR_RESERVATIONS_WKSP, VR_VEHICLES_WKSP, VR_VEHICLE_RENTAL_HISTORY_WKSP, VR_RENTAL_CLASSES_WKSP, VR_TRANS_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "B") THEN CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! COMPUTE THE BILL. ! PROCESSING WITH NONPARTICIPATING SERVER CALL PROCEDURE VR_COMPUTE_BILL_PROC IN VR_READ_SERVER USING VR_RESERVATIONS_WKSP, VR_RENTAL_CLASSES_WKSP; ACTION IS IF (ACMS$T_STATUS_TYPE = "B") THEN CANCEL TASK RETURNING ACMS$L_STATUS; END IF; ! ! COMPLETE THE CHECKIN PROCESS. ! PROCESSING CALL PROCEDURE VR_COMPLETE_CHECKIN_PROC IN VR_UPDATE_SERVER USING VR_RESERVATIONS_WKSP, VR_VEHICLES_WKSP, VR_VEHICLE_RENTAL_HISTORY_WKSP, VR_CONTROL_WKSP; ACTION IS MOVE "FSTCHKIN" TO VR_HIST_WKSP.TRANS_TYPE, VR_VEHICLES_WKSP.VEHICLE_ID TO VR_HIST_WKSP.VEHICLE_ID, VR_RESERVATIONS_WKSP.RENTAL_TOTAL_AMT TO VR_HIST_WKSP.RENTAL_TOTAL_AMT; PROCESSING CALL PROCEDURE VR_WRITE_HIST_RECORD_PROC IN VR_LOG_SERVER USING VR_HIST_WKSP, VR_RESERVATIONS_WKSP; END BLOCK; END DEFINITION;

The task queue VR_QUEUE is marked for RMS recovery unit journaling. Therefore, the QTI starts a distributed transaction before submitting the VR_COMP_FAST_CHKIN_TASK for processing. To join the distributed transaction, the task specifies TRANSACTION on the root block step.

The first two processing steps use the reservation ID, obtained by the agent, to retrieve reservation and car records. The third processing step computes the bill. Because these three processing steps are not writing to the database, they use the NONPARTICIPATING SERVER phrase to exclude themselves from the distributed transaction.