Setting and Getting Message Priorities


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using COBOL

Two ATMI calls allow you to determine and set the priority of a message request: TPSPRIO(3cbl) and TPGPRIO(3cbl). The priority affects how soon the request is dequeued by the server; servers dequeue requests with the highest priorities first.

This section describes:

Setting a Message Priority

The TPSPRIO(3cbl) routine enables you to set the priority of a message request.

The TPSPRIO routine affects the priority level of only one request: the next request to be sent by TPCALL or TPACALL, or to be forwarded by a service subroutine.

Use the following signature to call the TPSPRIO routine.

01 TPPRIDEF-REC.
   COPY TPPRIDEF.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPSPRIO" USING TPPRIDEF-REC TPSTATUS-REC.

Use the following signature for the TPPRIDEF-REC data structure.

05 PRIORITY     PIC S9(9) COMP-5.
05 PRIO-FLAG    PIC S9(9) COMP-5.
  88 TPABSOLUTE     VALUE 0.
  88 TPRELATIVE     VALUE 1.

The following table describes the arguments to the TPSPRIO routine.

TPSPRIO Routine Fields

Field
Description

PRIORITY

Integer indicating a new priority value. The effect of this argument is controlled by PRIO-FLAG. If PRIO-FLAG is set to 0, PRIORITY specifies a relative value and the sign accompanying the value indicates whether the current priority is incremented or decremented. Otherwise, the value specified indicates an absolute value and PRIORITY must be set to a value between 0 and 100. If you do not specify a value within this range, the system sets the value to 50.

PRIO-FLAG

Indicates whether the value of PRIORITY is treated as a relative value (0, the default) or an absolute value (TPABSOLUTE).

Field	Description
PRIORITY	Integer indicating a new priority value. The effect of this argument is controlled by PRIO-FLAG. If PRIO-FLAG is set to 0, PRIORITY specifies a relative value and the sign accompanying the value indicates whether the current priority is incremented or decremented. Otherwise, the value specified indicates an absolute value and PRIORITY must be set to a value between 0 and 100. If you do not specify a value within this range, the system sets the value to 50.
PRIO-FLAG	Indicates whether the value of PRIORITY is treated as a relative value (0, the default) or an absolute value (TPABSOLUTE).

The following sample code is an excerpt from the TRANSFER service. In this example, the TRANSFER service acts as a client by sending a synchronous request, via TPCALL, to the WITHDRAWAL service. TRANSFER also invokes TPSPRIO to increase the priority of its request message to WITHDRAWAL, and to prevent the request from being queued for the WITHDRAWAL service (and later the DEPOSIT service) after waiting on the TRANSFER queue.

Setting the Priority of a Request Message

    WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
    01 TPTYPE-REC.
       COPY TPTYPE.
*
    01 TPSTATUS-REC.
       COPY TPSTATUS.
*
    01 TPSVCDEF-REC.
       COPY TPSVCDEF.
*
    01 TPPRIDEF-REC.
       COPY TPPRIDEF.
*****************************************************
    01 DATA-REC               PIC X(100) VALUE SPACES.
******************************************************
    PROCEDURE DIVISION.
 START-FIG.
    . . .
    join application
    . . .
    MOVE 30 TO PRIORITY.
    SET TPRELATIVE TO TRUE.
    CALL "TPSPRIO" USING TPPRIDEF-REC TPSTATUS-REC
    IF NOT TPOK
       error processing
    MOVE "CARRAY" TO REC-TYPE.
    MOVE 100 TO LEN.
    MOVE "WITHDRAWAL" TO SERVICE-NAME.
    SET TPTRAN TO TRUE .
    SET TPBLOCK TO TRUE .
    SET TPNOTIME TO TRUE .
    SET TPSIGRSTRT TO TRUE .
    SET TPREPLY TO TRUE .
    CALL "TPACALL" USING TPSVCDEF-REC
                   TPTYPE-REC
                   DATA-REC
                   TPSTATUS-REC.
    IF NOT TPOK
       error processing
    . . .
    leave application

Getting a Message Priority

The TPGPRIO(3cbl) routine enables you to get the priority of a message request.

Use the following signature to call the TPGPRIO routine.

01 TPPRIDEF-REC.
   COPY TPPRIDEF.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPGPRIO" USING TPPRIDEF-REC TPSTATUS-REC.

A requester can call the TPGPRIO routine after invoking the TPCALL or TPACALL routine to retrieve the priority of the request message. If a requester calls the function but no request is sent, the routine fails, setting TP-STATUS to TPENOENT. Upon success, TPGPRIO sets TP-STATUS to TPOK and returns an integer value in the range of 1 to 100 (where the highest priority value is 100).

If a priority has not been explicitly set using the TPSPRIO routine, the system sets the message priority to that of the service routine that handles the request. Within an application, the priority of the request-handling service is assigned a default value of 50 unless a system administrator overrides this value.

The following example shows how to determine the priority of a message that was sent in an asynchronous call.

Determining the Priority of the Sent Request

   WORKING-STORAGE SECTION.
*****************************************************
* Tuxedo definitions
*****************************************************
   01 TPTYPE-REC-1.
   COPY TPTYPE.
   01 TPTYPE-REC-2.
   COPY TPTYPE.
*
   01 TPSTATUS-REC.
   COPY TPSTATUS.
*
   01 TPSVCDEF-REC-1.
   COPY TPSVCDEF.
   01 TPSVCDEF-REC-2.
   COPY TPSVCDEF.
*
   01 TPPRIDEF-REC-1.
   COPY TPPRIDEF.
   01 TPPRIDEF-REC-2.
   COPY TPPRIDEF.
*****************************************************
   01 DATA-REC-1     PIC X(100) VALUE SPACES.
   01 DATA-REC-2     PIC X(100) VALUE SPACES.
******************************************************
   PROCEDURE DIVISION.
START-FIG.
   . . .
   join application
   populate DATA-REC1 and DATA-REC2 with send request
   . . .
   MOVE "CARRAY" TO REC-TYPE IN TYPE-REC-1.
   MOVE 100 TO LEN IN TYPE-REC-1.
   MOVE "SERVICE1" TO SERVICE-NAME IN TPSVCDEV-REC-1.
   SET TPTRAN TO TRUE IN TPSVCDEV-REC-1.
   SET TPBLOCK TO TRUE IN TPSVCDEV-REC-1.
   SET TPNOTIME TO TRUE IN TPSVCDEV-REC-1.
   SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-1.
   SET TPREPLY TO TRUE IN TPSVCDEV-REC-1.
   CALL "TPACALL" USING TPSVCDEF-REC-1
                  TPTYPE-REC-1
                  DATA-REC-1
                  TPSTATUS-REC.
   IF NOT TPOK
      error processing
   CALL "TPGPRIO" USING TPPRIDEF-REC-1 TPSTATUS-REC
   IF NOT TPOK
      error processing
   MOVE "CARRAY" TO REC-TYPE IN TYPE-REC-2.
   MOVE 100 TO LEN IN TYPE-REC-2.
   MOVE "SERVICE2" TO SERVICE-NAME IN TPSVCDEV-REC-2.
   SET TPTRAN TO TRUE IN TPSVCDEV-REC-2.
   SET TPBLOCK TO TRUE IN TPSVCDEV-REC-2.
   SET TPNOTIME TO TRUE IN TPSVCDEV-REC-2.
   SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-2.
   SET TPREPLY TO TRUE IN TPSVCDEV-REC-2.
   CALL "TPACALL" USING TPSVCDEF-REC-2
                  TPTYPE-REC-2
                  DATA-REC-2
                  TPSTATUS-REC.
   IF NOT TPOK
      error processing
   CALL "TPGPRIO" USING TPPRIDEF-REC-2 TPSTATUS-REC
   IF NOT TPOK
      error processing
   IF PRIORITY IN TPSVCDEF-REC-1 >= PRIORITY IN TPSVCDEF-REC-2
               PERFORM DO-GETREPLY1
               PERFORM DO-GETREPLY2
   ELSE
                    PERFORM DO-GETREPLY2
                    PERFORM DO-GETREPLY1
   END-IF.
   . . .
   leave application
DO-GETRPLY1.
   SET TPGETHANDLE TO TRUE IN TPSVCDEV-REC-1.
   SET TPCHANGE TO TRUE IN TPSVCDEV-REC-1.
   SET TPBLOCK TO TRUE IN TPSVCDEV-REC-1.
   SET TPNOTIME TO TRUE IN TPSVCDEV-REC-1.
   SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-1.
   CALL "TPGETRPLY" USING TPSVCDEF-REC-1
                    TPTYPE-REC-1
                    DATA-REC-1
                    TPSTATUS-REC.
   IF NOT TPOK
            error processing
 DO-GETRPLY2
   SET TPGETHANDLE TO TRUE IN TPSVCDEV-REC-2.
   SET TPCHANGE TO TRUE IN TPSVCDEV-REC-2.
   SET TPBLOCK TO TRUE IN TPSVCDEV-REC-2.
   SET TPNOTIME TO TRUE IN TPSVCDEV-REC-2.
   SET TPSIGRSTRT TO TRUE IN TPSVCDEV-REC-2.
   CALL "TPGETRPLY" USING TPSVCDEF-REC-2
                    TPTYPE-REC-2
                    DATA-REC-2
                    TPSTATUS-REC.
   IF NOT TPOK
              error processing