The "Online-offline data transfer" is based on the AddInmodel specified in OPC 10001-7.
The transfer of information (Parameters) between offline nodes and the physical device is supported through OPC UA Methods. These Methodsare built on device specific knowledge and functionality.
The transfer is usually terminated if an error occurs for any of the Parameters. No automatic retry will be conducted by the Server. However, whenever possible after a failure, the Servershould bring the Deviceback into a functional state. The Clienthas to retry by calling the transfer Method again.
The transfer may involve thousands of Parametersso that it can take a long time (up to minutes), and with a result that may be too large for a single response. Therefore, the initiation of the transfer and the collection of result data are performed with separate Methods.
The Deviceshall have been locked by the Clientprior to invoking these Methods(see 7).
The TransferServicesTypeprovides the Methodsneeded to transfer data to and from the online Device. Figure 29shows the TransferServicesTypedefinition. It is formally defined in Table 44.
Figure 29– TransferServicesType
Table 44– TransferServicesType definition
|
Attribute |
Value |
||||
|
BrowseName |
TransferServicesType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
Subtype of the BaseObjectType defined in OPC 10000-5 |
|||||
|
HasComponent |
Method |
TransferToDevice |
|
|
Mandatory |
|
HasComponent |
Method |
TransferFromDevice |
|
|
Mandatory |
|
HasComponent |
Method |
FetchTransferResultData |
|
|
Mandatory |
|
Conformance Units |
|||||
|
DI Offline |
|||||
The StatusCode Bad_MethodInvalidshall be returned from the Call Servicefor Objectswhere locking is not supported. Bad_UserAccessDeniedshall be returned if the Client Userdoes not have the permission to call the Methods.
The support of TransferServicesfor an Objectis declared by aggregating an instance of the TransferServicesTypeas illustrated in Figure 30.
This Objectis used as container for the TransferServices Methodsand shall have the BrowseName Transfer. HasComponentis used to reference from a Deviceto its “TransferServices” Object.
The TransferServiceTypeand each instance may share the same Methods.
TransferToDeviceinitiates the transfer of offline configured data (Parameters) to the physical device. This Methodhas no input arguments. Which Parametersare transferred is based on Server-internal knowledge.
The Servershall ensure integrity of the data before starting the transfer. Once the transfer has been started successfully, the Methodreturns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.
The Serverwill reset any cached value for Nodesin the online instance representing Parametersaffected by the transfer. That way the cache will be re-populated from the Devicenext time they are requested.
The signature of this Methodis specified below. Table 45and Table 46specify the arguments and AddressSpacerepresentation, respectively.
Signature
TransferToDevice(
[out] Int32 TransferID,
[out] Int32 InitTransferStatus);
Table 45– TransferToDevice Method arguments
|
Argument |
Description |
|
TransferID |
Transfer Identifier. This ID has to be used when calling FetchTransferResultData. |
|
InitTransferStatus |
Specifies if the transfer has been initiated. 0 – OK -1 – E_NotLocked – the Device is not locked by the calling Client -2 – E_NotOnline – the Device is not online / cannot be accessed |
Table 46– TransferToDevice Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
TransferToDevice |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
|
|
|
|
|
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
TransferFromDeviceinitiates the transfer of values from the physical device to corresponding Parametersin the offline representation of the Device. This Methodhas no input arguments. Which Parametersare transferred is based on Server-internal knowledge.
Once the transfer has been started successfully, the Methodreturns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.
The signature of this Methodis specified below. Table 47and Table 48specify the arguments and AddressSpacerepresentation, respectively.
Signature
TransferFromDevice(
[out] Int32 TransferID,
[out] Int32 InitTransferStatus);
Table 47– TransferFromDevice Method arguments
|
Argument |
Description |
|
TransferID |
Transfer Identifier. This ID has to be used when calling FetchTransferResultData. |
|
InitTransferStatus |
Specifies if the transfer has been initiated. 0 – OK -1 – E_NotLocked – the Device is not locked by the calling Client -2 – E_NotOnline – the Device is not online / cannot be accessed |
Table 48– TransferFromDevice Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
TransferFromDevice |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
|
|
|
|
|
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
The TransferToDeviceand TransferFromDevice Methodsexecute asynchronously after sending a response to the Client. Execution status and execution results are collected during execution and can be retrieved using the FetchTransferResultData Method. The TransferIDis used as identifier to retrieve the data.
The Clientis assumed to fetch the result data in a timely manner. However, because of the asynchronous execution and the possibility of data loss due to transmission errors to the Client, the Servershall wait some time (some minutes) before deleting data that have not been acknowledged. This should be even beyond Sessiontermination, i.e. Clientsthat have to re-establish a Sessionafter an error may try to retrieve missing result data.
Result data will be deleted with each new transfer request for the same Device.
FetchTransferResultDatais used to request the execution status and a set of result data. If called before the transfer is finished it will return only partial data. The amount of data returned may be further limited if it would be too large. “Too large” in this context means that the Serveris not able to return a larger response or that the number of results to return exceeds the maximum number of results that was specified by the Clientwhen calling this Method.
Each result returned to the Clientis assigned a sequence number. The Clientacknowledges that it received the result by passing the sequence number in the new call to this Method. The Servercan delete the acknowledged result and will return the next result set with a new sequence number.
Clients shall not call the Methodbefore the previous one returned. If it returns with an error (e.g. Bad_Timeout), the Clientcan call the FetchTransferResultData with a sequence number 0. In this case the Server will resend the last result set.
The Server will return Bad_NothingToDo in the Method-specific StatusCodeof the Call Serviceif the transfer is finished and no further result data are available.
The signature of this Methodis specified below. Table 49and Table 50specify the arguments and AddressSpacerepresentation, respectively.
Signature
FetchTransferResultData(
[in] Int32 TransferID,
[in] Int32 SequenceNumber,
[in] Int32 MaxParameterResultsToReturn,
[in] Boolean OmitGoodResults,
[out] FetchResultType FetchResultData);
Table 49– FetchTransferResultData Method arguments
|
Argument |
Description |
|
TransferID |
Transfer Identifier returned from TransferToDeviceor TransferFromDevice. |
|
SequenceNumber |
The sequence number being acknowledged. The Servermay delete the result set with this sequence number. “0” is used in the first call after initialising a transfer and also if the previous call of FetchTransferResultData failed. |
|
MaxParameterResultsToReturn |
The number of Parametersin TransferResult.ParameterDefsthat the Client wants the Serverto return in the response. The Serveris allowed to further limit the response, but shall not exceed this limit. A value of 0 indicates that the Clientis imposing no limitation. |
|
OmitGoodResults |
If TRUE, the Server will omit data for Parameters which have been correctly transferred. Note that this causes all good results to be released. |
|
FetchResultData |
Two subtypes are possible:
|
Table 50– FetchTransferResultData Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
FetchTransferResultData |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
The FetchResultDataTypeis an abstract type. It is the base DataTypefor concrete result types of the FetchTransferResultData. Its elements are defined in Table 51.
Table 51– FetchResultDataType structure
|
Attribute |
Value |
|||
|
BrowseName |
FetchResultDataType |
|||
|
IsAbstract |
True |
|||
|
Subtype of Structure defined in OPC 10000-3 |
||||
|
References |
NodeClass |
BrowseName |
DataType |
|
|
HasSubtype |
DataType |
TransferResultErrorDataType |
Defined in Table 52. |
|
|
HasSubtype |
DataType |
TransferResultDataDataType |
Defined in Table 53. |
|
The TransferResultErrorDataTypeis a subtype of the FetchResultDataTypeand represents an error result. It is defined in Table 52.
Table 52– TransferResultError DataType structure
|
Name |
Type |
Description |
|
TransferResultError DataType |
Structure |
This structure is returned in case of errors. No result data are returned. Further calls with the same TransferIDare not possible. |
|
status |
Int32 |
-1 – Invalid TransferID: The Id is unknown. Possible reason: all results have been fetched or the result may have been deleted. -2 – Transfer aborted: The transfer operation was aborted; no results exist. -3 – DeviceError: An error in the device or the communication to the Deviceoccurred. “diagnostics” may contain device- or protocol-specific error information. -4 – UnknownFailure: The transfer failed. “diagnostics” may contain Device- or Protocol-specific error information. |
|
diagnostics |
DiagnosticInfo |
Diagnostic information. This parameter is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. The DiagnosticInfotype is defined in OPC 10000-4. |
The TransferResultData DataTypeis a subtype of the FetchResultDataTypeand includes parameter-results from the transfer operation. It is defined in Table 53.
Table 53– TransferResultData DataType structure
|
Name |
Type |
Description |
|
TransferResultData DataType |
Structure |
A set of results from the transfer operation. |
|
sequenceNumber |
Int32 |
The sequence number of this result set. |
|
endOfResults |
Boolean |
TRUE – all result data have been fetched. Additional FetchTransferResultDatacalls with the same TransferIDwill return a FetchTransferError with status=InvalidTransferID. FALSE – further result data shall be expected. |
|
parameterDefs |
ParameterResult DataType [] |
Specific value for each Parameterthat has been transferred. If OmitGoodResults is TRUE, parameterDefs will only contain Parameterswhich have not been transferred correctly. |
|
NodePath |
QualifiedName[] |
List of BrowseNames that represent the relative path from the Device Objectto the Parameterfollowing hierarchical references. The Clientmay use these names for TranslateBrowsePathsToNodeIdsto retrieve the Parameter NodeIdfor the online or the offline representation. |
|
statusCode |
StatusCode |
OPC UA StatusCodeas defined in OPC 10000-4and in OPC 10000-8. |
|
diagnostics |
DiagnosticInfo |
Diagnostic information. This parameter is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. The DiagnosticInfotype is defined in OPC 10000-4. |