previous next top contents index framed top this page unframed
A.1. Formats of the XIDAK Services Table
The server/client implementation currently depends on the
availability of a file describing the services available on each host
and the protocol(s) by which each service can be accessed.
This file is called the “services table”.
The need to maintain services tables may eventually be replaced by a XIDAK name server. When this happens, a program interface will be supplied to update the services table throughout a local network.
The services table can have one of two formats. The xidakservices format is the newer and more flexible of the two; the older format is called mslhosts. The use of xidakservices is recommended over mslhosts, but it is possible to use either one (but not both simultaneously).
xidakservices is easier to use than mslhosts because:
A comparison between mslhosts and xidakservices:
| mslhosts | xidakservices | |
|---|---|---|
| File Name | mslhosts | xidakservices |
| File Contents | host names, host protocols, host/service/protocol |
(see below) |
| MAINEX ENTER | (service protocol table) | (xidak services) |
| C Name | $SERVICESDIR/mslhosts | $SERVICESDIR/xidakservices |
and the file referred to by the ENTER exists,
then the xidakservices
file is used, even if there is also
an entry for the mslhosts file.
From C, if the file $SERVICESDIR/xidakservices
exists, it is assumed
to be in the xidakservices format, and it is used in preference to
the mslhosts file, if a mslhosts file also exists.
To use the mslhosts format of services table from MAINSAIL,
make sure that your MAINSAIL bootstrap or site.cmd
file has a MAINEX ENTER subcommand for:
and that the mslhosts file exists, but either that there does not
exist an ENTER for:
or that the file to which the ENTER refers does not exist.
To use mslhosts from C, make sure that the file
$SERVICESDIR/xidakservices does not exist.
A sample xidakservices file appears in Figure A–1.
Figure A–1. Sample xidakservices File
When a client requests connection to a service, the client's network
protocols are compared with the service's protocols to find a match.
The only valid MAINSAIL protocol MODULE name currently supported
is TCP.
If a DEFAULTPROTOCOL entry is supplied, then HOSTPROTOCOL
entries may
be omitted if they would be identical to the DEFAULTPROTOCOL entry.
In the increasingly common case where all hosts use the same single
network protocol (e.g., TCP), it is most convenient to supply a
DEFAULTPROTOCOL entry.
In the SERVICE entry, omitting the host name is the same as making
the entry for every host. An explicit host name and service name
makes the entry for a single host. The two kinds of entries can be
combined in a single file, but there can be only one entry for a
given explicit host:service
combination (not currently enforced).
The optional SUPPORTS clause is relevant to the MAINSAIL RPC
mechanism and is currently advisory only. It specifies that the
service is an RPC service that supports the listed remote MODULEs.
This information (obtained by calling the PROCEDURE
$getRemoteModules) may optionally be used by the server
program to decide which remote MODULEs to register, or by
applications to display the appropriate servers to which a
connection makes sense. The RPC mechanism itself does not
currently use or enforce the information in the SUPPORTS clause.
The WITH clause introduces property keywords that stored along with
each service and need not match predefined names. Each service can
inquire about its associated properties and attach meanings to them.
Using properties, an application can figure out which servers
it can talk to according to the values of the property for each
server in xidakservices. Although XIDAK considered defining a
standard keyword to indicate the RPC protocol being used, this value
could not be used by the RPC mechanism in any way, since the program
is responsible for making the connection on the client side.
If the VIA clause is omitted, the default is all the network
protocols supported on that host.
Typically, you will add an ENTER subcommand for this logical file
name to the MAINSAIL startup command file site.cmd (located in the
MAINSAIL directory) for any machine where a server or client program
is to be run.
Generally, on UNIX, the logical name will expand to
$SERVICESDIR/xidakservices, i.e.:
A typical mslhosts file is shown in
Example A–2.
Example A–2. Typical mslhosts File
The commands in the mslhosts file are described below.
A.1.1. Choosing Which Format of Services Table to Use
From MAINSAIL, if a MAINEX ENTER subcommand has been issued for
the logical name:
(xidak services)
(service protocol table)
(xidak services)
A.1.2. The xidakservices File Format
The file in which the xidakservices table is stored is normally
called xidakservices.
A.1.2.1. The Syntax of the file xidakservices
The following is a BNF grammar of the syntax for the contents of
xidakservices:
xidakservices
::= entryLine*
entryLine
::= XIDAKSERVICES xidakServicesVersion
::= SERVICE [hostName:]serviceName
[SUPPORTS remoteModuleNames]
[WITH propertySpec*]
[VIA networkProtocols]
::= HOSTPROTOCOL hostName networkProtocols
::= DEFAULTPROTOCOL networkProtocols
remoteModuleNames
::= remoteModuleName remoteModuleName*
remoteModuleName
::= MAINSAIL RPC Module Name
networkProtocols
::= networkProtocol networkProtocol*
networkProtocol
::= MAINSAIL Protocol MODULE Name
propertySpec
::= property = value
::= property = quote value quote
quote
::= '
::= "
xidakServicesVersion ::= number
serviceName ::= name
hostName ::= name
property ::= name
# Sample xidakservices file
XIDAKSERVICES 1
DEFAULTPROTOCOL TCP
# Services potentially available on all hosts
SERVICE gensrv SUPPORTS prosrv strsrv
# Services specific to a particular host
SERVICE rhea:xidak SUPPORTS tdbmod WITH HOMEDIRECTORY=/usr2/xidak
SERVICE rhea:ucrex SUPPORTS tdbmod WITH HOMEDIRECTORY=/usr2/ucrex
SERVICE atal:tst SUPPORTS ads tdbmod WITH HOMEDIRECTORY=/usr/tst
A.1.2.2. Semantics of the xidakservices Commands
Host names must be recognized as an alias for the host on all
relevant networks. Generally, the official host should be used.
Host numbers (Internet-style n.n.n.n...)
are allowed.
A.1.2.3. Logical File Name for xidakservices
To use the xidakservices facility, MAINSAIL programs must set up
a logical file name (e.g.,
with the MAINEX ENTER subcommand) for:
(xidak services)
ENTER (xidak services) $SERVICESDIR/xidakservices
A.1.3. The mslhosts File Format
To use the mslhosts file format from MAINSAIL,
the logical file name (service protocol table) must be defined,
typically with a MAINEX ENTER subcommand in the
site.cmd command file for each MAINSAIL installation.
HOSTNAME Apollo apollo s
HOSTNAME Poseidon poseidon p
HOSTPROTOCOL Apollo tcp
HOSTPROTOCOL Poseidon tcp
SERVICE gensrv Apollo/tcp Poseidon/tcp
SERVICE srv Poseidon/tcp
SERVICE ucrsrv Apollo/tcp
DEFAULTPROTOCOL tcp
A.1.3.1. MYHOST hostName
The MYHOST entry, not shown in Example A–2,
specifies the name of the host node
under which MAINSAIL is running. This entry is needed only on systems
that do not provide a system call that returns the current host's name
(all systems for which STREAMS is currently implemented do provide
such a call).
It should be omitted when possible,
since leaving it out allows the same
table to be shared among several hosts.
A.1.3.2. HOSTNAME officialName alias1
alias2 ... aliasn
The HOSTNAME entry declares a host
that is directly accessible from
the current system by some network protocol. There must be one
HOSTNAME
entry for each host on which a server is to run.
If there is no DEFAULTPROTOCOL entry, then there must also be
a HOSTNAME (and HOSTPROTOCOL)
entry for each host on which a client program is to run.
The first name is the “official” or canonical name by which that host is known, and the remaining names are acceptable aliases for the official name.
In general, it does not matter whether the hosts you specify
in the mslhosts file are actually attached to the network at
the time the entries are added. It does no harm to have entries
for nonexistent nodes or services, provided that you do not try
to access them; if you attempt to access something nonexistent,
an error results.
A.1.3.3. HOSTPROTOCOL hostName protocol1
protocol2 ... protocoln
By default, the
network protocols through which services on
each host may be accessed are assumed to be those given by the
DEFAULTPROTOCOL entry.
If no DEFAULTPROTOCOL entry is present, or if a given host's
protocols are different from the defaults,
then that host must have
a HOSTPROTOCOL entry
to describe the protocols it supports.
The protocols are valid STREAMS protocol MODULEs by which the access is made. Generally these names match the network methodology (e.g., TCP for TCP/IP). The list should be ordered by preference, with the most preferred method listed first.
Each client program must know what protocol to use in order to access a service. If a HOSTPROTOCOL entry is provided for both client and server nodes, then the first matching protocol from the two lists is chosen (it is not specified whether the protocol list for the server or the client is searched first). Otherwise, if no HOSTPROTOCOL entry is available, but there is a DEFAULTPROTOCOL entry, then a default protocol is used (if the server node supports one of the default protocols). If there is neither a HOSTPROTOCOL entry nor a DEFAULTPROTOCOL entry, then it is an error. It is also an error if the server and client have no protocols in common.
Available network protocol MODULEs are listed in
Appendix B.
A.1.3.4. SERVICE serviceName
hostName/protocol ...
For each service that is to be accessed or provided by a MAINSAIL
program, there must be a SERVICE entry. This entry specifies that
the named service (e.g., gensrv, ucrsrv)
is available on the named hosts
under the specified network protocols (the hosts and protocols are
associated in pairs).
A.1.3.5. DEFAULTPROTOCOL protocol1
protocol2 ... protocoln
The DEFAULTPROTOCOL
entry lists the default network protocols to try if
the host is not explicitly declared. This entry is optional;
see Section A.1.3.3.
A.1.4. Creating a mslhosts File
The minimal mslhosts file required to have general access
between hosts A and B is shown in Example A–3.
This example
assumes that the TCP protocol is being used. Other protocols may be
appropriate, and more than one protocol may be supplied for a host or
service on a host.
Example A–3. Minimal General mslhosts File between Hosts A and B
| HOSTNAME A HOSTNAME B HOSTPROTOCOL A tcp HOSTPROTOCOL B tcp SERVICE gensrv A/tcp B/tcp |
A.1.4.1. Adding ENTER Subcommands to the MAINSAIL Site-Specific
Startup Command File (site.cmd)
The mslhosts file is accessed by MAINSAIL through the logical
file name (service protocol table). An ENTER subcommand
for this logical name
must be made, e.g.,
in the MAINSAIL startup command file site.cmd, on
all MAINSAIL installations that are to be servers or clients, as shown
in Example A–4.
A.2.1. UNIX Services Table
Under BSD UNIX, the file /etc/services must
contain an entry similar to the one shown in Example A–5
for each service.
The server name gensrv is used in this example; you must
do something similar for any other server you install (but be
sure to choose a unique port number for each server).
The line shown in Example A–5 tells the host system that the gensrv server is available under port number 2047 using TCP (note that this kind of port, a TCP port, is not the same thing as a MAINSAIL port as represented by a $port record). You may have to choose a different number if 2047 is already used as a local service, but be sure to choose the same number on each system of the network. The number may be chosen arbitrarily within the constraints on TCP port numbers; check your operating system documentation for details.
The unregistered server mechanism requires that there be a directory (called the “services directory”) that can be accessed from both client and server. Server programs must have read and write access to the services directory; client programs need only read access to the services directory.
In both servers and MAINSAIL clients, there must be a $stringGlobalSymbol record in the global symbol table that defines the symbol:
servicesDirectory
as the name of the services directory. This $stringGlobalSymbol entry can be set up using the MAINEX GLOBALSYMBOL command, e.g., in a MAINSAIL bootstrap or site.cmd file. For example, if the services directory at your site is to be called /mars/servicesDir, you could add the following line to your site.cmd file:
GLOBALSYMBOL servicesDirectory /mars/servicesDir
Note that the global symbol name is case-sensitive; the identifier servicesDirectory must be entered exactly as shown.
For C clients on UNIX, the environment variable SERVICESDIR must be set to the name of the services directory before the C client is run. For example, you could use the C shell command:
setenv SERVICESDIR /mars/servicesDir
to make a C client uses the same services directory as shown for the MAINSAIL client above.
Once this directory has been set up and servers have write access to it, then whenever a server does a $bindService and discovers that its name is not registered with the operating system, it creates a file (the “service file”) on the services directory. The file name is based on the name of the service being bound. The service file contains the host and TCP port number on which the service is to be accessed. When a client starts up and attempts to connect to a service and finds that the service is not registered with the operating system, it looks in the services directory for the service's service file; if it finds it, it connects to the host/port combination given in the file.
When a server does an $unbindService, it deletes the service file, so that clients can no longer find the service.
Warning: Race conditions can occur when unregistered servers are used. For example, if the node on which a server is running crashes, the server's service file is not deleted. This makes it appear to clients that the server is running, when in fact it is not (unless it is restarted). Clients may therefore hang for a few minutes when attempting to connect to the nonexistent service. Furthermore, if, in the meantime, another server is started and takes the port that was being used by the old server (and is still recorded in the old server's invalid service file), a client may be connected to the wrong server.
For most reliable operation,
registered servers are recommended instead
of unregistered servers.
However, for experimentation and during prototyping, the ease of
creating a new unregistered server may outweigh the drawbacks of
unregistered servers.
Under BSD UNIX, for example,
the file /etc/rc.local may be edited to
start gensrv as a local demon by adding lines as shown in
Example A–6. This example assumes that MAINSAIL resides in
the directory /usr/mainsail.
The entry in /etc/rc.local causes
gensrv
to be started automatically whenever the computer system is booted.
Example A–6. Starting gensrv Automatically under BSD UNIX
The name of the file read at system startup and the shell syntax
used to read it vary from operating system to operating system;
check your operating system's documentation for details.
A.4. Arranging for a Server to Be Started
as a Background Process at System Startup
The method of starting a background process varies from system to
system.
Some servers should run as a “superuser” or “root” job so
that they can access all files. For safety,
each server should normally run on its own directory, one
with no important files in it.
if [ -f /usr/mainsail/gensrv ]; then
(echo -n ' gensrv'; cd /tmp; /usr/mainsail/gensrv&) \
>/dev/console
fi
A.5. Starting a Server Manually
A server may be started manually under UNIX as follows:
/usr/mainsail/myServerBootstrapName &
A.6. Installing the gensrv Server
The XIDAK service named gensrv is used to support several STREAMS
features, including:
For these features to be available, the gensrv server process must be started on each node and a services table must be created containing the names of the host systems and the servers that are running on each host.
To run the gensrv server, use the special MAINSAIL bootstrap named gensrv if the installation process has created one. This bootstrap, if present, is built during the MAINSAIL installation process. It is configured to use less memory than normal interactive MAINSAIL processes.
If no gensrv bootstrap is created (some platforms' installation scripts do not create a special gensrv bootstrap), run the MODULE GENSRV from any bootstrap (e.g., from the default bootstrap with the command mainsa gensrv).
The exact steps required for installing gensrv on a host are:
gensrv maintains a log file of its activities. The name of this file is given by definition of the logical name (gensrv log file) in the command file platformAbbrevg.cmd on the MAINSAIL directory, where platformAbbrev is the abbreviation for the MAINSAIL platform; this file is read by the gensrv bootstrap when it starts execution. You can change the name of the log file by editing the command file.
MAINSAIL STREAMS User's Guide, Appendix A