7 OPC UA ObjectTypes
7.1 ResultManagementType ObjectType Definition
7.1.1 Overview
The ResultManagementType provides mechanism to access results generated by the underlying system. Results can be managed in a local result store of the Server. Methods and Objects with Variables as well as Events and external file stores can be used to provide the results to the Client. The ObjectType is formally defined in Table 1.
| Attribute | Value | ||||
| BrowseName | ResultManagementType | ||||
| IsAbstract | False | ||||
| Description | Provides mechanism to access results generated by the underlying system. | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | Other |
|---|---|---|---|---|---|
| Subtype of the 0:BaseObjectType defined in OPC 10000-5 | |||||
| 0:HasProperty | Variable | 0:DefaultInstanceBrowseName | 0:QualifiedName | 0:PropertyType | |
| 0:HasComponent | Method | GetResultById | O | ||
| 0:HasComponent | Method | GetResultIdListFiltered | O | ||
| 0:HasComponent | Method | ReleaseResultHandle | O | ||
| 0:HasComponent | Method | GetLatestResult | O | ||
| 0:HasComponent | Object | ResultTransfer | ResultTransferType | O | |
| 0:HasComponent | Object | Results | 0:FolderType | O | |
| 0:HasComponent | Method | AcknowledgeResults | O | ||
| 0:GeneratesEvent | ObjectType | ResultReadyEventType | |||
| Conformance Units | |||||
|---|---|---|---|---|---|
| Machinery-Result Types |
The optional ResultTransfer Object is used to transfer the content of a result by a temporary file transfer. In order to be called by the Client, the Client first need to receive a ResultId.
The optional Results Object is used to organize available results of the system which the Server decides to expose in the AddressSpace. It may contain no result if no result is available, if the Server does not expose results in the AddressSpace at all or if no available result matches the criteria of the Server for exposure in the AddressSpace. It may contain multiple results if multiple results are available.
The components of the ResultManagementType have additional subcomponents which are defined in Table 2.
| Source Path | Reference | NodeClass | BrowseName | DataType | TypeDefinition | Others |
| Results | 0:HasComponent | Variable | <ResultVariable> | ResultDataType | ResultType | OP |
Each <ResultVariable> represents a result. If partial results are supported, the Variable value gets updated with partial results until the final result is provided as value.
The child Nodes of the ResultManagementType have additional Attribute values defined in Table 3.
| BrowsePath | Value Attribute | Description Attribute |
| 0:DefaultInstanceBrowseName | ResultManagement | The default BrowseName for instances of the type. |
7.1.2 GetResultById
The Method GetResultById is used to retrieve a result. Depending on the design of the system, the Client may be informed by Events of ResultReadyEventType that a new result is available. Then, the Client might fetch this result using the information provided by Events of ResultReadyEventType which is defined in Section 8.1.
Since the ResultId is supposed to be system-wide unique, this Method shall return only a single result. If the system supports partial results, only the latest partial result, or the final result, shall be returned.
Since there may be additional result content to be retrieved by temporary file transfer, the Server should keep result data available, resources permitting, until the Client releases the handle by calling ReleaseResultHandle. However, the Client cannot rely on the data to remain available until then.
The signature of this Method is specified below. Table 4 and Table 5 specify the Arguments and AddressSpace representation, respectively.
Signature
GetResultById (
[in] 0:TrimmedString resultId,
[in] 0:Int32 timeout,
[out] 0:Handle resultHandle,
[out] ResultDataType result,
[out] 0:Int32 error)| Argument | Description |
| resultId | System-wide unique identifier for the result. |
| timeout | With this argument the Client can give a hint to the Server how long it will need access to the result data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the Client will not need anything besides the data returned by the method call. A value < 0 indicates that the Client cannot give an estimate. The Client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the Server to optimize its resource management. |
| resultHandle | The Server shall return to each Client requesting result data a system-wide unique handle identifying the result set / Client combination. This handle should be used by the Client to indicate to the Server that the result data is no longer needed, allowing the Server to optimize its resource handling. If the instance of ResultManagementType does not support the ReleaseResultHandle Method, the resultHandle should always be set to 0. If the error is set to a value other than 0, the resultHandle may be set to 0. |
| result | The result including metadata. May be set to Null, if error is set to a value other than 0. |
| error | 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. |
| Attribute | Value | ||||
| BrowseName | GetResultById | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
7.1.3 GetResultIdListFiltered
The Method GetResultIdListFiltered is used to get a list of results matching certain filter criteria. The signature of this Method is specified below. Table 6 and Table 7 specify the Arguments and AddressSpace representation, respectively.
Signature
GetResultIdListFiltered (
[in] 0:ContentFilter filter,
[in] 0:RelativePath[] orderedBy,
[in] 0:UInt32 maxResults,
[in] 0:Int32 timeout,
[out] 0:Handle resultHandle,
[out] 0:TrimmedString[] resultIdList,
[out] 0:Int32 error)| Argument | Description |
| filter | Filter used to filter for specific results based on the meta data of the results. Valid BrowsePaths used in the filter can be built from the fields of the ResultReadyEventType, the ResultType VariableType or the ResultDataType or corresponding subtypes. |
| orderedBy | An array of RelativePaths identifying the ordering criteria for the results. If the array is null or empty, no ordering is executed. If several RelativePaths are provided, the first entry in the array is used as first ordering criteria, etc. |
| maxResults | Defines how many resultIds the Client wants to receive at most. If no maximum should be provided, it is set to 0. |
| timeout | With this argument the Client can give a hint to the Server how long it will need access to the result data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the Client will not need anything besides the data returned by the method call. A value < 0 indicates that the Client cannot give an estimate. The Client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the Server to optimize its resource management. |
| resultHandle | The Server shall return to each Client requesting result data a system-wide unique handle identifying the result set / Client combination. This handle has to be used by the Client to release the result set. If the instance of ResultManagementType does not support the ReleaseResultHandle Method, the resultHandle should always be set to 0. If the error is set to a value other than 0, the resultHandle may be set to 0. |
| resultIdList | List of resultIds of results matching the Filter. |
| error | 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. |
| Attribute | Value | ||||
| BrowseName | GetResultIdListFiltered | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
7.1.4 ReleaseResultHandle
The Method ReleaseResultHandle is used to inform the Server that the Client has finished processing a given result set allowing the Server to free resources managing this result set.
The Server should keep the data of the result set available for the Client until the ReleaseResultHandle Method is called or until a timeout given by the Client has expired. However, the Server is free to release the data at any time, depending on its internal resource management, so the Client cannot rely on the data being available. ReleaseResultHandle is merely a hint allowing the Server to optimize its internal resource management. For timeout usage see the description in Section 6.4.
The signature of this Method is specified below. Table 8 and Table 9 specify the Arguments and AddressSpace representation, respectively.
Signature
ReleaseResultHandle (
[in] 0:Handle resultHandle,
[out] 0:Int32 error)| Argument | Description |
| resultHandle | Handle returned by GetResultById or GetResultIdListFiltered, identifying the result set/Client combination. |
| Error | 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. |
| Attribute | Value | ||||
| BrowseName | ReleaseResultHandle | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
7.1.5 GetLatestResult
The Method GetLatestResult is used to retrieve the latest result created for the instance of ResultManagementType.
Since there may be additional result content to be retrieved by temporary file transfer, the Server should keep result data available, resources permitting, until the Client releases the handle by calling ReleaseResultHandle. However, the Client cannot rely on the data to remain available until then.
The signature of this Method is specified below. Table 10 and Table 11 specify the Arguments and AddressSpace representation, respectively.
Signature
GetLatestResult (
[in] 0:Int32 timeout,
[out] 0:Handle resultHandle,
[out] ResultDataType result,
[out] 0:Int32 error)| Argument | Description |
| timeout | With this argument the Client can give a hint to the Server how long it will need access to the result data. A value > 0 indicates an estimated maximum time for processing the data in milliseconds. A value = 0 indicates that the Client will not need anything besides the data returned by the method call. A value < 0 indicates that the Client cannot give an estimate. The Client cannot rely on the data being available during the indicated time period. The argument is merely a hint allowing the Server to optimize its resource management. |
| resultHandle | The Server shall return to each Client requesting result data a system-wide unique handle identifying the result set / Client combination. This handle should be used by the Client to indicate to the Server that the result data is no longer needed, allowing the Server to optimize its resource handling. If the instance of ResultManagementType does not support the ReleaseResultHandle Method, the resultHandle should always be set to 0. If the error is set to a value other than 0, the resultHandle may be set to 0. |
| result | The result including metadata. |
| error | 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. |
| Attribute | Value | ||||
| BrowseName | GetLatestResult | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
7.1.6 AcknowledgeResults
The Method AcknowledgeResults is used to inform the Server that the Client has finished the processing of given results allowing the Server to free resources managing those results.
The Server may be configured to keep the results available for the Client until the AcknowledgeResults Method is called. However, the Server is free to release the results at any time, depending on its internal resource management, so the Client cannot rely on the data being available.
Note: It is recommended that this Method is used only by the Client that is responsible for exclusively storing the results.
The signature of this Method is specified below. Table 12 and Table 13 specify the Arguments and AddressSpace representation, respectively.
Signature
AcknowledgeResults (
[in] 0:TrimmedString[] resultIds,
[out] 0:Int32[] errorPerResultId,
[out] 0:Int32 error
)| Argument | Description |
| resultIds | List of result identifiers to be acknowledged. |
| errorPerResultId | Shall be null or empty if error equals 0. Shall have the same length as resultIds if error is not equal 0. Indicates for each resultId in resultIds, if the acknowledge was successful. Per entry: 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. |
| error | 0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors. Shall be not equal 0 if any resultId of resultIds was not successfully acknowledged. Shall be 0 if all resultIds where acknowledged successful. |
| Attribute | Value | ||||
| BrowseName | AcknowledgeResults | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
7.2 ResultTransferType ObjectType Definition
7.2.1 Overview
This ObjectType is a subtype of the 0:TemporaryFileTransferType defined in OPC 10000-20 and is used to transfer result data as a file.
The ResultTransferType overwrites the Method GenerateFileForRead to specify the concrete type of the generateOptions Argument of the Method. It does not specialize the GenerateFileForWrite Method of the base type as results are supposed to be only generated by the Server, not received.
The ResultTransferType is formally defined in Table 14.
| Attribute | Value | ||||
| BrowseName | ResultTransferType | ||||
| IsAbstract | False | ||||
| Description | Transfers result data as a file. | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | Other |
|---|---|---|---|---|---|
| Subtype of the 0:TemporaryFileTransferType defined in OPC 10000-20 | |||||
| HasComponent | Method | GenerateFileForRead | M | ||
| Conformance Units | |||||
|---|---|---|---|---|---|
| Machinery-Result Types |
7.2.2 GenerateFileForRead
The Method GenerateFileForRead is used to start the read file transaction. A successful call of this Method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object. The signature of this Method is specified below. Table 15 and Table 16 specify the Arguments and AddressSpace representation, respectively.
Signature
GenerateFileForRead (
[in] BaseResultTransferOptionsDataType generateOptions,
[out] 0:NodeId fileNodeId,
[out] 0:UInt32 fileHandle,
[out] 0:NodeId completionStateMachine)| Argument | Description |
| generateOptions | Options how to generate the file, including the resultId of the result the file belongs to. |
| fileNodeId | NodeId of the temporary file. |
| fileHandle | The FileHandle of the opened TransferFile. The FileHandle can be used to access the TransferFile methods Read and Close. |
| completionStateMachine | If the creation of the file is completed asynchronously, the parameter returns the NodeId of the corresponding FileTransferStateMachineType Object. If the creation of the file is already completed, the parameter is null. If a FileTransferStateMachineType object NodeId is returned, the Read Method of the file fails until the TransferState changed to ReadTransfer. |
| Attribute | Value | ||||
| BrowseName | 0:GenerateFileForRead | ||||
| References | Node Class | BrowseName | DataType | TypeDefinition | ModellingRule |
|---|---|---|---|---|---|
| 0:HasProperty | Variable | 0:InputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |
| 0:HasProperty | Variable | 0:OutputArguments | 0:Argument[] | 0:PropertyType | 0:Mandatory |