Internet server application considerations

An Internet server application must conform to one of the process models defined by the Internet Daemon:

WAIT
The WAIT process model is for an Internet server application that is an iterative or single-thread program. The Internet Daemon starts the Internet server application as a child process using the tpf_fork function and does not start any more occurrences of the Internet server application until the one that is running ends.

For TCP servers, the Internet Daemon creates and monitors the listener socket. When a remote client connects, information about the socket that is associated with this client (the connected socket) is passed to the child process. The child process communicates with the remote client over the connected socket. If the child process ends and does not close the connected socket, the z/TPF system closes the connected socket automatically.

For UDP servers, the Internet Daemon creates and monitors the socket. When a message from a remote client is received, the socket is passed to the child process, allowing the child process to exchange data with the remote client.

Use user exit USOC to set socket options for the TCP listener socket or UDP server socket. Use user exit UACC to override socket options on a TCP connected socket.
NOWAIT
The NOWAIT process model is for an Internet server application that is a concurrent or multi-thread program. The Internet Daemon starts the Internet server application as a child process using the tpf_fork function and continues to start more occurrences of the Internet server application until a predefined limit is reached. When the limit is reached, no more occurrences are started until an occurrence that was previously started ends.

For TCP servers, the Internet Daemon creates and monitors the listener socket. When a remote client connects, information about the socket that is associated with this client (the connected socket) is passed to the child process. The child process communicates with the remote client over the connected socket. If the child process ends and does not close the connected socket, the z/TPF system closes the connected socket automatically. If you do not want the socket to be closed when the child process ends, the child process must issue an fcntl function with the O_TPF_NODDCLOSE option on the socket. You must do this when the child process passes the socket to another ECB (for example, using the activate_on_receipt function.)

For UDP servers, the Internet Daemon creates and monitors the socket. When a message from a remote client is received, the socket is passed to the child process, allowing the child process to exchange data with the remote client. The Internet Daemon will not create another child process until the previous child process ends, or until the previous child process sends a SIGUSR1 signal to the Internet Daemon. If child processes do not send SIGUSR1 signals, the NOWAIT model becomes single threaded and has the same characteristics as the WAIT model. If the UDP server application is bound to all local IP addresses and more than one local IP address exists, the child process should not send the SIGUSR1 signal until after the process has sent all its data to the remote client. If a SIGUSR1 signal is sent before all the data is sent, the wrong local IP address can be placed in the packets sent to the remote client, causing that data to be discarded.

Use user exit USOC to set socket options for the TCP listener socket or UDP server socket. Use user exit UACC to override socket options on a TCP connected socket.
AOA
The AOA process model is for an Internet server application that is a concurrent or multithread program, and can be used only for TCP servers, not UDP. The Internet Daemon creates the listener socket and issues the first activate_on_accept function call. When the first connection is received from the remote client, the Internet Daemon passes control to your TCP server application. The server application must issue all subsequent activate_on_accept function calls to accept another connection from the remote client.

Use user exit USOC to set socket options for the TCP listener socket. Use user exit UACC to override socket options on a TCP connected socket.
AOA2
The AOA2 process model is for an Internet server application that is a concurrent or multithread program, and can be used only for TCP servers, not UDP. The Internet Daemon creates the listener socket and issues all activate_on_accept function calls. When the remote client connects, the Internet Daemon activates your TCP server application in a new ECB.

Use user exit USOC to set socket options for the TCP listener socket. Use user exit UACC to override socket options on a TCP connected socket.
SSL
The SSL process model is for an Internet server application that is a concurrent or multithread program. The SSL process model can be used only for TCP servers, not UDP. The Internet Daemon creates and monitors the listener socket and CTX structure, and issues all activate_on_accept function calls. When a remote SSL client connects, the Internet Daemon activates an SSL server application in a new ECB.

Use user exit USSL to perform initialization tasks when the Internet Daemon SSL server is started, and to clean up server tables when the SSL server is stopped. Use user exit USOC to set socket options for the listener socket. Use user exit UACC to override socket options on an SSL connected socket.
AOR
The AOR process model is for an Internet server application that is a concurrent or multithread program. The AOR process model can be used only for TCP servers, not UDP. The Internet Daemon creates and monitors the listener socket. When a remote client connects, the Internet Daemon issues an activate_on_receipt or activate_on_receipt_with_length function to pass control of the new socket to your TCP server application when the first message is received from the remote client.

Use user exit USOC to set socket options for the TCP listener socket. Use user exit UACC to override socket options on a TCP connected socket.
DAEMON
The DAEMON process model is for an Internet server application that is started and monitored by the Internet Daemon. The Internet Daemon starts the Internet server application as a child process by using the tpf_fork function and does not start any more occurrences of the Internet server application until the one that is running ends. The Internet Daemon does not create or monitor any sockets for this process model.

Use the E-type loader recycle interface user Internet server programs user exit (UERA) to specify programs that are part of the Internet server application. If the system activation number changes due to a change in any of these specified program versions, the Internet daemon server application is recycled.
NOLISTEN
The NOLISTEN process model is for an Internet server application that the Internet Daemon only starts. The Internet Daemon does not create or monitor any sockets, nor does it monitor the server application.

Because these process models provide different levels of control, the overhead of system resource can be affected. The AOA, AOA2, SSL, and AOR process models have the potential to use system resources more effectively than the WAIT and NOWAIT process models. The AOR process model uses the activate_on_receipt or activate_on_receipt_with_length function to create the entry control block (ECB) for the Internet server application only after data is received on a connected socket, whereas the WAIT and NOWAIT process models use the tpf_fork function to create an ECB for immediate processing, which requires the Internet server application to request data and then wait for the data to arrive. The AOA, AOA2, and SSL process models use the activate_on_accept function to create the entry control block (ECB) for the Internet server application only after a connection request is received from the remote client. The AOA2 and SSL process models use the Internet Daemon to issue all activate_on_accept function calls.

For the NOWAIT process model, use the MAXPROC parameter in the ZINET ADD or ZINET ALTER command to limit the number of occurrences of an Internet server application that the Internet Daemon starts. For the AOA, AOA2, SSL, and AOR process models, there is no throttling control, so the Internet Daemon can potentially start more occurrences of the Internet server application until system resources are depleted. See z/TPF Operations for more information about the ZINET ADD and ZINET ALTER commands.

In general, a ported Internet server application uses the WAIT or NOWAIT process model and an Internet server application designed specifically for z/TPF architecture uses the AOA, AOA2, SSL, or AOR process model.

When the Internet Daemon is running, there is one long-running ECB for the Internet Daemon monitor program and one long-running ECB for each server application that the Internet Daemon is monitoring. Some E-type loader operations are not completed until all old ECBs exit in the system. When the Internet Daemon detects that the system activation number has changed, the Internet Daemon calls the E-type loader recycle interface for each server application to determine if any server application program versions have changed. If so, the server application is recycled. If not, the E-type loader recycle interface updates the activation number assigned to the long-running ECB for the server application and the activation numbers assigned to all child processes and thread siblings to allow E-type loader functions to complete. The Internet daemon also calls the E-type loader recycle interface to determine if any Internet daemon monitor program versions have changed. If so, the Internet daemon recycles itself.. A new instance of the Internet Daemon is immediately created in new ECBs, and the old Internet Daemon ECBs exit when all their child processes and thread siblings end. When the Internet Daemon recycles, the effect on the server application and sockets is based on the process model:

For the WAIT, NOWAIT, AOA, AOA2, SSL, and AOR process models, there is no disruption to the sockets. The fact that the Internet Daemon has recycled itself is completely transparent to the server and remote client applications.
For the NOLISTEN process model, no action is taken when the Internet Daemon recycles. Servers using these models are activated when the Internet Daemon first starts and, after that, the Internet Daemon does not monitor those applications.
For the DAEMON process model, the Internet Daemon issues a kill function to stop the old application server instance. The new instance of the Internet Daemon starts a new server application instance as soon as the old server instance ends. The Internet Daemon does not create or monitor sockets for this process model; therefore, your application must take the appropriate actions regarding any sockets that it created. A common implementation is for the old server application to close the sockets and have the new server application instance start new sockets. Another method is to keep the sockets active by having the old server application instance save the socket descriptors in a user table that the new server application instance picks up and uses.

If no Internet daemon monitor program versions have changed, the E-type loader recycle interface updates the activation number assigned to the Internet daemon monitor ECB and the activation number assigned to all child processes and thread siblings to allow E-type loader functions to complete.

When you enter the ZINET STOP command to stop a server application, the actions that are taken are based on the process model:

For a TCP server using the WAIT, NOWAIT, AOA, AOA2, SSL, or AOR process model, the listener socket is closed and no new connections can be started with this server. Existing connections (sockets) between remote clients and this server are allowed to continue their normal processing. If you want to break the existing connections that use TCP/IP native stack support, enter ZSOCK INACT LPORT-lport, where lport is the port number of the TCP server application.
For a UDP server using the WAIT or NOWAIT process model, the socket is closed.
For the NOLISTEN process model, no action is taken because the Internet Daemon does not monitor these process models.
For the DAEMON process model, the Internet Daemon issues a kill function to stop the application server. When using this process model, ensure that your Internet server application uses the signal function to enable the SIGTERM signal.

See z/TPF Operations for more information about the ZINET STOP and ZSOCK commands.