0 Replies Latest reply: Dec 30, 2008 12:14 PM by Susan Miller RSS

Understanding Commit

Susan Miller
For developers who want to understand the commit protocol here is the scoop written by the experts on how it works:

The commit process is both a function which has a protocol. The commit process is initiated on the console; by selecting the "Commit KM" entry on the "File" menu. When this occurs, behind the scenes, the console builds a list of file which is sent to the selected agents.  The list of files is known as a dependency list.  The dependency list  contains an entry for each file which the console could sent to an agent.  Each entry contains the name of the file and the version of the file.  After the dependency list is built it is sent to the agent. When the an agent received the dependency list it checks each entry to see if it has the same file and version as the console. For each file that the agent does not have or does not have the same version as the console it sends a request to the console for that file.  When the console receives a request for a file from a particular agent, it checks to see if it was one of the files which it offered and if it was sends the file to the requesting agent.  The requesting agent then receives the file and saves in the global knowledge/psl area.

How is the dependency list built

Firstly the .km files for all the loaded knowledge modules must be included in the dependency list. The rest of the list is built by examining the .km files corresponding to each loaded knowledge module.  Basically each .km file is examined (grepped) for dependent files, for example psl files, event catalog files, scripts for event escalation actions (psl/shell) etc.  Each dependent file is added to the dependency list. The following strings are searched for in each .km file:

EV_CATALOG_NAME = "
EV_CATALOG_SERIAL = "
ESCL_ACTION LOAD "
NOTIFY_ACTION LOAD "
MGT_ACTION LOAD "
ESCL_PSL_ACTION LOAD "
NOTIFY_PSL_ACTION LOAD "
MGT_PSL_ACTION LOAD "
_TEXT = LOAD "

In each case the text following the quote up to the next quote is the name of a file that KM uses, and is therefore added to the dependency list.  Usually these strings form a specific part of the KM structure.

Extending the Commit Protocol
To extend the commit protocol to allow arbitrary files to be committed to agents, the KM developer must be able to specify files which should be added to the dependency list that the console builds and sends to each agent. This mechanism can be provided by allowing the KM developer to define an extra parameter named "ExtraFilesList" for any KM. The parameter is created in the same way as any other parameter; however it should be set to be inactive so that an agent does not try to run it.  The command text of the parameter will contain the list of extra files that must be committed with the KM. The syntax of the Command text of this special parameter is described by the following grammar :

extra_files := extra_file | extra_files
extra_file := lib_file | arbitrary_file
lib_file := T_LIB `"' T_FILENAME '"'
arbitrary_file := T_EXTRA `"' T_FILENAME `"'
T_EXTRA := literal text "EXTRA" without the quotes
T_LIB := literal text "LIB" without the quotes
T_FILENAME := is any filename specified relative to the local/global PSL    directory (the local directory is checked first).

For example :

EXTRA "SomeFile"
EXTRA "../SomeOtherFile"
LIB "SomeFile.lib"
EXTRA "adduser.sh"

If this was the command text for the "ExtraFilesList" parameter of some KM then during a commit 4 extra files would be added to the dependency list that the console offers to the agent. All the "EXTRA" files are forced down to the agent regardless of whether the agents version of the file is the same. The "LIB" file may not be requested by a particular agent because it will do a version check on the "LIB" files and only request the file if its version differs from the consoles version.  Note that the files must be specified relative to the local/global PSL directory and that the local area is searched first when trying to find the file.

Limitations of the Commit Protocol with versions 3.3x and earlier.
a.      a. Large files can produce a connection time-out.Large number of files can produce a connection time-out.
b.      For each file that an agent requests, the console reads the file into memory before any of it is sent to the agent. Large files can use up all available memory.
c.      When an agent receives a file; the file is stored in memory until it has received the whole file. Large files can use up all available memory.

Note:
Some corrections...

The limitations mentioned above no longer exist for PATROL versions after 3.4. Neither the agent nor the console read the file into memory completely before sending, and the commit protocol no longer causes time outs.

How serial numbers are generated:

The various serial/version numbers in event catalogs, kms and PSL files are used to allow the agent/console to determine what really needs to be sent. If the same file name has the same serial/version on both sides then the file is not sent.