SUBSYSTEM OVERVIEW

Entity Validation Manager (EVM) Subsystem

The EVM subsystem provides an application or application interface with the utilities to manage entity validations. Information about each validation is stored in an ASCII file which is compiled with the vtc (validation table compiler) utility. This produces an include file and a message table which are used in the validation process. The EVM subsystem then allows information for each validation to be obtained based on a validation ID.

Note that this subsystem does not do any actual validations, it simply manages the information associated with a validation (message text, defaults, etc).

VALIDATION TABLES

All of the information managed by the EVM subsystem originates in a validation table. This is an ASCII file which defines various parameters about each validation. The format of the file is:


<table>	->	<subsystem> <errorlevel> <defs>
<subsystem>	->	<ident> SEMICOLON
<errorlevel>	->	EQUALS <int_lit> SEMICOLON
<defs>	->	<entries> {<entries>}
<entries>	->	<ident> {<keywords>} SEMICOLON
<keywords>	->	<key_sev> \| <key_fix> \| <key_def> \|
		<key_type> \| <key_msg>
<key_sev>	->	SEV EQUALS <int_lit>
<key_fix>	->	FIX EQUALS <int_lit>
<key_fixes>	->	FIX <int_lit> EQUALS <qstring>
<key_def>	->	DEF EQUALS <int_lit> \|
		DEF EQUALS <float_lit> \|
		DEF EQUALS <qstring>
<key_type>	->	TYPE EQUALS <int_lit>
<key_msg>	->	BRIEF EQUALS <qstring>
		VERBOSE EQUALS <qstring> {<qstring>}
		{DESC EQUALS <qstring> {<qstring>}}
		<key_fixes> {<key_fixes>} \|
		<qstring> {<qstring>}
		{DESC EQUALS <qstring> {<qstring>}}
		<key_fixes> {<key_fixes>}

Where <ident>, <int_lit>, <float_lit>, and <qstring> are lexical tokens corresponding to identifiers, integer literals, floating point literals, and quoted strings, respectively.

The keywords define characteristics of a validation. Note that the code which performs the validation determines which keywords are required and how they are used. A general definition of each keyword follows:

Keyword

Purpose

sev

Severity level associated with the check.

fix

The type of fixup to be performed.

def

Default value for validation (integer, floating point, or text as required by the validation).

type

Type of validation (usually in terms of computational overhead). This keyword must be specified as it usually defines whether a check should be performed. By convention a value of 0 indicates that the check should not be performed.

brief

The short definition of the message to be issued when the validation fails. If specified a verbose message must also be defined.

verbose

The long definition of the message to be issued when the validation fails.

desc

A description of the how the validation is done and the fixups that may be performed.

fix

Definition of the message to be issued when a fixup is made.

A sample validation file would be:

/* ------------------------------------------------------------ */ 
   subsystem ievm;
   errorlevel = 3;
   BAD_COLOR_NUM  sev=2  type=1  fix=1
      brief = "Bad color number.\n"
      verbose = "DE has an invalid color number.  \n"
                "Value found was %d. "
      desc =  "The color number found was not within the legal "
              "range of 0 to 8."
      /*  Fix 1: set the version number to 0  */
      fix 1 = "The color number has been set to zero.\n";
   BAD_STRUCTURE_PTR  sev=2  type=1 fix=1
      brief = "Bad structure pointer.\n"
      verbose = "DE has an invalid structure pointer.\n"
      /*  Fix 1: set the version number to 0  */
      fix 1 = "Bad structure pointer fixed.  Version number "
              "has been set to zero.\n";
   
   BAD_FONT_NUM  sev=2  type=1  def=1
      brief = "Bad font number. \n"
      verbose = "DE has an invalid font number.  Value found was "
                  "%d.\n"
/* ------------------------------------------------------------ */

The validation table compiler has two modes of operation, one designed for writers of validation subsystems and the other designed for developers who use these validation subsystems. See the vtc(1) manual page for more information on these two modes.

INITIALIZING THE VALIDATIONS

When compiled with the -msg option, the information associated with each validation is stored in an include file called xxx__ValCfg.h. This information must be loaded by including this file in ONE source file. The table is initialized at run-time by calling the function evm_InitializeTable. This must be done before any other EVM functions can be called with the table.

ACCESSING VALIDATIONS

Validations are accessed using the function evm_GetCheck. This returns a structure of type EVM_CHECK which has the following members:

Data Type	Field	Description

–

PDX_MSGT	Msg;	Message ID for the validation
char	Type;	Type of check
char	Fix;	Fix to be performed
char	Sev;	Severity of the error
MDA_ALL_TYPES	Def;	Default value

The fields in this structure correspond to the keyword fields defined in the validation entry. For keywords which were not defined the following defaults are used:

   Fix = 0
   Sev = 0
   Def = Undefined

MERGING TABLES

Normally a validation subsystem will define a set of validations which may be optionally modified by a developer through a user validation table (see vtc(1)). In order to use the modified validations, the modified table (defined in xxx_ValCfg.h) must first be initialized with evm_InitializeTable and then passed to the function evm_MergeTable.

RUN-TIME TABLE MODIFICATION

The following functions can be used to alter to the validation table at run time.

evm_SetFix
evm_SetType
evm_SetDefault
evm_SetSeverity