OpenTP1 Version 7 TP1/Client User's Guide TP1/Client/W, TP1/Client/P
(a) _s version of the function
#include <dcvclt.h>
DCLONG dc_clt_assem_send_s(DCCLT_ID cltid, char CLTFAR *buff, DCLONG sendleng,
char CLTFAR *hostname, unsigned short portnum, DCLONG timeout, DCLONG flags)
(b) Non-_s version of the function
#include <dcvclt.h>
DCLONG dc_clt_assem_send(char CLTFAR *buff, DCLONG sendleng, char CLTFAR *hostname,
unsigned short portnum, DCLONG timeout, DCLONG flags)
(2) Purpose
The dc_clt_assem_send_s function uses the message assembly facility to send messages. When this facility is used, the function sends four-byte message information followed by the message body specified in the buff argument. If a connection to the remote system has not been established, the function first establishes the connection according to the values specified in the hostname and portnum arguments.
If Y is specified for DCCLTDELIVERYCHECK of the client environment definition, the function also uses the message delivery confirmation facility. In this case, the size of the message information sent before the message body is 11 bytes. After receiving the 11-byte message information, TP1/Client returns control to the CUP.
Before issuing this function, make sure that you issue the dc_rpc_open_s function in which DCCLT_ONEWAY_SND or DCCLT_SNDRCV is specified for the flags argument.
(3) Arguments set by UAPs
- cltid
Specify the client ID received by the dc_clt_cltin_s function.
- buff
Specify the area that contains the message to be sent. The area must be larger than the length specified in sendleng.
- sendleng
Specify the length of the message to be sent.
- hostname
Specify the host name of the node to be connected if no connection has been established.
If NULL is specified, the function accesses the contents of DCSNDHOST in the client environment definition acquired when the dc_rpc_open_s function was issued.
You can specify a maximum of 63# characters for the host name.
You can also specify an IP address in decimal dot notation for the host name.
- #:
- If you specify 00000008 for DCCLTOPTION in the client environment definition, you can specify a maximum of 255 characters for the host name.
- portnum
Specify the port number of the node to be connected when there is no connection and a connection must be established.
If 0 is specified, the function accesses the contents of DCSNDPORT in the client environment definition acquired when the dc_rpc_open_s function was issued.
- timeout
This argument takes effect when the message delivery confirmation facility is used. Specify the maximum time (in seconds) that the function waits for response-only data to arrive. The value must be an integer from -1 to 65,535.
- If -1 is specified:
- The function waits indefinitely for response-only data.
- If 0 is specified:
- The function does not wait for response-only data. If there is no message to be received, the function returns a DCCLTER_TIMED_OUT error.
- If any value from 1 to 65,535 is specified:
- The function waits for a message, but returns a DCCLTER_TIMED_OUT error if a message does not arrive within the specified number of seconds.
If divided response-only data arrives, the function repeats the receive processing until 11-byte response-only data arrives. The timeout specified by this argument is applied every time the function attempts reception. If you want to use the value of this argument as the maximum response wait time for the client, specify the 00000002 option for DCCLTOPTION of the client environment definition.
- flags
Specify whether to release the connection after sending a message.
- DCNOFLAGS
- After a message is sent, the connection is not released until the dc_rpc_close_s function is issued (exception: an error occurs).
- DCCLT_RCV_CLOSE
- After a message is sent, the connection is released. If the message delivery confirmation facility is being used, the connection is released after message information has been received.
(4) Return values
Return value |
Value (decimal) |
Meaning |
DC_OK |
0 |
Normal termination |
DCCLTER_INVALID_ARGS |
-2501 |
Invalid argument |
DCCLTER_PROTO |
-2502 |
Possible causes are as follows:
- The dc_rpc_open_s function has not been issued.
- The dc_rpc_open_s function was issued but neither DCCLT_ONEWAY_SND nor DCCLT_SNDRCV was specified for the flags argument.
|
DCCLTER_NO_BUFS |
-2504 |
Insufficient memory |
DCCLTER_NET_DOWN |
-2506 |
A network error occurred. The connection is released. |
DCCLTER_TIMED_OUT |
-2507 |
A connection establishment request timed out. Alternatively, reception of response-only data timed out when the message delivery confirmation facility was being used. The connection is released. |
DCCLTER_SYSERR |
-2518 |
A system error occurred. If the error is a network error, the connection is released. |
DCCLTER_RESOURCE |
-2538 |
Insufficient resource |
DCCLTER_WRONG_HOST |
-2539 |
The host name is incorrect. Alternatively, a host name is not specified in either hostname or DCSNDHOST. |
DCCLTER_CONNREFUSED |
-2541 |
A connection establishment request to the remote system was rejected. |
DCCLTER_CONNFREE |
-2542 |
The connection was released by the remote system when the message delivery confirmation facility was being used. |
DCCLTER_INVALID_CLTID |
-2544 |
The client ID specified for cltid differs from the one received by the dc_clt_cltin_s function. |
DCCLTER_PORT_IN_USE |
-2547 |
Port numbers that can be assigned automatically by the operating system are insufficient. |
DCCLTER_INVALID_MESSAGE |
-2548 |
An invalid message was received when the message delivery confirmation facility was being used. The connection is released. |
DCCLTER_COLLISION_MESSAGE |
-2584 |
Messages collided when the message delivery confirmation facility was being used. The connection is released. |
- If the remote system releases the connection when the function sends a message to the remote system, depending on the length of the message, the function might not be able to detect that the connection has been released. The following describes what occurs in this case according to the facility used:
- When the message assembly facility is used:
- If the function fails to detect the release of a connection when it sends a message, a subsequent function might detect the release. This must be kept in mind when a CUP is created.
- When the message delivery confirmation facility is used:
- If the function fails to detect the release of a connection when it sends a message, the function detects the release when it receives response-only data.
- If the message assembly and message delivery confirmation facilities are used, short packets are used for sending and receiving. As a result, transmission processing might take more time. If more time might be required, specify Y for DCCLTTCPNODELAY of the client environment definition.
All Rights Reserved. Copyright (C) 2006, 2009, Hitachi, Ltd.