The preceding chapter discussed the ATMI calls that can be used to write client programs. In this chapter, some of the same routines are revisited in the context of the service subroutines. As you may recall, services are COBOL subroutines that are linked together with the BEA TUXEDO system-provided controlling program to create executable server programs.
In this chapter the discussion covers only services that operate in a request/response mode. Conversational clients and servers are the subject of Chapter 13, "Conversational Clients and Services."
Since the communication details are taken care of by the BEA TUXEDO system's controlling program, the programmer can concentrate on the application logic rather than communication implementation. For services to be compatible with the controlling program provided, they must adhere to certain conventions. These conventions are described here and on the Request/response services have the following characteristics:
Writing Request/Response Services
Application Service Template
TPSVCSTART(3cbl) reference page in the BEA TUXEDO Reference Manual, and they are referred to collectively as the service template for coding service routines.
TPSVCSTART routine.
TPRETURN or TPFORWAR routine.
The following sections examine these concepts more closely.
The service information data structure is defined as The members of the structure
The TPSVCSTART Routine
TPSVCSTART is the very first routine to be called when writing a service routine. It is an error to issue any other call within a service routine before calling TPSVCSTART. The syntax of this routine is:
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 TPSVCDEF-REC Structure
TPSVCDEF in the COBOL COPY file and includes the following members:
05 COMM-HANDLE PIC S9(9) COMP-5.
05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPNOBLOCK VALUE 0.
88 TPBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPNOTRAN VALUE 0.
88 TPTRAN VALUE 1.
05 TPREPLY-FLAG PIC S9(9) COMP-5.
88 TPNOREPLY VALUE 0.
88 TPREPLY VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPNOTIME VALUE 0.
88 TPTIME 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 TPGETANY VALUE 0.
88 TPGETHANDLE 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 TPNOCHANGE VALUE 0.
88 TPCHANGE 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 The The use of this member is left to the application to decide. 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/failure indication. (This is the logic of the BEA TUXEDO system default The When accessing the request data to be placed in DATA-REC, the service must be coded to expect 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 Listing 12-1 illustrates a typical service definition.
SERVICE-NAME member of the structure indicates to the service routine the name that the requesting process used to invoke the service.
The Settings of TPSVCDEF-REC
TPNOTRAN and TPTRAN settings of the structure are used to let the service know if it is in transaction mode or if the caller is expecting a reply. The various ways a service can be placed in transaction mode are discussed in Chapter 14, "Global Transactions in the BEA TUXEDO System." If the setting is TPTRAN, it indicates that the service is in transaction mode. When a service is called by TPCALL or TPACALL with a setting of TPNOTRAN, it indicates that the service cannot participate in the current transaction, but it is still possible for the service to be in transaction mode. So even when the caller sets TPNOTRAN, it is possible for TPTRAN to be set. The case that allows this to happen is discussed in Chapter 14, "Global Transactions in the BEA TUXEDO System."
TPNOREPLY is set if the service was called by TPACALL with the TPNOREPLY communication setting set. It is possible for both the settings to be set. When this represents a valid situation is discussed in the next chapter. However, if a called service is part of the same transaction as the calling process, it must return a reply to the caller.
The APPKEY Member of TPSVCDEF-REC
AUTHSVC service.) The key is held by the system on behalf of the client and is passed to subsequent service requests in the APPKEY field. By the time the key is passed to the service, the client has already passed authentication, but the APPKEY field can be used within the service to identify in some way the user invoking the service or some other parameters associated with the user. If not used, the value is set to -1 by the system.
The CLIENTID Member of TPSVCDEF-REC
CLIENTID is used by the system to carry the identification of the client. You should not make changes in this field.
Accessing Data that Comes with the Request
LEN IN TPTYPE-REC contains the maximum number of bytes that should be moved. LEN is not allowed to be 0 on input.
LEN contains the actual number of bytes moved. If the length of the message is greater than DATA-REC, DATA-REC will receive only as much of the message as possible and TPTRUNCATE is set in TPTYPE-REC. If LEN is 0, no data was received and DATA-REC remains unchanged. REC-TYPE and SUB-TYPE, both in TPTYPE-REC, contain the type and subtype for the service called, which in turn must agree with the typed record as defined for that service in the configuration file.
Listing 12-1
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
T PSTATUS-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 above 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 is able to retrieve the data record by accessing the CUST-REC record as illustrated in the above example. Note that after this record is retrieved and before the first database access is made, the consistency level of the transaction is specified. Refer to Chapter 14, "Global Transactions in the BEA TUXEDO System," for more details on transaction consistency levels.
Listing 12-2 shows the fictitious PRINTSR service testing the priority level of the request just received by invoking the TPGPRIO routine. Based on the priority level, the print job is routed to the appropriate destination printer, RNAME. The contents of INPUT-REC are sent to that printer. Also, the TPSVCDEF-REC settings are queried to see if a reply is expected. If one is expected, the name of the destination printer is returned to the client. Again, the use of TPRETURN is explained in the next section.
Listing 12-2 Determining the Priority of the 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.
TPRETURN and TPFORWAR are routines that indicate that a service routine has completed; they either send a reply back to the calling client or forward a request to another service for further processing.
The primary function of a service routine is to process a request and return the reply to a client process. In performing this routine, a service can in turn act as a requester and make request calls to other services with TPCALL or TPACALL. When TPRETURN is called, control always returns to the controlling program. If the service has sent requests with asynchronous replies, it must receive all expected replies or invalidate them with TPCANCEL before returning control to the controlling program; otherwise the outstanding replies are automatically dropped when they are received by the BEA TUXEDO system's controlling program, and an error is returned to the caller.
The TPRETURN routine, besides marking the end of the service routine, also causes the reply message to be sent to the requester. If the client invoked the service with TPCALL, after a successful call to TPRETURN, the reply message is available in the ODATA-REC record. If TPACALL was used to send the request, on success from TPRETURN, the reply message is available in TPGETRPLY's DATA-REC record. The syntax of this routine is:
01 TPSVCRET-REC.
COPY TPSVCRET.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC
TPSTATUS-REC BY TPSTATUS-REC.
Currently the settings are not used.
The TP-RETURN-VAL IN TPSVCRET-REC parameter can be set to TPSUCCESS, TPFAIL or TPEXIT. This value indicates whether the service has completed successfully or not on an application-level. These conditions are communicated to the calling client in the following way. When set to TPSUCCESS, the calling routine succeeded, and if there is a reply message, it is in the caller's record. If the service terminated unsuccessfully (that is, if the logic of the application set TP-RETURN-VAL IN TPSVCRET-REC to TPFAIL), an error is reported to the client process waiting for the reply. The client's TPCALL or TPGETRPLY routine call will fail and TP-STATUS will be set to TPESVCFAIL to indicate an application-defined failure. In the case of this kind of failure if a reply message was expected, it will be available in the caller's record. If TPEXIT is set in TP-RETURN-VAL IN TPSVCRET-REC, the functionality of TPFAIL is performed, but the server exits after the reply is sent back to the client. Note that if TP-RETURN-VAL is not set, the default value of TPFAIL is assigned to this parameter. The impact of the value of this parameter when a process is in transaction mode is discussed in Chapter 14, "Global Transactions in the BEA TUXEDO System."
The preceding discussion concerns the effect of TP-RETURN-VAL if application-defined errors are the only ones that occur. If, however, TPRETURN encounters errors while processing its arguments, it sends a failed message (if a reply is expected) to the calling process. This is detected by the caller by the value set in TP-STATUS. In case of failed messages, TP-STATUS is set to TPESVCERR. This situation overrides the effect of the value of TP-RETURN-VAL. If this type of error occurs, no reply data is returned, and the contents of the caller's output record and its length remain unchanged.
If TPRETURN sends back a message in a record whose type is not known or not allowed by the caller (that is, the call was made with a setting of TPNOCHANGE), TPEOTYPE is returned in TP-STATUS. Application success or failure cannot be determined and the contents of the caller's output record and its length remain unchanged.
Also, the value returned in TP-RETURN-VAL is not relevant in the case when TPRETURN is invoked and a time-out occurs for the call waiting on the reply. This situation overrides all others in determining the value that is returned in TP-STATUS. TP-STATUS is set to TPETIME and the reply data is not sent leaving the contents and length of the caller's reply record unchanged. There are two types of time-outs in the BEA TUXEDO system. Blocking time-out was discussed when explaining the TPNOBLOCK and TPNOTIME communication settings. The other type of time-out, transaction time-out, is discussed in Chapter 14, "Global Transactions in the BEA TUXEDO System."
The APPL-CODE IN TPSVCRET-REC parameter can be used to return to the caller an application-defined return code. The client can access the value returned in APPL-CODE by querying APPL-RETURN-CODE IN TPSTATUS-REC. This code is sent regardless of application success or failure; that is, it is returned in the case of TPSUCCESS or TPESVCFAIL. As indicated, no reply messages can be sent in the other error cases.
DATA-REC is the reply message that is to be returned to the client process with the length of the message specified by LEN IN TPTYPE-REC. If the record is self-defining (for example a VIEW record), LEN is ignored and can be set to 0. If REC-TYPE IN TPTYPE-REC is STRING and LEN is 0, then the request is sent with no data portion. If the reply message does not have a data part, REC-TYPE is SPACES, and DATA-REC and LEN are ignored. If a reply is expected by the client, and there is no data in the reply record, then a reply with no data portion is sent to the client. If no reply is expected, that is, TPNOREPLY was set, TPRETURN ignores any data passed to it and simply returns control to the controlling program; the server process is then free to process another request.
Listing 12-3 shows the TRANSFER service which makes synchronous calls to the WITHDRAWAL and DEPOSIT services. If the call to WITHDRAWAL should fail, Cannot withdraw from debit account is written to the status line of the form, the reply record is freed and the TP-RETURN-VAL IN TPSVCRET-REC parameter to TPRETURN is set to TPFAIL. If the call succeeds, the debit balance is retrieved from the reply record.
A similar scenario is followed for the call to DEPOSIT. On success, the service sets TP-RETURN-VAL IN TPSVCRET-REC to TPSUCCESS and returns the pertinent account information to the status line.
Listing 12-3 How to Use TPRETURN
IDENTIFICATION DIVISION.
PROGRAM-ID. TRANSFER.
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.
******************************************************
* User defined data records
******************************************************
01 TRANS-REC.
COPY TRANS-AMOUNT.
*
LINKAGE SECTION.
*
PROCEDURE DIVISION.
*
START-TRANSFER.
******************************************************
* Get the data that was sent by the client
******************************************************
MOVE LENGTH OF TRANS-REC TO LEN.
CALL "TPSVCSTART" USING TPSVCDEF-REC
TPTYPE-REC
TRANS-REC
TPSTATUS-REC.
IF NOT TPOK
MOVE "Transaction Encountered An Error" TO STATUS-LINE
SET TPFAIL TO TRUE.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY TRANS-REC
TPSTATUS-REC BY TPSTATUS-REC.
ELSE
. . . Check other parameters
******************************************************
* must have a valid debit and credit account number
******************************************************
CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-DEBIT-ACCOUNT IN TRANS-REC.
IF TRANS-DEBIT-ACCOUNT is not valid
MOVE "Invalid Debit Account Number"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
CALL "FIND-ACCOUNT-FUNCTION" USING TRANS-CREDIT-ACCOUNT IN TRANS-REC.
IF TRANS-CREDIT-ACCOUNT is not valid
MOVE "Invalid Credit Account Number"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Check amount to transfer
******************************************************
IF TRANS-AMOUNT IN TRANS-REC < 0
MOVE "Invalid Transfer Amount Requested"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Make Withdrawal using another service
******************************************************
MOVE "WITHDRAWAL" TO SERVICE-NAME.
. . . set other TPCALL parameters
CALL "TPCALL" USING . . .
IF NOT TPOK
MOVE "Cannot withdraw from debit account"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Make Deposit using another service
******************************************************
MOVE "DEPOSIT" TO SERVICE-NAME.
. . . set other TPCALL parameters
CALL "TPCALL" USING . . .
IF NOT TPOK
MOVE "Canno
If a service calling TPGETRPLY fails with TPETIME and decides not to wait any longer, it can invalidate the handle with a call to TPCANCEL. If the reply ever does arrive, it is silently discarded. TPCANCEL cannot be used for transaction replies (request was done without the TPNOTRAN setting); within a transaction TPABORT does the same job of invalidating the transaction communications handle. Listing 12-4 shows the code.
Listing 12-4 Invalidate a Reply after Timing Out
. . . Set up parameters to TPACALL
SET TPNOTRAN TO TRUE.
CALL "TPACALL" USING TPSVCDEF-REC
TPTYPE-REC
DEBIT-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
. . .
CALL "TPGETRPLY" USING TPSVCDEF-REC
TPTYPE-REC
DEBIT-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
IF TPETIME
CALL "TPCANCEL" TPSVCDEF-REC
TPSTATUS-REC.
. . .
SET TPSUCCESS TO TRUE.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DEBIT-REC
TPSTATUS-REC BY TPSTATUS-REC.
The TPFORWAR routine allows a service to forward a request to another service for further processing. This differs from a service call in that the service that forwards the request does not ever expect a reply. The reply is owed to the process that originated the request, and the responsibility for providing the reply has been passed to the service to which the request has been forwarded. It becomes the responsibility of the last server in the forward chain to send the reply back by invoking TPRETURN. The process that made the initial service call is the client and will be waiting for a reply.
The following figure gives you an idea of what a forward chain might look like. The request is initiated with a TPCALL and the eventual reply is provided by the TPRETURN that is invoked by the last service in the chain.
Figure 12-1 Forwarding a Request
Service routines can forward requests at specified priorities in the same manner that client processes send requests. You may recall that this is accomplished by invoking the TPSPRIO routine.
TPFORWAR is identical to TPRETURN in that when it is called, the controlling program regains control, and the server process is free to do more work. The syntax of this routine is:
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPFORWAR REPLACING TPSVCDEF-REC BY TPSVCDEF-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC
TPSTATUS-REC BY TPSTATUS-REC.
The name of the service to which the request is to be forwarded is specified in TPSVCDEF-REC. The request record is its third parameter, DATA-REC, and the length of the request data is available in LEN IN TPTYPE-REC. These two parameters share the same meanings as the corresponding ones specified for TPRETURN.
TPNOREPLY communication setting set or forwards the request the call will not fail since the caller is not waiting on itself.
Calling TPFORWAR can be used to indicate success up to that point in processing the request. If no application errors have been detected, you can invoke TPFORWAR; otherwise, call TPRETURN with TP-RETURN-VAL IN TPSVCRET-REC set to TPFAIL.
The example in Listing 12-5 is a service routine which shows what the service would look like if it used a call to TPFORWAR to send its data record to the DEPOSIT service. If the new account is added successfully, the branch record is updated to reflect the new account. On success, the data record gets forwarded to the DEPOSIT service. On failure, TPRETURN is called with TP-RETURN-VAL IN TPSVCRET-REC set to TPFAIL and the failure reported to the status line of the form.
Listing 12-5 How to Use TPFORWAR
. . .
******************************************************
* Get the data that was sent by the client
******************************************************
MOVE LENGTH OF TRANS-REC TO LEN.
CALL "TPSVCSTART" USING TPSVCDEF-REC
TPTYPE-REC
TRANS-REC
TPSTATUS-REC.
IF NOT TPOK
MOVE "Transaction Encountered An Error" TO STATUS-LINE
SET TPFAIL TO TRUE.
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
ELSE
. . . Check other parameters
******************************************************
* Insert new account record
******************************************************
CALL "ADD-NEW-ACCOUNT-FUNCTION" USING TRANS-ACCOUNT IN TRANS-REC.
IF Adding New Account Failed
MOVE "Account not added" TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
******************************************************
* Forward record to the DEPOSIT service to add initial
* balance into account
******************************************************
MOVE "DEPOSIT" TO SERVICE-NAME.
. . . set other TPFORWAR parameters
COPY TPFORWAR REPLACING
DATA-REC BY TRANS-REC.
The BEA TUXEDO system allows unsolicited messages to be sent to client processes without disturbing the processing of request/response calls or conversational communications. Unsolicited messages can be sent to client processes by name (TPBROADCAST) or by an identifier received with a previously processed message (TPNOTIFY). Messages sent via TPBROADCAST can originate either in a service or in another client. Messages sent via TPNOTIFY can originate only in a service, as shown in the following table.
| Initiator | Receiver | |
|---|---|---|
|
|
client, server |
client |
|
|
server |
client |
The DATA-REC argument identifies the data portion of the message up to the length specified by the TPBROADCAST Arguments
TPBROADCAST allows a message to be sent to registered clients of the application. (Registered clients are those that have successfully made a call to TPINITIALIZE and have not yet made a call to TPTERM). TPBROADCAST can be called in both client and service routines. The syntax of the routine is:
01 TPBCTDEF-REC.
COPY TPBCTDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPBROADCAST" USING TPBCTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.LMID, USRNAME, and CLTNAME, all in TPBCTDEF-REC, are identifiers used to select the target list of clients. A value of SPACES for any of these arguments acts as a wildcard for that argument, so the message can be directed to groups of clients or to the entire universe.
LEN IN TPTYPE-REC argument. If the record is self-defining, for example, a VIEW record, LEN is ignored and can be set to 0. The settings can be:
TPNOBLOCK
TPNOBLOCK or TPBLOCK must be set.
TPBLOCK
TPNOBLOCK or TPBLOCK must be set.
TPNOTIME
TPNOTIME or TPTIME must be set.
TPTIME
TPNOTIME or TPTIME must be set.
TPSIGRSTRT
TPBROADCAST to fail with the TPGOTSIG error code. Either TPSIGRSTRT or TPNOSIGRSTRT must be set.
TPNOSIGRSTRT
TPSIGRSTRT or TPNOSIGRSTRT must be set.
Listing 12-6 shows an example of a call to TPBROADCAST where all clients are targeted. The message to be sent is in a STRING record.
Listing 12-6 Using TPBROADCAST
. . .
**************************************************
* Prepare the record to broadcasted
**************************************************
MOVE "HELLO, WORLD" TO DATA-REC.
MOVE 11 TO LEN.
MOVE "STRING" TO REC-TYPE.
*
SET TPNOBLOCK TO TRUE.
SET TPNOTIME TO TRUE.
SET TPSIGRSTRT TO TRUE.
*
MOVE SPACES TO LMID.
MOVE SPACES TO USRNAME.
MOVE SPACES TO CLTNAME.
CALL "TPBROADCAST" USING TPBCTDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
TPNOTIFY can be called only from a service. The syntax of the routine is:
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPNOTIFY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
CLIENTID contains a client identifier saved from the TPSVCDEF-REC structure that accompanied the service request to this service. Thus it can be seen that TPNOTIFY is used to direct an out-of-band message to the client process that called the service. This is not the same as the reply to the service request that would be sent by when the service calls TPRETURN (or when a conversational service calls TPSEND to send a reply to the client), nor is it any part of a transaction, if one is in progress. It is used in cases where the service encounters information in processing that needs to be passed to the unsolicited message handler for the application.
The DATA-REC, LEN IN TPTYPE-REC and settings arguments are the same as they are for TPBROADCAST.
When servers are booted, they advertise the services they offer based on the specification in their CLOPT parameter in the configuration file. The default specification calls for the server to advertise all services with which it was built; this is the meaning of the -A option. (See ubbconfig(5) or servopts(5) in the BEA TUXEDO Reference Manual). When a service is advertised, it takes up a service table entry in the bulletin board. This can lead an application to decide to boot servers to offer some subset of their available services. As the servopts(5) manual page makes clear, the -s option allows a comma-separated list of services to be specified by service name. It also allows, with the -s services:func notation, for a routine with a name different from that of the advertised service to be called to process the service request. The BEA TUXEDO administrator can use the advertise and unadvertise commands of tmadmin(1) to control the services offered by servers.
The TPADVERTISE and TPUNADVERTISE routines allow that dynamic control to be exercised within a service of a request/response server or conversational server to advertise or unadvertise a service. The limitation is that the service to be advertised (or unadvertised) must be available within the same server as the service making the request.
The syntax of TPADVERTISE is:
01 SERVICE-NAME PIC X(15).
01 PROGRAM-NAME PIC X(32).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPADVERTISE" USING SERVICE-NAME PROGRAM-NAME TPSTATUS-REC.
SERVICE-NAME is a character string of 15 characters or less that names the service to be advertised. Names longer than 15 characters are truncated; a SPACES value causes an error, [TPEINVAL].
PROGRAM-NAME is the name of a BEA TUXEDO service routine that is called to perform the service. Of course, it is not uncommon that this name is the same as the name of the service. PROGRAM-NAME is not permitted to be SPACES.
Listing 12-7 shows an example of TPADVERTISE that is based on the following hypothetical situation:
TLR is specified to offer only the service TLRINIT when booted.
TLRINIT unadvertises itself.
Listing 12-7
Dynamic Advertising and Unadvertising
. . .
**************************************************
* Advertise DEPOSIT service to be processed by
* routine TLRFUNCS
**************************************************
MOVE "DEPOSIT" TO SERVICE-NAME.
MOVE "TLRFUNCS" TO PROGRAM-NAME.
CALL "TPADVERTISE" USING SERVICE-NAME
PROGRAM-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
**************************************************
* Advertise WITHDRAW service to be processed by
* the same routine TLRFUNCS
**************************************************
MOVE "WITHDRAW" TO SERVICE-NAME.
MOVE "TLRFUNCS" TO PROGRAM-NAME.
CALL "TPADVERTISE" USING SERVICE-NAME
PROGRAM-REC
TPSTATUS-REC.
IF NOT TPOK
error processing
**************************************************
* Unadvertise TLRINIT service (yourself)
**************************************************
MOVE "TLRINIT" TO SERVICE-NAME.
CALL "TPUNADVERTISE" USING SERVICE-NAME
TPSTATUS-REC.
IF NOT TPOK
error processing
The only argument is a name to the SERVICE-NAME being unadvertised. An example is included above in Listing 12-7.
The BEA TUXEDO system is delivered with a basic client authentication service: The service in To speed the development of servers the BEA TUXEDO system provides a predefined controlling program routine for server load modules. This controlling program is automatically included when the The predefined controlling routine does the following:
TPUNADVERTISE
TPUNADVERTISE, of course, is called to remove a service from the service table of the bulletin board. The syntax is:
01 SERVICE-NAME PIC X(15).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPUNADVERTISE" USING SERVICE-NAME TPSTATUS-REC. System-supplied Servers and Subroutines
AUTHSVR.
System-Supplied Server: AUTHSVR
AUTHSVR(5) can be used to provide individual client authentication for an application. It is called by TPINITIALIZE when the level of security for the application is TPAUTH, USER_AUTH, ACL, or MANDATORY_ACL.
AUTHSVR looks in the USER-DATA-REC record for a user password (not to be confused with the application password in the PASSWD field of the TPINFDEF-REC record). The string in USER-DATA-REC is checked against the /etc/passwd file by default. (The application can specify a different file to be checked.) When used by a native site client, the USER-DATA-REC record is sent along by TPINITIALIZE as it is received. This means that if the application wants the password to be encrypted, the client program must be coded accordingly. When used by a workstation client, TPINITIALIZE encrypts the data before sending it across the network.
The BEA TUXEDO System Controlling Program
buildserver -C command is executed.
SIGHUP signal)
-if the -updates the bulletin board to indicate that the server is -allocates a record for the request message and dispatches the service; that is, calls the service subroutine
-r option was specified, records the starting time of the service request
BUSY
-if the -updates statistics
-updates the bulletin board to indicate that the server is -checks its queue for the next service request
-r option was specified, records the ending time of the service request
IDLE; that is, ready for work
TPSVRDONE to perform any required user shutdown operations.
The controlling program that the system provides is a closed abstraction and can not be modified by the programmer. As indicated in the previous list items, it takes care of all the details concerning entrance into and exit from an application, record and transaction management, and communication. It leaves the programmer free to implement the application through the logic of the service subroutines. Note that as a result of the system supplied controlling program doing the work of joining and leaving the application, it is an error for services to make calls to the In addition to the above functionality, there are two user exits in the controlling program that allow the programmer to do various initialization and exiting activities. The next sections explain how these two system supplied subroutines are used.
There are two subroutines of the controlling program, When a server is booted the BEA TUXEDO controlling program calls Note that although not shown in the following examples, message communication can also be performed within this routine. However, The syntax of this routine is:
When a server is booted, before calling the Listing 12-8 shows an example of a TPINITIALIZE or TPTERM routines. This error returns TPEPROTO in TP-STATUS.
BEA TUXEDO System-Supplied Subroutines
TPSVRINIT and TPSVRDONE, that are provided with the BEA TUXEDO system software. The default versions can be modified to suit your application.
TPSVRINIT
TPSVRINIT during its initialization phase before it handles any service requests. If an application does not provide this routine in a server, the default one is called that opens the resource manager and makes an entry in the central event log indicating that the server has successfully started. The central event log is discussed in Chapter 15, "Error Management." For now, simply understand that it is a UNIX System file to which processes can write messages by calling the USERLOG routine. Coming as it does near the beginning of the system supplied controlling program, TPSVRINIT can be used for any initialization purposes that might be needed by an application. Two possibilities are illustrated here: receiving command line options and opening a database.
TPSVRINIT fails if it returns with asynchronous replies pending. In addition, the replies are ignored by the BEA TUXEDO system and the server exits gracefully. TPSVRINIT can also start and complete transactions, as discussed in Chapter 14, "Global Transactions in the BEA TUXEDO System."
LINKAGE SECTION.
01 CMD-LINE.
05 ARGC PIC 9(4) COMP-5.
05 ARGV.
10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
01 TPSTATUS-REC.
COPY TPSTATUS.
PROCEDURE DIVISION USING CMD-LINE TPSTATUS-REC.
* User code
EXIT PROGRAM. Using TPSVRINIT to Receive Command Line Options
TPSVRINIT routine, it reads the options specified for it in the configuration file. The options are passed through ARGC, which contains the number of arguments that have been passed, and ARGV, which contains the arguments separated by a single SPACE character. The predefined controlling program then calls TPSVRINIT.
TPSVRINIT coded to receive command line options.
Listing 12-8
Receiving Command Line Options in TPSVRINIT
IDENTIFICATION DIVISION.
PROGRAM-ID. TPSVRINIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. USL-486.
OBJECT-COMPUTER. USL-486.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
*
LINKAGE SECTION.
*
01 CMD-LINE.
05 ARGC PIC 9(4) COMP-5.
05 ARGV.
10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
01 SERVER-INIT-STATUS.
COPY TPSTATUS.
*
PROCEDURE DIVISION USING CMD-LINE SERVER-INIT-STATUS.
**********************************************************
* ARGC indicates the number of arguments and ARGV contains the
* arguments separated by a single SPACE.
**********************************************************
A-START.
*
. . . INSPECT the ARGV line and process arguments
IF arguments are invalid
SET TPEINVAL IN SERVER-INIT-STATUS TO TRUE.
ELSE arguments are OK continue
SET TPOK IN SERVER-INIT-STATUS TO TRUE.
*
EXIT PROGRAM.
Listing 12-9 shows a code fragment that illustrates another common use of TPSVRINIT: opening a resource manager. The BEA TUXEDO system provides a routine to generically open a resource manager, TPOPEN. It also provides the complementary routine, TPCLOSE. The details of these ATMI calls can be found in Section 3cbl of the BEA TUXEDO Reference Manual. Applications that use these calls to open and close their resource managers are portable in this respect. They work by accessing the resource manager instance-specific information that is available in the configuration file. These calls are optional and can be used in place of the resource manager specific calls that are sometimes part of the Data Manipulation Language (DML) if the resource manager is a database. In the example that follows, the code does not pick up command line options, but there is no reason it could not both pick up options and open the database. Also, note the use of the USERLOG routine to write to the central event log.
Listing 12-9 Opening a resource manager in TPSVRINIT
IDENTIFICATION DIVISION.
PROGRAM-ID. TPSVRINIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. USL-486.
OBJECT-COMPUTER. USL-486.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TPSTATUS-REC.
COPY TPSTATUS.
01 LOGMSG PIC X(50).
01 LOGMSG-LEN PIC S9(9) COMP-5.
*
LINKAGE SECTION.
01 CMD-LINE.
05 ARGC PIC 9(4) COMP-5.
05 ARGV.
10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
01 SERVER-INIT-STATUS.
COPY TPSTATUS.
*
PROCEDURE DIVISION USING CMD-LINE SERVER-INIT-STATUS.
A-START.
. . . INSPECT the ARGV line and process arguments
IF arguments are invalid
MOVE "Invalid Arguments Passed" TO LOGMSG
PERFORM EXIT-NOW.
ELSE arguments are OK continue
CALL "TPOPEN" USING TPSTATUS-REC.
IF NOT TPOK
MOVE "TPOPEN Failed" TO LOGMSG
ELSE IF TPESYSTEM
MOVE "System /T error has occurred" TO LOGMSG
ELSE IF TPEOS
MOVE "An Operating System error has occurred" TO LOGMSG
ELSE IF TPEPROTO
MOVE "TPOPEN was called in an improper Context" TO LOGMSG
ELSE IF TPERMERR
MOVE "Resource manager Failed to Open" TO LOGMSG
PERFORM EXIT-NOW.
SET TPOK IN SERVER-INIT-STATUS TO TRUE.
EXIT PROGRAM.
EXIT-NOW.
SET TPEINVAL IN SERVER-INIT-STATUS TO TRUE
MOVE 50 LOGMSG-LEN.
CALL "USERLOG" USING LOGMSG
LOGMSG-LEN
TPSTATUS-REC.
EXIT PROGRAM.
If an error occurs during the initialization activities, TPSVRINIT can be coded to permit the server to exit gracefully before the server starts processing service requests.
As might be expected, TPSVRDONE can call on the services of TPCLOSE to close the resource manager in a manner analogous to the way TPSVRINIT and TPOPEN are used to open it. If the application does not define a closing routine for TPSVRDONE, the BEA TUXEDO system calls the default version which calls TPCLOSE and USERLOG to close the resource manager and write to the central event log. The message to the log indicates that the server is about to exit. TPSVRDONE is called after the server has finished processing service requests but before it exits. Since the server is still part of the system, further communication and transactions can take place within the routine. The rules that must be followed to do this properly are covered in Chapter 14, "Global Transactions in the BEA TUXEDO System." The syntax of this routine is:
01 TPSTATUS-REC.
COPY TPSTATUS.
PROCEDURE DIVISION.
* User code
EXIT PROGRAM.
The following example shows the typical way in which TPSVRDONE is used.
Listing 12-10 Closing a resource manager in TPSVRDONE
IDENTIFICATION DIVISION.
PROGRAM-ID. TPSVRDONE.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. USL-486.
OBJECT-COMPUTER. USL-486.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TPSTATUS-REC.
COPY TPSTATUS.
01 LOGMSG PIC X(50).
01 LOGMSG-LEN PIC S9(9) COMP-5.
01 SERVER-DONE-STATUS.
COPY TPSTATUS.
PROCEDURE DIVISION.
A-START.
CALL "TPCLOSE" USING TPSTATUS-REC.
IF NOT TPOK
MOVE "TPCLOSE Failed" TO LOGMSG
ELSE IF TPESYSTEM
MOVE "System /T error has occurred" TO LOGMSG
ELSE IF TPEOS
MOVE "An Operating System error has occurred" TO LOGMSG
ELSE IF TPEPROTO
MOVE "TPCLOSE was called in an improper Context" TO LOGMSG
ELSE IF TPERMERR
MOVE "Resource manager Failed to Open" TO LOGMSG
PERFORM EXIT-NOW.
SET TPOK IN SERVER-DONE-STATUS TO TRUE.
EXIT PROGRAM.
EXIT-NOW.
SET TPEINVAL IN SERVER-DONE-STATUS TO TRUE
MOVE 50 LOGMSG-LEN.
CALL "USERLOG" USING LOGMSG
LOGMSG-LEN
TPSTATUS-REC.
EXIT PROGRAM.
To compile your service subroutines you have the same freedom you had in compiling clients. You can use regular COBOL Compilation System utilities to make object files. The object files can be kept as individual files or collected into an archive file. If you prefer, you can retain them as source (.cbl) files. In any event, when you invoke buildserver -C to produce an executable server, you specify them on the command line with the -f option. This applies to new versions of TPSVRINIT and TPSVRDONE as well as your application subroutines.
buildserver is used to put together an executable server with the BEA TUXEDO systems's controlling program. Options identify the name of the output file, input files provided by the application, and various libraries that permit you to run a BEA TUXEDO application in a variety of ways. When compiling a COBOL server, the -C option must be used to indicate that the language is COBOL. This ensures that the correct language libraries are included in linking the program.
buildserver invokes the cobcc command. The environment variables ALTCC and ALTCFLAGS can be set to name an alternative compile command and to set settings for the compile and link edit phases. The key buildserver command line options are described in the paragraphs that follow.
The -o option is used to assign a name to the executable output file. If no name is provided, the file is named SERVER.
The -f and -l options are used to specify files to be used in the link edit phase. The files specified in the -f option are brought in before the BEA TUXEDO system and resource manager libraries (first), whereas the files specified in the -l option are brought in after these libraries (last). There is a significance to the order of the options. The order is dependent on routine references and in what libraries the references are resolved. Source modules should be listed ahead of libraries that might be used to resolve their references. Any .cbl files are first compiled. Object files can be either separate .o files or groups of files in archive (.a) files. If more than a single file name is given as an argument to a -f or -l option, the syntax calls for a list enclosed in double quotes. You can use as many -f and -l options as you need.
The -r option is used to specify which resource manager access libraries should be link edited with the executable server. The choice is specified with a string from the $TUXDIR/udataobj/RM file. Only one string can be specified. The database routines in your service are the same regardless of which library is used.
All valid strings that name resource managers are contained in the $TUXDIR/udataobj/RM file. When integrating a new resource manager into the BEA TUXEDO system, this file must be updated to include the information about the resource manager. Refer to the buildtms(1) reference page and Administering the BEA TUXEDO System for more information.
The -s option is used to specify the service names included in the server and the name of the routines that perform each service. Normally, the routine name is the same as the name of the service. In the sample program our convention is to specify all uppercase for the service name. For example, the BUYSR service would be processed by routine BUYSR(). The following represents the command line to create the BUYSELL server.
buildserver -C -o BUYSELL \
-s SELLSR -f SELLSR.cbl \
-s BUYSR -f BUYSR.cbl
However, it is possible for the administrator to specify that only a subset of the services that were used to create the server with the buildserver command are to be advertised when the server is booted. Refer to Administering the BEA TUXEDO System.