The Version 2.0 NML Configuration File Format and Tool
Background
The version 1 configuration file format described in "Writing NML Configuration Files" has remained stable since 1995 except for some rarely used options that can be placed at the end of buffer and process lines . That format is also the only format that NML constructors can
currently use directly and it is the format generated by the
NML Configuration File Builder (a
CGI script and HTML form) and by the RCS Design Tool (a Java application).
In May 1999, the configuration format described here was proposed. The goals for this new configuration format were the following:
- Easier for multiple organizations to share configuration files.
- Less verbose files made possible by allowing users to specify only items that need to be different than the default.
- Fewer errors caused by novice users.
- Eliminate some tedious tasks.
The version 2 configuration format is supported only through a tool that takes files written in the new format and produces files in the older format. These files can then be used in an application in the same way as files written by hand in the older format or generated by one of the graphical tools.
The reader for this document is expected to be familiar with either C++ or Java, the NML Programmer's Guide, C++ Version/Java Version, and with the the older configuration file format.
Configuration File Line Types
The new configuration files are ASCII text files, that contain eight different types of lines that can be idenfied by the first character or word on the line:
Starting Word or Character
|
Line Description.
|
#
|
Comment Lines have no effect on the output file.
|
##
|
Insert lines have the same effect as regular comment
lines except that they are inserted as comments in the
output file.
|
include
|
Include lines cause the contents of another file to be
read as if the text were included at that point in the
original file.
|
define
|
Definition lines define a variable that can be used
through the rest of the file, by preceding the variable name
with "$" and surrounding it with parentheses "( )" like this "$(varname)"
.
|
buffer_default
|
Buffer Default lines set defaults that affect buffer
lines that occur after this line.
|
b
|
Buffer lines begin with must contain "name=" and
the name of the buffer somewhere on the line. These lines
are used to create and entry for a particular buffer.
|
process_default
|
Process Default lines set defaults that affect process
lines that occur after this line.
|
p
|
Process lines must contain either "name=" or
"bufname=" somewhere on the line and are used to
create an entry linking a particular process to a particular
buffer. For proper checking process lines must occur after
the buffer line for the buffer the process is connecting to.
|
Buffer Variables
The following variables with the exception of "name" can be set either on a buffer line to modify only one buffer or on a buffer default line to affect several buffers:
- name
- The name used as an argument to the NML constructor in the C++ or Java code. It must be unique. There is no default value, this variable must be set on each line with a "b ".
- buftype
- The type of buffer to create which can be shmem,globmem,filemem,locmem or phantom. The default value is shmem.
- host
- The host name where a server must be run if any processes are going to connect remotely. The default value is localhost.
- size
- The size of the largest message that can be sent to the buffer. The amount of memory allocated will be slightly larger than this to accomodate some handshaking flags. The default value is 960.
- neutral
- Whether the local buffer should be neutrally encoded. Buffers should be neutrally encoded if they can be accessed by multiple CPU types by a Bit3 adaptor for example or to force messages to go through format and update functions that significantly reduces message size such as when variable length arrays are used. Messages are always neutrally encoded when sent over a network. The default value is false.
- bufnumber
- A unique number used to identify the buffer within a server. The default value is calculated based on the position of the buffer line in the file. If its default value is modified with a default buffer line the default value for subsequent lines will still be incremented from this starting value.
- max_proc
- The maximum number of processes that can connect to a buffer locally. It does not affect remote processes or shmem buffers using the default mutual exclusion mechanism. The default value is calculated based on the number of processes connecting to this buffer.
- key
- A unique number used to identify the shared memory and semaphore used for mutual exclusion in a shared memory buffer. It is relavent when using the "ipcs" or "ipcrm" commands. The default value is calculated based on the position of the buffer line in the file.
- bsem
- A unique number used to identify the semaphore used for blocking reads. Ther default value is -1, so blocking reads are not allowed by default. However if the value is changed with a default buffer line then subsequent lines will increment this starting value.
- vme_addr
- The VME address used for GLOBMEM on a VME backplane. The default value is 0 which is unusable. However if the default value is changed with a default buffer line then subsequent buffers will use the sum of this values plus the size of the preceding buffers.
- remotetype
- The protocol that should be used by remote processes connecting to this buffer which could be tcp,stcp, or udp. The default value is tcp.
- port
- The TCP or UDP port used by remote processes. The default value is 30000.
- enc
- The nuetral encoding method which can be xdr,ascii,or disp. The default value is xdr.
- queue
- Whether messages in this buffer should be queued. Setting it to a value greater than 1 also multiplies the size of the buffer by this value.The default value is 0.
- diag
- Whether to enable supplemental timing diagnostic information to be logged to the buffer. ( See Supplementary NML Timing Diagnostics Tools.)
There are some additional flags that were available in the old configuration file that the new tool will not recognize. This will produce a wargning but the old flag should simply be pasted to the end of the generated buffer line which should allow the use of the unrecognized flag.
Process Variables
The following variables can be place either on a process line to affect only one process connection to one buffer or on a default process line to affect multiple connections:
- name
- The name of the process that is passed to the NML constructor in the C++ or Java constructor. There is no default value, this variable must be set.
- bufname
- The name of the buffer that this process is connecting to. There is no default value, this variable must be set.
- proctype
- The type of process which can be local or remote. The default is remote.
- host
- The name of the host this process is running on. It is currently only used to comment the output file. The default value is localhost.
- ops
-
- The operations allowed by this process on this buffer which can be r, w,or rw. (For READ_ONLY, WRITE_ONLY, and READ_WRITE respectively) The default value is rw.
- timeout
- The time in seconds to allow before this process should timeout waiting for a read or write specified as a double or "INF" to indicate infinity.The default value is infinity.
- master
- Whether this process will be the master of this buffer. The master creates and clears the buffer when it is started. The default value is false.
- server
- Whether this process will act as a server for this buffer. The value of 2 has the special meaning that the process will spawn a server but then continue to access the buffer locally. The default value is false or 0.
- c_num
- The connection number which should be unique among processes connecting to the same buffer locally. The default value is calculated based on the number of processes that connected to this buffer before.
- sub
- The subscription interval in seconds for remote processes. The default value is -1 which indicates no subscription.
Tool Command Line Arguments
The program "nmlcfg" converts files from the new format to the old format which must be done because the NML constructors can not currently read the new format.
All command line not preceded by one of the following flags
is considered to be input files that should be in the new format. If more
than one input file is specified they are read in the order they occur and only one output file will be produced.
Here are the additional flags:
- -D name=value
- Defines a value on the command line just as if a define line was used.
- -I directory
- Adds a directory to a list of directories to be searched if a include line is found.
- -o output_file
- Specified the file where the old format file will be written.
Examples
The following example includes a separate file that can be modified to
change the host name, 2 buffers, and 3 processes connecting to it.
The file "myhosts" contains the following.
# Set host aliases.
define host1=dopey
The file "ex.nml" contains the following:
include myhosts
buffer_default host=$(host1)
b name=ex_cmd
b name=ex_stat
process_default server=1 master=1 proctype=local name=mysvr
p bufname=ex_cmd
p bufname=ex_stat
process_default server=0 master=0
process_default name=pl
p bufname=ex_cmd
p bufname=ex_stat
process_default name=ex
p bufname=ex_cmd
p bufname=ex_stat
The old style config file generated is this:
# Buffers:
# name type host size neut 0 buf# max_proc . . .
B ex_cmd SHMEM dopey 1024 0 0 1 4 10001 TCP=30000 xdr
B ex_stat SHMEM dopey 1024 0 0 2 4 10002 TCP=30000 xdr
# Processes:
# Name Buffer type host ops server timeout master c_num . . .
P mysvr ex_cmd LOCAL localhost RW 1 INF 1 0
P mysvr ex_stat LOCAL localhost RW 1 INF 1 0
P pl ex_cmd LOCAL localhost RW 0 INF 0 1
P pl ex_stat LOCAL localhost RW 0 INF 0 1
P ex ex_cmd LOCAL localhost RW 0 INF 0 2
P ex ex_stat LOCAL localhost RW 0 INF 0 2
Last Modified: 15-Oct-1999
If you have questions or comments regarding this page or you would like to be notified of changes to the RCS library via email, please
contact Will Shackleford at shackle@cme.nist.gov