01 TPSVCDEF-REC. COPY TPSVCDEF. 01 TPTYPE-REC. COPY TPTYPE. 01 DATA-REC. COPY Data record definition. 01 TPSTATUS-REC. COPY TPSTATUS CALL "TPSVCSTART" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

TPSVCSTART is the first routine called when writing a service routine. In fact, it is an error to issue any other XATMI call within a service routine before calling TPSVCSTART. TPSVCSTART 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 or TPACALL receive, at most, one incoming message (upon successfully returning from TPSVCSTART) and send, at most, one reply (upon existing 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, the service routine may originate as many transactions as it wants using TXBEGIN, TXCOMMIT and TXROLLBACK. 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 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 contain the data's type and sub-type, respectively. If the message is larger than DATA-REC, DATA-REC contains only as many bytes as will fit the record. The remainder of the message is discarded and TPSVCSTART sets TPTRUNCATE.

If LEN is 0 upon successful return, the service has no incoming data and DATA-REC was not modified. It is an error for LEN to be 0 on input.

Upon successful return, SERVICE-NAME is populated with the service name that the requesting program used to invoke the service.

<<TPSVCDEF-REC

Will be assigned a value that indicates how the service routine was invoked. The specifiable values and their meanings will be explained later.>>

<<TPTYPE-REC

Will be assigned the data type and subtype record name of the receive data.>>

<<DATA-REC

Will be assigned the receive data.>>

<<TPSTATUS-REC

Will be assigned the return value indicating the result of TPSVCSTART execution.>>

The possible settings of TPSVCDEF-REC upon the return of TPSVCSTART are as follows:

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 communication handle for the conversation is available in COMM-HANDLE. 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.

Upon successful completion, TPSVCSTART sets TP-STATUS to TPOK. If the size of the incoming message is larger than the size specified in LEN on input, TPTRUNCATE is set and only LEN bytes are moved into DATA-REC. The remaining bytes are discarded.

Errors

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

TPEINVAL

Invalid arguments were given (for example, LEN is 0).

TPEPROTO

TPSVCSTART was called in an improper context.

TPESYSTEM

A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPEOS

An operating system error has occurred. The exact nature of the error is determined in a product-specific manner.

TPACALL, TPCALL, TPCONNECT, TPRETURN.