9.1.3.7 Modification of PubSub configuration

9.1.3.7.1 PubSubConfigurationType

This ObjectType represents a FileType the can be used to access a PubSub configuration. The PubSubConfigurationType is formally defined in Table 238.

The PubSubConfigurationType file is a UA Binary encoded stream containing an instance of UABinaryFileDataType that contains a PubSubConfiguration2DataType or subtype as Body. The UABinaryFileDataType is defined in OPC 10000-5. The PubSubConfiguration2DataType is defined in 6.2.12.4. The indices of the namespaces in the PubSubConfiguration2DataType and the Namespaces in the DataTypeSchemaHeader of the UABinaryFileDataType shall match the NamespaceArray in the OPC UA Server for a Session with the Server.

The FileType functionality is used instead of passing the PubSubConfiguration2DataType to read and write Methods to overcome potential limitations of communication buffers for OPC UA Service calls. It is expected that the PubSubConfiguration2DataType is used internally in Client and Server and that the FileType is only used to be able to transfer large configurations.

The Open Method shall not support modes other than Read (0x01), Write + EraseExisting (0x06) and Read + Write (0x03).

When a Client opens the file for writing the Server will not actually update the PubSub configuration until the CloseAndUpdate Method is called. Simply calling Close will discard the updates.

When a Client opens the file for reading and writing, the Client shall follow the following steps.

Read the existing configuration with the FileType Read Method.

Set the position to the beginning of the file with the FileType SetPosition Method.

Write the changes with the FileType Write Method.

Apply the changes with the CloseAndUpdate Method.

Access to the PubSub configuration may be used by multiple Clients in parallel. Read access can be done in parallel but open with the Write flag set requires exclusive access. Therefore Clients that have the file open should minimize the time the file is open to the currently required actions. The Client shall close the file as soon as it completes the sequence of actions needed to read or write the file. Clients with a user interface shall not keep the file open for user configuration. Such Clients should read and close the file to initialize the user interface. If the user changes should be written to the PubSub configuration, the Client should open the file with Read + Write (0x03), read the file, compare the version information and then write the changes if the version matches the version from the intial read.

9.1.3.7.2 PubSubConfigurationRefMask

This OptionSet defines flags indicating the PubSubConfigurationRefDataType options. The value of the mask is null, if none of the bits is set.

The PubSubConfigurationRefDataType is used to reference a configuration element in a PubSubConfiguration2DataType structure. The PubSubConfigurationRefDataType indicates the element type referenced and defines the operation to be executed for the referenced configuration element. The possible element operations are ElementAdd, ElementMatch, ElementModify and ElementRemove.

Only one of the reference bits shall be set. If more than one of these bits are set, the operation shall fail.

The PubSubConfigurationRefMask values are formally defined in Table 239.

The PubSubConfigurationRefMask representation in the AddressSpace is formally defined in Table 240.

9.1.3.7.3 PubSubConfigurationRefDataType

The PubSubConfigurationRefDataType allows to reference an element contained in the PubSubConfiguration2DataType Structure.

The PubSubConfigurationRefDataType is formally defined in Table 241.

The PubSubConfigurationRefDataType representation in the AddressSpace is formally defined in Table 242.

9.1.3.7.4 PubSubConfigurationValueDataType

The PubSubConfigurationValueDataType allows to indicate specific values contained in PubSubConfiguration elements.

The PubSubConfigurationValueDataType is formally defined in Table 243.

The PubSubConfigurationValueDataType representation in the AddressSpace is formally defined in Table 244.

9.1.3.7.5 ReserveIds Method

This Method reserves unique WriterGroupIds and DataSetWriterIds to allow PubSub configuration applications to apply unique Ids to new PubSub configuration elements when preparing a update to the PubSub configuration. It also returns the related default PublisherId. See 6.2.7.1 for more details on PublisherId and default values.

The ID shall be returned from the range 0x8000 - 0xFFFF for internal assignment. The Server shall ensure that the IDs returned are not used in the current PubSub configuration or are not reserved yet.

When a Client reserves IDs, these reservations are valid while the Session is open. The reserved IDs can only be used for configuration modifications through the same Session. The reservation is only valid until the ID is used in the configuration or until the Session is closed. The IDs can be re-used if a PubSub component that uses the ID is deleted.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

	ReserveIds (
		[in]	String		TransportProfileUri,
		[in]	UInt16		NumReqWriterGroupIds,
		[in]	UInt16		NumReqDataSetWriterIds,
		[out]	BaseDataType	DefaultPublisherId,
		[out]	UInt16[]		WriterGroupIds,
		[out]	UInt16[]		DataSetWriterIds
		);
	

Method Result Codes

Table 245 specifies the AddressSpace representation for the ReserveIds Method.

9.1.3.7.6 CloseAndUpdate Method

This Method closes the file and applies the changes to the PubSub configuration as defined in the ConfigurationReferences argument. It can only be called if the file was opened for writing. If the Close Method is called any cached data is discarded and the PubSub configuration is not changed.

The file content shall be a UABinaryFileDataType with a PubSubConfiguration2DataType as Body. The ConfigurationReferences argument specifies the configuration elements to add, modify or remove. Configuration elements in PubSubConfiguration2DataType that are not referenced by ConfigurationReferences may be used indirectly as parent elements for referencing. In this case only the name of the element is relevant and all other fields of the element are ignored. Configuration elements in PubSubConfiguration2DataType not referenced and not used as parent elements are ignored.

Remove element operations shall be processed before any other operations are processed. The PubSubConfiguration2DataType may contain duplicate names for cases where elements are removed and added with the same name.

The top-level fields in the PubSubConfiguration2DataType are not referenced in ConfigurationReferences argument. Most of them are only relevant for the read case.

The Enable field is ignored.

The DataSetClasses field is ignored.

The DefaultSecurityKeyServices field is ignored if the array is null or empty. If the array contains entries, the existing DefaultSecurityKeyServices are replaced with the new configuration.

The ConfigurationVersion field is ignored. The ConfigurationVersion is updated to the current time after successful execution of CloseAndUpdate.

The ConfigurationProperties field is merged with the existing ConfigurationProperties. If a key is provided with a value, the key is either inserted or it replaces the value of an existing key. If a key is provided with a null value, the key is deleted if it exists.

The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.

Signature

	CloseAndUpdate (
		[in]	UInt32					FileHandle,
		[in]	Boolean					RequireCompleteUpdate,
		[in]	PubSubConfigurationRefDataType[]	ConfigurationReferences,
		[out]	Boolean					ChangesApplied,
		[out]	StatusCode[]				ReferencesResults,
		[out]	PubSubConfigurationValueDataType[] ConfigurationValues,
		[out]	NodeId[]					ConfigurationObjects
		);
	

Method Result Codes

Element Result Codes

Table 246 specifies the AddressSpace representation for the CloseAndUpdate Method.