OpenTP1 Version 7 Programming Reference COBOL Language

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

TPSEND - Send a message in a conversational connection

Format

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

Description

TPSEND is used to send data across an open connection to another program. The caller must have control of the connection. COMM-HANDLE specifies the open connection over which data is sent. COMM-HANDLE is a communication handle returned from either TPCONNECT or TPSVCSTART.

DATA-REC contains the data to be sent and LEN specifies how much of the data to send. Note that if DATA-REC is a record of a type that does not require a length to be specified, LEN is ignored (and may be 0). If DATA-REC is a record of a type that does require a length, LEN must not be zero. If REC-TYPE does not have a subtype, SUB-TYPE is ignored (and may be SPACES). If REC-TYPE is SPACES, DATA-REC and LEN are ignored and a message is sent with no data (this might be done, for instance, to grant control of the connection without transmitting any data).

<<Data areas>>

<<TPSVCDEF-REC

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

<<TPTYPE-REC

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

<<DATA-REC

Points to the send data.>>

<<TPSTATUS-REC

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

The valid settings of TPSVCDEF-REC are as follows:

TPRECVONLY
This setting signifies that, after the caller's data is sent, the caller gives up control of the connection (that is, the caller cannot issue any more TPSEND calls). When the receiver on the other end of the connection receives the data sent by TPSEND, it also receives an event (TPEV-SENDONLY) indicating that it has control of the connection (and cannot issue any more TPRECV calls). Either TPRECVONLY or TPSENDONLY must be set.

TPSENDONLY
This setting signifies that the caller wants to remain in control of the connection. Either TPRECVONLY or TPSENDONLY must be set.

TPNOBLOCK
The data and any events are not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). 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.

If an event exists for COMM-HANDLE, TPSEND returns without sending the caller's data. The event type is returned in TP-EVENT. Valid events for TPSEND are as follows:

TPEV-DISCONIMM
Received by the subordinate of a conversation, this event indicates that the originator of the conversation has either issued an immediate disconnect on the connection via TPDISCON, or it issued TPRETURN, TXCOMMIT or TXROLLBACK with the connection still open. This event is also returned to the originator or subordinate when a connection is broken due to a communication error (for example, a server, machine, or network failure).

TPEV-SVCERR
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN without having control of the conversation. In addition, TPRETURN was issued in a manner different from that described for TPEV-SVCFAIL below.

TPEV-SVCFAIL
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued TPRETURN without having control of the conversation. In addition, TPRETURN was issued with the command TPFAIL and no data record (that is, the REC-TYPE passed to TPRETURN was set to SPACES).

Because each of these events indicates an immediate disconnection notification (that is, abortive rather than orderly), data in transit may be lost. The communication handle used for the connection is no longer valid. If the two programs were participating in the same transaction, the transaction has been marked rollback-only.

Return value

Upon successful completion, TPSEND sets TP-STATUS to TPOK. When TP-STATUS is set to TPEEVENT and TP-EVENT is TPEV-SVCFAIL, APPL-RETURN-CODE contains an application-defined value that was sent as part of TPRETURN.

Errors

Under the following conditions, TPSEND 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).

TPEBADDESC
COMM-HANDLE contains an invalid communication handle.

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 DATA-REC nor TPTYPE-REC are changed. If a transaction timeout occurred, any attempts to send or receive messages on any connections or to start a new connection fail with TPETIME until the transaction has been rolled back.

TPEEVENT
An event occurred and its type is available in TP-EVENT. DATA-REC is not sent when this error occurs.

TPEBLOCK
A blocking condition exists and TPNOBLOCK was specified.

TPEGOTSIG
A signal was received and TPNOSIGRSTRT was specified.

TPEPROTO
TPSEND 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

TPCONNECT, TPDISCON, TPRECV, 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 never return. 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. <<The value TPNOTIME is invalid under the relevant version of the OpenTP1.>>
  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 OpenTP1, when a process encounters transaction timeout, it terminates abnormally. Therefore, TPETIME returns only when blocking timeout occurs.>>
  5. <<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.>>
  6. <<Under the OpenTP1, even if the mate of conversation is running the function TPDISCON or TPRETURN, the function TPSEND cannot generate an event provided that the process which invoked the function TPSEND has not received an event.>>
  7. <<When OSI TP communication using the TP1/NET/OSI-TP-Extended is in progress, it cannot be used for conversational services. If an attempt is made to do so, the system operation is unpredictable.>>