gtpc1m3j | Transmission Control Protocol/Internet Protocol |
The activate_on_receipt function allows the issuing ECB to exit
and activate a different ECB at the program specified after information has
been received.
Format
#include <socket.h>
int activate_on_receipt(unsigned int s,
unsigned char *parm,
unsigned char *pgm);
- s
- The socket descriptor.
- parm
- A pointer to an 8-byte field. The data in this field is saved and
passed to a new ECB starting at EBW004. This new ECB is created after
information has been received.
- pgm
- A pointer to a 4-byte field that contains the name of the TPF real-time
program to be activated after information has been received.
Normal Return
Return code 0 indicates that the function was successful.
Error Return
Return code -1 indicates an error. You can get the specific
error code by calling sock_errno. See Appendix C, Socket Error Return Codes for more information about socket errors.
- Note:
- Unless otherwise stated in the description, the following error codes can be
returned for either TCP/IP offload support or TCP/IP native stack
support.
- Value
- Description
- SOCNOTSOCK
- The s parameter is not a valid socket descriptor.
- E1052STATE
- The socket was closed because the system was in or cycling down to 1052
state.
- EINACT
- All offload devices associated with the socket descriptor have been
disconnected. The socket is closed. This error code is returned
only for TCP/IP offload support.
- EINACTWS
- An offload device associated with the socket descriptor has been
disconnected. The socket is still available. This error code is
returned only for TCP/IP offload support.
- ESYSTEMERROR
- The system closed the socket because pgm is a program name that
does not exist.
- SOCNOBUFS
- There is not enough buffer space to issue the function call. This
error code is returned only for TCP/IP offload support.
- SOCNOTCONN
- The s socket is a stream socket, but the socket is not
connected.
- SOCINVAL
- The listen function was not called for socket s or
the read, recv, or recvfrom function is
already pending for socket s.
- EIBMIUCVERR
- The activate_on_receipt function was not successful because an
error occurred when the message was sent to the offload device. This
error code is returned only for TCP/IP offload support.
- SOCTIMEDOUT
- The operation timed out. The socket is still available. This
error code is returned only for TCP/IP native stack support.
Programming Considerations
- This unique TPF API function can be issued instead of the read,
recv, or recvfrom function. When the information
arrives, TPF socket support creates a new ECB and activates the program
specified by the pgm parameter.
- If TCP/IP activate on receipt load balancing (set by the AOR_BALANCE
option of the ioctl function) is set on, the ECB is created on the
least busy I-stream. If load balancing is set off, the ECB is created
on the I-stream of the ECB that issued the activate_on_receipt
function.
- When the program specified by the pgm parameter is activated,
the socket descriptor is passed in the 3 bytes at the EBROUT label in the ECB,
and the address and length of the data that has been received is passed in the
ECB work area fields EBW012-EBW019. The program must then issue a
read or recv socket API function for stream sockets or a
recvfrom socket API function for datagram sockets to receive the
data.
- When receiving the data, the program can either use the address passed to
it in the ECB work area or provide its own storage area to obtain the
data. The length specified in the read, recvfrom,
or recv function must equal the value passed to it in the ECB work
area. If the value specified in the read, recv,
or recvfrom function is less than the value in the ECB work area,
the message is truncated. If the application program activated supplies
its own buffer to read the data, the system buffer address in
EBW012-EBW015 is released on the ensuing read,
recv, or recvfrom function. The
MSG_OOB and MSG_PEEK flags cannot be used for the
subsequent recv or recvfrom function.
- Starting at EBW000, data is passed to the program specified by the
pgm parameter in the following format:
ECB Equates
| Length
| Description
|
EBW000
| 4
| Contains the name of the program specified by the pgm
parameter. For system use only.
|
EBW004
| 8
| The data passed by the original ECB pointed to by parm.
|
EBW012
| 4
| The address of the data that was received.
|
EBW016
| 4
| Length of the data that has been received by the system and should be
received by the application.
|
EBW020
| 16
| If a datagram socket was used, this field will contain the source address
of the message.
|
- Note:
- Information returned from an activate_on_receipt function is only
returned to the program specified in the activate_on_receipt
function; it is not returned to the program that issued the
activate_on_receipt.
- If EBW012-EBW019 is equal to zero, the
activate_on_receipt function was issued on a socket that is shut
down or closed. If EBW012-EBW015 is equal to 0 and
EBW016-EBW019 is equal to -1, the activate_on_receipt
function resulted in an error return from the TCP/IP offload device.
For both conditions, the application program that was activated must still
issue a read, recvfrom, or recv socket API
function to enable socket API support to complete the processing of the
activate_on_receipt function.
- If the return code is -1, the ECB is still connected to the
program. However, because it indicates a serious error, the ECB cannot
issue any more socket API functions for this socket but can issue socket API
functions for other sockets.
- For sockets using TCP/IP native stack support, the receive timeout value
(the SO_RCVTIMEO setsockopt option) determines how long to wait for
data to be received before the activate_on_receipt function times
out.
- For TCP sockets using TCP/IP native stack support, the receive low-water
mark (the SO_RCVLOWAT setsockopt option) determines the minimum
amount of data that must be received before the activate_on_receipt
function is completed. If the activate_on_receipt function
times out, any data that was received is returned to the application even if
the amount of data received is less than the receive low-water mark
value.
- The activate_on_receipt function cannot be issued if an
activate_on_receipt_with_length, read, recv,
or recvfrom call is pending for the socket. These operations
are mutually exclusive.
- For both TCP/IP offload support and TCP/IP native stack support, the
activate_on_receipt function cannot be issued if another
activate_on_receipt call is pending for this socket.
Examples
After accepting a connection from a new client, an
activate_on_receipt function is issued so that
server_sock can accept the next client request.
#include <types.h>
#include <socket.h>
·
·
·
int newclient_sock;
int server_sock;
u_char aorparm[8];
u_char aorpgm[4] = "abcd";
·
·
·
for(;;)
{
newclient_sock = accept(server_sock,(struct sockaddr *)0,(int)0);
·
·
·
/* No parameters will be passed to the new ECB */
memset(aorparm,0,sizeof(aorparm));
rc = activate_on_receipt(newclient_sock,aorparm,aorpgm);
·
·
·
}
Related Information