OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/W, TP1/Client/P
(a) TP1/Client/W
#include <dcvxatmi.h>
int tprecv(DCLONG cd, char *CLTFAR *data,
DCLONG CLTFAR *len,
DCLONG flags, DCLONG CLTFAR *revent)
(b) TP1/Client/P
#include <dcvxatmi.h>
int tprecv(DCLONG cd, char CLTFAR *CLTFAR *data,
DCLONG CLTFAR *len, DCLONG flags,
DCLONG CLTFAR *revent)
(2) Purpose
Receives data from the interactive service.
The system without control of connection can issue the tprecv function.
When the tprecv function returns with TPEV_SVCSUCC or TPEV_SVCFAIL specified in revent, the value passed by the application as the tpreturn function argument can be referenced as the global variable tpurcode.
(3) Arguments set by UAPs
- cd
Specify the connection for receiving data. Specify the descriptor indicated by the return value of the tpconnect function.
- data
Specify X_OCTET as the pointer to the typed buffer that contains received data.
Specifying NULL results in error.
- len
Specify the length of data to be received. The maximum length is 500 x 1024 bytes. If the specified value is greater than the total buffer length before the tprecv function is issued, a new value is set in len. If no data received, 0 is set.
- flags
Specify any of the following.
- TPNOCHANGE
- The buffer type specified in data is not converted.
- The buffer type of received data must match that specified in data. When TPNOCHANGE is not specified, the value of data is converted to the buffer type of the received data.
- TPNOBLOCK
- The tprecv function does not wait until data arrives.
- The tprecv function receives data and returns if data is ready for reception. When TPNOBLOCK is not specified and data is not ready for reception, the issuer of the function is blocked until data arrives.
- TPNOTIME
- The issuer of the function is blocked infinitely. Blocking timeout error will never occur. However, transaction timeout error may occur.
- TPSIGRSTRT
- System call interrupted by a signal during execution is recalled.
- revent
Specify the pointer to the typed buffer that stores events.
When an event is set for cd, the type of event is returned to revent. The value specified in data can be received with the TPEV_SVCSUCC, TPEV_SVCFAIL, and TPEV_SENDONLY events.
The following events can be specified for the tprecv function.
- TPEV_DISCONIMM
- The connection is immediately disconnected by the tpdiscon function issued by the initiator of the interactive service. Or, it is disconnected due to a communication error.
- When the connection is disconnected by the tpdiscon function, TPEV_DISCONIMM is returned to the remote system. When the connection is disconnected due to a communication error in which the server, machine, and network failed, TPEV_DISCONIMM is returned to both the initiator and the remote system.
- TPEV_DISCONIMM is returned immediately after the disconnection, and data being sent is aborted. The transaction is rolled back. In this case, the descriptor used for the connection is invalid.
- TPEV_SENDONLY
- The system at the other end of connection has aborted control of connection. The system that receives TPEV_SENDONLY can send but cannot receive data until it aborts control of connection.
- TPEV_SVCERR
- The remote system of the service initiator has issued the tpreturn function. Any of the following error occurred during execution of the tpreturn function.
- An invalid argument is passes to the tpreturn function.
- The tpreturn function is issued while the service was opening connection.
- When TPEV_SVCERR is returned, data or return values defined for the application will not affect the operation. The connection is disconnected and the value of cd is invalidated. If TPEV_SVCERR occurred in the transaction of the receiver of data, the transaction is rolled back.
- TPEV_SVCFAIL
- The service of the remote system was specified by the application, but terminated without being completed (the tpreturn function returns TPFAIL). TPEV_SVCFAIL is returned to the initiator.
- If the remote system's service has control of connection when the tpreturn function is issued, the service can pass the typed buffer to the initiator.
- The server disconnects connection when the tprecv function terminates; the value of cd is invalidated. If TPEV_SVCFAIL occurred in the transaction of the receiver of data, the transaction is rolled back.
- TPEV_SVCSUCC
- The service of the remote system at the other end of service was specified by the application, and terminated after being completed (the tpreturn function returns TPSUCCESS). TPEV_SVCSUCC is returned to the initiator.
- The server disconnects connection when the tprecv function terminates; the value of cd is invalidated. If TPEV_SVCSUCC occurred in the transaction of the receiver of data, the transaction is committed or rolled back by the server, depending on the transaction mode.
(4) Return values
If an error occurs, the tprecv function returns -1 and sets one of the following values in tperrno as a return value to report the information about the error.
Return value |
Meaning |
TPEINVAL |
Invalid argument |
TPEBADDESC |
Invalid descriptor is specified in cd. |
TPEOTYPE |
The issuer of the tprecv function does not identify the buffer type arrived. Alternatively, the buffer type specified in data does not match the sent buffer type when TPNOCHANGE is specified in the flags argument.
In either case, the value of data or len remains unchanged. When the service is executed as a transaction of the issuer of the tprecv function, the transaction is rolled back until the arrived buffer is aborted.
If the above error occurred, the specified event is aborted and the processing result of the service is undetermined. The issuer must terminate the service immediately. |
TPETIME |
A timeout error occurred.
- For the issuer in the transaction mode:
A transaction timeout error occurred. The transaction is rolled back. In this case, TPETIME is returned to new data transmission or undetermined response until the transaction is rolled back.
- For the issuer in other than the transaction mode:
A blocking timeout error occurred where neither TPNOBLOCK nor TPNOTIME is specified.
In either case, the value specified in data is not changed. |
TPEEVENT |
An event occurred. The return value is returned to revent. |
TPEBLOCK |
Blocking status occurred when the tprecv function was issued with TPNOBLOCK specified. |
TPGOTSIG |
The signal is received, but TPSIGRSTRT is not specified. |
TPEPROTO |
Inappropriate status for issuing the tpdiscon function. |
TPESYSTEM |
An error occurred in the communication resource manager. |
TPEOS |
An error occurred in the operating system. |
- When a signal is received, processing is interrupted and the system call is recalled. TPGOTSIG is not returned. Whether or not TPSIGRSTRT is specified does not affect the calling of system call.
- If a transaction timeout error occurred under OpenTP1, the process terminates abnormally. TPETIME is returned only for a blocking timeout error.
- Unless otherwise specified for X/Open, the error that needs rollback of the transaction under OpenTP1 is TPESYSTEM. Some transactions may not be rolled back if TPESYSTEM is returned.
- If a transaction timeout error occurred under TP1/Client, the CUP execution process terminates abnormally and all the connections established before the timeout error are disconnected. TPETIME is returned only for a blocking timeout error.
- The tpconnect function cannot be issued to TP1/Client. Only the descriptor returned by the tpconnect function can be specified in cd.
- When TPESYSTEM is returned for an error in TP1/Client, error information is output to the error log.
- When TPEOS is returned, insufficient memory is suspected to be the cause. Error information is output to the error log when the error occurred in TP1/Client.
All Rights Reserved. Copyright (C) 2006, 2009, Hitachi, Ltd.