IPCSEND

Sends data on a connection.

Syntax

IPCSEND  (vcdesc,data,dlen[,flags][,opt],result)

Parameters

vcdesc (input)

32-bit integer, by value. The VC socket descriptor, a number identifying the VC socket belonging to this process through which the data will be sent.

data (input)

Record or byte array, by reference. Contains the data to be sent or a list of data descriptors (maximum of two) indicating the locations from which the data will be gathered. If data descriptors are used, flags [31] must be set to indicate vectored sends. For programming in "C" language, see Appendix E “C Program Language Considerations”

dlen (input)

32-bit integer, by value. The byte length of the data parameter: that is, the amount of actual data (maximum of 30,000) or the combined length of the data descriptors. The data descriptor length is 8 for compatibility mode and 12 for native mode. The combined length is 16 for compatibility mode and 24 for native mode.

flags (input)

32 bits, by reference. A bit representation of various options. The only flag defined is:

flags [31] — vectored input. Indicates that the data to be sent are to be gathered from the addresses specified in the data parameter. (The parameter will not contain actual data.)

opt (input)

Record or byte array, by reference. A list of options, with associated information. Refer to "Common Parameters" for more information on the structure of this parameter. The following options are defined:

data offset (code=8, length=2; 2-byte integer) (input). Compatibility mode (CM) only. An offset in bytes from the data parameter's address indicating the actual beginning of the data. HP recommends that you do not use data offset if data descriptors are used to point to another location from which data should be obtained.
protocol flags (code=144, length=4; 4-byte buffer) (input). This option contains 32 bits of protocol-specific flags. The following flag is currently defined:
- end-to-end acknowledgment (bit 18, input). (X.25 only.) D bit will be set in the last X.25 data packet corresponding to this message. When this flag is set, IPCSEND waits to complete until acknowledgment from the remote that the complete message has been received. When the connection is between two HP 3000's running NS X.25, the acknowledgment is made when the remote IPC user has received the data.
- qualifier bit (bit 19, input). (X.25 only.) This flag indicates to X.25 to set the Q bit in the packets that contain this message.
- urgent data (bit 27, input). (TCP only). If set, this bit will cause the data sent to be marked urgent.

result (output)

32-bit integer, by reference. The error code returned; zero if no error.




	NOTE: When nowait I/O is used, the `result` parameter is not updated upon completion of `IOWAIT`. Therefore, the value of `result` will indicate only whether the call was successfully initiated. To determine whether the call completed successfully, you can use the `IPCCHECK` intrinsic after `IOWAIT` completes.

Description

The IPCSEND intrinsic is used to send data on a connection. The only required parameters are vcdesc, data, and dlen (option variable).

A set of addresses in the data parameter allows vectored data to be gathered from multiple locations.

The value specified for the data offset option (compatibility mode only) is relative to the data array. If data descriptors are used, specifying this option will cause a portion of the descriptor to be passed over (the offset is NOT applied to the pointer in the descriptor). This may lead to unexpected results.

If this intrinsic is called in nowait mode, the address of the data is passed to the TCP protocol module. The contents of the data buffer will have been read when IOWAIT completes. As many as 7 nowait sends may be outstanding on a connection.

Condition codes returned by IPCSEND and IOWAIT are:

CCE — Succeeded.
CCL — Failed.
CCG — Not returned.

This intrinsic can be called in split stack mode.

Protocol-Specific Considerations

The following Table 3-10 “IPCSEND Protocol Specific Parameters” outlines parameters that are specific to the particular protocol you are accessing.

Table 3-10 IPCSEND Protocol Specific Parameters

Parameters		TCP	X.25
opt
	144	Bit 27: urgent data	Bit 18: state of D bit in X.25 packets
			Bit 19: state of Q bit in X.25 packets

X.25 Considerations

Setting the Q bit flag causes X.25 to set the Q bit (qualifier bit) in X.25 data packets.

Setting the D bit flag causes X.25 to specify end-to-end acknowledgment of data packets. IPCSEND does not complete until it receives acknowledgment that the message has been received.

Common errors returned by IPCSHUTDOWN in result are:

SOCKERR   0  Request completed successfully.
SOCKERR  50  Invalid data length.
SOCKERR  65  Connection aborted by local protocol
             module.
SOCKERR  67  Connection failure detected.
SOCKERR 107  Transport is going down.
SOCKERR 159  Invalid X.25 D-bit setting.
SOCKERR 160  Incompatible with protocol state.

A complete table of SOCKERRs is included in Appendix C “Error Messages”

TCP

The urgent data bit of the protocol flags option (opt parameter) is used to inform TCP that the data to be sent should be marked urgent. This will not cause the data to be delivered out of band, and the receiver of this data will not know of urgent data that is pending until a receive is posted.

Cross-System Considerations For TCP

The following are cross-system programming considerations for this intrinsic:

HP 3000 to HP 1000:

Send size — The HP 3000 send size range is 1 to 30,000 bytes. The HP 1000 send size is 1 to 32,767 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

Note that the urgent data bit is not supported on the HP 1000; however, if this bit is set by the HP 3000 program, it will be ignored by the receiving process on the HP 1000.

HP 3000 to HP 9000:

Send size — The HP 3000 send size range is 1 to 30,000 bytes. The HP 9000 send size is 1 to 32,767 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

Note that the urgent data bit is not supported on the HP 9000; however, if this bit is set by the HP 3000 program, it will be ignored by the receiving process on the HP 9000. For differences in send and receive sizes see the discussion for IPCRECVCN.

HP 3000 to PC NetIPC:

Send size — The PC send and receive size range is 1 to 65,535 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

On the PC, you can specify the maximum receive size of the data buffer through the got array in the IPCCONNECT call. This determines what the maximum value for dlen can be for any IPCRECV call. PC NetIPC has no option array defined for IPCCONNECT. This does not affect cross-system communication. The maximum receive size of the data in the buffer on the HP 3000 will determine the receive size buffer on the PC.