OpenTP1 Version 7 Programming Reference COBOL Language
TPSVCSTART - Start a service routine
Format
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. |
Description
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.
<<Data areas>>
<<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:
Return value
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:
See also
TPACALL, TPCALL, TPCONNECT, TPRETURN.
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.