IReadContainer Interface Reference

Inherits IDispatch.

Collaboration diagram for IReadContainer:

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	GetDataAsByteArray ([out, retval] SAFEARRAY(BYTE)*data)
HRESULT	Add ([in] BSTR tag)
HRESULT	Remove ([in] BSTR tag)
HRESULT	Clear ()

Detailed Description

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

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

Definition at line 72 of file IReadContainer.idl.

Member Function Documentation

HRESULT IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //print name of the container
  Console.WriteLine("ContainerName: " + readContainer.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 IReadContainer::Update

(

void

)

This function updates the container by reading the data elements from the control and storing it in an internal data collection.

Returns

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

Example C#:

...
try
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");

  //update the container
  readContainer.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 IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //destroy the container
  readContainer.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 IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //create the container
  readContainer.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 IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //read the container information
  ContainerInformation info = 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);
}

Note:

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

HRESULT IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add some tags to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varInt");
  
  //read the item information
  Array itemInfo = readContainer.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);
}

Note:

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

HRESULT IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add some tags to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varInt");
  
  //read the tag list
  Array tagArray = readContainer.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);
}

Note:

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

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

This function reads data for a specified tag from the container. To get updated data, you need to call Update first.

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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //update the container
  readContainer.Update();

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

HRESULT IReadContainer::GetDataAsByteArray

(

[out, retval] SAFEARRAY(BYTE)*

data

)

This function reads all data as byte array from the container. To get updated data, you need to call Update first.

Parameters

[out]

data

The complete data from the internal storage.

Returns

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

Example C#:

...
try
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
  
  //update the container
  readContainer.Update();

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

HRESULT IReadContainer::Add

(

[in] BSTR

tag

)

This function adds a tag to the container. Each 'tag' identifies a data element which can be read. For example, a symbolic variable from the PLC or data from the input 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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString");
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IReadContainer::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
{
  IReadContainer readContainer = connection.Container.Read["MyReadContainer"];
  
  //add a tag to the container
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString1");
  readContainer.Add("LOGICLIB_SYMBOL,Application.PlcProg.varString2");
  //remove one of the added tags again
  readContainer.Remove("LOGICLIB_SYMBOL,Application.PlcProg.varString1");
}
catch (Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

HRESULT IReadContainer::Clear

(

)

This function removes all tags of the container.

Returns

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

Example C#:

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

---

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

• IReadContainer.idl