OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/W, TP1/Client/P
(a) TP1/Client/W
#include <dcvxatmi.h>
DCLONG tpconnect(char *svc, char *data, DCLONG len,
DCLONG flags)
(b) TP1/Client/P
#include <dcvxatmi.h>
DCLONG tpconnect(char CLTFAR *svc, char CLTFAR *data,
DCLONG len, DCLONG flags)
(2) Purpose
Establishes half-duplex connection between TP1/Client and an interactive service. When the function is processed normally, the descriptor that specifies the connection is returned.
The issuer of the tpconnect function can pass the specified information to the service function to the receiver during establishment of connection. To pass information, the pointer to the buffer allocated by the tpalloc function must be specified in data, and the data length to send must be specified in len.
The tpconnect function allows information to be received under the interactive service without issuing the function for receiving data.
(3) Arguments set by UAPs
- svc
Specify the service name of the service to request.
- data
Specify X_OCTET as the pointer to the typed buffer that contains send data.
- len
Specify the length of data to be sent. The maximum length is 500 x 1024 bytes. Set 0 when the length need not be specified. Do not set 0 for the buffer whose length must be specified.
- flags
Specify any of the following.
- TPNOTRAN
- When the issuer of the function is in the transaction mode, the started service does not belong to the issuer's transaction.
- Be sure to specify TPNOTRAN when the issuer of the function in the transaction mode requests the service that belongs to the server unavailable for transaction processing.
- When the issuer of the function is in the transaction mode, a transaction timeout error may occur even if TPNOTRAN is specified.
- Failure in the service started with TPNOTRAN will not affect the issuer's transaction.
- TPSENDONLY
- Connection is established first so that the issuer can send data and the service called by the function can only receive data. The called service first gains control of connection.
- TPRECVONLY
- Connection is established first so that the issuer can receive data and the service called by the function can only send data. The called service first gains control of connection.
- Either TPSENDONLY or TPRECVONLY must be specified.
- TPNOBLOCK
- When the blocking status occurs (e.g., the internal buffer is filled with messages sent), neither connection is established nor data is sent.
- If the blocking status occurs with TPNOBLOCK not specified, the issuer remains blocked until the cause of blocking is removed or a transaction or blocking timeout error occurs.
- TPNOTIME
- The issuer is infinitely blocked to prevent blocking timeout error.
- Transaction timeout error may occur even if TPNOTIME is specified.
- TPSIGRSTRT
- System call interrupted by a signal during execution is recalled.
(4) Return values
When the processing completes successfully, the tpconnect function returns a descriptor to specify the established connection. If an error occurs, the 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 |
TPENOENT |
Since the value specified in the argument is not defined in the system, connection cannot be established. |
TPEITYPE |
The value specified in the argument cannot be used in the specified service. |
TPELIMIT |
Since the number of unsolved connections reached to the limit, the request from the caller is not sent. |
TPETRAN |
The specified service belongs to the server unavailable for transaction processing, but TPNOTRAN is not specified. |
TPETIME |
A timeout error occurred.
- For the issuer in the transaction mode:
A transaction timeout error occurred. The process terminates abnormally. The transaction is rolled back. TPETIME is returned to any message sent or received by any connection until rollback is completed.
- For the issuer in other than the transaction mode:
A blocking timeout error occurred where neither TPNOBLOCK nor TPNOTIME is specified.
|
TPEBLOCK |
Blocking status occurred when the tpconnect function was issued with TPNOBLOCK specified. |
TPGOTSIG |
The signal is received, but TPSIGRSTRT is not specified. |
TPEPROTO |
Inappropriate status for issuing the tpconnect function. |
TPESYSTEM |
An error occurred in the communication resource manager. |
TPEOS |
An error occurred in the operating system. |
- When communication is disabled due to the blocking status under OpenTP1, TPESYSTEM is returned as well as for communication disabled due to network failure.
- When information unavailable to the service is specified under OpenTP1, TPESYSTEM is returned. When the issuer of the function is in the transaction mode, the transaction is rolled back.
- 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.
- When the service request is not authenticated under the OpenTP1 security facility, TPEPROTO is returned. Check the detailed error code of the UAP trace to find the cause of the error.
- TP1/Client cannot issue the tpconnect function in a transaction unless permanent connection has been established with the facility of establishing permanent connection.
- 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 blocking timeout error.
- 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. Error information is output to the error log when the error occurred in TP1/Client.
All Rights Reserved. Copyright (C) 2006, 2009, Hitachi, Ltd.