fwConfigurationDB_Hierarchies.ctl File Reference

Functions

void fwConfigurationDB_updateDeviceConfigurationFromDB (string configurationName, string hierarchyType, dyn_string &exceptionInfo, time validOn=0, dyn_string deviceList="", string systemName="", int options=fwConfigurationDB_deviceConfig_ALLDEVPROPS)
void fwConfigurationDB_getDBHierarchies (dyn_int &ids, dyn_string &types, dyn_string &descriptions, dyn_string &validFrom, dyn_string &validTo, dyn_string &exceptionInfo)
void fwConfigurationDB_getHierarchyFromPVSS (string rootNode, string hierarchyType, dyn_string &nodeList, dyn_string &exceptionInfo, string system="", string includeRootNode=TRUE)
void _fwConfigurationDB_copyDeviceListObjectEntry (dyn_dyn_mixed &srcObject, int src_idx, dyn_dyn_mixed &dstObject, int dst_idx, dyn_string &exceptionInfo)
void _fwConfigurationDB_ensureDeviceListObjectValid (dyn_dyn_mixed &obj)
void fwConfigurationDB_expandToDeviceListObject (string hierarchyType, dyn_string deviceList, dyn_dyn_mixed &deviceListObject, dyn_string &exceptionInfo)
void _fwConfigurationDB_completeDevicesInHierarchy (dyn_string &deviceList, string hierarchyType, string system, dyn_string &exceptionInfo)
void _fwConfigurationDB_verifyDatapoints (string hierarchyType, dyn_dyn_mixed &deviceListObject, dyn_dyn_mixed &missingDevicesListObject, dyn_string &exceptionInfo, bool checkDeviceLocal=FALSE)
void _fwConfigurationDB_createDevices (dyn_dyn_mixed deviceListObject, string hierarchyType, dyn_string &exceptionInfo)
void _fwConfigurationDB_configureDevices (dyn_dyn_mixed &deviceListObject, string hierarchyType, dyn_string &exceptionInfo, int options=fwConfigurationDB_deviceConfig_ALLDEVPROPS)
void fwConfigurationDB_getReferencesHistory (string configName, string hierarchyType, time startTime, time endTime, dyn_string itemNames, dyn_dyn_mixed &references, dyn_string &exceptionInfo)
void fwConfigurationDB_getDeviceConfigurations (string hierarchyType, dyn_string &confNames, dyn_string &confDescriptions, dyn_int &confIds, dyn_string &exceptionInfo)
int _fwConfigurationDB_checkCreateDeviceConfiguration (string hierarchyType, string confName, string confDescription, dyn_string &exceptionInfo)
void _fwConfigurationDB_checkSaveDpTypes (dyn_string dpTypes, dyn_int &dpTypeIds, dyn_mixed &dpTypeElements, dyn_mixed &dpTypeElementIds, time date, dyn_string &exceptionInfo)
void _fwConfigurationDB_configureFwDevicesWithDefaults (dyn_string &dps, dyn_string &dptypes, dyn_string &models, dyn_string &exceptionInfo)
void _fwConfigurationDB_configureDevicesFromDB (dyn_string &exceptionInfo, int options=fwConfigurationDB_deviceConfig_ALLDEVPROPS)
void _fwConfigurationDB_getIpropIdsInConfiguration (string configurationName, dyn_string &dpes, dyn_int &ipropIds, dyn_string &exceptionInfo)
void fwConfigurationDB_updateDeviceModelsInDB (dyn_string dpList, dyn_string &exceptionInfo, bool updateAliases=TRUE)
int _fwConfigurationDB_selectDevicesToLoad (string configurationName, string hierarchyType, dyn_string &deviceList, dyn_string &exceptionInfo, string topNode="")
int fwConfigurationDB_saveDevicesToDBMinimal (dyn_string &deviceList, dyn_string &exceptionInfo, bool abortWhenDeviceMissing=FALSE)
void fwConfigurationDB_resolveDevices (dyn_string deviceList, dyn_string &devHierarchies, dyn_string &devDatapoints, dyn_string &exceptionInfo, bool errorOnNotFound=TRUE, dyn_string deviceSystems="")

Variables

global string _fwConfigurationDB_fileVersion_fwConfigurationDB_Hierarchies_ctl = "3.5.7"
const int fwConfigurationDB_deviceConfig_VALUE = 1
const int fwConfigurationDB_deviceConfig_ADDRESS = 2
const int fwConfigurationDB_deviceConfig_ALERT = 4
const int fwConfigurationDB_deviceConfig_ARCHIVING = 8
const int fwConfigurationDB_deviceConfig_DPFUNCTION = 16
const int fwConfigurationDB_deviceConfig_CONVERSION = 32
const int fwConfigurationDB_deviceConfig_PVRANGE = 64
const int fwConfigurationDB_deviceConfig_SMOOTHING = 128
const int fwConfigurationDB_deviceConfig_UNITANDFORMAT = 256
const int fwConfigurationDB_deviceConfig_ALLDEVPROPS = 511
const int fwConfigurationDB_deviceConfig_NO_DEVICE_CREATE = 16384
const int fwConfigurationDB_deviceConfig_FW_DEFAULTS = 32768
const int fwConfigurationDB_deviceConfig_ADOPT_TO_SYSTEM = 65536
Indexing constants for deviceListObject variables

The following constants are used to refer to the data in a single row of a deviceListObject variable (a recipeRow).



const int fwConfigurationDB_DLO_DPNAME = 1
const int fwConfigurationDB_DLO_DPTYPE = 2
const int fwConfigurationDB_DLO_NAME = 3
const int fwConfigurationDB_DLO_MODEL = 5
const int fwConfigurationDB_DLO_COMMENT = 6
const int fwConfigurationDB_DLO_ITEMID = 7
const int fwConfigurationDB_DLO_PARENTID = 8
const int fwConfigurationDB_DLO_PARENTDPNAME = 9
const int fwConfigurationDB_DLO_DPID = 10
const int fwConfigurationDB_DLO_REFDP = 11
const int fwConfigurationDB_DLO_REFID = 12
const int fwConfigurationDB_DLO_REF_STATUS = 13
const int fwConfigurationDB_DLO_PROPIDS = 14
const int fwConfigurationDB_DLO_PROPNAMES = 15
const int fwConfigurationDB_DLO_CITEM_ID = 16
const int fwConfigurationDB_DLO_MAX_IDX = 16

Detailed Description

This package contains hierarchy-related functions of the Configuration Database tool

Author:
Piotr Golonka (EN/ICE-SCD)
Date:
October 2012

Function Documentation

void fwConfigurationDB_updateDeviceConfigurationFromDB ( string  configurationName,
string  hierarchyType,
dyn_string &  exceptionInfo,
time  validOn = 0,
dyn_string  deviceList = "",
string  systemName = "",
int  options = fwConfigurationDB_deviceConfig_ALLDEVPROPS 
)
void fwConfigurationDB_getDBHierarchies ( dyn_int &  ids,
dyn_string &  types,
dyn_string &  descriptions,
dyn_string &  validFrom,
dyn_string &  validTo,
dyn_string &  exceptionInfo 
)
void fwConfigurationDB_getHierarchyFromPVSS ( string  rootNode,
string  hierarchyType,
dyn_string &  nodeList,
dyn_string &  exceptionInfo,
string  system = "",
string  includeRootNode = TRUE 
)

Gets the list of children items, in specified hierarchy

Parameters:
rootNode the name of the parent device (item)
hierarchyType the Framework hierarchy type:

  • fwDevice_HARDWARE for Hardware hierarchy
  • fwDevice_LOGICAL for Logical hierarchy (other hierarchies are not supported yet).
nodeList the resulting list of child items will be stored in this variable. Note that this is "append" operation, i.e. the contents of the variable are not cleared from previous content!
exceptionInfo standard exception handling variable
system (optional) the name of the system (for distributed systems); when not specified, the local system is assumed
includeRootNode (optional) determined if the rootNode will be included in the list; if TRUE (default) rootNode will be included, if FALSE - it will not.
See also:
Device lists section of the Quick Start.
void _fwConfigurationDB_copyDeviceListObjectEntry ( dyn_dyn_mixed &  srcObject,
int  src_idx,
dyn_dyn_mixed &  dstObject,
int  dst_idx,
dyn_string &  exceptionInfo 
)

Copies one entry (line) of device object to another device object. if dst_idx=0 this is "append" operation

void _fwConfigurationDB_ensureDeviceListObjectValid ( dyn_dyn_mixed &  obj  ) 
void fwConfigurationDB_expandToDeviceListObject ( string  hierarchyType,
dyn_string  deviceList,
dyn_dyn_mixed &  deviceListObject,
dyn_string &  exceptionInfo 
)

For devices in the deviceList, the DeviceListObject is created, filled with complete information. Note that the function works for the devices that are already in the system (i.e. the function is used when saving hierarchy to DB)

void _fwConfigurationDB_completeDevicesInHierarchy ( dyn_string &  deviceList,
string  hierarchyType,
string  system,
dyn_string &  exceptionInfo 
)

adds the required (parent) devices to the list, puts the hierarchy in order

void _fwConfigurationDB_verifyDatapoints ( string  hierarchyType,
dyn_dyn_mixed &  deviceListObject,
dyn_dyn_mixed &  missingDevicesListObject,
dyn_string &  exceptionInfo,
bool  checkDeviceLocal = FALSE 
)

check if datapoints exist and verify that existing ones have appropriate types and models. Find and group in the missingDevicesListObject the ones that does not exist, report (with exceptionInfo) if some of them exist with incompatible type

void _fwConfigurationDB_createDevices ( dyn_dyn_mixed  deviceListObject,
string  hierarchyType,
dyn_string &  exceptionInfo 
)
void _fwConfigurationDB_configureDevices ( dyn_dyn_mixed &  deviceListObject,
string  hierarchyType,
dyn_string &  exceptionInfo,
int  options = fwConfigurationDB_deviceConfig_ALLDEVPROPS 
)
void fwConfigurationDB_getReferencesHistory ( string  configName,
string  hierarchyType,
time  startTime,
time  endTime,
dyn_string  itemNames,
dyn_dyn_mixed &  references,
dyn_string &  exceptionInfo 
)

Returns the history of hierarchies mapping for specipied period of time, and for certain configuration.

Parameters:
configName the name of static configuration
hierarchyType type of hierarchy (eg. fwDevice_LOGICAL)
startTime start of queried period of time
endTime end of queried period of time. Passing 0 as a parameter means: up to now
itemNames list of logical names of devices being queried
references the result will be put in this variable on return; explanation of the output format below
exceptionInfo standard exception handling variable

The data returned by the function has a format of 4-column array:

  • references[1] contain item names (in logical view)
  • references[2] contain corresponding dp names from hardware view
  • references[3] contain the start of validity period for this mapping
  • references[4] contain the end of validity period for this mapping

The rows are sorted by logical dpname and start of validity.

Example:

references[1]

references[2]

references[3]

references[4]

SubSys/straw1

dist_1:CAEN/crate01/board00/channel001

5 Jan 2006

6 Jan 2006

SubSys/straw1

dist_1:CAEN/crate01/board00/channel011

6 Jan 2006

10 Jan 2006

SubSys/straw1

dist_1:CAEN/crate01/board10/channel001

10 Jan 2006

SubSys/straw2

dist_1:CAEN/crate01/board01/channel002

5 Jan 2006

SubSys/straw3

dist_1:CAEN/crate01/board01/channel003

5 Jan 2006

In this example, one can see that the SubSys/straw1 aparently had some problems: it was initially mapped to first channel of first board, then on 6th of January 2006, reconnected to eleventh channel of first board, then again, on 10th of January 2006 it was reconnected to first channel of tenth board, and stays as such since then. The other two straws were not touched and stay connected to channel 2 and 3 on first board...

void fwConfigurationDB_getDeviceConfigurations ( string  hierarchyType,
dyn_string &  confNames,
dyn_string &  confDescriptions,
dyn_int &  confIds,
dyn_string &  exceptionInfo 
)
int _fwConfigurationDB_checkCreateDeviceConfiguration ( string  hierarchyType,
string  confName,
string  confDescription,
dyn_string &  exceptionInfo 
)
Returns:
the device configuration id (CONF_ID);
void _fwConfigurationDB_checkSaveDpTypes ( dyn_string  dpTypes,
dyn_int &  dpTypeIds,
dyn_mixed &  dpTypeElements,
dyn_mixed &  dpTypeElementIds,
time  date,
dyn_string &  exceptionInfo 
)
void _fwConfigurationDB_configureFwDevicesWithDefaults ( dyn_string &  dps,
dyn_string &  dptypes,
dyn_string &  models,
dyn_string &  exceptionInfo 
)
void _fwConfigurationDB_configureDevicesFromDB ( dyn_string &  exceptionInfo,
int  options = fwConfigurationDB_deviceConfig_ALLDEVPROPS 
)
void _fwConfigurationDB_getIpropIdsInConfiguration ( string  configurationName,
dyn_string &  dpes,
dyn_int &  ipropIds,
dyn_string &  exceptionInfo 
)
void fwConfigurationDB_updateDeviceModelsInDB ( dyn_string  dpList,
dyn_string &  exceptionInfo,
bool  updateAliases = TRUE 
)

Updates the device models in the database to the current ones

Parameters:
dpList the list of datapoint names, for which the model is to be changed. Note that if the datapoin
exceptionInfo standard framework exception-handling variable
updateAliases (optional, default TRUE), determines if the models for LOGICAL devices which correspond to the specified datapoints should also be updated.

: Use with care and cautiously, of what the implications could be! To be used from the dedicated device-conversion panels, such as the ones for the fwWiener component.

int _fwConfigurationDB_selectDevicesToLoad ( string  configurationName,
string  hierarchyType,
dyn_string &  deviceList,
dyn_string &  exceptionInfo,
string  topNode = "" 
)

Selects the devices to be loaded, prepares the data in ConfDB data-exchange tables.

There are two ways to specify the list of devices:

  • explicitly: by passing it as input in deviceList parameter
  • look-up in the DB: specify the top node, such as the system name; this mode is activated by the fact of passing empty deviceList on input (on output it will be populated with device names); the topNode parameter should be passed: if left empty, the name of the current system will be taken.

Then a cross-check is done on the deviceList passed on input: if all devices indeed exist in the specified configuration, the deviceList parameter, then they are sorted alphabeticaly (so that on return the deviceList param DIFFERS than the one on input) all the preparation is done and return code of zero is returned. However, if some of devices passed in deviceList are not present in the database, they will be skipped - on return a modified deviceList parameter will have the valid one, and the return value from the function will be 1

Return codes less than zero signify an error - details in exceptionInfo

int fwConfigurationDB_saveDevicesToDBMinimal ( dyn_string &  deviceList,
dyn_string &  exceptionInfo,
bool  abortWhenDeviceMissing = FALSE 
)

Stores "minimal" information about the devices to DB

This function stores minimal information about devices into the DB, so that recipes for these devices may also be stored.

Parameters:
[in,out] deviceList - list of names of devices; may include a mixture of devices from the HARDWARE and LOGICAL hierarchies; on exit, it will contain the list of devices that were actually stored/verified, namely: the non-existing devices are removed from the list, and devices that are needed to satisfy the hierarchical constraints (parents, grandparents,...) are added to the list
[out] exceptionInfo - standard exception-handling parameter
[in] abortWhenDeviceMissing (optional, default FALSE) - if set to TRUE, the function will abort (and return an error) if some of specified devices does not exist, i.e. it will not store the good ones in the database; otherwise (the default behaviour), the missing devices will be skipped, the good ones will be stored in the database, and the return value of 1 will signify that there were missing devices.
Return values:
0 - everything OK: all devices are in DB now
1 - some devices in the deviceList do not exist, and were skipped; the list of them is in the exceptionInfo; apart from that, everything was OK
-1 - there was an error while storing the devices; details in the exceptionInfo

How to handle the return value and the exceptionInfo, when the abortWhenDeviceMissing parameter is FALSE. This example shows how to make sure that the recipeObject can be saved to DB. The devices that exist - are saved. For all devices that are missing, we post-process the recipeObject to remove the data for non-existing devices, then save the recipeObject to DB

    dyn_dyn_mixed recipeObject;
    // ... get the recipe into the recipeObject somehow...

    dyn_string deviceList=recipeObject[fwConfigurationDB_RO_DP_NAME];

    int rc=fwConfigurationDB_saveDevicesToDBMinimal(deviceList,exceptionInfo,FALSE);
    if (rc!=0) {
      // means something happen
      if (rc==-1) {
        fwExceptionHandling_display(exceptionInfo);
        // abort!
        return FALSE;
      } else if (rc==1) {
        // it is still OK, even though some of the devices were missing:
        // we choose not to display the exception, but only print a message to a log
        DebugN("There were some missing devices - the others were saved OK");
        // post-process the recipeObject, to remove the missing devices...
        // the good ones are returned in the (modified!) deviceList
        for (int i=1;i<=dynlen(recipeObject[fwConfigurationDB_RO_DP_NAME]);i++) {
          string dev=recipeObject[fwConfigurationDB_RO_DP_NAME][i];
          if (!dynContains(deviceList,dev)) {
            // remove the line from all data columns of the recipeObject
            for (int j=1;j<=fwConfigurationDB_RO_MAXIDX;j++) {
              dynRemove(recipeObject[j],i);
             }
             i--;//reset iterator
           }

         }
      }
    }

    // we could save the recipe into the DB now...
    fwConfigurationDB_saveRecipeToDB(recipeObject,"","MyTestRecipe",exceptionInfo);
    if (dynlen(exceptionInfo)){fwExceptionHandling_display(exceptionInfo);return;};
void fwConfigurationDB_resolveDevices ( dyn_string  deviceList,
dyn_string &  devHierarchies,
dyn_string &  devDatapoints,
dyn_string &  exceptionInfo,
bool  errorOnNotFound = TRUE,
dyn_string  deviceSystems = "" 
)

Resolves device names

This functions takes the list of device names - devices being in either hierarchy, and tells what are the actual hierarchy to which they belong, and what are the datapoint to which they refer


Variable Documentation

{@ contains model name for framework devices, "DATAPOINT" if this is a non-framework data point, "SYSTEM" if this is a top-node of hierarchy


Generated on 4 Oct 2012 for Configuration Database component by  doxygen 1.6.1