The master socket

The master socket is used to communicate between the transport provider and both the Common INET layer and its own transport driver. It is used mostly for initialization and, potentially, for later dynamic route updates. If the TP ever has to initiate a message to the TD (for instance, due to an asynchronous configuration update), it can do so over the master socket.
  • The master socket is created by the transport provider with the standard socket() C function or the BPX1SOC/BPX4SOC callable service, by specifying AF_INET for the Domain and -1 for the Protocol parameters.

    This builds a session from the TP to the CINET layer.

    The TP address space must be defined to RACF® as a z/OS UNIX user with a UID of 0.

  • The only functions that are used with the master socket are ioctl and close.

    Most of the ioctl command codes that are used with z/OS UNIX are nonstandard, so these ioctls must be issued with the w_ioctl() C function or the BPX1IOC/BPX4IOC callable service.

    The socket can be closed with either close() or BPX1CL0/BPX4CL0.

  • The first thing that flows on the master socket must be an SIOCSETRTTD ioctl to connect the socket to a specific transport driver. This ioctl is also known as the left bookend, signifying the start of TD–TP initialization. On the call, the Argument_length should be specified as 8, and Argument should refer to an 8-byte area in which the TD name is filled in. For more information about the interface to ioctl, refer to vn_ioctl — I/O control.

    The vfs_socket request is issued at this point to the specified TD, which builds the normal socket support between the LFS and PFS, but does not propagate this session to the TP.

    The SIOCSETRTTD command is then passed on to the TD with an ioctl call.

    Note: The TP must know the name of its own TD in order to select it with SIOCSETRTTD. This name was specified with the NAME parameter of the SUBFILESYSTYPE statement that started the TD, and is passed to the TD when it is initialized. There are several ways to make this name known to the TP. It could be a product-specified constant value; the value could be configured into the TP through its externals; the TD could pass the name to the TP if it starts the PC session first; or the TD could store the name with the MVS™ Named Token Services, where the TP would retrieve it.
  • Subsequent ioctls are then sent from the TP to the TD to perform product-specific initialization, as necessary. For instance, these could drive the TD to establish the PC session to the TP. These ioctl calls can specify application-defined commands, or use existing command definitions. The ioctl command values that are used must not conflict with any of the commands that are discussed here, or any that are used by the prerouter.

    These commands pass through z/OS UNIX without any interpretation.

    Note: If the PFS is designed to run directly attached to the LFS, it has already solved the problems of initialization between the TD and TP. This does not have to change when it is attached through CINET. Only the first and last ioctl commands discussed here are required on the master socket.
  • After any product-specific initialization is finished, an IOCC#TCCE ioctl command is sent by the TP to notify CINET that this file system is ready for business. This ioctl command is also known as the right bookend, signifying the end of TD–TP initialization. For this command, no other specific data is required, so the Argument_length can be zero.

    This command is also passed on to the TD.

    At this time, the transport is considered to be active. The prerouter gathers configuration information from the transport and applications that had used the SO_EioIfNewTP socket option receive notification that a new transport is available for use. This notification is performed by failing any socket accept or receive type calls with a return code of EIO, after which the application closes that socket and opens a new socket to pick up the new transport.

    If the transport is not yet ready to accept new socket requests, the notification phase can be delayed. If the argument length for IOCC#TCCE is four bytes and the argument contains a value of one, this signifies a delay and the SO_EioIfNewTP notification phase is skipped. The transport must later send another IOCC#TCCE ioctl command with a value of two to perform just the notification phase.

  • At this point the prerouter will start its conversation with the TD–TP on a separate socket session, see Common INET prerouting function.

Ioctls that flow on the master socket to the TD are never passed through to the TP, because that is where they came from. Some of the ioctl commands are intended only for the Common INET layer, and these are not even passed on to the TD. However, the TD should be coded to ignore the ioctl commands that are intended for the Common INET layer, because when it is connected directly to the LFS it will receive these requests. The TP could also be configured to know how the TD is set up within z/OS UNIX and process accordingly, but this is usually not worth the extra effort and externals.

The master socket is left open for the duration of the transport provider. If this socket is closed, the prerouter assumes that the transport provider has terminated. This socket may also be needed later for dynamic route updates, and it can be used within the TD/TP recovery design. If the TP abnormally terminates, the master socket for it is closed. The TD sees this as a vn_close, at which point it can take whatever recovery actions may be necessary. Thus, a resource manager for the TP and the code to notify the TD are not necessary solely for the purpose of letting the TD know when the TP crashes.

The constants for the various ioctl commands that are used during initialization are defined in BPXYPFSI.