Errata exists for this version of the document.
Methods represent the function calls of Objects. They are defined in OPC 10000-3. Methods are invoked and return only after completion (successful or unsuccessful). Execution times for Methods may vary, depending on the function that they perform.
The Method Service Set defines the means to invoke Methods. A Method shall be a component of an Object. Discovery is provided through the Browse and Query Services. Clients discover the Methods supported by a Server by browsing for the owning Objects References that identify their supported Methods.
Because Methods may control some aspect of plant operations, Method invocation may depend on environmental or other conditions. This may be especially true when attempting to re-invoke a Method immediately after it has completed execution. Conditions that are required to invoke the Method might not yet have returned to the state that permits the Method to start again.
This Service is used to call (invoke) a list of Methods.
This Service provides for passing input and output arguments to/from a Method. These arguments are defined by Properties of the Method.
If the Method is invoked in the context of a Session and the Session is terminated, the results of the Method’s execution cannot be returned to the Client and are discarded. This is independent of the task actually performed at the Server.
The order the operations are processed in the Server is not defined and depends on the different tasks and the internal Server logic. If a Method is contained in more than one operation, the order of the processing is undefined. If a Client requires sequential processing the Client needs separate Service calls.
Table 65 defines the parameters for the Service.
Table 65 – Call Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.28 for RequestHeader definition). |
|
methodsToCall [] |
CallMethodRequest |
List of Methods to call. This structure is defined in-line with the following indented items. |
|
objectId |
NodeId |
The NodeId shall be that of the Object or ObjectType on which the Method is invoked. In case of an ObjectType the ObjectType or a super type of the ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId. In case of an Object the Object or the ObjectType of the Object or a super type of that ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId. See OPC 10000-3 for a description of Objects and their Methods. |
|
methodId |
NodeId |
NodeId of the Method to invoke. If the objectId is the NodeId of an Object, it is allowed to use the NodeId of a Method that is the target of a HasComponent Reference from the ObjectType of the Object. |
|
inputArguments [] |
BaseDataType |
List of input argument values. An empty list indicates that there are no input arguments. The size and order of this list matches the size and order of the input arguments defined by the input InputArguments Property of the Method. The name, a description and the data type of each argument are defined by the Argument structure in each element of the method’s InputArguments Property. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.29 for ResponseHeader definition). |
|
results [] |
CallMethodResult |
Result for the Method calls. This structure is defined in-line with the following indented items. |
|
statusCode |
StatusCode |
StatusCode of the Method executed in the server. This StatusCode is set to the Bad_InvalidArgument StatusCode if at least one input argument broke a constraint (e.g. wrong data type, value out of range). This StatusCode is set to a bad StatusCode if the Method execution failed in the server, e.g. based on an exception. |
|
inputArgumentResults [] |
StatusCode |
List of StatusCodes corresponding to the inputArguments. This list is empty unless the operation level result is Bad_InvalidArgument. If this list is populated, it has the same length as the inputArguments list. |
|
inputArgumentDiagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information corresponding to the inputArguments. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. |
|
outputArguments [] |
BaseDataType |
List of output argument values. An empty list indicates that there are no output arguments. The size and order of this list matches the size and order of the output arguments defined by the OutputArguments Property of the Method. The name, a description and the data type of each argument are defined by the Argument structure in each element of the methods OutputArguments Property. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the statusCode of the results. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request. |
Table 66 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.
Table 66 – Call Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 177 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 177 for the description of this result code. |
Table 67 defines values for the statusCode parameter and Table 68 defines values for the inputArgumentResults parameter that are specific to this Service. Common StatusCodes are defined in Table 178.
Server vendors or OPC UA companion specifications may reuse existing StatusCodes for application specific error information. This is valid as long as the canonical description of the StatusCode does not have a different meaning than the application specific description. To eliminate any vagueness, the Server should include the application specific description in the DiagnosticInfo.
Good StatusCodes with sub-status shall not be used as statusCode since many programming language bindings would cause such codes to throw an exception.
Table 67 – Call Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NodeIdInvalid |
See Table 178 for the description of this result code. Used to indicate that the specified Object is not valid. |
|
Bad_NodeIdUnknown |
See Table 178 for the description of this result code. Used to indicate that the specified Object is not valid. |
|
Bad_NotExecutable |
The executable Attribute does not allow the execution of the Method. |
|
Bad_ArgumentsMissing |
The Client did not specify all of the input arguments for the Method. |
|
Bad_TooManyArguments |
The Client specified more input arguments than defined for the Method. |
|
Bad_InvalidArgument |
See Table 177 for the description of this result code. Used to indicate in the operation level results that one or more of the input arguments are invalid. The inputArgumentResults contain the specific status code for each invalid argument. |
|
Bad_UserAccessDenied |
See Table 177 for the description of this result code. |
|
Bad_SecurityModeInsufficient |
See Table 178 for the description of this result code. |
|
Bad_MethodInvalid |
The method id does not refer to a Method for the specified Object. |
|
Bad_NoCommunication |
See Table 178 for the description of this result code. |
Table 68 – Call Input Argument Result Codes
|
Symbolic Id |
Description |
|
Bad_OutOfRange |
See Table 178 for the description of this result code. Used to indicate that an input argument is outside the acceptable range. |
|
Bad_TypeMismatch |
See Table 178 for the description of this result code. Used to indicate that an input argument does not have the correct data type. A ByteString is structurally the same as a one dimensional array of Byte. A Server shall accept a ByteString if an array of Byte is expected. |