Version Information
Release Notes, Update information, Certifications and Frequently Asked Questions.
Concepts
Your first step into modern and powerful process visualization.
Deployment
Topics, you need to know, before using WinCC OA.
Security
Go beyond the norm in cybersecurity.
Engineering
Powerful tools for easy or complex engineering tasks.
Data Management
Classify, structure and archive your data.
Business Logic / Control
Endless possibilities in data processing for your projects.
- Introduction to CTRL
  An introduction to the product's own programming language Control(CTRL).
- Control Classes
  The overview of classes available in Control.
- Types of Control Functions
  An overview of the types of functions distinguished within Control.
- 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.
    - "duration"
      Returns the duration of the current media.
    - 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
- CtrlExtension
  The CtrlExtension allows the addition of custom C++ code.
- CTRL Debugger
  You can use the CTRL debugger to debug the Control programming language. The debugger can be used via its own panel, which also enables the monitoring and setting of variable values during the execution of a script.
- SQL in CONTROL
  The database functions enable you to quickly carry out value queries on data points and elements.
- API Manager
  The WinCC OA API (Application Programming Interface) offers a number of functions adding special Managers to this process control system.
Data Visualization
User interfaces, Trends and Reports for every purpose and device.
Southbound Interfaces
The process connection to the actual machines/sensors.
Northbound Interfaces
Your portal to the cloud or supervising systems.
Web Connectivity / Network Interfaces
Data exchange, APIs and web technologies
User Management
All about authorization, authentication and login-customization.
Availability
How to get your system uptime to the maximum.
Reporting
Create state of the art project reports without limits.
Addons
Useful tools and enhancements for special demands.
Reference Tables
Detailed and extensive content for special project adaptation.
Videos & Tutorials
Explore the capabilities of WinCC OA with our carefully selected collection of video tutorials and guides.
WinCC OA Documentation
Basic information about terms and functions within the documentation.
Disclaimer
A brief clarification of liability exclusions or legal notices.

dpSetComment()

Synopsis

int dpSetComment(string dp, langString comment);

Parameters


Parameter	Meaning
dp	data point element to be commented on
comment	comment (in one or several languages)

Return Value

If successful 0, otherwise -1.

Errors

Errors can be retrieved with getLastError(). An error message is issued in the event of incorrect DPs or missing arguments!

Description

New consistent name for the function setDpComment(). The function dpSetComment() sets a comment for the data point element dp. This comment can be retrieved with the help of the function dpGetComment(). Comments are not archived historically. Comments which have been replaced can therefore no longer be retrieved!

Example

A new data point is created, a comment is written and then read out again for checking.

main()
{
  dpCreate("number_1","ExampleDP_Int"); // new DP
  dpSetComment("number_1.","Here is the comment");
  DebugN(dpGetComment("number_1."));//output in the log viewer
}

The following example sets a comment in two languages (a multilingual project with two languages) ("Riesenrad") German and ("EmpireStateBuilding") English.

main()
{
  langString descr;
  setLangString(descr,0,"Riesenrad");
  setLangString(descr,1,"EmpireStateBuilding");
  dpSetComment("integer_1.",descr); 
}

Assignment

Data point function, waiting Control function

Availability

CTRL