EstablishConnections signature – OPC Unified Architecture – Part 81: UAFX Connecting Devices and Information Model

6.2.4.2 EstablishConnections signature

The signature of this Method is specified below; the arguments are defined in Table 8.

Signature

	EstablishConnections (
	  [in] 2:FxCommandMask				CommandMask,
	  [in] 2:AssetVerificationDataType[]		AssetVerifications,
	  [in] 2:ConnectionEndpointConfigurationDataType[]	
								ConnectionEndpointConfigurations,
	  [in] 2:ReserveCommunicationIdsDataType[]	ReserveCommunicationIds,
	  [in] 2:CommunicationConfigurationDataType[]	CommunicationConfigurations,
							
	  [out] 2:AssetVerificationResultDataType[]	AssetVerificationResults,
	  [out] 2:ConnectionEndpointConfigurationResultDataType[]	
							ConnectionEndpointConfigurationResults,
	  [out] 2:ReserveCommunicationIdsResultDataType[]	
								ReserveCommunicationIdsResults,
	  [out] 2:CommunicationConfigurationResultDataType[]	
								CommunicationConfigurationResults
	  );

Table 8 – EstablishConnections Method arguments

Argument	Description
CommandMask	CommandMask provides the commands to be processed by the implementation of this Method. How individual commands shall be processed is described in 6.2.4.3. The CommandMask contains bits for the following commands: VerifyAssetCmd (see 6.2.4.3.2), VerifyFunctionalEntityCmd (see 6.2.4.3.3 ), ReserveCommunicationIdsCmd (see 6.2.4.3.4), CreateConnectionEndpointCmd (see 6.2.4.3.5), EstablishControlCmd (see 6.2.4.3.6), SetConfigurationDataCmd (see 6.2.4.3.7), ReassignControlCmd (see 6.2.4.3.8), SetCommunicationConfigurationCmd (see 6.2.4.3.9), and EnableCommunicationCmd (see 6.2.4.3.10). For a formal definition of the CommandMask, see 10.23. The CommandMask shall have at least one command bit set to TRUE.
AssetVerifications	Provides parameters for Asset verification. For a formal definition of the AssetVerificationDataType, see 10.5. If CommandMask VerifyAssetCmd is set, AssetVerifications shall contain at least one element. If CommandMask VerifyAssetCmd is not set, AssetVerifications shall be null or empty.
ConnectionEndpointConfigurations	Provides configuration information for Connections. For a formal definition of the ConnectionEndpointConfigurationDataType, see 10.14. If CommandMask VerifyFunctionalEntityCmd, CreateConnectionEndpointCmd, EstablishControlCmd, SetConfigurationDataCmd, ReassignControlCmd, SetCommunicationConfigurationCmd, or EnableCommunicationCmd is set, ConnectionEndpointConfigurations shall contain at least one element. If CommandMask VerifyFunctionalEntityCmd, CreateConnectionEndpointCmd, EstablishControlCmd, SetConfigurationDataCmd, ReassignControlCmd, SetCommunicationConfigurationCmd, and EnableCommunicationCmd are not set, ConnectionEndpointConfigurations shall be null or empty. If CommandMask VerifyFunctionalEntityCmd is set, at least one of the ConnectionEndpointConfigurations elements shall contain ExpectedVerificationVariables with at least one element. If CommandMask VerifyFunctionalEntityCmd is not set, all ExpectedVerificationVariables in all ConnectionEndpointConfigurations shall be null or empty. For the EstablishControlCmd, SetConfigurationDataCmd, ReassignControlCmd, SetCommunicationConfigurationCmd, or EnableCommunicationCmd, a non-null ConnectionEndpoint is required. If CommandMask CreateConnectionEndpointCmd is set, at least one of the ConnectionEndpointConfigurations elements shall expose ConnectionEndpointDefinitionDataType with Parameter (see 10.16) as ConnectionEndpoint. If CommandMask CreateConnectionEndpointCmd is not set, all ConnectionEndpointConfigurations elements shall expose ConnectionEndpointDefinitionDataType with Node (see 10.16) as ConnectionEndpoint. If CommandMask EstablishControlCmd or ReassignControlCmd is set, at least one of the ConnectionEndpointConfigurations elements shall contain ControlGroups with at least one element. If CommandMask EstablishControlCmd and ReassignControlCmd are not set, all ControlGroups in all ConnectionEndpointConfigurations shall be null or empty. If CommandMask SetConfigurationDataCmd is set, at least one of the ConnectionEndpointConfigurations elements shall contain ConfigurationData with at least one element. If CommandMask SetConfigurationDataCmd is not set, all ConfigurationData in all ConnectionEndpointConfigurations shall be null or empty. If CommandMask SetCommunicationConfigurationCmd is set, at least one of the ConnectionEndpointConfigurations elements shall contain a non-null CommunicationLinks. If CommandMask SetCommunicationConfigurationCmd is not set, all CommunicationLinks in all ConnectionEndpointConfigurations shall be set to null.
ReserveCommunicationIds	Provides the request for communication model-specific identifiers. For a formal definition of the ReserveCommunicationIdsDataType, see 10.43. If CommandMask ReserveCommunicationIdsCmd is set, ReserveCommunicationIds shall contain at least one element. If CommandMask ReserveCommunicationIdsCmd is not set, ReserveCommunicationIds shall be null or empty.
CommunicationConfigurations	Provides the ConfigurationData specific to the communication model utilised by the provided Connections. For a formal definition of the CommunicationConfigurationDataType, see 10.10. If CommandMask SetCommunicationConfigurationCmd is set, CommunicationConfigurations shall contain a single element. If CommandMask SetCommunicationConfigurationCmd is not set, CommunicationConfigurations shall be null or empty.
AssetVerificationResults	Indicates the results for the command VerifyAssetCmd (see 6.2.4.3.2). For a formal definition of the AssetVerificationResultDataType, see 10.6. If CommandMask VerifyAssetCmd is set, the length of this array shall match the length of AssetVerifications, and each element shall contain the result of the corresponding element in AssetVerifications. If CommandMask VerifyAssetCmd is not set, it shall be null or empty.
ConnectionEndpointConfigurationResults	Indicates the results for the commands VerifyFunctionalEntityCmd (see 6.2.4.3.3), CreateConnectionEndpointCmd (see 6.2.4.3.5), EstablishControlCmd (see 6.2.4.3.6), SetConfigurationDataCmd (see 6.2.4.3.7), ReassignControlCmd (see 6.2.4.3.8), SetCommunicationConfigurationCmd (see 6.2.4.3.9) or EnableCommunicationCmd (see 6.2.4.3.10). For a formal definition of the ConnectionEndpointConfigurationResultDataType, see 10.15. If CommandMask VerifyFunctionalEntityCmd, CreateConnectionEndpointCmd, EstablishControlCmd, SetConfigurationDataCmd, ReassignControlCmd, SetCommunicationConfigurationCmd, or EnableCommunicationCmd are set, the length of this array shall match the length of ConnectionEndpointConfigurations, and each element shall contain the result of the corresponding element in ConnectionEndpointConfigurations. If CommandMask VerifyFunctionalEntityCmd, CreateConnectionEndpointCmd, EstablishControlCmd, SetConfigurationDataCmd, ReassignControlCmd, SetCommunicationConfigurationCmd, and EnableCommunicationCmd are not set, it shall be null or empty. For the setting of the individual results in the ConnectionEndpointConfigurationResultDataType, see 6.2.4.3 (if the appropriate CommandMask bit is set) and 10.15 (if the appropriate CommandMask bit is not set).
ReserveCommunicationIdsResults	Indicates the results for the command ReserveCommunicationIdsCmd (see 6.2.4.3.4). For a formal definition of the ReserveCommunicationIdsResultDataType, see 10.44. If CommandMask ReserveCommunicationIdsCmd is set, the length of this array shall match the length of the ReserveCommunicationIds, and each element shall contain the result of the corresponding element in ReserveCommunicationIds. If CommandMask ReserveCommunicationIdsCmd is not set, it shall be null or empty.
CommunicationConfigurationResults	Indicates the result for the command SetCommunicationConfigurationCmd (see 6.2.4.3.9). For a formal definition of the CommunicationConfigurationResultDataType, see 10.11. If CommandMask SetCommunicationConfigurationCmd is set, a single element shall exist containing the result of the SetCommunicationConfigurationCmd command. If CommandMask SetCommunicationConfigurationCmd is not set, it shall be null or empty.

The possible Method result codes are formally defined in Table 9.

Table 9 – EstablishConnections Method result codes

Result Code	Description
Bad_InvalidArgument	One or multiple Arguments do not match the requirements specified for the commands set in CommandMask (see Table 8), or no bits in CommandMask are set.
Bad_InvalidState	A command bit or combination of command bits set in CommandMask cannot be processed in the AutomationComponent’s current state.
Bad_TooManyOperations	The requested number of Connections to establish exceeds the MaxConnectionsPerCall capability of the AutomationComponent (see 6.2.6).
Uncertain	The Method was aborted due to errors while executing a command. Depending on the executed commands, one or more of the AssetVerificationResults, ConnectionEndpointConfigurationResults, ReserveCommunicationIdsResults, and CommunicationConfigurationResults will contain additional information.

The possible StatusCodes for the AssetVerificationResults VerificationStatus are formally defined in Table 10.

Table 10 – AssetVerificationResults VerificationStatus StatusCodes

Result Code	Description
Bad_NodeIdUnknown	AssetToVerify does not exist in the Server address space.
Bad_NodeIdInvalid	The syntax of AssetToVerify is invalid.
Bad_InvalidArgument	AssetToVerify is not an Asset.
	Also, include all Result Codes in Table 32.

The possible StatusCodes for the ConnectionEndpointConfigurationResults FunctionalEntityNodeResult are formally defined in Table 11.

Table 11 – FunctionalEntityNodeResult StatusCodes

Result Code	Description
Bad_NodeIdUnknown	The NodeId for FunctionalEntityNode does not exist in the Server address space.
Bad_NodeIdInvalid	The syntax of the NodeId for FunctionalEntityNode was invalid.
Bad_InvalidArgument	The NodeId for FunctionalEntityNode was not a FunctionalEntity or related to the AutomationComponent on which EstablishConnections was called.
Good	The NodeId for FunctionalEntityNode was valid.

The possible StatusCodes for the ConnectionEndpointConfigurationResults ConnectionEndpointResult are formally defined in Table 12.

Table 12 – ConnectionEndpointResult StatusCodes

Result Code	Description
Bad_NotSupported	The requested IsPersistent was not supported. The requested Connection does not include a feedback signal (PubSubConnectionEndpointParameterDataType Mode is set to Publisher), but the FunctionalEntity requires it (FeedbackSignalRequired is set to TRUE (see 6.4.7)).
Bad_TypeDefinitionInvalid	The requested ConnectionEndpointTypeId does not reference a supported type (see 6.6).
Bad_InvalidArgument	Neither InputVariableIds nor OutputVariableIds was specified. An element of InputVariableIds or OutputVariableIds has an unknown or invalid NodeId or was not a Variable. An element of InputVariableIds is not referenced from an input folder in either the FunctionalEntityNode or a SubFunctionalEntity of it. An element of OutputVariableIds is not referenced from an output folder in either the FunctionalEntityNode or a SubFunctionalEntity of it. The NodeId for the requested ConnectionEndpoint was not a ConnectionEndpoint. A null RelatedEndpoint was specified. A null ConnectionEndpoint was supplied, but the command required a ConnectionEndpoint. The requested ConnectionEndpointTypeId does not match a concrete subtype of ConnectionEndpointType. A preconfigured ConnectionEndpoint exists, but it does not match the requested parameters. The preconfigured ConnectionEndpoint was not found. This error code may also be used for any other parameter error in an EstablishConnections Call.
Bad_BrowseNameDuplicated	The name for the ConnectionEndpoint was not unique within the scope of the FunctionalEntity’s ConnectionEndpoints Folder.
Bad_ResourceUnavailable	Maximum number of Connections exceeded. See AutomationComponentCapabilityType MaxConnections in section 6.2.6. An AutomationComponent may set this StatusCode, even if the optional AutomationComponentCapability MaxConnections does not exist.
Bad_NothingToDo	The operation was skipped. Creating this ConnectionEndpoint was skipped because a preceding command had already resulted in an error.
Bad_NodeIdUnknown	The NodeId for the requested ConnectionEndpoint does not exist in the FunctionalEntity.
Bad_NodeIdInvalid	The syntax of the NodeId for the requested ConnectionEndpoint was invalid.
Bad_RequestNotAllowed	The ConnectionEndpoint to be enabled references input Variables, which are referenced by another enabled ConnectionEndpoint.
Bad_InvalidState	A preconfigured ConnectionEndpoint exists, but it is currently in use, as indicated by a RelatedEndpoint.
Good	Creating or using the ConnectionEndpoint succeeded.

The possible StatusCodes for the ConnectionEndpointConfigurationResults EstablishControlResult are formally defined in Table 13.

Table 13 – EstablishControlResult StatusCodes

Result Code	Description
Bad_NodeIdUnknown	The NodeId for the requested ControlGroup does not exist in the FunctionalEntity.
Bad_NodeIdInvalid	The syntax of the NodeId for the requested ControlGroup was invalid.
Bad_InvalidArgument	The NodeId for the requested ControlGroup was not a ControlGroup.
Bad_NothingToDo	Establishing control was skipped because a preceding command had already resulted in an error.
	Also, include all Result Codes in Table 65.

The possible StatusCodes for the ConnectionEndpointConfigurationResults ConfigurationDataResult are formally defined in Table 14.

Table 14 – ConfigurationDataResult StatusCodes

Result Code	Description
Bad_NodeIdUnknown	The NodeId for the requested Key does not exist in the FunctionalEntity hierarchy.
Bad_NodeIdInvalid	The syntax of the NodeId for the requested Key was invalid.
Bad_InvalidArgument	The NodeId for the requested Key was not a Node in the ConfigurationData Folder hierarchy.
Bad_TypeMismatch	The value supplied for the configuration Variable is not of the same type as the implemented configuration Variable.
Bad_UserAccessDenied	The change to a configuration Variable failed; this may result from a Lock existing on the Variable.
Bad_NothingToDo	Applying the Value to this Key was skipped because a preceding command had already resulted in an error.
Bad_ConfigurationError	The applied configuration data is inconsistent.
Good	Setting the ConfigurationData succeeded.

The possible StatusCodes for the ConnectionEndpointConfigurationResults ReassignControlResult are formally defined in Table 15.

Table 15 – ReassignControlResult StatusCodes

Result Code	Description
Bad_NodeIdUnknown	The NodeId for the requested ControlGroup does not exist in the FunctionalEntity.
Bad_NodeIdInvalid	The syntax of the NodeId for the requested ControlGroup was invalid.
Bad_InvalidArgument	The NodeId for the requested ControlGroup was not a ControlGroup, or the LockContext was null, invalid, or non-existent.
Bad_NothingToDo	Reassigning control was skipped because a preceding command had already resulted in an error.
Bad_ConfigurationError	The applied configuration data is inconsistent.
	Also, include all Result Codes in Table 70

The possible StatusCodes for the ConnectionEndpointConfigurationResults CommunicationLinksResult are formally defined in Table 16.

Table 16 – CommunicationLinksResult StatusCodes

Result Code	Description
Bad_NotFound	At least one of the configuration elements referenced by the CommunicationLinks was not found in the CommunicationConfiguration.
Bad_InvalidArgument	At least one of the CommunicationLinks contains an invalid ConfigurationMask (see Table 148).
Bad_NoMatch	At least one of the configuration elements referenced by the CommunicationLinks does not match the ConnectionEndpoint.
Bad_ConfigurationError	The version of the DataSet related to the DataSetReader and/or DataSetWriter referenced by the CommunicationLinks does not match the expected version.
Bad_NothingToDo	Establishing communication links was skipped because a preceding command had already resulted in an error.
Bad_InvalidState	At least one of the configuration elements referenced by the CommunicationLinks or one of its parent elements is not persisted for a persistent ConnectionEndpoint.
Good	The operation was either successfully executed or not executed since CommandMask SetCommunicationConfigurationCmd was not set.
	Also, include all StatusCodes defined by OPC 10000-14

The possible StatusCodes for the ConnectionEndpointConfigurationResults EnableCommunicationResult are formally defined in Table 17.

Table 17 – EnableCommunicationResult StatusCodes

Result Code	Description
Bad_NothingToDo	EnableCommunicationCmd was skipped because a preceding command had already resulted in an error.
Bad_RequestNotAllowed	The ConnectionEndpoint to be enabled references InputVariables, which are referenced by another enabled ConnectionEndpoint.
Bad_InvalidState	Required ToDataSetReader or ToDataSetWriter References are not configured for the ConnectionEndpoint.
Good	The operation was either successfully executed or not executed since CommandMask EnableCommunicationCmd was not set.
	Also, include all StatusCodes defined by OPC 10000-14

The possible StatusCodes for the ReserveCommunicationIdsResults Result are formally defined in Table 18.

Table 18 – ReserveCommunicationIdsResults Result StatusCodes

Result Code	Description
	Include all Method Result Codes of the ReserveIds Method defined by OPC 10000-14

The possible StatusCodes for the CommunicationConfigurationResults Result are formally defined in Table 19.

Table 19 – CommunicationConfigurationResults Result StatusCodes

Result Code	Description
Bad_ConfigurationError	The communication configuration violates the capabilities of the AutomationComponent, FunctionalEntity, Input- or OutputGroup, or the applied configuration data is inconsistent.
Bad_ResourceUnavailable	The Server does not have enough resources to add the entire PubSub configuration.
Bad_InvalidState	The current State of the Object does not allow a configuration change.
Bad_NothingToDo	The ConfigurationReferences array is null or empty, or the SetCommunicationConfigurationCmd was skipped because a preceding command had already resulted in an error.

The EstablishConnections Method representation in the AddressSpace is formally defined in Table 20.

Table 20 – EstablishConnections Method AddressSpace definition

Attribute	Value
BrowseName	3:EstablishConnections

References	Node Class	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	M
0:GeneratesEvent	ObjectType	2:AuditUpdateMethodResultEventType	Defined in 8.2

ConformanceUnits
UAFX AutomationComponent Base