[Top] [Prev] [Next] [Bottom]

TPSVCSTART(3CBL)

TPSVCSTART(3CBL)

Name

TPSVCSTART-start a BEA TUXEDO system service

synopsis

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.

Description

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
The service was invoked with either TPCALL() or TPACALL(). This setting is mutually exclusive with TPCONV.

TPCONV
The service was invoked with TPCONNECT(). The communications handle for the conversation is available in COMM-HANDLE in TPSVCDEF-REC. This setting is mutually exclusive with TPREQRSP.

TPNOTRAN
The service routine is not in transaction mode. This setting is mutually exclusive with TPTRAN.

TPTRAN
The service routine is in transaction mode. This setting is mutually exclusive with TPNOTRAN.

TPNOREPLY
The program invoking the service routine is not expecting a reply. This setting is meaningful only when TPREQRSP is set. This setting is mutually exclusive with TPREPLY.

TPREPLY
The program invoking the service routine is expecting a reply. This setting is meaningful only when TPREQRSP is set. This setting is mutually exclusive with TPNOREPLY.

TPSENDONLY
The service is invoked such that it can send data across the connection and the program on the other end of the connection can only receive data. This setting is meaningful only when TPCONV is set. This setting is mutually exclusive with TPRECVONLY.

TPRECVONLY
The service is invoked such that it can only receive data from the connection and the program on the other end of the connection can send data. This setting is meaningful only when 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.

Return Values

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.

Errors

Under the following conditions, TPSVCSTART fails and sets TP-STATUS to:

[TPEINVAL]
Invalid arguments were given.

[TPEPROTO]
TPSVCSTART was called in an improper context.

[TPESYSTEM]
A BEA TUXEDO system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]
An operating system error has occurred.

See Also

TPSVRINIT(), TPSVRDONE(), buildserver(1), TPBEGIN() TPCONNECT(), TPCALL(), TPINIT(), TPOPEN()



[Top] [Prev] [Next] [Bottom]