CONTROL
- Introduction to CTRL
- CONTROL Classes
- Types of Control Functions
- Control graphics
- CONTROL Functions
  - Funtions A
  - Funtions B
  - Funtions C
  - Funtions D
    - dataHost()
      Returns the host name the Data Manager is running on.
    - dataPort()
      Returns the port number of the data manager.
    - day()
      Returns the day of the month.
    - daylightsaving()
      Checks whether the time is winter time or summer time.
    - daySecond()
      Returns the seconds of the day.
    - dbAddNew()
      Database function that generates a new, empty data record.
    - dbBeginTransaction()
      Database function for starting a transaction.
    - dbBulkCommand()
      Summarizes the ADO functions dbStartCommand() (prepares a data manipulation command), dbExecuteCommand() (executes a data manipulation command) and dbFinishCommand() (closes a data manipulation command).
    - dbCloseConnection()
      Function for closing a connection to a data source.
    - dbCloseRecordset()
      Database function for closing a tabular data subset of a data source.
    - dbCommitTransaction()
      Database function for closing a transaction, changes are implemented.
    - dbDelete()
      Database function which deletes the current data record.
    - dbEOF()
      Database function for determining whether the data record pointer has reached the end of the record set.
    - dbExecuteCommand()
      Database function for executing a database manipulation command.
    - dbFinishCommand()
      Database function for releasing a command object.
    - dbGetError()
      Database function that returns the currently waiting error codes and messages.
    - dbGetField()
      Database function which reads a column (field) of the current data record.
    - dbGetRecord()
      Reads the records from a row.
    - dbGetResult()
      Returns all results of an SQL query.
    - dbMove()
      Database function which moves the data record pointer to any record in the record set relative to the current position.
    - dbMoveFirst()
      Database function which moves the data record pointer to the first record in the record set.
    - dbMoveLast()
      Database function which moves the data record pointer to the last record in the record set.
    - dbMoveNext()
      Database function which moves the data record pointer to the next record in the record set.
    - dbMovePrevious()
      Database function which moves the data record pointer to the previous record in the record set.
    - dbOpenConnection()
      Database function for opening a connection to a data source.
    - dbOpenRecordset()
      Database function for opening a tabular data subset of a data source.
    - dbPutField()
      Database function that changes a column (field) of the current data record.
    - dbRequery()
      Rereads the data of the record set from the data source.
    - dbRollbackTransaction()
      To end a transaction, no changes are made.
    - dbSetParameter()
      Database function for setting name/value pairs for use as a parameter in the subsequent commands.
    - dbStartCommand()
      To prepare a data manipulation command.
    - dbUpdate()
      Writes all the changes made back to the current data record with dbPutField().
    - Debug()
      Evaluates any Control expressions and writes the result to stderr.
    - DebugBreak()
      The function allows to set a debug break point.
    - DebugFN()
      Evaluates any number of control expressions, if a specific debug flag is set and writes the result to stderr, followed by a new line.
    - DebugFTN()
      Evaluates any number of control expressions, if a specific debug flag is set and writes the result with a time stamp to stderr followed by a new line.
    - DebugN()
      Evaluates any Control expressions and writes the result to stderr, followed by a new line.
    - DebugTN()
      Like the function DebugN(), but with a time stamp.
    - deg2rad()
      Converts an angle from measurement in degrees to a radian measurement
    - delay()
      Delays the next program step.
    - deleteImageFromCache()
      Allows to remove a file from the pixmap cache.
    - delExt()
      The function deletes the file extension of the specified file.
    - desDecrypt()
      The function decodes the content of a blob variable using the DES algorithm.
    - desEncrypt()
      The function encodes the content of a string or blob variable using the DES algorithm.
    - dirName()
      The function returns the directory path for the specified directory.
    - dollarSubstitute()
      The function replaces dollar parameters in an expression with the parameters.
    - dpActivateAlert()
      Activates an alert handling at the given data point element either with or without NULL time.
    - dpAliases()
      Returns all aliases with fitting pattern of filter and (optional) suitable filter dpeFilter of the data point elements.
    - dpAliasToName()
      Returns the data point element for the given alias.
    - dpAttributeType()
      Returns the data type.
    - dpCancelSplitRequest()
      If a query takes very long, use the function dpCancelSplitRequest in order to cancel the query function.
    - dpChange()
      The function opens a data point in the PARA module in change mode.
    - dpConnect()
      Calls a callback function whenever the passed data point values/attributes change.
    - dpConnectUserData()
      Calls a callback function on data change of the defined data point values/attributes and passes them to it. In contrast to dpConnect(), this function allows you to also pass any data to the callback function.
    - dpCopy()
      Copies a data point including the configuration.
    - dpCopyBufferClear()
      Clears the buffer copies prior to a new dpCopy().
    - dpCopyConfig()
      The function dpCopyConfig() copies a config from a source data point element into a target data point element.
    - dpCopyConfigMerge()
      dpCopyConfigMerge() copies specific configs from a source data point element into a target data point element.
    - dpCopyConfigMergeBufferClear()
      Clears the buffer copies prior to a new dpCopyConfigMerge().
    - dpCopyOriginal()
      Copies the original value of the source data point to the target data point.
    - dpCreate()
      Creates a data point.
    - dpDeactivateAlert()
      Deactivates an alert handling at the given data point element either with or without NULL time.
    - dpDelete()
      Deletes a data point.
    - dpDisconnect()
      The function unregisters function work().
    - dpDisconnectUserData()
      Unregisters a callback function which was called using dpConnectUserData().
    - dpElementType()
      Returns the data type.
    - dpExists()
      The function dpExists() checks the existence of a valid data point identifier.
    - dpGet()
      Reads values of data point attributes in variables.
    - dpGetAlias()
      New consistent name for the function dpNameToAlias. The function dpGetAlias() returns the alias for the specified data point element.
    - dpGetAllAliases()
      Returns all data points and their aliases. For the return of aliases you can also define filters in this function (see description of the parameters below). The function replaces getAllDpAliases() in versions > 2.11.1.
    - dpGetAllAttributes()
      Returns all attributes of the config "_config" (for example, of "_original")
    - dpGetAllComments()
      The function may not used any longer; replaced by dpGetAllDescriptions(). Returns in dpe all data point elements and in comments all comments with a suitable (optional) filter for comments. Further more optional: data point elements with fitting filter for data point elements
    - dpGetAllConfigs()
      Returns all possible configs, which are allowed to configure to a data point element "dpe" resp. to a data type "dpeType(bit, bitarray, structure, ...).
    - dpGetAllDescriptions()
      Returns via dps all data points and via descriptions all descriptions that correspond to the descriptionFilter. You can also specify a dpeFilter. This means that only the data points containing the specified data point element are returned provided that the description of the data point element corresponds to the descriptionFilter.
    - dpGetAllDetails()
      Returns all details of a config (for example, of "_lock").
    - dpGetAsynch()
      Reads values of data point attributes at a particular source time and writes them to variables.
    - dpGetCache()
      The function returns the content of the cache.
    - dpGetComment()
      Returns the comment for the data point element(s).
    - dpGetDescription()
      Returns the description for the data point element(s).
    - dpGetDpTypeRefs()
      The function returns all references in a DPT.
    - dpGetFormat()
      This function returns the "format" of a data point.
    - dpGetId()
      Returns the data point ID and the element ID of the defined data point.
    - dpGetMaxAge()
      The use of this function is only useful if an input or input/output peripheral address exists for a datapoint element. If a peripheral address exists, the function triggers a singleQuery for a driver if the value of the data point element "dpName" is older than the parameter "age". The function returns the value from the driver. This function is available for the OPC UA Client, Modbus, S7Plus, SNMP, Ethernet/IP, OPC drivers and S-Bus driver.
    - dpGetName()
      Returns the data point name for the passed data point ID and element ID.
    - dpGetPeriod()
      The function queries DP attributes over a specified period of time.
    - dpGetPeriodSplit()
      Queries DP attributes over a certain period of time. Use the function when you query a large amount of data. The function reduces the system load and offers a considerable advantage when dealing with a large amount of data.
    - dpGetRefsToDpType()
      The function returns all DPTs and DPs that contain the specified DPT as a reference.
    - dpGetStatusBit()
      Retrieves status bits.
    - dpGetUnit()
      This function returns the unit of a data point.
    - dpIsLegalName()
      Checks, whether the name of a data point contains incorrect characters.
    - dpNameCheck()
      This function should not be used anymore and was replaced by the function nameCheck(). Checks, whether the name of a data point contains only the following characters: 0...9, A...Z, _, a...z.
    - dpNames()
      Returns all the data point names or data point element names that match a pattern. The data point structures are written to the array in alphabetical order.
    - dpQuery()
      Retrieves attribute values with the help of SQL statements.
    - dpQueryConnectAll()
      The function dpQueryConnectAll subscribes to attributes of configs from multiple Data Point Elements, which meet a certain query condition. When a subscribed attribute changes, a callback function (“work” function) is executed. The event manager will always send all subscribed elements, even if only one changes. Therefore update messages will always contain all subscribed elements.
    - dpQueryConnectSingle()
      The function dpQueryConnectSingle subscribes to attributes of configs from multiple Data Point Elements, which meet a certain query condition. When a subscribed attribute changes, a callback function (“work” function) is executed. The Event Manager will send every single change separately, so update messages will normally contain only one element. If however several of the subscribed attributes are changed together within one message (i.e. in one dpSet() function call), then these will be all be forwarded in one message to the subscribing work function. Additionally, the execution of the work function can be delayed with the optional parameter blockingTime to accumulate more changes, increasing performance.
    - dpQueryDisconnect()
      Ends registration to a work function of dpQuerysConnectAll() or dpQueryConnectSingle()
    - dpQuerySplit()
      Retrieves attribute values with the help of SQL statements. Use the function when you query a large amount of data. The function reduces the system load and offers a considerable advantage when dealing with a large amount of data.
    - dpRemoveCache()
      The function deletes the specified datapoint from the cache.
    - dpRename()
      The function renames a data point.
    - dpSelector()
      Opens the data point selector and writes the selected data point address to s. See DP-Selector
    - dpSet()
      The function assigns data point attributes values or creates data point configs.
    - dpSetAlias()
      The function dpSetAlias() sets the alias for the specified data point element.
    - dpSetAndWaitForValue()
      This function is a combination of the functions dpSet() and dpWaitForValue().
    - dpSetCache()
      The function sets the content of the cache.
    - dpSetComment()
    - dpSetDescription()
      Sets a comment for the data point element dp.
    - dpSetDynErrorCheck()
      Setting several data points.
    - dpSetErrorCheck()
      Sets a data point.
    - dpSetFormat()
      Sets the format of a DP element.
    - dpSetTimed()
      Assigns values and a source time to the original attributes that can be changed by the user or to the attribute "_corr.._value".
    - dpSetTimedWait()
      Assigns values and a source time to the original attributes that can be changed by the user or to the attribute "_corr.._value".
    - dpSetUnit()
      Sets the unit of a DP element.
    - dpSetWait()
      Assigns data point attributes and waits for an answer from the event manager.
    - dpSubStr()
      The function dpSubStr() returns the part (sub string) of a data point name given by pattern. The function returns the neutral form of configs and attributes.
    - dpTreeSetIcons()
      Sets any icons for a system, a data point type or a data point element in the data point tree view.
    - dpTypeChange()
      The function changes data point types.
    - dpTypeCreate()
      The function creates a new data point type.
    - dpTypeDelete()
      The function deletes an existing data point type.
    - dpTypeGet()
      Returns the structure of a data point type.
    - dpTypeName()
      Returns the data point type for the data point name.
    - dpTypeRefName()
      The function "dpTypeRefName" returns the type reference of the selected DPE.
    - dpTypes()
      Returns all the data point types from the current project.
    - dpValToString()
      This function converts the value specified in val into a string, with the format string of the data point element dp being used. If anytype is a dyn, then this function returns a dyn_string as the result.
    - dpWaitForValue()
      The function waits for a certain time (timeout) for a value change that fulfills the condition and returns the values of the different or same data points via the parameter returnValues.
    - dragStart()
      Starts a drag operation.
    - dropAccept()
      Defines whether a graphics object accepts drop operations.
    - dynAppend()
      Appends y to the field x.
    - dynAppendConst()
      The functions is comparable to the function dynAppend() but will not change the source variable that is appended.
    - dynAvg()
      Returns the average of the elements of the dynamic field x.
    - dynAvgWT()
      Returns the average of the elements of the dynamic field x.
    - dynClear()
      Deletes the entire array.
    - dynContains()
      Returns the index of the first occurrence of y in the dynamic field x
    - dynCount()
      Returns the number of elements with the same pattern in the array.
    - dynDynSort()
      Sorts a dynamic variable field of dyns in ascending or descending order according to a specific column.
    - dynDynTurn()
      The function dynDynTurn turns rows of a dyn_dyn_type variable into columns and visa versa.
    - dynInsertAt()
      Inserts an element/elements in a field at the specified position.
    - dynInsertAtConst()
      The function is comparable to dynInsertAt() but will not change the source variable that is inserted.
    - dynIntersect()
      Returns a DynVar with each values from value, which occurs in key.
    - dynlen()
      Outputs the number of field elements
    - dynMax()
      Outputs the largest field element.
    - dynMin()
      Outputs the smallest field element.
    - dynPatternMatch()
      Checks whether particular strings in a dynamic field have a specific pattern.
    - dynRemove()
      Removes an element from a dyn variable.
    - dynSort()
      Sorts a dynamic variable field in ascending or descending order.
    - dynSortAsc()
      Sorts a field in ascending order.
    - dynSum()
      Adds field elements.
    - dynUnique()
      Reduces field elements to unique elements and outputs their number.
  - Functions E
  - Functions F
  - Functions G
  - Functions H
  - Functions I
  - Functions J
  - Functions K
  - Functions L
  - Functions M
  - Functions N
  - Functions O
  - Functions P
  - Functions Q
  - Functions R
  - Functions S
  - Functions T
  - Functions U
  - Functions V
  - Functions W
  - Functions X
  - Functions Y
  - Functions Z
- CTRL Debugger
  With the CTRL Debugger you can debug the programming language Control.
- CtrlExtension, basics

dpGetAsynch()

Reads values of data point attributes at a particular source time and writes them to variables.

Note: This function is only meaningful if the data point has been archived!

Note: If there is no value available at the specified time, the value of the element that was last saved before the query time is returned.

Synopsis

int dpGetAsynch(time t, string|dyn_string dp1, <type1>|<dyn_type1> &var1 [, string|dyn_string dp2, <type2>|<dyn_type2> &var2 ...]);

Parameter


Parameter	Meaning
t	source time
dp1, dp2, ...	data point attributes to be read Note: Please note that in the dpGetAsynch function, the parameter dp (data point) cannot be a dyn element, but each data point that you want to query must be specified separately.
var1, var2, ...	variables to be written

Return Value

If the function was successfully executed, it returns 0 and in the event of a failure -1. The return value 0 only indicates that the message was correctly sent to Event Manager.

Errors

Independently of the return value, errors can be retrieved with getLastError() (nonexistent data points, missing arguments or no read permission).

Description

The function dpGetAsynch() reads the values of the data point attributes dp1, dp2, ... with the source time t from the database and writes them to the variables var1, var2, ... of the appropriate type.

If an alias is used for a query, this is passed as a parameter to the external query function; function calls for dpQuery() and alertGetPeriod().

With the help of dpGetAsynch() only attributes of the configs "_original", "_online", "_offline" and "_corr" can be retrieved. See also dpGetPeriod(). You can find information on querying whether the values of the required attribute are located in the database. The parameter t1 may not predate 1.1.1970 0:0 (UTC).

If a definition for a config or attribute does not exist, the following defaults are used:


Function	Default
dpSet*()	_original.._value
dpGet()	_online.._value
dpGetAsynch()	_offline.._value
dpGetPeriod()	_offline.._value
dpConnect()	_online.._value
dpDisconnect()	_online.._value

Assignment of the valve regulation ratio from March the 5th, 12.30 to the variable x

main()
{
  dpGetAsynch(makeTime(1996, 3, 5, 12, 30), "Valve17.opening:_offline.._value", x);
}

Assignment

Data point function, waiting Control function

Availability

CTRL