IWriteContainer Interface Reference

Inherits IDispatch.

Collaboration diagram for IWriteContainer:

Public Member Functions
HRESULT	GetName ([out, retval] BSTR *name)
HRESULT	Update (void)
HRESULT	Destroy (void)
HRESULT	Create (void)
HRESULT	GetInformation ([out, retval] struct ContainerInformation *containerInformation)
HRESULT	GetItemInformation ([out, retval] SAFEARRAY(struct ContainerItemInformation)*containerInfo)
HRESULT	GetTagList ([out, retval] SAFEARRAY(BSTR)*tagList)
HRESULT	GetDataByTag ([in] BSTR tag, [out, retval] VARIANT *data)
HRESULT	SetDataByTag ([in] BSTR tag, [in] VARIANT data)
HRESULT	GetDataAsByteArray ([out, retval] SAFEARRAY(BYTE)*data)
HRESULT	SetDataAsByteArray ([in] SAFEARRAY(BYTE) data)
HRESULT	Add ([in] BSTR tag)
HRESULT	Remove ([in] BSTR tag)
HRESULT	Clear ()

Detailed Description

Definition of the IWriteContainer interface which can be used to establish a fast data exchange of grouped data elements for writing.

Use the containers when you need to access a larger set of data repetitively and with maximum update speed. For example, output data you want to write every machine cycle.

Definition at line 71 of file IWriteContainer.idl.

Member Function Documentation

HRESULT IWriteContainer::GetName

(

[out, retval] BSTR *

name

)

This function returns the identifier for this container.

Parameters

[out]

name

Identifier for this container.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //print name of the container
  Console.WriteLine("ContainerName: " + writeContainer.GetName());
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiContainerGetName, where you can find further documentation.

HRESULT IWriteContainer::Update

(

void

)

This function updates the container by writing the data elements from the internal data collection to the control.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");

  //write data
  writeContainer.SetDataByTag("LOGICLIB_SYMBOL,Application.PlcProg.varString", "Hello World");

  //update the container
  writeContainer.Update();
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiContainerUpdate, where you can find further documentation.

HRESULT IWriteContainer::Destroy

(

void

)

This function destroys the container if it is not longer used.

Note

Unused containers should be destroyed because they will consume hardware resources.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //destroy the container
  writeContainer.Destroy();
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiContainerDestroy, where you can find further documentation.

HRESULT IWriteContainer::Create

(

void

)

This function creates the container. It will automatically be called within the Update function if the container does not exist.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //create the container
  writeContainer.Create();
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiContainerCreate, where you can find further documentation.

HRESULT IWriteContainer::GetInformation

(

[out, retval] struct ContainerInformation *

containerInformation

)

This function reads information about the container using struct IContainer::ContainerInformation.

Parameters

[out]

containerInformation

Information about the container.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //read the container information
  ContainerInformation info = m_readContainer.GetInformation();
  if (info.accessFlag == ContainerAccess.CONTAINER_ACCESS_READ)
    Console.WriteLine("This is a read container. Size: " + info.dataSize.ToString());
  else
    Console.WriteLine("This is a write container. Size: " + info.dataSize.ToString());
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::GetItemInformation

(

[out, retval] SAFEARRAY(struct ContainerItemInformation)*

containerInfo

)

This function reads information about the container items using struct IContainer::ContainerItemInformation.

Parameters

[out]

containerInfo

Information about the container items.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add some tags to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varInt");
  
  //read the item information
  Array itemInfo = writeContainer.GetItemInformation();
  ContainerItemInformation[] infoArray = (ContainerItemInformation[])itemInfo;
  for (int i = 0; i < infoArray.Length; i++)
  {
    Console.WriteLine("Item " + i + " Type: " + infoArray[i].type.ToString() + " Datasize: " + infoArray[i].dataSize.ToString());
  }
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::GetTagList

(

[out, retval] SAFEARRAY(BSTR)*

tagList

)

This function reads the tag list of the container.

Parameters

[out]

tagList

Tag list of the container.

Returns

Return value indicating success (>=0) or error (<0).

: GetTagList() requires the tags of the container to be valid. This is because GetTagList() verifies the tags on server side. An invalid or empty tag list will result in this method to return an error!

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add some tags to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varInt");
  
  //read the tag list
  Array tagArray = writeContainer.GetTagList();
  string[] tagList = (string[])tagArray;
  for (int i = 0; i < tagList.Length; i++)
  {
    Console.WriteLine("Tag " + i + ": " + tagList[i]);
  }
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::GetDataByTag	(	[in] BSTR	tag,
		[out, retval] VARIANT *	data
	)

This function reads data for a specified tag from the containers internal data collection. This data will possibly differ from the data on the control because a write container will never read data from the control.

Parameters

[in]	tag	Tag string which identifies the data element.
[out]	data	The elements data from the internal storage.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //write data
  writeContainer.SetDataByTag("LOGICLIB_SYMBOL,Application.PlcProg.varString", "Hello World");

  //read the data
  object value = writeContainer.GetDataByTag("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  Console.WriteLine("Data: "+ value.ToString());
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::SetDataByTag	(	[in] BSTR	tag,
		[in] VARIANT	data
	)

This function writes data for a specified tag to the container. To update the data on the control you need to call Update afterwards.

Parameters

[in]	tag	Tag string which identifies the data element.
[in]	data	The elements data to write to the internal storage.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //write data
  writeContainer.SetDataByTag("LOGICLIB_SYMBOL,Application.PlcProg.varString", "Hello World");

  //update the container
  writeContainer.Update();

}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::GetDataAsByteArray

(

[out, retval] SAFEARRAY(BYTE)*

data

)

This function reads all data as byte array from the container. This data will possibly differ from the data on the control because a write container will never read data from the control.

Parameters

[out]

data

The complete data from the internal storage.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //write data
  writeContainer.SetDataByTag("LOGICLIB_SYMBOL,Application.PlcProg.varString", "Hello World");

  //read the data
  Array dataArray = m_readContainer.GetDataAsByteArray();
  Byte[] byteArray = (Byte[])dataArray;
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::SetDataAsByteArray

(

[in] SAFEARRAY(BYTE)

data

)

This function writes all data as byte array to the container. To update the data on the control you need to call Update afterwards. The size of the byte array needs to match the size of all data elements specified in the containers tag list.

Parameters

[in]

data

The complete data to write to the internal storage.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");

  //create a byte array and write it to the container
  byte[] data = new byte[50];
  data[0] = 0x54;
  data[1] = 0x65;
  data[2] = 0x73;
  data[3] = 0x74;
  writeContainer.SetDataAsByteArray(data);

  //update the container
  writeContainer.Update();
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::Add

(

[in] BSTR

tag

)

This function adds a tag to the container. Each 'tag' identifies a data element which can be written. For example, a symbolic variable from the PLC or data from the output area of the I/O mapping. The first argument of a tag always defines the type of data to read or write. The following data sources are available:

• LOGICLIB_MEMORY_AREA: Accessing Input, Output and Marker area of PLC (I, O, M).
• LOGICLIB_SYMBOL: Accessing variables and arrays of PLC by symbolic name using symbolic variables. Access requires a symbol configuration of desired variables.
• IOLIB_FIELBUS_IO: Accessing fieldbus IO data directly from fieldbus driver.
• ALIGNMENT_DUMMY: Dummy elements to align the subsequent tag.

LOGICLIB_MEMORY_AREA

• argument 1: application name. (e.g. "Application")
• argument 2: area. (Either "INPUT", "OUTPUT" or "MARKER")
• argument 3: bit offset. (e.g. "0" to read from start offset)
• argument 4: bit length. (Note: single bit access or byte access supported. e.g. "1", "8", "16", "24", ... )

LOGICLIB_SYMBOL

• argument 1: symbol name. (e.g. "Application.PlcProg.boDummy")

IOLIB_FIELBUS_IO

• argument 1: master name. (e.g. "Onboard_I_O")
• argument 2: slave address. (e.g. "1");
• argument 3: area. (Either "INPUT" or "OUTPUT")
• argument 4: bit offset. (e.g. "0" to read from start offset)
• argument 5: bit length. (Note: single bit access or byte access supported. e.g. "1", "8", "16", "24", ... )

ALIGNMENT_DUMMY

• argument 1: byte length (Note: only "1", "2", "4" or "8" byte supported)

Parameters

[in]

tag

Tag string which identifies the data element.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::Remove

(

[in] BSTR

tag

)

This function removes a tag from the container. Convention for the tags is the same as for the Add method.

Parameters

[in]

tag

Tag string which identifies the data element.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString1");
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString2");
  //remove one of the added tags again
  writeContainer.Remove("LOGICLIB_SYMBOL,Application.PlcProg.varString1");
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IWriteContainer::Clear

(

)

This function removes all tags of the container.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

...
try
{
  IWriteContainer writeContainer = connection.Container.Write["MyWriteContainer"];
  
  //add a tag to the container
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString1");
  writeContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString2");
  //remove all tags again
  writeContainer.Clear();
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

---

The documentation for this interface was generated from the following file:

• IWriteContainer.idl