BEA Logo BEA Tuxedo Release 7.1

  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

Defining a Service

When writing a service routine, you must call the TPSVCSTART(3cbl) routine before any others. This routine is used to retrieve the service's parameters and data. Use the following signature to call the TPSVCSTART routine.

01 TPSVCDEF-REC.
   COPY TPSVCDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPSVCSTART" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

The service information data structure is defined as TPSVCDEF in the COBOL COPY file. It includes the following members. 

 05 COMM-HANDLE          PIC S9(9) COMP-5.
 05 TPBLOCK-FLAG         PIC S9(9) COMP-5.
        88 TPBLOCK       VALUE 0.
        88 TPNOBLOCK     VALUE 1.
 05 TPTRAN-FLAG          PIC S9(9) COMP-5.
        88 TPTRAN        VALUE 0.
        88 TPNOTRAN      VALUE 1.
 05 TPREPLY-FLAG         PIC S9(9) COMP-5.
        88 TPREPLY       VALUE 0.
        88 TPNOREPLY     VALUE 1.
 05 TPACK-FLAG         PIC S9(9) COMP-5 REDEFINES TPREPLY-FLAG.
        88 TPNOACK        VALUE 0.
        88 TPACK          VALUE 1.
 05 TPTIME-FLAG          PIC S9(9) COMP-5.
        88 TPTIME        VALUE 0.
        88 TPNOTIME      VALUE 1.
 05 TPSIGRSTRT-FLAG      PIC S9(9) COMP-5.
        88 TPNOSIGRSTRT   VALUE 0.
        88 TPSIGRSTRT     VALUE 1.
 05 TPGETANY-FLAG        PIC S9(9) COMP-5.
        88 TPGETHANDLE   VALUE 0.
        88 TPGETANY      VALUE 1.
 05 TPSENDRECV-FLAG      PIC S9(9) COMP-5.
        88 TPSENDONLY     VALUE 0.
        88 TPRECVONLY     VALUE 1.
 05 TPNOCHANGE-FLAG      PIC S9(9) COMP-5.
        88 TPCHANGE      VALUE 0.
        88 TPNOCHANGE    VALUE 1.
 05 TPSERVICETYPE-FLAG   PIC S9(9) COMP-5.
        88 TPREQRSP      VALUE 0.
        88 TPCONV        VALUE 1.
*
 05 APPKEY               PIC S9(9) COMP-5.
 05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5.
 05 SERVICE-NAME         PIC X(15).

The following table describes the members of a TPSVCDEF data structure.

TPSVCDEF Data Structure

Field

Description

COMM-HANDLE

Specifies, to the service routine, the communication handle used by the requesting process to invoke the service.

SETTINGS
(TPBLOCK-FLAG
TPTRAN-FLAG, etc.)

Miscellaneous settings that control server characteristics. For more information on the settings, refer to the BEA Tuxedo COBOL Function Reference.

APPKEY

Reserved for use by the application. If application-specific authentication is part of your design, the application-specific authentication server, which is called at the time a client joins the application, should return a client authentication key, as well as a success or failure indication. The BEA Tuxedo system holds the APPKEY on behalf of the client and passes the information to subsequent service requests in this field. By the time the APPKEY is passed to the service, the client has already been authenticated. However, the APPKEY field can be used within the service to identify the user invoking the service or some other parameters associated with the user.

CLIENTID

Identifier of the client that originates a request.

SERVICE-NAME

Name of the service routine used by the requesting process to invoke the service.

For a description of the TPTYPE-REC data structure, refer to Defining Typed Records.

You must code the service in such a way that when it accesses the request data to be placed in DATA-REC, it expects the data to be in a record of the type defined for the service in the configuration file. Upon successful return, DATA-REC contains the data received and LEN contains the actual number of bytes moved.

The following sample listing shows a typical service definition.

Typical Service Definition

 

    IDENTIFICATION DIVISION.
    PROGRAM-ID. BUYSR.
    AUTHOR. TUXEDO DEVELOPMENT.
    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER. USL-486.
    OBJECT-COMPUTER. USL-486.
*
    INPUT-OUTPUT SECTION.
    . . .
******************************************************
* Tuxedo definitions
******************************************************
    01 TPSVCRET-REC.
    COPY TPSVCRET.
*
    01 TPTYPE-REC.
     COPY TPTYPE.
*
    01 TPSTATUS-REC.
    COPY TPSTATUS.
*
    01 TPSVCDEF-REC.
    COPY TPSVCDEF.
******************************************************
* Log message definitions
******************************************************
    01 LOGMSG.
            05 LOGMSG-TEXT        PIC X(50).
*
    01 LOGMSG-LEN                 PIC S9(9) COMP-5.
******************************************************
* User defined data records
******************************************************
    01 CUST-REC.
    COPY CUST.
*
    LINKAGE SECTION.
*
    PROCEDURE DIVISION.
*
 START-BUYSR.
    MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    OPEN files or DATABASE
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE "Server Started" TO LOGMSG-TEXT.
    PERFORM DO-USERLOG.
    MOVE LENGTH OF CUST-REC TO LEN IN TPTYPE-REC.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      CUST-REC
                      TPSTATUS-REC.
    IF TPTRUNCATE
        MOVE "Input data exceeded CUST-REC length" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF NOT TPOK
        MOVE "TPSVCSTART Failed" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF REC-TYPE NOT = "VIEW"
        MOVE "REC-TYPE in not VIEW" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
    IF SUB-TYPE NOT = "cust"
        MOVE "SUB-TYPE in not cust" TO LOGMSG-TEXT
        PERFORM DO-USERLOG
        PERFORM A-999-EXIT.
     . . .
     set consistency level of the transaction
     . . .
******************************************************
* Exit
******************************************************
  A-999-EXIT.
     MOVE "Exiting" TO LOGMSG-TEXT.
     PERFORM DO-USERLOG.
     SET TPFAIL TO TRUE.
     COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
     TPTYPE-REC BY TPTYPE-REC
     DATA-REC BY CUST-REC
     TPSTATUS-REC BY TPSTATUS-REC.
******************************************************
* Write to userlog
******************************************************
  DO-USERLOG.
     CALL "USERLOG" USING LOGMSG
              LOGMSG-LEN
              TPSTATUS-REC.

In the preceding example, the request record on the client side was originally sent with REC-TYPE set to VIEW and the SUB-TYPE set to cust. The BUYSR service is defined in the configuration file as a service that knows about the VIEW typed record. BUYSR retrieves the data record by accessing the CUST-REC record. The consistency level of the transaction is specified after this record is retrieved but before the first database access is made. For more details on transaction consistency levels, refer to Writing Global Transactions.

Note: The TPGPRIO and TPSPRIO routines, used for getting and setting priorities, respectively, are described in detail in Setting and Getting Message Priorities.

The example code in this section shows how a service called PRINTER tests the priority level of the request just received using the TPGPRIO routine. Then, based on the priority level, the application routes the print job to the appropriate destination printer RNAME.

Next, the contents of INPUT-REC are sent to the printer. The application queries TPSVCDEF-REC to determine whether a reply is expected. If so, it returns the name of the destination printer to the client. For more information on the TPRETURN routine, refer to Terminating a Service Routine.

Checking the Priority of a Received Request

 

    IDENTIFICATION DIVISION.
    PROGRAM-ID. PRINTSR.
    AUTHOR. TUXEDO DEVELOPMENT.
    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER. USL-486.
    OBJECT-COMPUTER. USL-486.
*
    INPUT-OUTPUT SECTION.
    . . .
******************************************************
* Tuxedo definitions
******************************************************
    01 TPSVCRET-REC.
    COPY TPSVCRET.
*
    01 TPTYPE-REC.
    COPY TPTYPE.
*
    01 TPSTATUS-REC.
    COPY TPSTATUS.
*
    01 TPSVCDEF-REC.
    COPY TPSVCDEF.
*
    01 TPPRIDEF-REC.
    COPY TPPRIDEF.
******************************************************
* Log message definitions
******************************************************
    01 LOGMSG.
            05 FILLER           PIC S9(9) VALUE
                    "TP-STATUS=".
            05 LOG-TP-STATUS    PIC S9(9).
            05 LOGMSG-TEXT      PIC X(50).
*
    01 LOGMSG-LEN  PIC S9(9) COMP-5.
******************************************************
* User defined data records
******************************************************
    01 INPUT-REC           PIC X(1000).
    01 PRNAME              PIC X(20).
*
    LINKAGE SECTION.
*
    PROCEDURE DIVISION.
*
 START-PRINTSR.
    MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    OPEN files or DATABASE
******************************************************
* Get the data that was sent by the client
******************************************************
    MOVE ZERO to TP-STATUS.
    MOVE "Server Started" TO LOGMSG-TEXT.
    PERFORM DO-USERLOG.
    MOVE LENGTH OF INPUT-REC TO LEN.
    CALL "TPSVCSTART" USING TPSVCDEF-REC
                      TPTYPE-REC
                      INPUT-REC
                      TPSTATUS-REC.
    IF NOT TPOK
             MOVE "TPSVCSTART Failed" TO LOGMSG-TEXT
             PERFORM DO-USERLOG
             SET TPFAIL TO TRUE.
             PERFORM A-999-EXIT.
    . . .
    Check other parameters
    CALL "TPGPRIO" USING TPPRIDEF-REC
                   TPSTATUS-REC.
    IF NOT TPOK
             MOVE "TPGPRIO Failed" TO LOGMSG-TEXT
             PERFORM DO-USERLOG
             SET TPFAIL TO TRUE.
             PERFORM A-999-EXIT.
    IF PRIORITY < 20
             MOVE "BIGJOBS" TO RNAME
    ELSE IF PRIORITY < 60
             MOVE "MEDJOBS" TO RNAME
    ELSE
             MOVE "HIGHSPEED" TO RNAME.
    . . .
    Print INPUT-REC on RNAME printer
    . . .
    IF TPNOREPLY
             MOVE SPACES TO REC-TYPE
             MOVE 0 TO LEN
             SET TPSUCCESS TO TRUE
             PERFORM A-999-EXIT
    IF TPREPLY
             MOVE "STRING" TO REC-TYPE
             MOVE LENGTH OF PRNAME TO LEN
             SET TPSUCCESS TO TRUE
             PERFORM A-999-EXIT.
******************************************************
* Exit
******************************************************
 A-999-EXIT.
     MOVE "Exiting" TO LOGMSG-TEXT.
     PERFORM DO-USERLOG.
     SET TPSUCCESS TO TRUE.
     COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
              TPTYPE-REC buTPTYPE-REC
              DATA-REC BY PRNAME
              TPSTATUS-REC BY TPSTATUS-REC.
******************************************************
* Write to userlog
******************************************************
 DO-USERLOG.
     MOVE TP-STATUS TO LOG-TP-STATUS.
     CALL "USERLOG" USING LOGMSG
               LOGMSG-LEN
               TPSTATUS-REC.

 

 

Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.