fwRDBArchiver  8.4.0
fwRDBArchiver.ctl File Reference

Functions

int fwRDBArchiver_convertToParallelArchiving (string db, string user, string password, dyn_string &exceptionInfo)
 
int fwRDBArchiver_convertToOracle (string db, string user, string password, dyn_string &exceptionInfo)
 
bool fwRDBArchiver_isRDBArchive ()
 
bool fwRDBArchiver_isParallelArchive ()
 
int fwRDBArchiver_checkCredentials (string db, string user, string password, dyn_string &exceptionInfo)
 
int fwRDBArchiver_convertPasswordEncodingToHexadecimal (bool passwordConvertedToUnicode, dyn_string &exceptionInfo, bool forceConversion=false)
 
bool _fwRDBArchiver_isPasswordHexadecimal (const string &encryptedPassword)
 
int fwRDBArchiver_configRDB (string db, string user, string password, dyn_string &exceptionInfo)
 
int _fwRDBArchiver_manageManagers (dyn_string &exceptionInfo)
 
int _fwRDBArchiver_addRDBManager (dyn_string &exceptionInfo)
 
int _fwRDBArchiver_hasRDBManager (dyn_string &exceptionInfo)
 
int _fwRDBArchiver_deactivateFileArchive (string fileType, dyn_string &exceptionInfo)
 
int fwRDBArchiver_fetchStatistics (int timerangeMode, string group, time start, time stop, string schema, dyn_dyn_anytype &stats, dyn_string &exceptionInfo)
 
int fwRDBArchiver_fetchDPEStatistics (string dpe, int timerangeMode, string group, time start, time stop, string schema, dyn_dyn_anytype &stats, dyn_string &exceptionInfo)
 
string _fwRDBArchiver_getSQLPeriod (int timerangeMode, time start, time stop)
 
string _fwRDBArchiver_timeToOracle (time t)
 
int fwRDBArchiver_listRDBUsers (dyn_string &userList, dyn_string &exceptionInfo)
 
int fwRDBArchiver_getLocalSchemaName (string &schemaName, dyn_string &exceptionInfo)
 
int fwRDBArchiver_getArchiveGroups (string schema, dyn_string &archiveGroups, dyn_string &exceptionInfo)
 
int _fwRDBArchiver_setConfigFileValue (string section, string key, mixed value, bool replace, dyn_string &exceptionInfo)
 
int _fwRDBArchiver_setConfigFileMultipleValues (string section, mapping options, bool replace, dyn_string &exceptionInfo)
 
int fwRDBArchiver_compareAndCompleteArchiveGroups (dyn_string &exceptionInfo)
 
int fwRDBArchiver_enableMultipleVAForwarding (dyn_int VANumbers, dyn_string &exceptionInfo)
 
int fwRDBArchiver_enableVAForwarding (int VANum, dyn_string &exceptionInfo)
 

Detailed Description

Library which provides a set of functions in order to manage RDB configuration

Author
CERN BE-ICS
Version
8.2.1
Date
June 2018

Function Documentation

int fwRDBArchiver_convertToParallelArchiving ( string  db,
string  user,
string  password,
dyn_string &  exceptionInfo 
)
Reconfigures the project to use RDB+Valarch parallel archiving
Returns
INTEGER - 0 if no error, a negative number in case of error
Reviewed:
2018-06-21 StandaloneTool used in the fwRDBSettingsParallelSCADAR component of SAS

The status of this function should be reviewed with SCADA Application Service, to determine if it is still needed. In particular, with NextGenArchiver coming in near future, parallel archiving will be achieved in a different way.

int fwRDBArchiver_convertToOracle ( string  db,
string  user,
string  password,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_convertToOracle

Returns
INTEGER - 0 if no error, a negative number in case of error.
bool fwRDBArchiver_isRDBArchive ( )

fwRDBArchiver_isRDBArchive

Returns
Return true if the project is already configured with RDB archiving.
bool fwRDBArchiver_isParallelArchive ( )

fwRDBArchiver_isRDBArchiveParallel

Returns
Return true if the project is already configured with parallel archiving.
int fwRDBArchiver_checkCredentials ( string  db,
string  user,
string  password,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_checkCredentials

Returns
Return true if DB credentials are correct.
int fwRDBArchiver_convertPasswordEncodingToHexadecimal ( bool  passwordConvertedToUnicode,
dyn_string &  exceptionInfo,
bool  forceConversion = false 
)

This function converts RDB password from binary to hexadecimal encoding.

The password is retrieved from _RDBArchive.db.password DPE and written back to it after the conversion. If the password is already encoded in hexadecimal form, by default the function doesn't do anything. As there is a possibility, albeit extremely low, that a binary-encoded password may only consist of hex characters, an option to force the conversion is provided if the caller is sure that the password is in fact binary-encoded.

Depending on 3.15 -> 3.16 project migration method used, binary data stored in the encrypted password string can be left unchanged, as it is the case when ASCII export/import is used, or changed, when Project Upgrade tool in Project Administrator is used. If the binary form of the password has been converted to UTF-8, passwordConvertedToUnicode argument should be set to true in order for the conversion process to work correctly.

Rule of thumb for using the function:

  • In 3.15 project that uses ISO-8859-1 encoding: call with passwordConvertedToUnicode == false.
  • In 3.16 project, upgraded from 3.15 project using Project Upgrade tool in Project Administrator: call with passwordConvertedToUnicode == true.
  • In 3.16 project, into which _RDBArchive.db.password DPE was imported using ASCII import: call with passwordConvertedToUnicode == false.
  • In 3.16 project, created from scratch (_RDBArchive.db.password DPE not ASCII imported from an ISO-encoded project): call with passwordConvertedToUnicode == false.

Note that after the conversion all old clients (older than P018 for 3.15 and P008 for 3.16) will not be able to establish the connection to RDB, as they expect the encrypted password to be binary-encoded.

More information on RDB password encryption mechanism change and ISO to UTF-8 conversion can be found at https://indico.cern.ch/event/802974/contributions/3361422/attachments/1814373/2964787/PasswordEncodingJcopFwwg.pdf and https://indico.cern.ch/event/822983/contributions/3459591/attachments/1859873/3056230/ISO_to_UTF8.pdf

Parameters
passwortConvertedToUnicodeShould be set to true if encrypted password was converted to UTF-8 and it has to be re-encoded as ISO-8859-1 before the conversion.
exceptionInfoDetails of any errors are returned here.
forceConversionPerform the conversion also if the password is already hex-encoded.
Returns
INTEGER - 0 if conversion was successful, 1 - if no conversion was necessary, a negative number in case of error (check exceptionInfo).
bool _fwRDBArchiver_isPasswordHexadecimal ( const string &  encryptedPassword)

This function checks if encrypted password string only contains hex characters.

Parameters
encryptedPasswordstring to be checked.
Returns
bool - true if the string contains only hexadecimal characters, false otherwise.
int fwRDBArchiver_configRDB ( string  db,
string  user,
string  password,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_configRDB

This function configure PVSS to use the RDB archiver.

The config file will be completed with the following entries: [general] useRDBArchive = 1 useRDBGroups = 1

[ui] CtrlDLL = "CtrlRDBArchive" CtrlDLL = "CtrlRDBCompr"

[ctrl] CtrlDLL = "CtrlRDBArchive" CtrlDLL = "CtrlRDBCompr"

[ValueArchiveRDB] DbType = "ORACLE" writeWithBulk = 1 Db = "TheSpecifiedDP" DbUser = "TheSpecifiedUser"

The RDB configuration will be completed with the given password for the database (encrypted). The DataManager configuration will be completed by setting the relevant DPEs.

Parameters
dbThe Oracle TNS name for the database.
userThe user name (or schema name) for the database.
passwordThe password in clear text associated to the database account.
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int _fwRDBArchiver_manageManagers ( dyn_string &  exceptionInfo)

fwRDBArchiver_manageManagers.

Parameters
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int _fwRDBArchiver_addRDBManager ( dyn_string &  exceptionInfo)

_fwRDBArchiver_addRDBManager.

Parameters
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int _fwRDBArchiver_hasRDBManager ( dyn_string &  exceptionInfo)

_fwRDBArchiver_hasRDBManager

Parameters
exceptionInfoDetails of any errors are returned here.
Returns
BOOLEN - 1 if manager already exists, 0 if there is no manager, a negative value in case of error.
int _fwRDBArchiver_deactivateFileArchive ( string  fileType,
dyn_string &  exceptionInfo 
)

_fwRDBArchiver_deactivateFileArchive

Parameters
fileTypeDesignate the type of file archive ("_Event" or "_Alert" for instance).
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error.
int fwRDBArchiver_fetchStatistics ( int  timerangeMode,
string  group,
time  start,
time  stop,
string  schema,
dyn_dyn_anytype &  stats,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_fetchStatistics

This function get statistics from a RDB schema about the usage of all the archived datapoints.

Time range mode is one of the constants fwRDBArchiver_timerange_* (defined at the beginning of this file).

  • "1hour", "1day", "1week" and "1month" are fairly self-explained. They are using SQL functions. Thus you don't need to specify valid start and stop parameters. Reference point is taken at the moment of execution of the query.
  • "explicit" means that you explicitly give the start and stop parameters to define the time range.

In all cases time zone and daylight saving are properly handled by the function.

The results are available in the output parameters stats. It is an array of array. Each of these nested array contains two elements:

  • The datapoint name.
  • The number of value archived.
Parameters
timerangeModeOne of the fwRDBArchiver_timerange_* constant.
groupThe RDB table group you want to fetch ("EVENT" for normal DPE, "ALERT" for alerts).
startThe starting time of the range if timerangeMode is "explicit".
stopThe ending time of the range if timerangeMode is "explicit".
schemaSpecify the RDB schema (you must have read rights on it). Blank ("") equal to the schema locally used by the project.
statsOUTPUT - The statistics returned by the database.
exceptionInfoOUTPUT - Details of any error are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_fetchDPEStatistics ( string  dpe,
int  timerangeMode,
string  group,
time  start,
time  stop,
string  schema,
dyn_dyn_anytype &  stats,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_fetchDPEStatistics

This function get statistics from a RDB schema about the usage of one archived datapoint.

Time range mode is one of the constants fwRDBArchiver_timerange_* (defined at the beginning of this file).

  • "1hour", "1day", "1week" and "1month" are fairly self-explained. They are using SQL functions. Thus you don't need to specify valid start and stop parameters. Reference point is taken at the moment of execution of the query.
  • "explicit" means that you explicitly give the start and stop parameters to define the time range.

In all cases time zone and daylight saving are properly handled by the function.

The result is available in the output parameters stats. It is an array of array. The length of the outer array is zero if no result (datapoint is not archived or no value has been archived over the period for instance), or one (one nested array) if results. This nested array contains five elements:

  • The minimum value archived over the period (blank if the DPE is a string).
  • The maximum value archived over the period (blank if the DPE is a string).
  • The average value archived over the period (blank if the DPE is a string).
  • The first time a value has been archived over the period (in UTC!).
  • The last time a value has been archived over the period (in UTC!).
Parameters
dpeThe DPE for which you want detailed statistics.
timerangeModeOne of the fwRDBArchiver_timerange_* constant.
groupThe RDB table group you want to fetch ("EVENT" for normal DPE, "ALERT" for alerts).
startThe starting time of the range if timerangeMode is "explicit".
stopThe ending time of the range if timerangeMode is "explicit".
schemaSpecify the RDB schema (you must have read rights on it). Blank ("") equals to the schema locally used by the project.
statsOUTPUT - The statistics returned by the database.
exceptionInfoOUTPUT - Details of any error are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
string _fwRDBArchiver_getSQLPeriod ( int  timerangeMode,
time  start,
time  stop 
)

_fwRDBArchiver_getSQLPeriod

Parameters
timerangeModeOne of the fwRDBArchiver_timerange_* constant.
startThe starting time of the range if timerangeMode is "explicit".
stopThe ending time of the range if timerangeMode is "explicit".
Returns
The piece of SQL that correspond to the given time range.
string _fwRDBArchiver_timeToOracle ( time  t)

_fwRDBArchiver_timeToOracle

Parameters
tThe time variable to convert to Oracle SQL format
Returns
The piece of SQL that correspond to the given time.
int fwRDBArchiver_listRDBUsers ( dyn_string &  userList,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_listRDBUsers

This function will give you the list of RDB users in the database, which can be roughly considered as the list of RDB schemas.

You need to configure the connection to RDB in PVSS first to use this function. You also need to be connected with a user who has right to access the SYS.ALL_TABLES table in the database.

Parameters
userListOUTPUT - An array with RDB users.
exceptionInfoOUTPUT - Details of any error are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_getLocalSchemaName ( string &  schemaName,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_getLocalSchemaName

This function gives you the locally configured user/schema name for RDB.

Parameters
schemaNameOUTPUT - The user/schema name.
exceptionInfoOUTPUT - Details of any error are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_getArchiveGroups ( string  schema,
dyn_string &  archiveGroups,
dyn_string &  exceptionInfo 
)

fwRDBArchiver_getArchiveGroups

This function will give you the list of RDB archive groups in a specific schema.

You need to configure the connection to RDB in PVSS first to use this function. You also need to be connected with a user who has right to access the tables of other RDB schemas if you want to look inside foreign schemas.

Parameters
schemaSpecify the RDB schema (you must have read rights on it). Blank ("") equals to the schema locally used by the project.
archiveGroupsOUTPUT - An array with the archive groups of the schema.
exceptionInfoOUTPUT - Details of any error are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int _fwRDBArchiver_setConfigFileValue ( string  section,
string  key,
mixed  value,
bool  replace,
dyn_string &  exceptionInfo 
)

This function set a value for a key in the config file of the project. It allows the replacement of all existing keys before, or allows to add it as a value list (parameter "replace"). If the (key,value) pair already exists, nothing will be done.

Parameters
sectionThe section under which the key will be added.
keyThe key to add.
valueThe value associated to the key.
replaceIf true, delete all previous occurrences of the key before adding the new value. If false, just add the value.
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int _fwRDBArchiver_setConfigFileMultipleValues ( string  section,
mapping  options,
bool  replace,
dyn_string &  exceptionInfo 
)

This function allows to set multiple values to a section of the config file of the project. It uses a mapping as input. It allows the replacement of all existing keys before, or allows to add them as a value list (parameter "replace"). If a (key,value) pair already exists, it will not be inserted.

Parameters
sectionThe section under which the keys will be added.
optionsAll the options to set (mapping type, key:value).
replaceIf true, delete all previous occurences of the keys before adding the new value. If false, just add the value.
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_compareAndCompleteArchiveGroups ( dyn_string &  exceptionInfo)

This function compares which arc groups are defined in the DB and in the project and complete the setup if there are differences

Parameters
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_enableMultipleVAForwarding ( dyn_int  VANumbers,
dyn_string &  exceptionInfo 
)

This function creates if necessary arc groups for the parallel archiving of value archivers

Parameters
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error, a negative number in case of error (check exceptionInfo).
int fwRDBArchiver_enableVAForwarding ( int  VANum,
dyn_string &  exceptionInfo 
)

This function enables forwarding for the value archiver

Parameters
VANumnumber of the archiver to enable the forwarding
exceptionInfoDetails of any errors are returned here.
Returns
INTEGER - 0 if no error or arc group already exits, a negative number in case of error (check exceptionInfo).