TPSVCSTART
-start a BEA TUXEDO system service
01
TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPSVCSTART" USINGTPSVCDEF-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 (i.e., 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.
Following are the possible settings in TPSVCDEF-REC
upon return of TPSVCSTART
.
TPREQRSP
TPCALL
() or TPACALL
(). This setting is mutually exclusive with TPCONV
.
TPCONV
TPCONNECT
(). The communications handle for the conversation is available in COMM-HANDLE
in TPSVCDEF-REC
. This setting is mutually exclusive with TPREQRSP
.
TPNOTRAN
TPTRAN
.
TPTRAN
TPNOTRAN
.
TPNOREPLY
TPREQRSP
is set. This setting is mutually exclusive with TPREPLY
.
TPREPLY
TPREQRSP
is set. This setting is mutually exclusive with TPNOREPLY
.
TPSENDONLY
TPCONV
is set. This setting is mutually exclusive with TPRECVONLY
.
TPRECVONLY
TPCONV
is set. This setting is mutually exclusive with TPSENDONLY
.
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:
TPEINVAL
]
TPEPROTO
]
TPSVCSTART
was called in an improper context.
TPESYSTEM
]
TPEOS
]
TPSVRINIT
(), TPSVRDONE
(), buildserver
(1), TPBEGIN
() TPCONNECT
(), TPCALL
(), TPINIT
(), TPOPEN
()