Startseite
CONTROL
CONTROL Functions
Functions G
groupCreate()
Creates a new data point group and passes the name of the created data point of the group as well as the error code via parameters.

CONTROL
- Introduction to CTRL
- Control Classes
- Types of Control Functions
- Control graphics
- CONTROL Functions
  - Funtions A
  - Funtions B
  - Funtions C
  - Funtions D
  - Functions E
  - Functions F
  - Functions G
    - getACount()
      Returns the internal number of an alarm (count starts at 0) at a particular time.
    - getActiveHttpServerUrl()
      Returns the URL of the server to which an HTTP request shall be sent.
    - getActiveIconTheme()
      Returns the icon theme currently in use.
    - getActiveLang()
      Returns the active language. The function getActiveLangId() provides the same functionality but returns an OaLanguage enum.
    - getActiveLangId()
      Returns the active language as an OaLanguage Enum. This function is the same as getActiveLang() but uses the OaLanguage Enum as return value.
    - getAIdentifier()
      Outputs the name of a data point.
    - getAllDpAliases()
      Returns all the data points and their aliases. The function has been renamed to dpGetAllAlias() as from version 2.11.1.
    - getAllGroupsPVSS()
      Returns all WinCC OA user groups.
    - getAllLangIds()
      Returns a vector of all languages available in WinCC OA.
    - getAllUsersPVSS()
      Returns all WinCC OA users as well as the user data. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons. Use the function getAllSavedUsers() instead.
    - getApplicationProperty()
      Returns additional information about the client (browser) connected to the HTTP server or checks whether a stylesheet is used.
    - getBit()
      Returns the value of a particular bit.
    - getCatStr()
      This function exports a catalog entry.
    - getChildCentralPosition()
      The function returns the central position of a child panel in a root panel.
    - getClipboardText()
      Returns the clipboard text as plain text, or an empty string if the clipboard does not contain any text.
    - getColorNames()
      Outputs names of colors according to a pattern.
    - getComponentName()
      Returns the name of a component.
    - getConfigActiveHttpServerUrl()
      Returns the URL which addresses the project's active HTTP Server.
    - getConfirmDps()
      Returns an array with the data points of a panel to be acknowledged.
    - getCurrentDomainName()
    - getCurrentOSUserLocal()
      The function returns the user name, full name, description and the groups of a Windows & Linux user.
    - getWindowsEvents()
      The function returns the Windows events. The events under Windows are split into three different log types.
    - getCurrentTime()
      Returns the current time.
    - getCursorPosition()
      Returns the current position of the mouse cursor in a panel or screen.
    - getDollarList()
      The function getDollarList() returns the dollar parameters of a panel.
    - getDollarParams()
      The dollar parameters of the reference can be queried using this CTRL function. Only in the panel for reference configuration in GEDI. Use getDollarParamsFromPanel() for getting the dollar parameters from a panel.
    - getDollarParamsFromPanel()
      The dollar parameters of the panel can be queried with this CTRL function.
    - getDollarValue()
      This function returns the value of a dollar parameter.
    - getDomainOSUser()
      The function returns the domain, the user name, the full name, the description and the groups of the Windows user logged in.
    - getDynAnytype(), getDynBit32(), getDynBit64(), getDynBool(), getDynChar(), getDynFloat(), getDynInt(), getDynLong(), getDynString(), getDynTime(), getDynUInt(), getDynULong(), getDynATime()
      The functions return the content of a dyn-dyn variable column.
    - getenv()
      Reads the value from an environment variable.
    - getErrorCatalog()
      Returns the error cataloge (.cat) from the error class from getLastError().
    - getErrorCatalog()
      Returns the error cataloge (.cat) from the error class from getLastError().
    - getErrorCode()
      Returns the error code from the error class from getLastError().
    - getErrorDpName()
      Returns the data point name from getLastError().
    - getErrorManId()
      Returns the manager identifier from getLastError() from the error class.
    - getErrorPriority()
      Returns the priority of the error from getLastError() from the error class.
    - getErrorStackTrace()
      Returns a dynamic string containing the stack trace (call stack) of an occurred exception.
    - getErrorText()
      Returns the text part of an error message string from getLastError() from the error class (e.g. "no authorisation").
    - getErrorType()
      Returns the type of error from getLastError() from the error class.
    - getErrorUserId()
      Returns the identification number of the user from the error class from getLastError().
    - getExt()
      The function returns the file extension.
    - getFileCryptoHash()
      Allows to create a checksum for a file.
    - getFileModificationTime()
      The function returns the modification date and time of a file.
    - getFileNameFromPath()
      The function returns the file name and extension from the given path. This function does not check if the path/file exists.
    - getFileNames()
      Lists the files or sub directories of a directory.
    - getFileNamesLocal()
      The function searches for files recursive and relative to the project path.
    - getFileNamesRemote()
      The function searches for files recursive and relative to the project path. The function works not only on a local machine but on mobile devices.
    - getFileNamesRev()
      Reverse of the function getFileNames().
    - getFilePermissions()
      Retrieves the permissions for a file.
    - getFilesFromDirectory()
      Adds all files names from given directory 'absolutePath' to 'files'.
    - getFileSize()
      The function checks the size of the defined file.
    - getFilesRecursive()
      Adds filenames to the parameter 'files' from the given directory 'absolutePath' including all subdirectories.
    - getGediNames()
      Returns the opened modules of the type GEDI.
    - getGlobalLangId()
      Returns the sequence number of a project language from the lang.dir file <wincc_oa_path>/nls. This means that you pass an index of a project language (from the config file) as a parameter and the sequence number of this language from thelang.dir file will be returned.
    - getGlobals()
      The function queries existing global variables.
    - getGlobalType()
      The function queries the type of the specified global variables.
    - getGroupDataPVSS()
      Returns group data for a WinCC OA group. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons! Use the function getGroup() instead.
    - getGroupsOfUserPVSS()
      Returns the group memberships for a specific user. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons. Use the function UserManagement::getGroupsByUser(UserManagementUser user)
    - getHostByAddr()
      Returns the host name for a given IP address.
    - getHostByName()
      Returns the IP address for a given host name.
    - getHostname()
      Returns the name of the current host as a string.
    - getICanvas()
      Returns the IDispatch interface for the Canvas of the module.
    - getInitialZoomFactor()
      Returns the defined zoom factor that scales all panels (even childpanels) after the start of a UI.
    - getInputState()
      Returns the current input state.
    - getKerberosSecurity()
      Returns the Kerberos security level for the connection to a specified manager.
    - getLangIdx()
      The function getLangIdx() returns the sequence number of the passed language (language that has been passed as a parameter) from the project config file. If you, for example, pass the language ID "ru_RU.utf8" (Russian) as a parameter and this language is on the third place in the config file, the function returns 2. The function returns 2 instead of 3 because the index of the languages in the config file starts at 0.
    - getLastError()
      Gets the last error that occurred.
    - getLastException()
      Gets the last exception that occurred during processing of the function.
    - getLicenseOption()
      The function getLicenseOption() allows you to query the current license and obtain a license from a license container.
    - getLocale()
      Returns the language identifier
    - getManIdFromInt()
      Converts manager ID into manager type and manager number.
    - getMetaLang()
      Returns the index of the meta language.
    - getMobileUserInfo()
      Returns the user information that has been stored within the Mobile UI Application or Desktop UI project connection configuration.
    - getMultiValue()
      Writes several graphics attributes to variables.
    - getNetworkDevices()
      Returns a list of information for the available network devices and interfaces.
    - getNoOfLangs()
      Gets the number of languages currently available.
    - getOSDomainName()
      The function returns the domain name under Windows and Linux, regardless which user is currently logged in.
    - getOSGroupID()
      Returns the operating system ID of a specific user group.
    - getOSGroupInfo()
      Returns the attributes of a domain group.
    - getOSGroupName()
      Returns the group name for an OS specific ID.
    - getOSGroups()
      Returns an array containing the attributes of all groups of a domain (no local groups).
    - getOSGroupUsers()
      Returns all users of a group.
    - getOSUser()
      The function returns the user name, the full name, the OS ID, the domain and the comment of the current user.
    - getOSUserGroups()
      Returns an array containing the attributes of all groups a user is member of.
    - getOSUserGroupsMembership()
      The function getOSUserGroupsMembership queries the operating system group memberships of a user.
    - getOSUserID()
      Returns the operating system ID of a specific user.
    - getOSUserInfo()
      Returns the attributes for a user "userName".
    - getOSUserName()
      Returns the user name for an OS specific ID.
    - getOSUsers()
      Returns an array (mapping) containing the user data (name, full name, OSID, Comment, PrimaryGroupOSID, PrimaryGroupName).
    - getOverallConnState()
      The function checks if a connection is working by using the connection name.
    - getPanelPreview()
      Creates a preview (image) of the available panel references for Drag & Drop of DPTs and DPs.
    - getPanelSize()
      Returns the size of a panel (width and height).
    - getPath()
      This function determines the absolute paths for panels, scripts etc.
    - getPendingFileTransferCount()
      The function getPendingFileTransferCount() returns the number of currently pending file transfers.
    - getPrimaryScreen()
      Returns the number of the applications primary screen.
    - getPrinterNames()
      The function returns a list of available printers.
    - getProjectLangIds()
      Returns a vector of all languages available within the project.
    - getRcvLevel()
      The function returns the receive debug level for messages.
    - getReduDp()
      The function getReduDp() checks if a right-side redundancy partner exists (if the specified data point has a redundant partner).
    - getRemoteSystemHosts()
      The function dyn_string getRemoteSystemHosts(string sSystem); returns the host names of the system sSystem. In case of redundancy, it returns the host name of both servers otherwise the host name of the first system only.
    - getRemoteSystemNamesConnected()
      The function returns the host names and System IDs of the connected systems in a distributed system.
    - getScaleStyle()
      Returns the configured scale style of the module for zooming.
    - getScreenCount()
      Returns the number of the connected screens.
    - getScreenNumber()
      Returns the screen number for the stated coordinates.
    - getScreenshot()
      This function takes a screenshot, which can be saved with imageToFile().
    - getScreenSize()
      Reads the current size of the given screens in pixel.
    - getScript()
      Returns the script for setting parameters of a particular graphics attribute.
    - getShape()
      Graphics objects can be addressed with this CTRL function (instead of setValue()) and attributes can be set (see also Attributes of the graphics elements). The examples of the graphics attributes are largely dealt with in accordance with this new method.
    - getShapes()
      This function returns a list of shape names (or RefName.ShapeName) which are located in given Module/Panel parameters and fit the wanted attribute and value pair.
    - getShapesStrict()
      This function returns a list of shape names (or RefName.ShapeName) which are located in given Module/Panel parameters and fit the wanted attribute and value pair. It is similar to getShapes(), but uses a different search method.
    - getShapeStrict()
      This function is used to address graphics objects and set attributes. It is similar to getShape(), but uses a different search method.
    - getSndLevel()
      The function returns the send debug level for messages.
    - getStackTrace()
      Returns a dynamic string with the stack trace (call stack) from this position of the code.
    - getStandardPath()
      The function getStandardPath() returns the directory path (location) where files of type (see parameter "type" below) should be written to, or an empty string if the location cannot be determined.
    - getSystemEnvironment()
      Returns a mapping of the environment variables.
    - getSystemId()
      Returns the system ID.
    - getSystemName()
      Returns the name of the system.
    - getSystemNames()
      Returns a list of all the system names and system IDs known to the own system.
    - getThreadId()
      Returns the identification number of the current thread.
    - getThrowErrorAsException()
      Checks if "throw error as exception" is activated.
    - getTranslationFile()
      Returns the translation file name of the project level.
    - getTrendConfig()
      Get currently visible trendsettings object.
    - getType()
      Query of the data type of any Control expression.
    - getTypeName()
      Returns the data type of any Control expression as string.
    - getUiFunctionList()
      Returns all UI functions that can be used in WinCC OA scripts.
    - getUiStyle()
      Returns the available display styles of windows and buttons dependent on the actually used style.
    - getUserDataByNamePVSS()
      Returns user data for a WinCC OA user by name. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons. Use the function getUserByName() instead.
    - getUserDataPVSS()
      Returns user data for a WinCC OA user. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons. Use the method getUser() of the UserManagement class instead.
    - getUserId()
      Returns the associated ID for the specified user name.
    - getUserName()
      Returns the associated user name for a specified ID.
    - getUserPermission()
      Checks authorizations.
    - getUsersInGroupPVSS()
      Returns the users for a specific group. The function is obsolete as of WinCC OA version 3.17. The function is, however, available for compatibility reasons. Use the function getSavedUsersByGroupId() instead.
    - getValue()
      Reads graphics attribute values for a graphics object in variables.
    - getVariable()
      The function returns the value of the specified variable.
    - getVersionInfo()
      The function returns the current version information of WinCC OA.
    - getVisionNames()
      Outputs all the open Vision modules.
    - getWindowsEvents()
      The function returns the Windows events. The events under Windows are split into three different log types.
    - getYoungerFiles()
      Returns all the files of a directory that has changed since a particular date.
    - getZoomFactor()
      Reads the zoom factor for a panel.
    - getZoomRange()
      Returns the minimum and maximum value that can be used while zooming.
    - globalExists()
      This function queries whether a specific global variable exists.
    - groupCreate()
      Creates a new data point group and passes the name of the created data point of the group as well as the error code via parameters.
    - groupDelete()
      Deletes a data point group.
    - gunzip()
      Extracts the content of source. The result is saved in the parameter target. CtrlZlib is a shared library with functions for data compression. It is based on libz (gzip, gunzip).
    - gzip()
      CtrlZlib is a shared library with functions for data compression. It is based on libz (gzip, gunzip). The functiongzip()compresses the content of the parameter source. The result is saved in the parameter target.
    - gzread()
      Reads maximum "len" bytes from the file "path" into the variable "content".
    - gzwrite()
      CtrlZlib ia a shared library with functions for data compression. It is based on libz (gzip, gunzip).
  - 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
- 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.

groupCreate()

Creates a new data point group and passes the name of the created data point of the group as well as the error code via parameters.

Synopsis

void groupCreate(langString ls, bool bPrivate, string &newGroup, bool main, int &iError);

Parameters


Parameter	Description
ls	Name of the data point group.
bPrivate	Defines the type of the data point group. TRUE= Private data point group. FALSE = Public data point group.
newGroup	Return value. Name of the data point of the new group with the syntax "_DpGroup<NNNNN>_<type>". If the limit of 7999 groups is reached, the function will search for an available group ID starting from the first group. If an available group ID is found, it is used. If no group indices are available, a new group can be created after you delete a group.
main	Defines whether the new group should belong to the main group. TRUE = Main group (_DpGroup<NNNNN>_<type>.Level=1) FALSE = Not main group (_DpGroup<NNNNN>_<type>.Level=0)
iError	Return value. Error code (see below).

Return value

Name of the data point of the created data point group and the error code.

Error

The return value of the iError parameter indicates whether an error occurred during the creation of the data point group. The following error codes are available:

0 = OK, group was created without any failures
-1 = The user has not the permission to create a data point group
-8 = maximum number of data point groups reached
-9 = Group already exists
-10 = The name of the data point group is empty (ls parameter)

Description

Creates a new data point group and passes the name of the created data point of the group as well as the error code via parameters.

Example

The data point group MyDpGroup will be created.

main()
{
  string newGroup;
  int err;
  groupCreate("MyDpGroup", false, newGroup, false, err);
  DebugN(newGroup, err);
  //Returns for example: ["_DpGroup00016_Public"][0]
}

Assignment

Data point function

Availability

CTRL