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
  - 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
  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 datapoints and elements.
- WinCC OA JavaScript Manager for Node.js
  The WinCC OA JavaScript Manager for Node.js is a manager that allows for the integration of the TypeScript/JavaScript runtime environment Node.js® into WinCC OA.
- 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.
Documentation
Basic information about terms and functions within the documentation.
Support & Services
An experienced team of support agents, consultants and trainers are ready to facilitate active partnerships with our customers, so they can profit from our comprehensive service.
Disclaimer
A brief clarification of liability exclusions or legal notices.

dpCreate()

Creates a datapoint.

Synopsis

int dpCreate(string dpname, string dptype [, int sysnum, unsigned dpNo]]);

Parameters


Parameter	Meaning
dpname	Name of the datapoint to be created
dptype	Type of datapoint to be created
sysnum	When creating a datapoint on a remote system in a distributed system, this parameter must contain the system number.
dpNo	The ID of the datapoint. If a datapoint with the given ID already exists, a random ID is chosen.

Return Value

dpCreate() returns 0 on success and -1 on failure. In some cases the function returns 0 (success) but due to e.g.: name clashes the DP could not be created. This can be queried using getLastError().

Errors

Errors can be retrieved with getLastError(). This includes incorrect or missing arguments.

Description

The function dpCreate() create s a datapoint with the name dpname of the datapoint type dptype. The specified datapoint type must already exist. If a datapoint with the specified name already exists, the call of the function dpCreate() has no effect. dpCreate() is a waiting function, it waits until the DP has been created.

Refer to nameCheck() for not permitted characters in datapoint names.

Example

Creating the datapoint number_1 of the datapoint type ExampleDP_Int. If the data point already exists, a message is issued. Furthermore a datapoint named TestDP of the datapoint type PUMP1 is created on the system with number 2.

main()
{
  if (dpExists("number_1")) DebugN("already exists");
  else dpCreate("number_1","ExampleDP_Int"); // Create
  dpCreate("TestDP", "PUMP1", 2); /*Create DP on the system with
  number 2*/
}

Assignment

Datapoint function, Waiting Control function

Availability

UI, CTRL