activate_on_receipt: Activate a program after data received

The activate_on_receipt socket function allows the issuing ECB to exit and activate a different ECB at the program specified after information has been received.

Last updated

Changed for PUT15 (information only; no code change).
Changed for PUT14.
Changed for PUT06.
Added for PUT00.

Format

#include <sys/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 z/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. For more information about socket errors, see Socket error return codes.

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.
ESYSTEMERROR: The system closed the socket because pgm is a program name that does not exist.
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 activate_on_receipt, activate_on_receipt_with_length, activate_on_receipt_of_TCP_message, read, recv, recvfrom, or tpf_read_TCP_message function is already pending for socket s. This error also is returned if the activate_on_receipt function is called for a UNIX domain socket.
SOCTIMEDOUT: The operation timed out. The socket is still available.

Programming considerations

This unique z/TPF API function can be issued instead of the read, recv, or recvfrom function. When the information arrives, z/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 tightly coupled scheduler selects which I-stream to create the ECB on. 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, the address of the data that has been received is passed in the ECB work area fields EBW024-EBW031, and the length of the data is passed in the ECB work area fields EBW016-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 maximum amount of data that can be received after using the activate_on_receipt function is 65535 bytes and the maximum amount of data that can be received after using the activate_on_receipt_with_length function is 1048576 bytes.
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. To avoid copying the data to another buffer, the application can specify the system buffer address that was passed in the ECB work area by the activate_on_receipt function. If the application program activated supplies its own buffer to read the data, the system buffer address in EBW024–EBW031 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.
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.
The activate_on_receipt_with_length function can be used to specify a maximum length to read.

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 pgm.
EBW016	4	Length of the data that has been received by the system and should be received by the application.
EBW020	4	If a datagram socket was used, this field will contain the source address of the message.
EBW024	8	The address of the data that was received.

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 EBW016–EBW019 and EBW024–EBW031 are equal to zero and the socket is TCP, the activate_on_receipt function was issued on a socket that is shut down or closed. If EBW024–EBW031 is equal to 0 and EBW016–EBW019 is equal to -1, the activate_on_receipt function resulted in an error. 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.
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.
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, activate_on_receipt_with_length, activate_on_receipt_of_TCP_message, read, recv, recvfrom, or tpf_read_TCP_message call is pending for the socket. These operations are mutually exclusive.
For UDP sockets, zero length messages can be received on the 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 <sys/types.h>
#include <sys/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

See z/TPF Transmission Control Protocol/Internet Protocol for information about z/TPF TCP/IP support.