The "Online-offline data transfer" is based on the AddIn model specified in OPC 10000-3.
The transfer of information (Parameters) between offline nodes and the physical device is supported through OPC UA Methods. These Methods are 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 Server should bring the Device back into a functional state. The Client has to retry by calling the transfer Method again.
The transfer can involve thousands of Parameters so that it can take a long time (up to minutes), and with a result that can 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 Device shall have been locked by the Client prior to invoking these Methods (see 7).
The TransferServicesType provides the Methods to transfer data to and from the online Device. Figure 29 shows the TransferServicesType definition. It is formally defined in Table 53.
Figure 29 – TransferServicesType
Table 53 – TransferServicesType definition
|
Attribute |
Value |
||||
|
BrowseName |
1:TransferServicesType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
Subtype of the 0:BaseObjectType defined in OPC 10000-5 |
|||||
|
0:HasComponent |
Method |
1:TransferToDevice |
|
|
M |
|
0:HasComponent |
Method |
1:TransferFromDevice |
|
|
M |
|
0:HasComponent |
Method |
1:FetchTransferResultData |
|
|
M |
|
Conformance Units |
|||||
|
DI Offline |
|||||
The StatusCode Bad_MethodInvalid shall be returned from the Call Service for Objects where locking is not supported. Bad_UserAccessDenied shall be returned if the Client User does not have the permission to call the Methods.
The support of TransferServices for an Object is declared by aggregating an instance of the TransferServicesType as illustrated in Figure 30.
This Object is used as container for the TransferServices Methods and shall have the BrowseName Transfer. HasComponent is used to reference from a Device to its “TransferServices” Object.
The TransferServiceType and each instance can share the same Methods.
TransferToDevice initiates the transfer of offline configured data (Parameters) to the physical device. This Method has no input arguments. Which Parameters are transferred is based on Server-internal knowledge.
The Server shall ensure integrity of the data before starting the transfer. Once the transfer has been started successfully, the Method returns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.
The Server will reset any cached value for Nodes in the online instance representing Parameters affected by the transfer. That way the cache will be re-populated from the Device next time they are requested.
The signature of this Method is specified below. Table 54 and Table 55 specify the arguments and AddressSpace representation, respectively.
Signature
TransferToDevice(
[out] 0:Int32 TransferID,
[out] 0:Int32 InitTransferStatus);
Table 54 – 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 55 – TransferToDevice Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
1:TransferToDevice |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
|
|
|
|
|
|
0:HasProperty |
Variable |
0:OutputArguments |
0:Argument[] |
0:PropertyType |
M |
|
Conformance Units |
|||||
|
DI Offline |
|||||
TransferFromDevice initiates the transfer of values from the physical device to corresponding Parameters in the offline representation of the Device. This Method has no input arguments. Which Parameters are transferred is based on Server-internal knowledge.
Once the transfer has been started successfully, the Method returns immediately with InitTransferStatus = 0. Any status information regarding the transfer itself has to be collected using the FetchTransferResultData Method.
The signature of this Method is specified below. Table 56 and Table 57 specify the arguments and AddressSpace representation, respectively.
Signature
TransferFromDevice(
[out] 0:Int32 TransferID,
[out] 0:Int32 InitTransferStatus);
Table 56 – 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 57 – TransferFromDevice Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
1:TransferFromDevice |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
|
|
|
|
|
|
0:HasProperty |
Variable |
0:OutputArguments |
0:Argument[] |
0:PropertyType |
M |
|
Conformance Units |
|||||
|
DI Offline |
|||||
The TransferToDevice and TransferFromDevice Methods execute 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 TransferID is used as identifier to retrieve the data.
The Client is 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 Server shall wait some time (some minutes) before deleting data that have not been acknowledged. This should be even beyond Session termination, i.e., Clients that have to re-establish a Session after an error can try to retrieve missing result data.
Result data will be deleted with each new transfer request for the same Device.
FetchTransferResultData is 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 can be further limited if it would be too large. “Too large” in this context means that the Server is 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 Client when calling this Method.
Each result returned to the Client is assigned a sequence number. The Client acknowledges that it received the result by passing the sequence number in the new call to this Method. The Server can delete the acknowledged result and will return the next result set with a new sequence number.
Clients shall not call the Method before the previous one returned. If it returns with an error (e.g., Bad_Timeout), the Client can 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 StatusCode of the Call Service if the transfer is finished and no further result data are available.
The signature of this Method is specified below. Table 58 and Table 59 specify the arguments and AddressSpace representation, respectively.
Signature
FetchTransferResultData(
[in] 0:Int32 TransferID,
[in] 0:Int32 SequenceNumber,
[in] 0:Int32 MaxParameterResultsToReturn,
[in] Boolean OmitGoodResults,
[out] FetchResultType FetchResultData);
Table 58 – FetchTransferResultData Method arguments
|
Argument |
Description |
|
TransferID |
Transfer Identifier returned from TransferToDevice or TransferFromDevice. |
|
SequenceNumber |
The sequence number being acknowledged. The Server can 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 Parameters in TransferResult.ParameterDefs that the Client wants the Server to return in the response. The Server is allowed to further limit the response, but shall not exceed this limit. A value of 0 indicates that the Client is 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 59 – FetchTransferResultData Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
1:FetchTransferResultData |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
0:HasProperty |
Variable |
0:InputArguments |
0:Argument[] |
0:PropertyType |
M |
|
0:HasProperty |
Variable |
0:OutputArguments |
0:Argument[] |
0:PropertyType |
M |
|
Conformance Units |
|||||
|
DI Offline |
|||||
The FetchResultDataType is an abstract type. It is the base DataType for concrete result types of the FetchTransferResultData. Its elements are defined in Table 60.
Table 60 – FetchResultDataType structure
|
Attribute |
Value |
|||
|
BrowseName |
1:FetchResultDataType |
|||
|
IsAbstract |
True |
|||
|
Subtype of 0:Structure defined in OPC 10000-3 |
||||
|
References |
NodeClass |
BrowseName |
DataType |
|
|
Conformance Units |
||||
|
DI Offline |
||||
The TransferResultErrorDataType is a subtype of the FetchResultDataType and represents an error result. It is defined in Table 61.
Table 61 – TransferResultErrorDataType structure
|
Name |
Type |
Description |
|
TransferResultErrorDataType |
0:Structure |
This structure is returned in case of errors. No result data are returned. Further calls with the same TransferID are not possible. |
|
status |
0:Int32 |
-1 – Invalid TransferID: The Id is unknown. Possible reason: all results have been fetched or the result can 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 Device occurred. “diagnostics” can contain device- or protocol-specific error information. -4 – UnknownFailure: The transfer failed. “diagnostics” can contain Device- or Protocol-specific error information. |
|
diagnostics |
0: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 DiagnosticInfo type is defined in OPC 10000-4. |
Its representation in the AddressSpace is defined in Table 62.
Table 62 – TransferResultErrorDataType Definition
|
Attribute |
Value |
|||||
|
BrowseName |
1:TransferResultErrorDataType |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
Subtype of 1:FetchResultDataType. |
||||||
|
Conformance Units |
||||||
|
DI Offline |
||||||
The TransferResultData DataType is a subtype of the FetchResultDataType and includes parameter-results from the transfer operation. It is defined in Table 63.
Table 63 – TransferResultDataDataType structure
|
Name |
Type |
Description |
|
TransferResultDataDataType |
0:Structure |
A set of results from the transfer operation. |
|
sequenceNumber |
0:Int32 |
The sequence number of this result set. |
|
endOfResults |
0:Boolean |
TRUE – all result data have been fetched. Additional FetchTransferResultData calls with the same TransferID will return a FetchTransferError with status=InvalidTransferID. FALSE – further result data shall be expected. |
|
parameterDefs |
1:ParameterResult DataType [] |
Specific value for each Parameter that has been transferred. If OmitGoodResults is TRUE, parameterDefs will only contain Parameters which have not been transferred correctly. |
|
NodePath |
0:QualifiedName[] |
List of BrowseNames that represent the relative path from the Device Object to the Parameter following hierarchical references. The Client can use these names for TranslateBrowsePathsToNodeIds to retrieve the Parameter NodeId for the online or the offline representation. |
|
statusCode |
0:StatusCode |
OPC UA StatusCode as defined in OPC 10000-4 and in OPC 10000-8. |
|
diagnostics |
0: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 DiagnosticInfo type is defined in OPC 10000-4. |
Its representation in the AddressSpace is defined in Table 64.
Table 64 – TransferResultDataDataType definition
|
Attribute |
Value |
|||||
|
BrowseName |
1:TransferResultDataDataType |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
|
Subtype of 1:FetchResultDataType. |
||||||
|
Conformance Units |
||||||
|
DI Offline |
||||||