Infrastructure Configuration


Descrption Macros Config File Keywords (Directives)
Config File Examples

Description:
Infrastructure initialization requires a configuration file to be read.    This is a flat text file with an extension of '.cfg', but is always referred to by the unextended file name.    The config file's name may be derived by looking at the command line "sysgo infTst", else the environment variable 'CFGNAM'.    The location of the file is either "/usr/local/etc", the current working directory, or contained in the environment variable 'CFGDIR'.    The CRUNCH or '#' defines a comment and the rest of the line following the CRUNCH is not seen by config processing.    A line in the config file may be extended by adding a BACKSLASH as the last character of the line (just before the NEWLINE) as in bash scripts.    If the keyword "INFHOME" is included in the configuration file and is defined equal to a directory the process will change to this directory before continuing execution.    Unix environment variables may be referenced from the config file by preceeding it with a dollar "$" sign and wrapping the variable name with parenthesis "$(HOME)".    You may define a macro using any name you choose (so long as it doesn't conflict with system keywords) and later reference it using the same syntax as the Unix environment variables.
BARF = hello
Greet = $(BARF)    Now Greet contains "hello".   
These environment variables are expanded after each line is read and before any keyword lookups and processing is done.    Configuration is not included in the low level (libUt) infrastructure layers, hence, no config file is required.

The simplest configuration file would look like this:
     TCP        LogicalPortName        HostName        PortNumber        EncryptionType        EncryptionKey
     PROC     ExecutableName     LogicalProcessName        Any Command Line Arguments
The two lines define the first (and only) process' command port and relate the process executable and logical process name.    The process' logical process name must match the file name without the extension (.cfg).

Sysgo, which is built around the sys.c layer, is used to initiate and control a group of processes, usually called an engine.    Sysgo reads a configuration file then, if directed, changes directories, builds a sub-directory and config file for each "CHILD" process defined, then starts the non-disabled processes.    During process startup sysgo attempts to "ping" each defined process to determine if there is an existing instantiation of the process.    If one is found, sysgo asumes control over it instead of starting a new copy.    If an existing process is not found, a new process is started in the appropriate directory.    When a process is started, it reads it's config file and if a "PARENT" directive is found, the sub-process "pings" it's parent, thus making itself known to the parent.    These special "ping" and reaponse messages contain the sending process' HostName, logical process name, a ping sequence number, process' PID, and an optional message from a sending function.

After startup is complete sysgo waits, monitoring it's sub-processes.    If a subprocess should die, the permanent virtual circuit created by the initial "ping", disconnects, creating a call-back.    At the disconnect call-back, sysgo checks the sub-proc's config and if no prohibitions exist and the process has not died more than six times within the last minute, starts another copy of the sub-process.   

Sysgo also responds to the infCtl tool, with options of shutting down the entire system, shut down or start a selected processes, or vectoring control commands to a selected sub-process.

The logical process name is set using the unextended result of the config file name, and must match the first process defined in the config file.

Every process must have a control queue defined (although it might not be used). The first process in a config file must be explicitly defined using the 'PORT' or 'TCP' directive.    Additional processes may be explicitly defined or will use the incremented port number of the previous process.    The host part is always the localhost or loopback on these command queues.    The Input/Output layer is also cabaple of opening an input queue (socket) on any external interface of the current computer.   

Two Ways to Setup Program Variables:
There are two ways to configure program variables supported by the infrastructure, the original way (focused on the config file) using the configuration macros explained below and a second or dynamic way (focused on the variables themselves) wich uses a single macro and an include.
The dynamic approach allows program variables to be set from the config file, or via a configuration server daemon, or dynamically using events.    This new method requires insertion of a single macro name ~VAR in a comment, followed by the variable names and an include file containing the 'C' file name (no .c) with 'Vars" appended and of course followed by '.c'.    For more information about this please see the Cfg doc. Theses This new method requires insertion of a single macro name ~VAR in a comment, followed by the variable names.

Configuration Macros:
Each process may have a configuration table which it registers before running the configuration initialization.    This config table relates config file keywords to program variables of different types.    A set of macros has been created to help build the configuration table and register it.   

CFG_BGN( "label" )
Beging the configuration table and assign the label to it (for infCtl display).   
CFG_INT( "NAME", IntVariable )
Define a config file name that will assign the converted argument to an integer variable.   

CFG_STR( "NAME", StringVariable )
Define a config file name that will assign the argument to a string variable.   

CFG_FUN( "NAME", FunctionName, Argument )
Define a config file name that will call the specified function to process the argument from the config file.
     Function prototype:              int func( cfgTbl_t* ptr, char *configFileArgument );
The function will be called with a pointer to the referencing confiuration table entry and the remainder of the config file line which triggered the call.    If the function returns 'OK', the config file processing will continue normally.    if the function returns 'ERR', processing will be stopped and an error message will be traced.   

CFG_FLG( "NAME", FlagVariable, Value )
Define a config file name that will assign the Value to a flag (char) variable.    The Value will be placed in the FlagVariable.    This allows the inclusion of a keyword in the config file to set or clean char flags.

CFG_END
Terminate the config table construction.   

CFG_REG;
Register the config table built using the CFG_BGN to CFG_END macros.   


Configuration File Keywords:
inf.c
INFHOME infInit will change directory to here before returning to it's caller.    This allows the infrastructure to be started from anywhere but will only run in the INFHOME directory.
PARENT Current process' parent name, if one exists.    The presence of this variable triggers a process to contact it's parent.
NOCMDQUE Do not open a command queue for this process
CORELIMIT Set a userlimit core size so core dumps may be generated.


io1.c Input/Output configuration directives
TCP Queue definition for TCP/IP protocol socket.
WAITROUND Use round-robin wait polling. If set ioWait will poll all ready fds. If not set, ioWait will return after processing the first ready fd.


Cfg.c Configuration directives
CFGNAM Name of configuration file (will have the extension .cfg).
CFGDIR Directory where configuration file will be found. Default is ./.
ENV The following name and value will be placed into the environment of the current process.
PROC Begin definition of a specific process.
NOCMDQUE Do not open a process command queue. This is handy for persistent cgis.


opt.c Command line options layer
DEBUG The process debug flag, prevents daemonizing, etc.


trc.c The trace layer
TRACECTL Used to enable tracing at startup.
Example: TRACECTL Mask,Level
Mask = IO+INF+SYS+CFG+APP1+APP2+APP3+UTIL+MSG+MSG1+MSGO Mask selects system layer.
Level = integer from 0 to 255. Level selects the granularity of the tracing (higher level = more trace info).
LOGDIR Directory path to write the trace and error logs.


Sys.c The system control layer had these configuration key-words.
INFHOME Change to this directory before starting an engine.
BINDIR Directory path for binary executables
HOMEDIR Engine's home directory
PROCPORT Port for first process
STARTUPDELAY between starting each process
PROC Process declaration beginning
CHILD Child process declaration beginning
NO_RESTART Do not restart this process when/if it dies
NO_AUTOSTART Do not automatically start this process at engine start-up
CLONE_OK Alright to clone this process if requested
HIDE_NAME Hide executable name from argv[0] (Needed on Progress under HPUX)
SOFT_KILL At shutdown or when requested to kill a process, use kill -2.


EXAMPLES


Typical Client Configuration File:
TCP mopTst * 4011
TCP Server * 4010
PROC mopTst
#      TRACECTL = APP1,26
#      ROTMONTH
     NOCMDQUE

Typical Server configuration file:
# Test Server Config
TCP srv * 4010
PROC srv
#      TRACECTL = IO,99
     WAITROUND

Typical System config file:
BINDIR = /home/pturner/code/inf/inf
# TRACECTL = APP1+CFG,55
PROCPORT = 4100
TCP trcLog * 4101
TCP errLog * 4101
TCP sys * 4100
PROC sysgo sys

     TRACECTL = IO+SYS,99

CHILD trcd trc trace error

CHILD srvTst Srv1
     # NO_AUTOSTART
     NO_RESTART
     TRACECTL = IO,99

CHILD cltTst Clt1 -c -p 10
     TRACECTL = IO,99
# NO_AUTOSTART
NO_RESTART

CHILD cltTst Clt2 -c -p 10
TRACECTL = IO,99
# NO_AUTOSTART
NO_RESTART

CHILD cltTst Clt3
TRACECTL = IO,99
NO_AUTOSTART
NO_RESTART