The Data Dictionary support supplied with the Tsentry system is a collection of functions and programs that provide easy access to all of the global variables defined in the system.  It is included in all versions of Tsentry and is used internally for basic functionality as system startup, shutdown, and ProbeX and TrendX displays.

Access to a variable is provided by the fully qualified variable name; that is the variable name as it might be used in a ‘C’ program.  This variable name may be used by data dictionary functions to access and update the variable value.  Additionally, the variable may have a user defined minimum, maximum, and initial values defined as well as a text description.  These values are also accessible through data dictionary functions calls.

The HMI included in Tsentry is provided with components that directly reference data dictionary functionality.  Components display text values and graphical objects that change size, shape, and color based on variable values reference global common variables through the data dictionary functionality.

Global variables are initialized using the contents of data dictionary control and data files whenever the application system is restarted.  On system shutdown, these same variables are saved on files for restoration on the next system restart.

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

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

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:

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

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. 

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

1.  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.

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:

1. 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.

2. 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:

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:

[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:

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.

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

tpriGsmDDCom::Create();

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

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");
      }

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

tpriGsmDDCom::Destroy();

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

tpriGsmDDCom::saveAllPersist();

Maintenance requirements include the following:

1. Insure that all of the global shared memory regions are defined in the [GblCmnDef] section of the sysVars.ini

2. 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.

3. 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.

4. Manual changes made in the sysVars.ini file will not take effect until the application system is restarted.

The contents and format of the sys.ini file are completely described in section 4.1.1.1.  The 3 lines of interest for the Data Dictionary setup are the lines that define the fully qualified file names of the DDStruct and DDVars files in the [IniFiles] section.  Examples of these lines follow:

[IniFiles]

#define the Data Dictionary Structure definition file
DDStruct=d:\locNtRt\sys\pif\sysStruct.ini

#define the Data Dictionary variables definition file
DDVars=d:\locNtRt\sys\pif\sysVars.ini
…
…

This file is a standard ‘C’ language header file.  It normally contains include definitions all of the application header files required to define all of the global common variables. 

This file is normally set up at application development time.  It would not normally be changed unless there were global common areas added to the application system.

An example follows:

#include "sysparam.h"
#include "afcdata.h"
#include "agcdata.h"
#include "sysdata.h"

This file contains 2 sections:

The [GblCmnDef] section defines the global common structure and sections names to be built and installed.  Each line describes a separate global common area and includes several columns of information about the global common area:

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 the variable’s value saved and restored.  Variable information in this section is completely optional; it may be included by the user for none, any, or all variables.

An example as follows

[GblCmnDef]
# VarName  Type     GSMName  Mask  AscFile                Description
VegCom     VegCom   VegCom   A     "D:\veg\VegVars.sav"   "Veg/EE data"
SimCom     SimCom   SimCom   A     "D:\veg\SimVars.sav"   "Simulator data"

[VarDef]
# VarName             Persist Format InitVal  MinVal MaxVal  Description
VegCom.szScheduleIni  I       %s     "d:\Sch" *      *       "Schedule definition"

# RunMode definitions:
VegCom.RunMode        I       %d     3        *      *       "System RunMode"

# VegMode definitions:
VegCom.TrackMode      F       %d     1        *      *       "System TrackMode"

# VegEnable software switch
VegCom.bVegEnableSw   F       %d     1        *      *       "VegEnable software switch"

# Analog input scaling
VegCom.rAiVoltsA      I       %f     0.004882 *      *       "A/I A coef"
VegCom.rAiVoltsB      I       %f     0.0      *      *       "A/I B coef"

# A/I Mux addresses
VegCom.iSpeedMuxAddr  I       %d     0        *      *       "Speed Signal Mux Address"
VegCom.iUWDiaMuxAddr  I       %d     2        *      *       "Unwind Diameter Mux Addr"
VegCom.iUWCurMuxAddr  I       %d     3        *      *       "Unwind Current Mux Addr""

This file is completely produced by the GsmPifBld program.  It is read by the NtRtMgr process at application system startup by the Data Dictionary initialization functions.

GsmPifBld does not support the following C/C++ constructs:

Multiple variable definitions of the same type:

// this is not supported 
int a, b;

// instead do this
int a;
int b;

“#if defined” statements:
// this is not supported 
#if defined A
#endif

// do this instead
#ifdef A
#endif

// this is not supported 
#if !defined B
#endif

// do this instead
#ifndef B
#endif

// this is not supported 
#if ((defined C) && (!defined D))
#endif

// do this instead
#ifdef C
#ifndef D
#endif
#endif