TPSVCSTART() - start a BEA Tuxedo system service
COPY User data.
CALL "TPSVCSTART" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPSVCSTART() is the first BEA Tuxedo system routine to be called when writing a service routines. In fact, it is an error to issue any other call within a service routine before calling TPSVCSTART(). TPVCSTART() is used to retrieve the service's parameters and data. This routine is used for services that receive requests via TPCALL() or TPACALL() routines as well as by services that communicate via TPCONNECT(), TPSEND(), and TPRECV() routines.
Service routines processing requests made via either TPCALL(), TPACALL(), or TPFORWAR() receive at most one incoming message (upon successfully returning from TPSVCSTART) and send at most one reply (upon exiting the service routine with TPRETURN()).
Conversational services, on the other hand, are invoked by connection requests with at most one incoming message along with a means of referring to the open connection. Upon successfully returning from TPSVCSTART(), either the connecting program or the conversational service may send and receive data as defined by the application. The connection is half-duplex in nature meaning that one side controls the conversation (that is, it sends data) until it explicitly gives up control to the other side of the connection.
Concerning transactions, service routines can participate in at most one transaction if invoked in transaction mode. As far as the service routine writer is concerned, the transaction ends upon returning from the service routine. If the service routine is not invoked in transaction mode, then the service routine may originate as many transactions as it wants using TPBEGIN(), TPCOMMIT(), and TPABORT(). Note that TPRETURN() is not used to complete a transaction. Thus, it is an error to call TPRETURN() with an outstanding transaction that originated within the service routine.
DATA-REC specifies where the service's data is read into, and, on input, LEN in TPTYPE-REC indicates the maximum number of bytes that should be moved into DATA-REC. Upon successful return from TPSVCSTART, LEN contains the actual number of bytes moved into DATA-REC. REC-TYPE and SUB-TYPE, both in TPTYPE-REC, contain the data's type and sub-type, respectively. If the message is larger than DATA-REC, then DATA-REC will contain only as many bytes as will fit in the record. The remainder of the message is discarded and TPSVCSTART() sets TPTRUNCATE().
If LEN is 0 upon successful return, then the service has no incoming data and DATA-REC was not modified. It in an error for LEN to be 0 on input.
Upon successful return, SERVICE-NAME in TPSVCDEF-REC is populated with the service name that the requesting program used to invoke the service.
The following are the possible settings in TPSVCDEF-REC upon return of TPSVCSTART().
APPKEY in TPSVCDEF-REC is set to the application key assigned to the requesting client program by the application defined authentication service. This key value is passed along with any and all service requests made while within this invocation of the service routine. APPKEY will have a value of -1 for originating clients that do not pass through the application authentication service. This includes clients of an earlier release level interoperating with a security application.
Upon successful completion, TPSVCSTART() sets TP-STATUS to [TPOK]. If the size of the incoming message was larger then the size specified in LEN on input, TPTRUNCATE() is set and only LEN amount of data was moved to DATA-REC, the remaining data is discarded.
Under the following conditions, TPSVCSTART() fails and sets TP-STATUS to:
buildserver(1), TPBEGIN(3cbl), TPCALL(3cbl), TPCONNECT(3cbl), TPINITIALIZE(3cbl), TPOPEN(3cbl), TPSVRDONE(3cbl), TPSVRINIT(3cbl)
Copyright © 2000 BEA Systems, Inc. All rights reserved.