OpenSCADAWiki: Home Page En/Doc/API/part5 ...

5. Subsystem "Archives" (TArchiveS)

Subsystem "Archives" is represented by an object TArchiveS, which contains at the subsystem level the modular objects of the archivers types TTypeArchivator. Each object of the archiver type contains objects of the messages' archivers TMArchivator and values' archivers TVArchivator. In addition, the subsystem object contains the methods of the messages archive and objects of the values' archives TVArchive. The object of the values' archive TVArchive contains the buffer of values through the inheritance of the buffer object TValBuf. To connect the archive of values with the archivers the object of the value element TVArchEl is provided. This object is contained in the archiver and it is referenced by the archive. Structure of the subsystem "Archives" is presented in Fig. 5.

Fig. 5. The hierarchical structure of subsystem "Archives".

Subsystem "Archives" contains the mechanisms for archiving of messages and values. It directly contains the messages' archive together with its buffer. Contains methods for accessing the archives of the values and for the archivers of values and messages. Besides it performs the actively data acquisition from sources of values for the archives of values, as well as archiving the archive of messages by the archivers.

Archive of values (TVArchive) contains the buffer (TValBuf) for intermediate values' accumulation before archiving. It is connected with the source of values in the person of OpenSCADA system parameters in active or passive mode, as well as with other sources in the passive mode. To archive to the physical storage it is connected with the values' archivers of various types.

Object of the buffer TValBuf contains an array of values of the main types of OpenSCADA system: string, integer, real and boolean. It is supported the storage of values in the modes of hard, soft grid and in the free access mode. It is also provided the mode of high-resolution time (microseconds). It is used for direct storage of large arrays of values, and for the exchange of large arrays by the frame-accurate method of access.

Root object of the module of subsystem "Archives" (TTypeArchivator) contains information about the specific type of module. Within the individual modules it can implement their own module-wide functions. In general, for modules of this type it contains methods to access the repositories of values and messages.

Object of the messages' archiver (TMArchivator) contains the specific implementation of the message storage. In general, for messages' archivers the interface of access to the implementation of an archiving mechanism in modules is provided.

Object of the values' archiver (TVArchivator) contains the specific implementation of the repository of values. In general, for the values' archivers the access interface to implementation of the archiving mechanism and the appointment of archives of values for service by archiver are provided.

Object of the archive element TVArchEl links the archive objects with the archivers. It is used to access the archiver from the archive, as well as to archives from the archiver, ie for cross-calls.

5.1. The object of the subsystem "Archives" (TArchiveS)

Public methods:

• int subVer( ); — Subsystem's version.
• int messPeriod( ); — Period of archiving of messages from the buffer (seconds).
• int valPeriod( ); — Acquisition of values period for the active archivers (milliseconds).
• int valPrior( ); — Priority of the tasks of the values acquisition for the active archivers.
• bool valForceCurTm( ); — Points to force of current time as the time-stamp of the getting values.
• void setMessPeriod( int ivl ); — Setting the period of the archiving of messages from the buffer (seconds).
• void setValPeriod( int ivl ); — Setting the values' acquisition period for active archivers (milliseconds).
• void setValPrior( int ivl ); — Setting the priority of the values' acquisition task for the active archivers.
• void setValForceCurTm( bool vl ); — Force of current time as the time-stamp of the getting values.
• void setToUpdate( ); — Planing update flag set.
• void subStart( ); — Start of the subsystem.
• void subStop( ); — Stop of the system.
• void valList( vector<string> &list ); — The list of the values'archives in the subsystem.
• bool valPresent( const string &iid ); — Check for the availability of the values' archive iid.
• void valAdd( const string &iid, const string &idb = "*.*" ); — Addition of the new values' archive iid.
• void valDel( const string &iid, bool db = false ); — Deleting of the values' archive iid.
• AutoHD<TVArchive> valAt( const string &iid ); — Connection/addressing to the values' archive iid.
• void setActMess( TMArchivator *a, bool val ); — Setting of the messages archivator a into the active status val. Active archivator will be provided by the subsystem with the flow of messages.
• void setActVal( TVArchive *a, bool val ); — Setting of the value archive a into the active status val. Active archive will be provided by the subsystem with the periodic flow of values (is determined by the periodicity of the archive).
• AutoHD<TTypeArchivator> at( const string &name ); — Connection/addressing to the archiver's type (module) name.
• void messPut( time_t tm, int utm, const string &categ, int8_t level, const string &mess, const string &arch = "", bool force = false ); — Location of the value mess with the level level of the category categ and time tm+utm into the buffer, and then into the messages' archive or direct to the pointed archivators arch (separated by symbol ';'). force for direct writing to the archivator omit the redundancy.
• void messPut( const vector<TMess::SRec> &recs, const string &arch = "", bool force = false ); — Location of the group of values recs into the buffer, and then into the messages' archive or direct to the pointed archivators arch (separated by symbol ';'). force for direct writing to the archivator omit the redundancy.
• void messGet( time_t b_tm, time_t e_tm, vector<TMess::SRec> & recs, const string &category = "", int8_t level = TMess::Debug, const string &arch = "", time_t upTo = 0 ); — Values' request reqs for the specified period of time b_tm, e_tm for the specified category (by the template) category and level level from the archivators arch (separated by symbol ';').
• time_t messBeg( const string &arch = "" ); — Beginning of the messages' archive as a whole or for the specified archiver arch.
• time_t messEnd( const string &arch = "" ); — End of the messages' archive as a whole or for the specified archiver arch.
• void rdActArchMList( vector<string> &ls, bool isRun = false ); — The list of active message archivators working in the redundancy scheme. When we indicate isRun there will be in the list only running message archvators in this station.
• string rdStRequest( const string &arch, XMLNode &req, const string &prevSt = "", bool toRun = true ); — Request req to the redundant station on behalf of the message archivator arch. The station for the request is selected after specified in prevSt for the running remotely message archivators when indicating toRun.
• TElem &messE( ); — DB structure of the messages' archivers.
• TElem &valE( ); — DB structure of the values' archivers.
• TElem &aValE( ); — DB structure of the values' archives.

Public methods:

• bool SubStarting; — The subsystem starting flag.

5.2. The object of the values' archive (TVArchive)

Data:
The data acquisition mode/source (struct — TVArchive::SrcMode):

• Passive — passive mode of the data acquisition, the source puts the data into the archive itself;
• PassiveAttr — passive mode of the data acquisition from the parameter's attribute, the parameter's attribute puts the data into the archive itself;
• ActiveAttr — active mode of the data acquisition from the parameter's attribute, the parameter's attribute is periodically polled by the subsystem "Archives";

Public methods:

• TVArchive( const string &id, const string &db, TElem *cf_el ); — Initializing constructor of the archive, where id — archive ID, db — DB for storage and cf_el — DB structure of the values' archives.
• string id( ); — Archive's ID.
• string name( ); — Archive's name.
• string dscr( ); — Archive's description.
• SrcMode srcMode( ); — Linkage mode with the data source.
• AutoHD<TVal> srcPAttr( bool force = false, const string &ipath = "" ); — Connect to associated attribute of parameter of data source.
• string srcData( ); — Parameters of the data source, in the case of access mode to the parameter this is the address of the parameter.
• bool toStart( ); — Sign: "Start the archive when starting the system".
• bool startStat( ); — Status: "Archive started".
• string DB( ); — DB address of the values' archive.
• string tbl( ); — DB table of the values' archive.
• string fullDB( ); — Full name of the DB table of the values' archive.
• int64_t end( const string &arch = BUF_ARCH_NM ); — End of the archive time at whole (arch="") or the specified archiver, buffer (arch="<bufer>").
• int64_t begin( const string &arch = BUF_ARCH_NM ); — Start of the archive time at whole (arch="") or the specified archiver, buffer (arch="<bufer>").
• int64_t period( const string &arch = BUF_ARCH_NM ); — Periodicity of the archive buffer or the specified archiver (microseconds).
• TFld::Type valType( bool full = false ); — Type of the archived value. full — request full type, else only generic.
• bool hardGrid( ); — Using of the hard grid in the archive buffer.
• bool highResTm( ); — Using of the high-resolution time in the archive buffer (microseconds).
• bool fillLast( ); — Fill pass points to a last value. Mostly the pass values fill by EVAL but sometime the source's data periodicity greater to the archive's one and it is normal.
• int size( ); — Archive buffer size (units).
• void setName( const string &inm ); — Setting the name of the archive.
• void setDscr( const string &idscr ); — Setting the description of the archive.
• void setSrcMode( SrcMode vl = SaveCur, const string &isrc = "<*>", bool noex = false ); — Setting the linkage mode with the data source.
• void setToStart( bool vl ); — Setting the sign: "Start the archive when starting the system".
• void setDB( const string &idb ); — Setting the DB address of the values' archive.
• void setValType( TFld::Type vl ); — Setting the type of the archived value.
• void setHardGrid( bool vl ); — Setting the using of the hard grid in the archive buffer.
• void setHighResTm( bool vl ); — Setting of using of the high-resolution time in the archive buffer (microseconds).
• void setFillLast( bool vl ); — Set to fill pass points to a last value.
• void setSize( int vl ); — Setting of the archive buffer size (units).
• void setPeriod( int64_t vl ); — Setting the periodicity of the archive buffer.
• void start( ); — Start of the archive.
• void stop( bool full_del = false ); — Stop of the archive with it's completely deleting full_del.
• TVariant getVal( int64_t *tm = NULL, bool up_ord = false, const string &arch = "", bool onlyLocal = false ); — Request of the single value for the time tm and with the sign of the moving to the top up_ord from the specified archiver arch, buffer (arch = "<bufer>") or from all archivers in the course of falling quality (arch =""). To process the request only by the local station onlyLocal is set.
• void getVals( TValBuf &buf, int64_t beg = 0, int64_t end = 0, const string &arch = "", int limit = 100000, bool onlyLocal = false ); — Request of the values' frame buf for the time from beg to end from the specified archiver arch, buffer (arch = "<bufer>") or from the all archivers in the course of falling quality (arch =""), limiting the size of the request limit of the record. To request only the local archives, without compensation gaps in the archives from the backup stations, set onlyLocal.
• void setVals( TValBuf &buf, int64_t beg, int64_t end, const string &arch ); — Set of the values' frame buf for the time from beg to end to the specified archiver arch, buffer (arch = "<bufer">) or to all archivers (arch ="").
• void getActiveData( const int64_t &tm = 0 ); — To interrogate the data source with forcing time-stamp to tm (not zero). Is used for periodic data acquisition by the active archives in the subsystem.
• void archivatorList( vector<string> &ls ); — List of archivers which serves the archive.
• bool archivatorPresent( const string &arch ); — Check the archiver for it's servicing of the given archive.
• void archivatorAttach( const string &arch ); — Connecting the archive to be served by the specified archiver.
• void archivatorDetach( const string &arch, bool full = false ); — Disabling this archive from the servicing of the specified archiver.
• void archivatorSort( ); — Sort of the serving archivers in the order of decreasing quality.
• string makeTrendImg( int64_t beg, int64_t end, const string &arch, int hsz = 650, int vsz = 230 ); — Building of the (pdf) image of the trend for the specified amount of time beg, end and for this archiver arch.
• TArchiveS &owner( ); — Subsystem "Archives" - the owner of the archive of values.

5.3. Object of the values' buffer (TValBuf)

Public methods:

• TValBuf( ); — Buffer initializer with default settings.
• TValBuf( TFld::Type vtp, int isz, int64_t ipr, bool ihgrd = false, bool ihres = false ); — Buffer initializer with the specified parameters.
• void clear( ); — Cleaning the buffer.
• TFld::Type valType( bool full = false ); — Type of the value stored in the buffer. full — request full type, else only generic.
• bool hardGrid( ); — Hard grid working mode.
• bool highResTm( ); — High resolution (microseconds) working mode of the buffer.
• bool fillLast( ); — Fill pass points to a last value. Mostly the pass values fill by EVAL but sometime the source's data periodicity greater to the archive's one and it is normal.
• int size( ); — Maximum buffer size (units).
• int realSize( ); — Real buffer size (units).
• int64_t period( ); — Frequency of values in the buffer (microseconds). If the frequency is zero the buffer operates in the mode of free access.
• int64_t begin( ); — Start time of the buffer (microseconds).
• int64_t end( ); — End time of the buffer (microseconds).
• bool vOK( int64_t ibeg, int64_t iend ); — Checking for values in the buffer for the specified period of time from ibeg to iend.
• void setValType( TFld::Type vl ); — Setting of the value type stored by the buffer.
• void setHardGrid( bool vl ); — Setting the hard grid mode.
• void setHighResTm( bool vl ); — High resolution (microseconds) working mode setting.
• void setFillLast( bool vl ); — Set to fill pass points to a last value.
• void setSize( int vl ); — Buffer size (units) setting.
• void setPeriod( int64_t vl ); — Frequency of values in the buffer (microseconds) setting.
• virtual void getVals( TValBuf &buf, int64_t beg = 0, int64_t end = 0 ); — Request of the values' frame buf for the time from beg to end.
• TVariant get( int64_t *tm = NULL, bool up_ord = false ); — Request value for the time tm and with the sign of moving to the top up_ord.
• virtual string getS( int64_t *tm = NULL, bool up_ord = false ); — Request of the string type value for the time tm and with the sign of moving to the top up_ord.
• virtual double getR( int64_t *tm = NULL, bool up_ord = false ); — Request of the real type value for the time tm and with the sign of moving to the top up_ord.
• virtual int64_t getI( int64_t *tm = NULL, bool up_ord = false ); — Request of the integer type value for the time tm and with the sign of moving to the top up_ord.
• virtual char getB( int64_t *tm = NULL, bool up_ord = false ); — Request of the boolean type value for the time tm and with the sign of moving to the top up_ord.
• virtual void setVals( TValBuf &buf, int64_t beg = 0, int64_t end = 0 ); — Setting the values' frame from buf fro the time from beg to end.
• void set( const TVariant &value, int64_t tm = 0 ); — Setting value with the time tm.
• virtual void setS( const string &value, int64_t tm = 0 ); — Setting the string type value with the time tm.
• virtual void setR( double value, int64_t tm = 0 ); — Setting the real type value with the time tm.
• virtual void setI( int64_t value, int64_t tm = 0 ); — Setting the integer type value with the time tm.
• virtual void setB( char value, int64_t tm = 0 ); — Setting the boolean type value with the time tm.

Protected methods:

• void makeBuf( TFld::Type v_tp, int isz, int64_t ipr, bool hd_grd, bool hg_res ); — Rebuilding the buffer for the specified parameters.

5.4. The modular object of the archiver's type (TTypeArchivator)

Public methods:

• void messList( vector<string> &list ); — The list of the messages' archivers.
• bool messPresent( const string &iid ); — Check for the presence of the specified messages' archiver.
• void messAdd( const string &iid, const string &idb = "*.*" ); — Adding of the messages' archiver.
• void messDel( const string &iid, bool full = false ); — Deleting of the messages' archiver.
• AutoHD<TMArchivator> messAt( const string &iid ); — Connection to the messages' archiver.
• void valList( vector<string> &list ); — The list of the values' archivers.
• bool valPresent( const string &iid ); — Check for the presence of the specified values' archiver.
• void valAdd( const string &iid, const string &idb = "*.*" ); — Adding of the values' archiver.
• void valDel( const string &iid, bool full = false ); — Deleting of the values' archiver.
• AutoHD<TVArchivator> valAt( const string &iid ); — Connection to the values' archiver.
• TArchiveS &owner( ); — Subsystem "Archives" - the owner of the archiver's type.

Protected methods:

• virtual TMArchivator *AMess( const string &iid, const string &idb ); — The modular method of creating of the messages' archiver.
• virtual TVArchivator *AVal( const string &iid, const string &idb ); — The modular method of creating of the values' archiver.

5.5. The object of the messages' archiver (TMArchivator)

Public methods:

• TMArchivator( const string &id, const string &db, TElem *cf_el ); — Initializing constructor of the messages' archiver with the ID id, for the storage in the database db with the structure <cf_el>.
• string id( ); — Archiver's ID.
• string workId( ); — Working identifier, it includes the name of the module.
• string name( ); — Archiver's name.
• string dscr( ); — Archiver's description.
• bool toStart( ); — The sign "To start the archiver".
• bool startStat( ); — Archivers' status "Run".
• string &addr( ); — Address of the archiver's storage.
• int &level( ); — The level of messages, serviced by the archiver.
• void categ( vector<string> &list ); — Categories (templates) of messages, serviced by the archiver.
• string DB( ); — DB address of the archiver.
• string tbl( ); — Table address of the archiver's DB.
• string fullDB( ); — The full table address of the archiver's DB.
• void setName( const string &vl ); — Setting the archiver's name.
• void setDscr( const string &vl ); — Setting the archiver's description.
• void setToStart( bool vl ); — Setting the sign "To start the archiver".
• void setAddr( const string &vl ); — Setting the address of the archiver's storage.
• void setLevel( int lev ); — Setting the level of messages, serviced by the archiver.
• void setDB( const string &idb ); — Setting the DB adress of the archiver.
• bool redntUse( ); — Getting the data from the backup station mode.
• void setRedntUse( bool vl ); — Changing of the getting the data from the backup station mode.
• Redundant redntMode( ); — Redundancy mode ("<high>", "<low>", "<optimal>", {ForceStation}), enabling.
• void setRedntMode( Redundant vl ); — Setting of the redundancy mode, enabling.
• string redntRun( ); — Configuration of the preferred execution.
• void setRedntRun( const string &vl ); — Setting the configuration of the preferred execution.
• virtual void redntDataUpdate( ); — An operation of the data receiving from the backup station execution. It is called automatically by the service procedure of the redundancy scheme of the subsystem.
• virtual void start( ); — Start of the archiver.
• virtual void stop( ); — Stop of the archiver.
• virtual time_t begin( ); — The beginning of the archive of the specified archiver.
• virtual time_t end( ); — The end of the archive of the specified archiver.
• virtual bool put( vector<TMess::SRec> &mess, bool force = false ); — Place the group of messages in the messages' archive of the specified archivator. Return "true" on successful operation. force for direct writing to the archivator omit the redundancy.
• virtual void get( time_t b_tm, time_t e_tm, vector<TMess::SRec> &mess, const string &category = "", char level = 0, time_t upTo = 0 ); — Get the messages from the archive of the specified archiver for the specified filter parameters.
• TTypeArchivator&owner( ); — Archiver's type – the owner of the messages' archiver.

Protected attributes:

• bool run_st; — Sign "Run".
• int messHead; — The pointer to last read message of the messages buffer.

Protected methods:

• bool chkMessOK( const string &icateg, int8_t ilvl ); — Check the message to the filter conditions.

5.6. The object of the values' archiver (TVArchivator)

Public methods:

• TVArchivator( const string &id, const string &db, TElem *cf_el ); — Initializing constructor of the values' archiver with the ID id, for the storage in the database db with the structure cf_el.
• string id( ); — Archiver's ID.
• string workId( ); — Working identifier, it includes the name of the module.
• string name( ); — Archiver's name.
• string dscr( ); — Archiver's description.
• string addr( ); — Address of the archiver's storage.
• double valPeriod( ); — Frequency of values of the archiver (microseconds).
• int archPeriod( ); — Frequency of the values' archiving by the archiver. Time after which the archiver makes archiving of the frame of values from the archive's buffer.
• int selPrior( ); — Selection priority for mode "All" archivers.
• bool toStart( ); — The sign "To start the archiver".
• bool startStat( ); — Archivers' status "Run".
• string DB( ); — DB address of the archiver.
• string tbl( ); — Table address of the archiver's DB.
• string fullDB( ); — The full table address of the archiver's DB.
• void setName( const string &inm ); — Setting the archiver's name.
• void setDscr( const string &idscr ); — Setting the archiver's description.
• void setAddr( const string &vl ); — Setting the address of the archiver's storage.
• void setValPeriod( double iper ); — Setting the frequency of values of the archiver (microseconds).
• void setArchPeriod( int iper ); — Setting the frequency of the values' archiving by the archiver. Time after which the archiver makes archiving of the frame of values from the archive's buffer.
• void setSelPrior( int vl ); — Set selection priority for mode "All" archivers.
• void setToStart( bool vl ); — Setting the sign "To start the archiver".
• void setDB( const string &idb ); — Setting the DB adress of the archiver.
• virtual void start( ); — Start of the archiver.
• virtual void stop( bool full_del = false ); — Stop of the archiver with the possibility of it's full deleting full_del.
• void archiveList( vector<string> &ls ); — The archive's list, serviced by the archiver.
• bool archivePresent( const string &iid ); — Check for the servicing of the specified archive by the specified archiver.
• TTypeArchivator &owner( ); — Archiver's type – the owner of the values' archiver.

Protected methods:

• TVArchEl *archivePlace( TVArchive &item ); — Add the archive item to the processing by the archiver.
• void archiveRemove( const string &id, bool full = false ); — Remove the archive id from the processing by the archiver, with the possibility of its full deleting full.
• virtual TVArchEl *getArchEl( TVArchive &arch ); — Getting the object of the archive's element for the specified archive.

Protected attributes:

• Res a_res — Resource of the archiving process.
• bool run_st — Sign "Archive is run".
• vector<TVArchEl *> arch_el; — Array of elements of archives.

5.7. The object of the archive's element in the archiver (TVArchEl)

Public methods:

• TVArchEl( TVArchive &iarchive, TVArchivator &iarchivator ); — Initializing constructor fro the connection the archive iarchive with the archiver iarchivator.
• virtual void fullErase( ); — Full deleting of the element.
• virtual int64_t end( ); — End time of data (microseconds).
• virtual int64_t begin( ); — Start time of data (microseconds).
• int64_t lastGet( ); — Time of last transfer of the data from the buffer to the storage.
• TVariant getVal( int64_t *tm, bool up_ord, bool onlyLocal = false ); — Request of the value for the time tm and with the sign of moving to the top up_ord, with the specifying of the request of only local archive in onlyLocal.
• void getVals( TValBuf &buf, int64_t beg = 0, int64_t end = 0, bool onlyLocal = false ); — Request of the values' frame buf for the time from beg to end, with the specifying of the request of only local archive in onlyLocal.
• void setVals( TValBuf &buf, int64_t beg = 0, int64_t end = 0 ); — Setting the values' frame from the buf for the time from beg to end.
• TVArchive &archive( ); — Elements' archive.
• TVArchivator &archivator( ); — Elements' archiver.

Public methods:

• int64_t prev_tm; — The previous value time. It is used for averaging.
• string prev_val; — The previous value time. It is used for averaging.

Protected methods:

• virtual TVariant getValProc( int64_t *tm, bool up_ord ); — The processing function of the single value from the archive request.
• virtual void getValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Function of the processing the request of the module to get the data.
• virtual void setValsProc( TValBuf &buf, int64_t beg, int64_t end ); — Function of the processing the request of the module to set the data.