GETARCHARR_TO_CNT action


Function
Reading a value block of specified historical values within given time interval.
Declaration
 GETARCHARR_TO_CNT archIdent, _retCNTHandle, pageSize, timeFromIdent_TmA, timeToIdent_TmA, stepIdent_Int, maxValsIdent_Int, statusIdent_Int[, archivInstance_Int]
Parameters
archIdentinReference to one value of historical value, reference to object or item identifier of Structured variable type object (note: values of object or item must be archived).

Warning: If the parameter is the reference to an object archived several times, there is not specified which one of the historical objects is to be used.

retCNTHandleoutVariable which will contain the identifier of data container after the successful loading.
pageSizeoutRequired size of one page.
timeFromItemIdent_TmAnIdentifier of AbsTime type for the interval beginning.
timeToItemIdent_TmAinIdentifier of AbsTime type for the interval end.
stepIdentinIdentifier of Int type - time step for the oversampling of values in the archive.
maxValsIdent_IntinMaximal number of values. If more values is in the required interval, they will be trimmed and the action returns the warning _ERR_MORE_DATA in the identifier statusIdent_Int.
statusIdent_IntoutAction success.
archivInstance_IntinOptional identifier of Int type - identification of archive instance. If the parameter is not defined, the value 0 will replace it.
Description

The action reads values of the historical value archIdent within the time interval from timeFromIdent_TmA to timeToIdent_TmA with the steps stepIdent_Int (given in seconds). Maximal number of values is given by the identifier maxValsIdent_Int.
It arranges the read archival values to so-called pages, each of them containing upto pageSize values. Individual pages are put into data container, which is created by action internally. Identifier (integer value) is given through return parameter retCNTHandle. The user is responsible for deleting of container.
This action creates a container every time the non-zero number of values were read (the values were read even if statusIdent_Int had been set to the value _ERR_MORE_DATA).

Data container crated by GETARCHARR_TO_CNT action contains the values on the individual pages and in memory-optimal structure that is why this action is more suitable if it works with bulk data.
The pages are identified by integral value starting 1. The calling of CNT_GETNR action detects the number of pages.
CNT_FIND action accesses to the pages. The output parameter _value must be a local structured variable (the action changes the size as necessary).
If it consists of one column, it will be filled by values (with time stamp).
If it consists of two columns, the first one will be filled by values (with time stamp) and the second one by archival flags.
If it consists of more columns, they will not be initialized.
CNT_DESTROY action clears the container.

Other CNT_* actions are disabled for the container made this way. Otherwise it causes the run-time error _ERR_INVALID_HANDLE.

The parameter stepIdent_Int defines the oversampling (in seconds) of read values. If it is equal to 0, reading is not to be oversampled.

If the parameter archIdent is the reference to an object of Historical value type, the action performance is described above. If the parameter is the reference to an object (not of Historical value type) or a structured variable item that is not of Object type, the system is attempting to find an object of Historical value type that archives values of the object (item).
If the parameter archIdent is the reference to a structured variable item that is of Object type, the item "points" to an object in the system. If the object is of Historical value type, the action will read data from it. If it is not, the system is attempting to find an object of Historical value type that archives values of the object.


The return code statusIdent_Int can get one of the following values:


  • _ERR_TRANS_ABORT
  • _ERR_TRANS_ERROR
  • _ERR_TRANS_IGNORED
  • _ERR_NO_ERROR
  • _ERR_NO_DATA - no data within given interval
  • _ERR_MORE_DATA - more data than maxValsIdent_Int within given interval
  • _ERR_OBJECT_IS_NOT_IN_ARCHIVE


The error _ERR_MORE_DATA has only informative character and the required number of data is available.

The value of the parameter stepIdent_Int specifies resampling interval (in seconds). Value of 0 means that the read values are not to be resampled.


Value of parameter archivInstance_Int defines the instance of archive which executes the request. If the parameter is not defined (or the value is 0), the active instance of archive will execute the request.


Example
The following example demonstrates the applying of actions GETARCHARR and GETARCHARR_TO_CNT:

E.GetArch, H.SingleStorage, SD.ArchVal, SD.ArchValOne, SD.ArchValOneBool

0 komentárov

Nie ste prihlásený. Akékoľvek zmeny, ktoré vykonáte, sa označia ako anonymné. Ak už máte svoj účet, pravdepodobne sa budete chcieť prihlásiť .