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 BPX1CLS/BPX4CLS.
- 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 will be 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.