The Data Dictionary is normally built as a standard part of the application build procedure.

: References in the files in the remainder of this chapter to ‘Loc’ indicate where you would substitute an abbreviation of your location. ‘Sys’ refers to places where you would substitute an abbreviation of your system.

...

Data Dictionary Form

Expand

title	OverviewOperation

The Data Dictionary Form displays all of the data dictionaries available on the host system.

Expand

title	Operation

The data dictionary form is primarily used to select one or more variables out of the data dictionary for display on a given screen. The list of currently selected variables shown in the top-right of the form and shows the variable name, type, description, and source (dictionary) for each selected variable.

The top-left of this form contains the data dictionary browser which displays the currently selected data dictionary either as a hierarchical tree-based or as a list of variable names, depending on the type of data dictionary. For a tree-based data dictionary such as TsentryGsm, the root elements in the tree represent each of the available global commons, and expanding one of these commons reveals its internal structure. For a list-based data dictionary such as one associated with a historical trend data file, the individual variable names are presented as a flat list. The currently displayed dictionary can be changed by clicking on the “…” button above the browser.

The bottom half of this form allows the user to search for text within the list of all variable names and descriptions. The user can search the data dictionary for multiple strings by separating them with spaces in the Search string; in this case all of the specified words must exist in either the variable name or description in order for the variable to be displayed.

Variables can be added to the list of selected variables from either the data dictionary browser or the search results by highlighting the appropriate variable and either clicking the Add button or simply dragging the variable name up to the list. The Remove button removed the currently selected variable from the list and the Clear button removes all variables from the list.

Right-clicking on the list displays a popup menu with several options for modifying the variables in the list. The Prefix Variable sub-menu allows the user to apply a prefix to the variable name in case he wishes to return not the variable value itself but rather some metadata about the variable. The following prefix options are available:

Prefix	Description
Name	The variable name itself.
Desc	The variable description (prepends '#' to the variable name).
Min	The specified minimum value of the variable (prepends '<' to the variable name).
Max	The specified maximum value of the variable (prepends '>' to the variable name).
Initial	The specified initial value of the variable (prepends '=' to the variable name).
String	Treat character array as a string (prepends '$' to the variable name and removes any trailing square braces '[]' indicating an array)

When the user clicks the Accept button each of the variables in the selection list will be passed back to the caller. For instance, on the ProbeX screen selecting multiple variables in the data dictionary form will add a probe for each selected variable

Expand

title	Data Dictionary Files

All of the files used by the TsentryGsm data dictionary system reside in the ‘Pif’ directory of the application. (example: \LocNtRt\sys\pif\* ).

The following table describes the files used by the TsentryGsm data dictionary.

File	Creation	Description and Comments
sys.ini	User Defined	Application system Initialization file. This file contains the definitions of important files referenced by system wide applications. This file is created by the user at system installation and is normally not modified thereafter. This file contains 1 line which defines the Data Dictionary Structure Definition file (sysStruct.ini), and 2. 1 line which defines the Data Dictionary Variables Definition file (sysVars.h).
sysGsm.h	User Defined	This file looks like a standard ‘C’ language header file. It contains ‘#include’ directives for each of the application header files required to define all of the global common variables.
sysVars.ini	User Defined	This file contains 2 sections: The [GblCmnDef] section defines the global common structure and section names to be built and installed The [VarDef] section defines the “important” variables in global common. An “important” variable is one for which you wish to define a minimum value, maximum value, initial value, text description, or wish to have saved and restored. Any variable information in this section is completely optional.
sysStruct.ini	Produced by Program	Contains the actual structure and variable definitions. This file is produced by the program GsmPifBld using the user defined header file sysGsm.h.

Expand

title	Building the Dictionary

The data dictionary is built with the GsmPifBld program located in the \tpriNtRt\bin directory. It requires two parameters:

The The fully qualified name of the sysGsm.h header file (input)

2.

The fully qualified name of the

sysStruct.ini file (output)

The following is an example command as would be submitted to a DOS box command line:

d:\LocNtRt\tpriNtRt\bin\GsmPifBld d:\LocNtRt\sys\Inc\sysGsm.h d:\LocNtRt\sys\Pif\sysStruct.ini

Execution of this program will replace the current copy of sysStruct.ini with an updated copy built from the latest application C/C++ language header files.

This program parses all header files included in sysGsm.h and generates the text sysStruct.ini file that specifies the name, type, size, dimensions, and descriptions for all structures and structure members that it finds in the header files.

Expand

title	Variable Descriptions

The data dictionary builder automatically extracts descriptions from the comments associated with each structure member defined in the header files. Descriptions are parsed according to the following rules:

Any comment immediately to the right of and on the same line as a structure member declaration will be interpreted as the description for the variable.
If a comment is found to the right of the variable declaration, then any comments on subsequent lines will be also be included in the variable description. Description parsing is terminated when a subsequent line contains anything except a comment (e.g. a new structure member declaration or a blank line) or any comment that does not have whitespace immediately following the start-of-comment token (e.g. “//int oldVariable;” will terminate the description parsing).

These descriptions are stored in the sysStruct.ini file along with the properties (name, type, size, etc.) of each of the structure members.

Note however that these descriptions are associated with single structure members in the data dictionary, and a given structure member may exist in multiple locations in the entire data dictionary. The data dictionary generates the description for a fully qualified variable as follows:

If the variable is explicitly specified in the sysVars.ini file, and the variable definition includes a description, the data dictionary uses this string as the official description.
1. Variable descriptions can be omitted from a variable definition in the sysVars.ini file by specifying an empty string (“”) or an asterisk (*) as the description.
If the variable is not specified in the sysVars.ini file, or the variable definition does not include a description, the description for the fully qualified variable name is generated at runtime by concatenating together the descriptions for each structure and member in the variable. For the global common itself, the system uses the description specified in the [GblCmnDef] section of the sysVars.ini file. Structure member descriptions are concatenated in reverse order relative to the fully qualified variable name so that the description for the final element is shown first.

For example, suppose a system includes the following header file:

Code Block

struct ROLLDATA
   {
   double Radius;       // Roll radius (in) 
   double FaceLen;      // Roll face length (in) 
   double Crown;        // Parabolic roll crown (in) 
   };
struct MILDATA
   {
   ROLLDATA Roll[4];    // Rolls installed in mill
   };

and the data dictionary is initialized with the following sysVars.ini file:

Code Block

[GblCmnDef]
# VarName  Type     GSMName  Mask  AscFile                Description
MILDATA    MILDATA  MILDATA  A     "D:\MILDATA.sav"       "Mill data"

[VarDef]
# VarName               Persist Format InitVal  MinVal MaxVal  Description
MILDATA.Roll[0].FaceLen I       %g     0.001    *      *       *
MILDATA.Roll[0].Crown   I       %g     0.001    *      *       "Concave crown""

The data dictionary would indicate descriptions for each of the following variables as:

Variable	Description
MILDATA.Roll[0].Radius	Roll radius (in) -> Rolls installed in mill -> Mill data
MILDATA.Roll[0].FaceLen	Roll face length (in) -> Rolls installed in mill -> Mill data
MILDATA.Roll[0].Crown	Concave crown

Expand

title	Application Program Interface

The initialization of the data dictionary, including reading the variable definitions, allocation of the global shared regions, populating the global shared regions, and saving the global shared regions is automatically taken care of by the NtRtMgr process.

Expand

title	Create

The data dictionary access may be initialized within any task with the following call:

code

tpriGsmDDCom::Create();

Expand

title	mapGsm

Access to an individual Global Shared Memory region within a process may be gained with the following call (example region = “SYSDATA”):

Code Block

struct SYSDATA *pSYS = NULL;
pSYS = (struct SYSDATA *)tpriGsmDDCom::mapGsm("SYSDATA");
   if (pSYS == NULL)
      {  // error in Mapping the global shared memory area
      LogMsg(NTRTTASK,DBFERR, 
             "SYSDATA Global Shared Memory mapping error\n");
      forever = 0;
      }
   else
      {
      LogMsg(NTRTTASK, DBDETAIL, 
             "SYSDATA GSM mapping completed successfully\n");
      }

Expand

title	Destory

Access to the Data Dictionary and to the associated Global Shared Memory Regions may be deleted from a process with the following function call:

code

tpriGsmDDCom::Destroy();

Expand

title	saveAllPersist

The variables in the Global Shared Memory Regions with “F” persistence may be saved to disk with the following call:

code

tpriGsmDDCom::saveAllPersist();

Expand

title	Maintenance

Maintenance requirements include the following:

Insure that all of the global shared memory regions are defined in the [GblCmnDef] section of the sysVars.ini
Insure that all global shared memory structures are defined in the sysGsm.h file. If this condition is not met, the GsmPifBld execution will fail.
Build a new Data Dictionary (sysStruct.ini) each time you have changed the definitions of any variable in any of the Global Shared Memory regions.
Manual changes made in the sysVars.ini file will not take effect until the application system is restarted.

...

Versions Compared

Old Version 1

New Version Current

Key

Data Dictionary Form

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Data Dictionary Form