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
  - 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 catalog (.cat) from the error class.
    - getErrorCatalog()
      Returns the error catalog (.cat) from the error class.
    - 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 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).
    - 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. 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
  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.
- NextGen Archiver Backend-API
  This chapter describes the NextGen Archiver Backend API
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.

getHostByName()

Returns the IP address for a given host name.

Synopsis

string getHostByName(string name [, dyn_string &addr_list]);

Parameters


Parameter	Description
name	Internet host name (for example, "www.etm.at")
addr_list	List of IP addresses suitable for the given Internet host names

Return value

Returns the IP address for a host name. In case of errors, an empty string will be returned and an error message will be displayed in the log viewer.

Error

Wrong or missing arguments.

Description

Returns the IP address for any wanted host name. The parameter addr_list can be used to output further IP addresses that are suitable for a given internet host. The return value of the function is the last value in the addr_list field (addr_list[n]).

Example

Returns the IP address for the host name "www.etm.at".

main()
{
  string name, ip;
  dyn_string addr_list;
  name = "www.etm.at";
  ip = getHostByName(name, addr_list);
  DebugN("IP address:" + ip);
  DebugN("Further IP addresses:" + addr_list);
}

Assignment

Miscellaneous functions

Availability

CTRL