OpenTP1 Version 7 Programming Reference COBOL Language

[Contents][Index][Back][Next]

TPCALL - Send a service request and synchronously await its reply

Format

01  TPSVCDEF-REC.
    COPY  TPSVCDEF.
01  ITPTYPE-REC.
    COPY  TPTYPE.
01  IDATA-REC.
    COPY  Data record definition.
01  OTPTYPE-REC.
    COPY TPTYPE.
01  ODATA-REC.
    COPY  Data record definition.
01  TPSTATUS-REC.
    COPY  TPSTATUS.
 
CALL  "TPCALL"  USING  TPSVCDEF-REC  ITPTYPE-REC  IDATA-REC
                       OTPTYPE-REC ODATA-REC TPSTATUS-REC.

Description

TPCALL sends a request and synchronously awaits its reply. A call to this routine is the same as calling TPACALL immediately followed by TPGETRPLY. TPCALL sends a request to the service named by SERVICE-NAME. The data portion of a request is specified by IDATA-REC and LEN in ITPTYPE-REC specifies how much of IDATA-REC to send. Note that if ITYPE-REC is a record of a type that does not require a length to be specified, LEN in ITPTYPE-REC is ignored (and may be 0). If IDATA-REC is a record of a type that does require a length, LEN in ITPTYPE-REC must not be zero. If REC-TYPE in ITPTYPE-REC does not have a subtype, SUB-TYPE in ITPTYPE-REC is ignored (and may be SPACES). If REC-TYPE in ITPTYPE-REC is SPACES, IDATA-REC and LEN in ITPTYPE-REC are ignored and a request is sent with no data portion. REC-TYPE in ITPTYPE-REC and SUB-TYPE in ITPTYPE-REC must match one of the types and sub-types recognized by SERVICE-NAME.

ODATA-REC specifies where the reply is read into, and, on input, LEN in OTPTYPE-REC indicates the maximum number of bytes that should be moved into ODATA-REC. If the same record is to be used for both sending and receiving, redefine ODATA-REC (REDEFINES) to IDATA-REC. Upon successful return from TPCALL, LEN in OTPTYPE-REC contains the actual number of bytes moved into ODATA-REC. REC-TYPE in OTPTYPE-REC and SUB-TYPE in OTPTYPE-REC contain the reply's type and sub-type, respectively. If the reply is larger than ODATA-REC, ODATA-REC contains only as many bytes as fit in the record. The remainder of the reply is discarded and TPCALL sets TPTRUNCATE.

If LEN in OTPTYPE-REC is 0 upon successful return, the reply has no data portion and ODATA-REC was not modified. It is an error for LEN in OTPTYPE-REC to be 0 on input.

<<Data areas>>

<<TPSVCDEF-REC

Specify a value indicating the TPCALL operation. The specifiable values and their meanings will be explained later.>>

<<ITPTYPE-REC

Indicates the record type and subtype record name of the send data.>>

<<IDATA-REC

Points to the send data.>>

<<OTPTYPE-REC

Indicates the record type and subtype record name of the receive data.>>

<<ODATA-REC

Points to the receive data.>>

<<TPSTATUS-REC

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

The valid settings of TPSVCDEF-REC are as follows:

TPNOTRAN
If the caller is in transaction mode and this setting is used, when SERVICE-NAME is invoked, it is not performed on behalf of the caller's transaction. If SERVICE-NAME does not support transactions, this setting must be used when the caller is in transaction mode. A caller in transaction mode that uses this setting is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller's transaction is not affected. Either TPNOTRAN or TPTRAN must be set.

TPTRAN
If the caller is in transaction mode and this setting is used, when SERVICE-NAME is invoked, it is performed on behalf of the caller's transaction. This setting is ignored if the caller is not in transaction mode. Either TPNOTRAN or TPTRAN must be set.

TPNOCHANGE
When this setting is used, the type of ODATA-REC is not allowed to change. That is, the type and sub-type of the reply record must match REC-TYPE in OTPTYPE-REC and SUB-TYPE in OTPTYPE-REC, respectively. Either TPNOCHANGE or TPCHANGE must be set.

TPCHANGE
The type and/or subtype of the reply record are allowed to differ from those specified in REC-TYPE in OTPTYPE-REC and SUB-TYPE in OTPTYPE-REC, respectively, so long as the receiver recognizes the incoming record type. Either TPNOCHANGE or TPCHANGE must be set.

TPNOBLOCK
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Note that this setting applies only to the send portion of TPCALL: the routine may block waiting for the reply. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME
This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.

TPTIME
This setting signifies that the caller receives blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.

TPSIGRSTRT
If a signal interrupts any underlying system calls, the interrupted system call is re-issued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT
If a signal interrupts any underlying system calls, the interrupted system call is not restarted and the routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

Return value

Upon successful completion, TPCALL sets TP-STATUS to TPOK. When TP-STATUS is set to either TPOK or TPESVCFAIL, APPL-RETURN-CODE contains an application-defined value that was sent as part of TPRETURN. If the size of the incoming message is larger than the size specified in LEN in OTPTYPE-REC on input, then TPTRUNCATE is set in OTPTYPE-REC and only LEN in OTPTYPE-REC bytes are moved into ODATA-REC. The remaining bytes are discarded.

Errors

Under the following conditions, TPCALL fails and sets TP-STATUS to one of the values below. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.

TPEINVAL
Invalid arguments were given (for example, settings in TPSVCDEF-REC are invalid).

TPENOENT
Cannot send to SERVICE-NAME because it does not exist.

TPEITYPE
The pair REC-TYPE in ITPTYPE-REC and SUB-TYPE in ITPTYPE-REC is not one of the allowed types and sub-types that SERVICE-NAME accepts.

TPEOTYPE
Either the type and sub-type of the reply are not known to the caller, or TPNOCHANGE was set and REC-TYPE in OTPTYPE-REC and SUB-TYPE in OTPTYPE-REC do not match the type and sub-type of the reply sent by the service. Neither ODATA-REC nor OTPTYPE-REC are changed. If the service request was made on behalf of the caller's current transaction, the transaction is marked rollback-only since the reply is discarded.

TPETRAN
SERVICE-NAME does not support transactions and TPTRAN was set.

TPETIME
A timeout occurred. If the caller is in transaction mode, a transaction timeout occurred and the transaction is marked rollback-only; otherwise, a blocking timeout occurred and both TPBLOCK and TPTIME were specified. In either case, neither ODATA-REC nor OTPTYPE-REC are changed. If a transaction timeout occurred, any attempts to send new requests or receive outstanding replies fail with TPETIME until the transaction has been rolled back.

TPESVCFAIL
The service routine sending the caller's reply called TPRETURN with TPFAIL. This is an application-level failure. The contents of the service's reply, if one was sent, are available in ODATA-REC. If the service request was made on behalf of the caller's current transaction, the transaction is marked rollback-only. Note that so long as the transaction has not timed out, further communication may be attempted before rolling back the transaction. Such attempts may be processed normally or may fail (producing an error return to event). Such attempts should be made with TPNOTRAN set if they are to have any lasting effect. Any work performed on behalf of the caller's transaction is rolled back upon transaction completion.

TPESVCERR
An error was encountered either in invoking a service routine or during its completion in TPRETURN (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither ODATA-REC nor OTPTYPE-REC are changed). If the service request was made on behalf of the caller's transaction, the transaction is marked rollback-only. Note that so long as the transaction has not timed out, further communication may be attempted before rolling back the transaction. Such attempts may be processed normally or may fail (producing an error return or event). Such attempts should be made with TPNOTRAN set if they are to have any lasting effect. Any work performed on behalf of the caller's transaction is rolled back upon transaction completion.

TPEBLOCK
A blocking condition was found on the send portion of TPCALL and TPNOBLOCK was specified.

TPEGOTSIG
A signal was received and TPNOSIGRSTRT was specified.

TPEPROTO
TPCALL 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.

See also

TPACALL, TPGETRPLY, TPRETURN.

<<Notes on use with OpenTP1>>

  1. <<The value TPNOBLOCK is invalid under the relevant version of the OpenTP1. Therefore, the error code TPEBLOCK will not be returned to TP-STATUS. The OpenTP1 is designed so that if communication is impossible because of blocking, TPESYSTEM is returned as when communication is impossible because of network failure.>>
  2. <<Under the relevant version of the OpenTP1, the value TPNOTIME is valid only when a response is received. It is invalid when blocking occurs at the time of service request transmission.>>
  3. <<The value TPSIGRSTRT is invalid. Regardless of whether this value is set, when a signal is received, the interrupted system call is reinvoked. TPEGOTSIG will never return.>>
  4. <<Under the relevant version of the OpenTP1, TPEITYPE will not return. If a record of a type unavailable with SERVICE-NAME is passed, TPESYSTEM will return. If the calling program is in transaction mode, the rollback_only state comes into effect.>>
  5. <<Under the OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
  6. <<Under the relevant version of the OpenTP1, an error which raises need for rollback causes the return of TPESYSTEM unless otherwise specified by the X/Open. However, the rollback_only state may not come into effect even when TPESYSTEM returns.>>
  7. <<If the SPP that was asked to offer its service abnormally terminates, the function could return with a TPETIME error before the time assigned to watch_time in the definition elapses. If watch_time is assigned 0 (infinitely wait for a response), the function could return with a TPEPROTO error.>>
  8. <<If the service request is not validated when OpenTP1 security is in use, the function returns with a TPEPROTO error. To determine whether the error return was caused by an invalidated service request, refer to the detailed information in the UAP trace.>>
  9. <<If a line error occurs during OSI TP communication using the TP1/NET/OSI-TP-Extended, the function returns with a TPESVCERR error.>>
  10. <<For OSI TP communication using the TP1/NET/OSI-TP-Extended, the length of the send or receive data must not exceed the value assigned to the length operand of the NET buffer group definition (nettbuf) contained in the NET/Library common definition.>>