PMDF System Manager's Guide
PMDF-REF-6.0

Compile the PMDF configuration, alias, mapping, conversion, security, system wide filter, circuit check, and option files and load the resulting image file into shared memory.

Syntax

pmdf cnbuild

Command Qualifiers	Defaults
-image_file=file-spec	-image_file=PMDF_CONFIG_DATA
-maximum	-nomaximum
-option_file=file-spec	-option_file=PMDF_OPTION_FILE
-remove	None
-sizes	-nosizes
-statistics	-nostatistics

restrictions

Must have superuser privileges (UNIX) or be logged in as Administrator (NT) in order to use this utility.

PARAMETERS

None.

DESCRIPTION

The cnbuild utility compiles the textual configuration, option, mapping, conversion, security, system wide filter, circuit check, and alias files, and loads the resulting image file into shared memory. The resulting image is the file named by the PMDF_CONFIG_DATA option of the PMDF tailor file, /etc/pmdf_tailor, (usually /pmdf/lib/config_data).

Whenever a component of PMDF (e.g., a channel program) must read any possibly compiled configuration component, it first checks to see whether the file named by the PMDF tailor file option PMDF_CONFIG_DATA is loaded into shared memory; if this compiled image exists but is not loaded, PMDF loads it into shared memory. If PMDF finds (or not finding, is able to load itself) a compiled image in shared memory, the running program uses that image. There are four exceptions to this rule. The first is pmdf cnbuild itself, which for obvious reasons always reads the text files and never tries to use an image form of the configuration data. The remaining three exceptions are pmdf test -rewrite, pmdf test -mapping, and pmdf test -x400 which can all be instructed with the -image_file qualifier to use a different compiled configuration file. This facility in pmdf test -rewrite is useful for testing changes prior to compiling them.

The reason for compiling configuration information is simple: performance. The only penalty paid for compilation is the need to recompile and reload the image any time the configuration or alias files are edited. Also, be sure to restart any programs or channels which load the configuration data only once when they start up, e.g., the PMDF multithreaded TCP SMTP server.

Once you begin to use a compiled configuration, it will be necessary to recompile the configuration every time changes are made to any of the following files: the PMDF configuration file (or any files referenced by it), the PMDF system alias file, the PMDF mapping file, the PMDF option file, the PMDF conversion file, the PMDF security configuration file, or the circuit check configuration file. Specifically, these are the files pointed at the PMDF tailor file options (UNIX) or PMDF Tailor Registry keys (NT) PMDF_CONFIG_FILE, PMDF_ALIAS_FILE, PMDF_MAPPING_FILE, PMDF_OPTION_FILE, PMDF_CONVERSION_FILE, and PMDF_SECURITY_CONFIG_FILE, respectively, which usually point on UNIX to

• /pmdf/table/pmdf.cnf,
  /pmdf/table/aliases,
  /pmdf/table/mappings,
  /pmdf/table/option.dat,
  /pmdf/table/conversions, and
  /pmdf/table/security.cnf,

or on NT to

• C:\pmdf\table\pmdf.cnf,
  C:\pmdf\table\aliases,
  C:\pmdf\table\mappings,
  C:\pmdf\table\option.dat,
  C:\pmdf\table\conversions, and
  C:\pmdf\table\security.cnf.

as well as the file /pmdf/table/circuitcheck.cnf (UNIX) or C:\pmdf\table\circuitcheck.cnf (NT). Until such time as the configuration is rebuilt, changes to any of these files will not be visible to the running PMDF system.

See Chapter 8 for further details on the use of compiled configurations.

COMMAND QUALIFIERS

-image_file[=file-spec]

-noimage_file

By default, pmdf cnbuild creates as output the image file named by the PMDF_CONFIG_DATA option of the PMDF tailor file, /etc/pmdf_tailor, (UNIX) or PMDF Tailor Registry key (NT). With the -image_file qualifier, an alternate file name may be specified. When the -noimage_file qualifier is specified, pmdf cnbuild does not produce an output image file. This qualifier is used in conjunction with the -option_file qualifier to produce as output an option file which specifies table sizes adequate to hold the configuration required by the processed input files.

-maximum

-nomaximum (default)

When -maximum is specified, the file /pmdf/table/maximum.dat is read in addition to the file named by the PMDF_OPTION_FILE option in the PMDF tailor file, /etc/pmdf_tailor, (UNIX) or PMDF Tailor Registry key (NT). This file specifies near maximum table sizes but does not change any other option file parameter settings. Only use this qualifier if the current table sizes are inadequate. The -noimage_file and -option_file qualifiers should always be used in conjunction with this qualifier---it makes no sense to output the enormous configuration that is produced by -maximum, but it does make sense to use -maximum to get past size restrictions in order to build a properly sized option file so that a properly sized configuration can be built with a subsequent pmdf cnbuild invocation.

-option_file[=file-spec]

-nooption_file (default)

pmdf cnbuild can optionally produce an option file that contains correct table sizes to hold the configuration that was just compiled (plus a little room for growth). The -option_file qualifier causes this file to be output. By default, this file is the file named by the PMDF_OPTION_FILE option in the PMDF tailor file, /etc/pmdf_tailor, (UNIX) or PMDF Tailor Registry key (NT). The value on the -option_file qualifier may be used to specify an alternate file name. If the -nooption_file qualifier is given, then no option file will be output. pmdf cnbuild always reads any option file that is already present via the PMDF_OPTION_FILE option of the PMDF tailor file, /etc/pmdf_tailor, (UNIX) or PMDF Tailor Registry key (NT); use of this qualifier will not alter this behavior. However, use of the -maximum qualifier causes pmdf cnbuild to read PMDF options from the file maximum.dat in the PMDF table directory in addition to reading the file named by PMDF_OPTION_FILE. This file specifies near maximum table sizes. Only use this qualifier if the current table sizes are inadequate, and only use it to create a new option file. The -noimage_file qualifier should always be specified when -maximum is specified since a maximum-size image would be truly enormous and extremely wasteful.

-remove

Remove any existant compiled configuration; i.e., remove the file named by the PMDF_CONFIG_DATA option of the PMDF tailor file, /etc/pmdf_tailor, (UNIX) or PMDF Tailor Registry key (NT).

-sizes

-nosizes (default)

The -sizes qualifier instructs pmdf cnbuild to output information on the sizes of uncompiled PMDF tables.

-statistics

-nostatistics (default)

The -statistics qualifier instructs pmdf cnbuild to output information on how much of the various tables in the compiled configuration were actually used to store data. These numbers give a rough measurement of the efficiency of the compilation, and may indicate whether or not an additional rebuild with the -option_file qualifier is needed.

EXAMPLES

# pmdf cnbuild

This is the standard command used on UNIX to regenerate a compiled configuration. After compiling the configuration, restart any programs which may need to reload the new configuration; e.g., the TCP SMTP server should be restarted.

# pmdf cnbuild -noimage_file -option_file -maximum
# pmdf cnbuild
 

Use these two UNIX commands when you encounter the infamous "No room in table" error message.

C:\> pmdf cnbuild

This is the standard command used on NT to regenerate a compiled configuration. After compiling the configuration, restart any programs which may need to reload the new configuration; e.g., the Dispatcher should be restarted.

C:\> pmdf cnbuild -noimage_file -option_file -maximum
C:\> pmdf cnbuild
 

Use these two NT commands when you encounter the infamous "No room in table" error message.