Configuration Database component
Functions | Variables
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)
 
void fwConfigurattionDB_deleteDeviceConfiguration (string confName, dyn_string &exceptionInfo, bool deleteOldOnly=false)
 
void fwConfigurationDB_deleteDeviceConfiguration (string confName, dyn_string &exceptionInfo, bool deleteOldOnly=false)
 
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 ="7.0.0"
 
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_ALIAS = 512
 
const int fwConfigurationDB_deviceConfig_ALLDEVPROPS = 1023
 
const int fwConfigurationDB_deviceConfig_ALIAS_FWDEVICE = 4096
 
const int fwConfigurationDB_deviceConfig_ALERTCLEANUP = 8192
 
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 (BE/ICS-SDS)
Date
July 2016

(c) Copyright CERN, All Rights Reserved

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
rootNodethe name of the parent device (item)
hierarchyTypethe Framework hierarchy type:
  • fwDevice_HARDWARE for Hardware hierarchy
  • fwDevice_LOGICAL for Logical hierarchy (other hierarchies are not supported yet).
nodeListthe 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!
exceptionInfostandard 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
configNamethe name of static configuration
hierarchyTypetype of hierarchy (eg. fwDevice_LOGICAL)
startTimestart of queried period of time
endTimeend of queried period of time. Passing 0 as a parameter means: up to now
itemNameslist of logical names of devices being queried
referencesthe result will be put in this variable on return; explanation of the output format below
exceptionInfostandard 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 
)
void fwConfigurattionDB_deleteDeviceConfiguration ( string  confName,
dyn_string &  exceptionInfo,
bool  deleteOldOnly = false 
)

version with improper spelling, for backward compatibility, FWCDB-1102

void fwConfigurationDB_deleteDeviceConfiguration ( string  confName,
dyn_string &  exceptionInfo,
bool  deleteOldOnly = false 
)
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
dpListthe list of datapoint names, for which the model is to be changed. Note that if the datapoin
exceptionInfostandard 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

global string _fwConfigurationDB_fileVersion_fwConfigurationDB_Hierarchies_ctl ="7.0.0"
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_ALIAS = 512
const int fwConfigurationDB_deviceConfig_ALLDEVPROPS = 1023
const int fwConfigurationDB_deviceConfig_ALIAS_FWDEVICE = 4096
const int fwConfigurationDB_deviceConfig_ALERTCLEANUP = 8192
const int fwConfigurationDB_deviceConfig_NO_DEVICE_CREATE = 16384
const int fwConfigurationDB_deviceConfig_FW_DEFAULTS = 32768
const int fwConfigurationDB_deviceConfig_ADOPT_TO_SYSTEM = 65536
const int fwConfigurationDB_DLO_DPNAME = 1
const int fwConfigurationDB_DLO_DPTYPE = 2
const int fwConfigurationDB_DLO_NAME = 3
fwConfigurationDB_DLO_MODEL = 5

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

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