gtpc1m3k | Transmission Control Protocol/Internet Protocol |
The activate_on_receipt_with_length function allows the issuing
entry control block (ECB) to exit and activate a different ECB at the program
specified after information with a specified length has been received.
Format
#include <socket.h>
int activate_on_receipt_with_length(unsigned int s,
unsigned char *parm,
unsigned char *pgm,
unsigned int len);
- 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.
- len
- The length of data to be read before giving control to the new ECB.
Normal Return
Return code 0 indicates that the function was successful.
Error Return
A return code equal to -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
- A system error has occurred and closed the socket.
- 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.
- EIBMIUCVERR
- The activate_on_receipt_with_length 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 application programming interface (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_with_length 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.
- The number of bytes received (in EBW016) will be as many as the number of
bytes of data specified by the len parameter. If fewer than
the number of bytes requested is available, the function returns the number
currently available.
- 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 that is 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 the parm
parameter.
|
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_with_length
function is only returned to the program specified in the
activate_on_receipt_with_length function; it is not returned
to the program that issued the activate_on_receipt_with_length
function.
- If EBW012-EBW019 is equal to zero, the
activate_on_receipt_with_length 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_with_length 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_with_length 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_with_length
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_with_length function is completed. If
the activate_on_receipt_with_length 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_with_length function cannot be issued
if an activate_on_receipt, read, recv, or
recvfrom call is pending for the socket. These operations
are mutually exclusive.
- The activate_on_receipt_with_length function cannot be issued
if another activate_on_receipt_with_length call is already pending
for this socket.
Examples
After accepting a connection from a new client, an
activate_on_receipt_with_length 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;
int aor_len = 4;
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));
/* read 1st 4 bytes of message. This can be useful, for */
/* example, if the application puts the message length in the */
/* first 4 bytes of message. The aor will read the 1st 4 */
/* bytes to get the message length, then issue subsequent */
/* reads for the rest of the data. */
rc = activate_on_receipt_with_length(newclient_sock,aorparm,aorpgm,aor_len);
·
·
·
}
Related Information