< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 49 of 145 5.1.9.3.4 InnerErrorInfo The Services described in 5.1return StatusCodes on the service level and on the operation level. These StatusCodes are protocol- independent and device-independent. In cases where a StatusCode results from a call to the underlying system (e.g., communication system, device) the status of the underlying system can be reported via InnerErrorInfo. The components of this parameter are defined in Table 40. Table 40 – InnerErrorInfo Name Type Description InnerErrorInfo structure Communication- or Device-specific information. symbolicId String This string shall be used to identify the result of some internal operation. The maximum length of this string is 32 characters. Systems wishing to return a numeric return code should convert the return code into a string and use this string as symbolicId (e.g., "0xC0040007" or "-4"). errorText LocalizedText A textual representation of the symbolic id. The maximum length of this text string is 256 characters 5.1.9.3.5 LocalizedText This data type defines a structure containing a String in a locale-specific translation specified in the identifier for the locale. Its elements are defined in Table 41. Table 41 – LocalizedText Definition Name Type Description LocalizedText structure — text String The localized text. locale String The identifier for the locale (e.g. “en-US”). The element locale shall be a string composed of a language component and a country/region component according to RFC 3066. The <country/region> component is always preceded by a hyphen. The format of the LocaleId string is shown below: <language>[-<country/region>], where <language> shall be a two-letter code for a language according to ISO 639 , <country/region> shall be a two-letter code for the country/region according to ISO 3166. The rules for constructing LocaleIds shall be according to RFC 3066 and shall be restricted as follows: • This specification permits only zero or one <country/region> component to follow the <language> component. • This specification also permits the “-CHS” and “-CHT” three-letter <country/region> codes for “Simplified” and “Traditional” Chinese locales. • This specification also allows the use of other <country/region> codes as deemed necessary by the FDI Client or the FDI Server. Table 42 shows examples of locale ids. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 50 of 145 Table 42 – LocaleId Examples Locale OPC UA LocaleId English en English (US) en-US German de German (Germany) de-DE German (Austrian) de-AT An empty or NULL string indicates that the locale is unknown. 5.1.9.3.6 Numeric Range Numeric Range is represented as a String. The syntax for the String contains one of the following two constructs. The first construct is the String representation of an individual integer. For example, “6” is valid, but “6,0” and “3,2” are not. The minimum and maximum values that can be expressed are defined by the use of this parameter and not by this parameter type definition. The second construct is a range represented by two integers separated by the colon (“:”) character. The first integer shall always have a lower value than the second. For example, “5:7” is valid, while “7:5” and “5:5” are not. No other characters, including white-space characters, are permitted. All indexes start with 0. The maximum index is one less than the length of the array. When reading with a numeric range outside the bounds of the array, the FDI Server shall return a partial result if some elements exist within the range. The FDI Server shall return a Bad_OutOfRange if no elements exist within the range. When writing a value the numeric range shall be within the array. A numeric range can also be used to specify substrings for ByteString and String values. 5.1.9.3.7 Range This structure defines the range structure needed for the EURange Attribute. It is defined in Table 43. Table 43 – Range Data Type Structure Name Type Description Range structure “low” and “high” can contain any data type that is appropriate for the data type of the Variable Value Attribute. low Variant Lowest value in the range. high Variant Highest value in the range. 5.1.9.3.8 EUInformation This structure contains information about the EngineeringUnits. Its elements are defined in Table 44. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 51 of 145 Table 44 – EUInformation Data Type Structure Name Type Description EUInformation structure — unitId UInt32 Identifier for programmatic evaluation. 0 is used if a unitId is not available. displayName LocalizedText The displayName of the engineering unit is typically the abbreviation of the engineering unit, e.g. ”h” for hour or ”m/s” for meter per second. description LocalizedText Contains the full name of the engineering unit such as hour or meter per second . An empty text field indicates that no description is available. 5.1.9.3.9 EnumValueType This Structured DataType is used to represent a human-readable representation of an Enumeration. Its elements are described in Table 45. When this type is used in an array representing human-readable representations of an enumeration, each value of an IntegerRepresentation will be unique in that array. Table 45 – EnumValueType Definition Name Type Description EnumValueType structure — value Int64 The Integer representation of an Enumeration. displayName LocalizedText A human-readable representation of the integer representation of the Enumeration. description LocalizedText A localized description of the enumeration value. This field can contain an empty String if no description is available. 5.1.9.4 Variant A Variant is a union of all data types. Variants can also contain arrays of any of these types. Variants can be empty. An empty Variant is described as having a Null value. A Null value in a Variant is not the same as a Null String. Variants can contain arrays of Variants but they cannot directly contain another Variant. 5.2 Hosting Services General The Hosting Services are provided by the FDI Client for use by the UIP. The Hosting Services include services related to the FDI Client environment allowing the UIP to acquire information about the environment. The Hosting Services also include services to launch other UIPs as well as showing feedback. Services 5.2.2.1 General Programmatic access to the services may be synchronous or asynchronous. 5.2.2.2 GetClientTechnology Version 5.2.2.2.1 Description This service returns the technology version of the FDI Client that hosts the UIP. 5.2.2.2.2 Parameters Table 46 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 52 of 145 Table 46 – GetClientTechnologyVersion Service parameters Name Type Description Request Response version String FDI Technology Version that is supported by the FDI Client. The format of the value is xx.yy.zz as defined in FCG TS62769-4. 5.2.2.3 OpenUserInterface Service 5.2.2.3.1 Description This service is used by a UIP to request the FDI Client to open another UIP. The UIP is opened in either a modal or a non-modal window as follows: • UIPs are always invoked in a modal window, if the calling UIP runs in a modal window or if their style is dialog. • UIPs are invoked non-modal if their style = window and the calling UIP runs in non-modal mode also. NOTE A technology mapping might provide the capability to explicitly start a UIP modal even if the style is defined differently. If the UIP is already opened, this service shall bring the respective window into the foreground. 5.2.2.3.2 Parameters Table 47 defines the parameters for the service. Table 47 – OpenUserInterface Service parameters Name Type Description Request uipID String Identification of the UIP to be opened. This string is a UUID that defines a Node in the Information Model. The value of this UUID is defined in the FDI Package corresponding to the UIP to be opened (see FCG TS62769-4). Response uipHandle UInt32 FDI Client assigned id for the UIP opened. In case of a modal UIP opened, the value is null. 5.2.2.3.3 Service results There are no service results other than the common codes specified in 5.1.4.4. 5.2.2.4 CloseUserInterface Service 5.2.2.4.1 Description This service is used by a UIP to close itself or close other UIPs. The called UIP shall finish all pending or running functions that are still open. 5.2.2.4.2 Parameters Table 48 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 53 of 145 Table 48 – CloseUserInterface Service parameters Name Type Description Request uipHandle String Identification of the UIP to be closed. The uipHandle is returned by the OpenUserInterface service. This parameter can be null, if the UIP wants to close itself. Response 5.2.2.4.3 Service results There are no service results other than the common codes specified in 5.1.4.4. If the UIP refuses the Close request, Bad_RequestCancelled should be returned. 5.2.2.5 LogAuditTrailMessage Service 5.2.2.5.1 Description This service is used by a UIP to log an audit trail message. 5.2.2.5.2 Parameters Table 49 defines the parameters for the service. Table 49 – LogAuditTrailMessage Service parameters Name Type Description Request message String The message to be logged in the audit trail. Response None. 5.2.2.6 SaveUserSettings Service 5.2.2.6.1 Description This service is used by a UIP to instruct the FDI Client to save the supplied user settings. The settings are stored per UIP type in a persistent store under the control of the FDI Client. All previously saved user settings of this UIP type are replaced. The FDI Client shall not alter the user settings requested of the storage. Typically, user settings include layout information or other user preferences. They are not designed to be used for instance-specific data. There is no support for partial modifications of the user settings. A UIP has to load all settings, update them and save the complete set. The structure and content of the user setting strings is UIP type specific. For example, a UIP could use name- value pairs. Versioning issues of this data are under the responsibility of the UIP. Different UIPs of the same type can overwrite each other’s settings. Data structure is completely under control of the UIP. Therefore also versioning issues with respect to different UIP versions are under the responsibility of the UIP. 5.2.2.6.2 Parameters Table 50 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 54 of 145 Table 50 – SaveUserSettings Service parameters Name Type Description Request userSetting[] String List of user settings. The content of the strings is UIP-type specific. Response 5.2.2.7 LoadUserSettings Service 5.2.2.7.1 Description This service is used by a UIP to instruct the FDI Client to retrieve the previously saved user settings. 5.2.2.7.2 Parameters Table 51 defines the parameters for the service. Table 51 – LoadUserSettings Service parameters Name Type Description Request Response userSetting[] String List of user settings. The content of the strings is UIP-specific. 5.2.2.8 Trace Service 5.2.2.8.1 Description This service shall be used by the UIP to provide the FDI Client with information about internal events in the UIP. The trace messages are typically used for trouble shooting. The UIP shall call this service according to the trace level settings specified in the UIP Service SetTraceLevel (see 6.1.1.4). 5.2.2.8.2 Parameters Table 52 defines the parameters for the service. Table 52 – Trace Service parameters Name Type Description Request eventType TraceLevel Severity of the trace message. One of the values that specifies the severity of the trace data (see 6.1.2). classification String UIP-specific classification of the trace message. message String Trace message. The trace message language shall be English. Embedded text might be localized. Response 5.2.2.9 ShowMessageBox Service 5.2.2.9.1 Description This service opens a message box and waits until the user presses one of the given buttons. An open message box shall block any activity for the related device instance. It is recommended that simultaneous interactions with other Device instances are not affected. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 55 of 145 5.2.2.9.2 Parameters Table 53 defines the parameters for the service. Table 53 – ShowMessageBox Service parameters Name Type Description Request acknStyle AcknStyle See Table 72. message String Message to be shown to the user. caption String Title bar caption to display. buttonSet ButtonSet See Table 71. defaultResult Integer Id of the default button; see Table 70. Response buttonSelected Integer Id of the selected button; see Table 70. 5.2.2.10 ShowProgressBar Service 5.2.2.10.1 Description This service opens a progress bar. The progress bar remains on the user interface after the service returns. The information shown can be updated with the UpdateShowProgressBar service (see 5.2.2.11). The progress bar can be closed with the EndShowProgressBar service (see 5.2.2.12). Only one progress bar per UIP can be shown at a time. 5.2.2.10.2 Parameters Table 54 defines the parameters for the service. Table 54 – ShowProgressBar Service parameters Name Type Description Request message String Message to be shown to the user. callback CancelCallback Service called by the Client to inform the UIP that the user has cancelled the operation. See 5.2.2.13. The CancelCallback service is implemented and provided by the UIP. Response 5.2.2.11 UpdateShowProgressBar Service 5.2.2.11.1 Description This service updates an already open progress bar. 5.2.2.11.2 Parameters Table 55 defines the parameters for the service. NOTE A call of this service is rejected without a preceeding ShowProgressBar service call. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 56 of 145 Table 55 – UpdateShowProgressBar Service parameters Name Type Description Request message String Updated message to be shown to the user percentage Integer Updated percentage of progress to be shown to the user Response 5.2.2.12 EndShowProgressBar Service 5.2.2.12.1 Description This service closes an open progress bar. The service will wait until the user has pressed a button or will immediately return with the result if the user has previously pressed the button. 5.2.2.12.2 Parameters Table 56 defines the parameters for the service. Table 56 – EndShowProgressBar Service parameters Name Type Description Request message String Updated message to be shown to the user percentage Integer Updated percentage of progress to be shown to the user Response 5.2.2.13 CancelCallback Service 5.2.2.13.1 Description With this service the Client informs the UIP that the User requested to cancel the operation. This service is implemented and provided by the UIP when calling the ShowProgressBar service. The UIP is responsible for closing the ProgressBar. Due to the asynchronous nature of callbacks, the CancelCallback might be called even after the UIP has called the EndShowProgressBar service. 5.2.2.13.2 Parameters There are no specific parameters for the service. 5.2.2.14 StandardUIActionItemsChangeCallback Service 5.2.2.14.1 Description This service is used by the UIP to notify the FDI Client about the change in the standard UI action items’ state (enabled/disabled). See 6.1.2.2 for standard UI action items. 5.2.2.14.2 Parameters Table 57 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 57 of 145 Table 57 – StandardUIActionItemsChange Service parameters Name Type Description Request Response StandardUIActionItems[] StandardUIActionItem Updated list of Standard Actions provided by the UIP. 5.2.2.15 SpecificUIActionItemsChangeCallback Service 5.2.2.15.1 Description This service is used by the UIP to notify FDI Client about the change in the UI action items that are specific to this UIP. The UIP shall use this callback whenever there is addition or removal of action items or whenever there is a change in the state of an action item (i.e. enabled/disabled). See 6.1.2.4 for specific UI actions. 5.2.2.15.2 Parameters Table 58 defines the parameters for the service. Table 58 – SpecificUIActionItemsChange Service parameters Name Type Description Request Response SpecificUIActionItems[] SpecificUIActionItem Updated list of UI action Items specific to the UIP. 5.2.2.16 InitExportFile Service 5.2.2.16.1 Description This service is used by the UIP to save a file with access rights of the FDI Client. A file dialog is opened by the FDI Client to enter path and filename. The selected path and filename as well as a handle are returned. The handle shall be used in the WriteExportFile and FinishExportFile services to transfer the content of the file to the FDI Client and finish or cancel the operation. 5.2.2.16.2 Parameters Table 59 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 58 of 145 Table 59 – InitExportFile Service parameters Name Type Description Request SuggestedFileName String The name of the file to be saved. Can be changed by the user. The SuggestedFileName is not fully qualified, and the host manages the default directory where the file should be stored. The user can change the name and path. This is returned as FullyQualifiedFileName. Filter String Filter contains a list of possible file extensions and file types. The user can select one of the options during export. The selected filter is returned in SelectedFilterIndex. For each file extension and file type, the filter string contains a description, followed by the vertical bar (|) and the filter pattern. The strings for different filtering options are separated by the vertical bar. For example: “Word document (*.docx)|*.docx| PDF (*.pdf)|*.pdf” SuggestedFilterIndex Integer Index into the filter that is selected as default value. Response FullyQualifiedFileName String Fully qualified file name where the file was stored. SelectedFilterIndex Integer The selected filter FileHandle <technology dependent> Handle that is used in WriteExportFile and FinishExportFile to identify the overall operation. 5.2.2.17 WriteExportFile Service 5.2.2.17.1 Description This service is used to transfer data to the file to be exported. UIPs will typically call this service several times to provide the full content of the file. 5.2.2.17.2 Parameters Table 60 defines the parameters for the service. Table 60 – WriteExportFile Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitExportFile service. Data Byte[] An array of bytes containing data to be written to the file. The file created with InitExportFile is empty and the first WriteExportFile call for the file starts filling the file from the beginning, all additional calls add the data to the end of the file. Writing an empty array of Bytes returns a Good result code without any effect on the file. Response 5.2.2.18 FinishExportFile Service 5.2.2.18.1 Description This service finalizes the export file operation. It either cancels or finalizes the export of the file. 5.2.2.18.2 Parameters Table 60 defines the parameters for the service. Next >