|
|
NetIPC 3000/XL Programmer's Reference Manual: HP 3000 MPE/iX Computer Systems > Chapter 3 NetIPC IntrinsicsIPCRECV |
|
Receives a response to a connection request, thereby completing a connection, or receives data on an existing connection.
The IPCRECV intrinsic serves two purposes: (1) to receive a response to a connection request, thereby completing a connection, and (2) to receive user data on an established connection.
In receiving a response to a connection request, the IPCRECV intrinsic returns nothing in the data buffer. A result value of zero indicates a successful connection establishment. For X.25 only, the facility field and call user data field are returned in the option field. The result parameter will indicate an error if the destination rejected the request. In that case you must still call IPCSHUTDOWN with the returned VC socket descriptor value to shut down the connection. Successful completion of an IPCRECV request on an established connection (result code zero) means that some amount of data was received: the amount requested or the amount transmitted, whichever is smaller. It does not mean that you received all the data you asked for. Completion of IPCRECV (in wait mode) with a non-zero result can mean that a fatal error occurred. If nowait I/O is being used, IPCCHECK must be called to detect a fatal error reported for the specified VC descriptor after IOWAIT has been called and the receive completes. Unless the intrinsic is called in nowait mode, the process is blocked until some data arrive or a timeout occurs. In nowait mode, the addresses of the data, flags and output opt options parameters are retained by NetIPC until needed. The input value of flags is retained and updated (with the "more data" flag off or on) when IOWAIT completes. The data parameter will then contain the data received. Only one nowait receive may be outstanding on a single connection. The returned dlen parameter (or the IOWAIT tcount parameter in the case of a nowait request) shows how many bytes of data were actually received in the data parameter. This amount may be different from what you requested. If you did not receive all the data you want, you can obtain the additional data in a subsequent IPCRECV call. For more information, see the discussion of "Sending and Receiving Data Over a Connection" in Chapter 1 “NetIPC Fundamentals” and the programmatic examples in Chapter 4 “NetIPC Examples” Condition codes returned by this intrinsic are:
This intrinsic can be called in split stack mode. The following Table 3-7 “IPCRECV Protocol Specific Parameters” outlines parameters that are specific to the particular protocol you are accessing. Table 3-7 IPCRECV Protocol Specific Parameters
In receiving a response to a connection request, the option field returns the facility field and the call user data (CUD) field. With fast select, up to 128 bytes of call user data may be returned in the call user data receive buffer (opt 5). A single IPCRECV call returns data for one message only. If the "more data" flag is set, the complete message has not been received. The remaining part of the message can be received by subsequent calls to IPCRECV, unless the destroy flag (29) is set. If the destroy flag is set, the remaining part of the message is destroyed. The end of message is indicated by the "more data" flag not being set. If an interrupt packet is received in the middle of a data packet stream, IPCRECV returns no data. The result parameter indicates that an interrupt event has occurred. The interrupt user data field can be retrieved by calling IPCCONTROL, request 12 (reason for error or event). The next call to IPCRECV returns the whole data message. If a reset packet is received in the middle of a data packet stream, all previously received packets are discarded. IPCRECV returns no data. The result parameter indicates a reset has occurred. Use the IPCCONTROL request 12 (reason for error or event) to retrieve the cause and diagnostic fields for the reset. Common errors returned by IPCRECV in result are:
A complete table of SOCKERRs is include in Appendix C “Error Messages” The urgent data bit indicates that urgent data has been received. Table 3-8 “TCP Urgent and More Data Bit Combinations” demonstrates the meaning of urgent data and more data. Use these bits in combination to determine the status of data received. Table 3-8 TCP Urgent and More Data Bit Combinations
The following are cross-system programming considerations for this intrinsic: Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. Range for the HP 1000 is 1 to 8,000 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. Data wait flag — The HP 1000 IPCRecv call supports a "DATA_WAIT" flag. This flag, when set, specifies that the call will not complete until the amount of data specified by the dlen parameter has been received. This flag is not available on the HP 3000, meaning that the call may complete before all the data is received. However, the HP 3000 IPCRECV supports other flags such as the "more data" and "destroy data" flags. Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. Range for the HP 9000 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. Data wait flag — The HP 9000 IPCRECV call supports a "DATA_WAIT" flag. This flag, when set, specifies that the call will not complete until the amount of data specified by the dlen parameter has been received. This flag is not available on the HP 3000, meaning that the call may complete before all the data is received. However, the HP 3000 IPCRECV supports other flags such as the "more data" and "destroy data" flags. Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. 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 the dlen parameter can be for any IPCRECV call. PC NetIPC has no option array defined in 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. |
|