To facilitate the development of ATMI servers, the Oracle Tuxedo system provides a predefined controlling program for server load modules. When you execute the
buildserver -C command, the controlling program is automatically included as part of the server.
•
|
Calls the routine TPSVRINIT to process any command-line arguments listed after the double dash ( --) and optionally to open the resource manager. These command-line arguments are used for application-specific initialization.
|
•
|
If the -r option is specified, records the starting time of the service request.
|
•
|
If the -r option is specified, records the ending time of the service request.
|
As indicated above, the main() routine handles all of the details associated with joining and exiting from an application, managing records and transactions, and handling communication.
Notes:
|
If you want to write your own versions of TPSVRINIT and TPSVRDONE, remember that the default versions of these two routines call tx_open() and tx_close(), respectively. If you write a new version of TPSVRINIT that calls tpopen() rather than tx_open(), you should also write a new version of TPSVRDONE that calls tpclose(). In other words, both routines in an open/close pair must belong to the same set.
|
You can use the AUTHSVR(5) server to provide individual client authentication for an application. The
TPINITIALIZE routine calls this server when the level of security for the application is
TPAPPAUTH,
USER_AUTH,
ACL, or
MANDATORY_ACL.
The service in AUTHSVR looks in the
USER-DATA-REC record for a user password (not to be confused with the application password specified in the
PASSWD field of the
TPINFDEF-REC record). By default, the system takes the string in
data and searches for a matching string in the
/etc/passwd file.
When called by a native-site client, TPINITIALIZE forwards the
USER-DATA-REC record as it is received. This means that if the application requires the password to be encrypted, the client program must be coded accordingly.
When a server is booted, the Oracle Tuxedo system controlling program calls
TPSVRINIT(3cbl) during its initialization phase, before handling any service requests.
You can use the TPSVRINIT routine for any initialization processes that might be required by an application, such as the following:
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.
The following example illustrates another common use of TPSVRINIT: opening a resource manager. The Oracle Tuxedo system provides routines to open a resource manager,
TPOPEN(3cbl) and
TXOPEN(3cbl). It also provides the complementary routines,
TPCLOSE(3cbl) and
TXCLOSE(3cbl). Applications that use these routines 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.
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.
The TPSVRDONE routine calls
TPCLOSE to close the resource manager, similarly to the way
TPSVRINIT calls
TPOPEN to open it.
01 TPSTATUS-REC.
COPY TPSTATUS.
PROCEDURE DIVISION.
* User code
EXIT PROGRAM.
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.
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” in
Programming Oracle Tuxedo ATMI Applications Using C.
The TPRETURN(3cbl),
TPCANCEL(3cbl), and
TPFORWAR(3cbl) routines specify that a service routine has completed with one of the following actions:
•
|
TPRETURN sends a reply to the calling client.
|
•
|
TPFORWAR forwards a request to another service for further processing.
|
The TPRETURN(3cbl) and
TPFORWAR(3cbl) calls are COBOL copy files that contain
EXIT statements to mark the end of a service routine and send a message to the requester or forward the request to another service, respectively. Use the following signature to call the
TPRETURN routine:
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.
Note:
|
You must use COPY here instead of CALL to ensure that the EXIT statement is called properly, and the COBOL service routine returns control to the Oracle Tuxedo system.
|
05 TPRETURN-VAL PIC S9(9) COMP-5.
88 TPSUCCESS VALUE 0.
88 TPFAIL VALUE 1.
88 TPFAIL VALUE 2.
05
APPL-CODE PIC S9(9) COMP-5.
Table 5‑2 describes the members of a
TPSVCRET-REC data structure.
|
|
|
•
|
TPSUCCESS—the calling routine succeeded. The routine stores the reply message in the caller’s record. If there is a reply message, it is in the caller’s record.
|
•
|
TPFAIL (default)—the service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply. In this case, the client’s TPCALL or TPGETRPLY routine call fails and the system sets the TP-STATUS variable to TPESVCFAIL to indicate an application-defined failure. If a reply message was expected, it is available in the caller’s record.
|
•
|
TPEXIT—the service terminated unsuccessfully. The routine reports an error message to the client process waiting for the reply, and exits.
|
|
|
Returns an application-defined return code to the caller. The client can access the value returned in APPLC-CODE by querying APPL-RETURN-CODE IN TPSTATUS-REC. The routine returns this code regardless of success or failure.
|
When TPRETURN is called, control always returns to the controlling program. If a 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 Oracle Tuxedo system controlling program, and an error is returned to the caller.
If the client invokes the service with TPCALL, after a successful call to
TPRETURN, the reply message is available in the
O-DATA-REC record. If
TPACALL is used to send the request, and
TPRETURN returns successfully, the reply message is available in the
DATA-REC record of
TPGETRPLY.
If a reply is expected and TPRETURN encounters errors while processing its arguments, it sends a
failed message to the calling process. The caller detects the error by checking the value placed in
TP-STATUS. In the case of failed messages, the system sets the
TP-STATUS to
TPESVCERR. This situation takes precedence over the value of
APPL-RETURN-CODE IN TPSTATUS-REC. If this type of error occurs, no reply data is returned, and both the contents and length of the caller’s output record remain unchanged.
If TPRETURN returns a message in a record of an unknown type or a record that is not allowed by the caller (that is, if the call is made with
TPNOCHANGE), the system returns
TPEOTYPE in
TP-STATUS. In this case, application success or failure cannot be determined, and the contents and length of the output record remain unchanged.
The value returned in APPL-RETURN-CODE IN TPSTATUS-REC is not relevant if the
TPRETURN routine is invoked and a timeout occurs for the call waiting for the reply. This situation takes precedence over all others in determining the value that is returned in
TP-STATUS. In this case,
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 timeouts in the Oracle Tuxedo system: blocking and transaction timeouts (discussed in
“Writing Global Transactions” in
Programming Oracle Tuxedo ATMI Applications Using C).
The example code in this section shows the TRANSFER service that is part of the
XFER server. Basically, the
TRANSFER service makes synchronous calls to the
WITHDRAWAL and
DEPOSIT services. It allocates a separate record for the reply message since it must use the request record for the calls to both the
WITHDRAWAL and the
DEPOSIT services. If the call to
WITHDRAWAL fails, the service writes the message
cannot withdraw on the status line of the form and sets
TP-RETURN-VAL IN TPSVCRET-REC of the
TPRETURN routine to
TPFAIL. If the call succeeds, the debit balance is retrieved from the reply record.
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 "Cannot Deposit into credit account"
TO STATUS-LINE IN TRANS-REC
SET TPFAIL TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
. . .
MOVE "Transfer completed" TO STATUS-LINE IN TRANS-REC
. . . MOVE
all the data into TRANS-REC needed by the client
SET TPSUCCESS TO TRUE
COPY TPRETURN REPLACING
DATA-REC BY TRANS-REC.
If a service calling TPGETRPLY (described in detail in
“Writing Request/Response Clients and Servers” in
Programming Oracle Tuxedo ATMI Applications Using C) fails with
TPETIME and decides to cancel the request, it can invalidate the descriptor with a call to
TPCANCEL(3cbl). If a reply subsequently arrives, it is silently discarded.
TPCANCEL cannot be used for transaction replies (that is, for replies to requests made without the
TPNOTRAN flag set). Within a transaction,
TPABORT(3cbl) does the same job of invalidating the transaction call descriptor.
Listing 5‑7 shows how to 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(3cbl) routine allows a service to forward a request to another service for further processing.
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 functionality of TPFORWAR differs from a service call: a service that forwards a request does not expect a reply. The responsibility for providing the reply is passed to the service to which the request has been forwarded. The latter service sends the reply to the process that originated the request. It becomes the responsibility of the last server in the forward chain to send the reply to the originating client by invoking
TPRETURN.
Figure 5‑1 shows one possible sequence of events when a request is forwarded from one service to another. Here a client initiates a request using the
TPCALL routine and the last service in the chain (
SVC_C) provides a reply using the
TPRETURN routine.
When a process calls TPFORWAR, the system that supplied the controlling program regains control, and the server process is free to do more work.
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, you can call
TPRETURN with
TP-RETURN-VAL IN TPSVCRET-REC set to
TPFAIL.
The following example illustrates how the service sends its data record to the DEPOSIT service by calling
TPFORWAR. If the new account is added successfully, the branch record is updated to reflect the new account, and the data record is forwarded to the
DEPOSIT service. On failure,
TPRETURN is called with
TP-RETURN-VAL IN TPSVCRET-REC set to
TPFAIL and the failure is reported on the status line of the form.
. . .
******************************************************
* 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.
An Oracle Tuxedo application administrator can use the advertise and
unadvertise commands of
tmadmin(1) to control the services offered by servers. The
TPADVERTISE and
TPUNADVERTISE routines enable you to dynamically control the advertisement of a service in a request/response or conversational server. The service to be advertised (or unadvertised) must be available within the same server as the service making the request.
01 SERVICE-NAME PIC X(127).
01
PROGRAM-NAME PIC X(32).
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPADVERTISE" USING
SERVICE-NAME PROGRAM-NAME TPSTATUS-REC.
Table 5‑3 describes the members of a
TPADVERTISE data structure.
The TPUNADVERTISE(3cbl) routine removes the name of a service from the service table of the bulletin board so that the service is no longer advertised.
01 SERVICE-NAME PIC X(127).
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPUNADVERTISE" USING
SERVICE-NAME TPSTATUS-REC.
The TPUNADVERTISE data structure contains one member, which is described in
Table 5‑4.
The following example shows how to use the TPADVERTISE routine. In this example, a server called
TLR is programmed to offer only the service called
TLRINIT when booted. After some initialization,
TLRINIT advertises two services called
DEPOSIT and
WITHDRAW. Both are performed by the
TLRFUNCS routine, and both are built into the
TLR server.
. . .
**************************************************
* 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
buildserver -C -o filename -f
filenames -l
filenames -s -v
Table 5‑5 describes the
buildserver command-line options:
By default, the buildserver command invokes the UNIX
cobcc command, which uses the MicroFocus Net Express compiler. To use Fujitsu’s NetCOBOL
ALTCC must be set, even on a Windows system. You must set
ALTCC=cobcc85 for NetCOBOL. You can specify an alternative compile command and set your own flags for the compile and link-edit phases, however, by setting the
ALTCC and
ALTCFLAGS environment variables, respectively. For more information, refer to
“Setting Environment Variables” in
Programming Oracle Tuxedo ATMI Applications Using C.
Note:
|
1. On a Windows system, the ALTCC and ALTCFLAGS environment variables are not applicable and setting them will produce unexpected results. You must compile your application first using a COBOL compiler and then pass the resulting object file to the buildserver command.
|
2. ALTCFLAGS only works for the MicroFocus COBOL compiler. For other supported COBOL compilers (i.e., IBMCOBOL or AccuCOBOL),
CFLAGS is supported and is sufficient.
The following command processes the acct.o application file and creates a server called
ACCT that contains two services:
NEW_ACCT, which calls the
OPEN_ACCT routine, and
CLOSE_ACCT, which calls a routine of the same name: