Versionsinformationen
Release Notes, Update-Informationen, Zertifizierungen and häufig gestellte Fragen.
Konzepte
Ihr erster Schritt in die moderne und leistungsstarke Prozessvisualisierung.
Deployment
Themen, die Sie vor der Nutzung von WinCC OA wissen sollten.
Sicherheit
Wachsen sie in Bezug auf Cybersecurity über die Norm hinaus.
Engineering
Leistungsstarke Tools für einfache sowie komplexe Engineering-Aufgaben.
Datenmanagement
Klassifizieren, strukturieren und archivieren sie Ihre Daten.
Business Logic / Control
Endlose Möglichkeiten in der Datenverarbeitung für Ihre Projekte.
- 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
  - Functions A
  - Functions B
  - Functions C
  - Functions 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.
    - decrypt()
      Decrypts the specified ciphertext using the specified passphrase.
    - 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 datapoint element either with or without NULL time.
    - dpAliases()
      Returns all aliases with fitting pattern of filter and (optional) suitable filter dpeFilter of the datapoint elements.
    - dpAliasToName()
      Returns the datapoint 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 datapoint in the PARA module in change mode.
    - dpConnect()
      Calls a callback function whenever the passed datapoint values/attributes change.
    - dpConnectUserData()
      Calls a callback function on data change of the defined datapoint 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 datapoint including the configuration.
    - dpCopyBufferClear()
      Clears the buffer copies prior to a new dpCopy().
    - dpCopyConfig()
      The function dpCopyConfig() copies a config from a source datapoint element into a target datapoint element.
    - dpCopyConfigMerge()
      dpCopyConfigMerge() copies specific configs from a source datapoint element into a target datapoint element.
    - dpCopyConfigMergeBufferClear()
      Clears the buffer copies prior to a new dpCopyConfigMerge().
    - dpCopyOriginal()
      Copies the original value of the source datapoint to the target datapoint.
    - dpCreate()
      Creates a datapoint.
    - dpDeactivateAlert()
      Deactivates an alert handling at the given datapoint element either with or without NULL time.
    - dpDelete()
      Deletes a datapoint.
    - 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 datapoint identifier.
    - dpGet()
      Reads values of datapoint attributes in variables.
    - dpGetAlias()
      New consistent name for the function dpNameToAlias. The function dpGetAlias() returns the alias for the specified datapoint element.
    - dpGetAllAliases()
      Returns all datapoints 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 datapoint elements and in comments all comments with a suitable (optional) filter for comments. Further more optional: datapoint elements with fitting filter for datapoint elements
    - dpGetAllConfigs()
      Returns all possible configs, which are allowed to configure to a datapoint element "dpe" resp. to a data type "dpeType(bit, bitarray, structure, ...).
    - dpGetAllDescriptions()
      Returns via dps all datapoints and via descriptions all descriptions that correspond to the descriptionFilter. You can also specify a dpeFilter. This means that only the datapoints containing the specified datapoint element are returned provided that the description of the datapoint element corresponds to the descriptionFilter.
    - dpGetAllDetails()
      Returns all details of a config (for example, of "_lock").
    - dpGetAsynch()
      Reads values of datapoint 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 datapoint element(s).
    - dpGetDescription()
      Returns the description for the datapoint element(s).
    - dpGetDpTypeRefs()
      The function returns all references in a DPT.
    - dpGetFormat()
      This function returns the "format" of a datapoint.
    - dpGetId()
      Returns the datapoint ID and the element ID of the defined datapoint.
    - dpGetMaxAge()
      If a peripheral address exists, the function triggers a singleQuery for a driver if the value of the datapoint element dpName is older than the parameter age and returns the value from the driver.
    - dpGetName()
      Returns the datapoint name for the passed datapoint 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 datapoint.
    - dpIsLegalName()
      Checks, whether the name of a datapoint contains incorrect characters.
    - dpNameCheck()
      This function should not be used anymore and was replaced by the function nameCheck(). Checks, whether the name of a datapoint contains only the following characters: 0...9, A...Z, _, a...z.
    - dpNames()
      Returns all the datapoint names or datapoint element names that match a pattern. The datapoint 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 Datapoint 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()
      Can be used to unregister work functions registered via dpQueryConnectAll() 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 datapoint.
    - dpSelector()
      Opens the datapoint selector and writes the selected datapoint address to s. See DP-Selector
    - dpSet()
      The function assigns datapoint attributes values or creates datapoint configs.
    - dpSetAlias()
      The function dpSetAlias() sets the alias for the specified datapoint 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 datapoint element dp.
    - dpSetDynErrorCheck()
      Setting several datapoints.
    - dpSetErrorCheck()
      Sets a datapoint.
    - 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 datapoint attributes and waits for an answer from the event manager.
    - dpSubStr()
      The function dpSubStr() returns the part (sub string) of a datapoint name given by pattern. The function returns the neutral form of configs and attributes.
    - dpTreeSetIcons()
      Sets any icons for a system, a datapoint type or a datapoint element in the datapoint tree view.
    - dpTypeChange()
      The function changes datapoint types.
    - dpTypeCreate()
      The function creates a new datapoint type.
    - dpTypeDelete()
      The function deletes an existing datapoint type.
    - dpTypeGet()
      Returns the structure of a datapoint type.
    - dpTypeName()
      Returns the datapoint type for the datapoint name.
    - dpTypeRefName()
      The function "dpTypeRefName" returns the type reference of the selected DPE.
    - dpTypes()
      Returns all the datapoint types from the current project.
    - dpValToString()
      This function converts the value specified in val into a string, with the format string of the datapoint 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 datapoints 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()
      Returns the number of elements of the dynamic field.
    - 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
  Die CtrlExtension ermöglicht das Hinzufügen von benutzerdefiniertem C++-Code.
- CTRL-Debugger
  Der CTRL-Debugger ermöglicht ein Debuggen der Pogrammiersprache Control. Der Debugger kann über ein eigenes Panel verwendet werden, welches es auch erlaubt die Variablen zu beinflussen, Breakpoints zu setzen, usw.
- SQL in CONTROL
  Mit den Datenbankfunktionen besteht eine Möglichkeit, Werteabfragen von Datenpunkten und -elementen schnell durchzuführen.
- WinCC OA JavaScript Manager für Node.js
  Der WinCC OA JavaScript Manager für Node.js ist ein Manager, welcher die Einbindung der TypeScript/JavaScript Runtime-Umgebung in WinCC OA erlaubt.
- API Manager
  Das API von WinCC OA (Application Programming Interface) bietet eine Reihe von Funktionen, die es ermöglichen, dieses Prozessleitsystem um spezielle Manager zu erweitern.
Datenvisualisierung
User Interfaces, Trends und Reports für jeden Zweck und jedes Gerät.
Southbound Interfaces
Der Prozessanschluss zu den echten Maschinen/Sensoren.
Northbound Interfaces
Ihr Portal zur Cloud oder übergeordneten Systemen.
Konnektivität / Netzwerk Schnittstellen
Datenaustausch, APIs und moderne (Web) Technologien.
Benutzerverwaltung
Alles über Autorisierung, Authentifizierung und Login-Anpassung.
Verfügbarkeit
Wie sie maximale Systemverfügbarkeit erreichen können.
Reporting
Erstellen sie "State of the art"-Reports ohne Limits.
Erweiterungen
Nützliche Werkzeuge und Erweiterungen für spezielle Anforderungen.
Referenztabellen
Detaillierte und umfangreiche Inhalte für spezielle Projektanpassungen.
Videos & Tutorials
Erkunden Sie die Möglichkeiten von WinCC OA mit unserer sorgfältig ausgewählten Sammlung von Video-Tutorials und Anleitungen.
Dokumentation
Grundlegende Informationen über Bezeichnungen und Funktionsweisen innerhalb der Dokumentation.
Support & Services
Ein erfahrenes Team von Support-Mitarbeitern, Beratern und Trainern steht bereit, aktive Partnerschaften mit Kunden zu fördern, die von unserem umfassenden Service profitieren.
Disclaimer
Erläuterungen zu Haftungsausschlüssen oder rechtlichen Hinweisen.

dpSetDescription()

Sets a comment for the datapoint element dp.

The function replaces dpSetComment(), which remains for compatibility!

Synopsis

int dpSetDescription (string dp, langString comment);

Parameters


Parameter	Meaning
dp	datapoint element to be commented on
comment	comment

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

The function dpSetDescription() sets a comment for the datapoint element dp. This comment can be retrieved with the help of the function dpGetDescription(). Comments are not archived historically. Comments which have been replaced can therefore no longer be retrieved!

The function replaces dpSetComment(), which is conserved for compatibility.

The use of "@" or another character used as DPCommentSeparator, will result in the datapoint comment being separated at the character. The characters after the first "@" character will be saved as datapoint format, the characters after the second "@" as the datapoint unit. Should the "@"character be needed, the separator character can be changed with the config entry [general] DPCommentSeperator.

Example

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

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

Assignment

Datapoint function, waiting Control function

Availability

CTRL