Common function

Collaboration diagram for Common function:

Functions
MLPIRESULT	mlpiContainerCreate (const MLPIHANDLE connection, const WCHAR16 *tagList, const MlpiContainerAccess accessFlag, MlpiContainerHandle *handle, ULONG *dataSize)
MLPIRESULT	mlpiContainerUpdate (const MLPIHANDLE connection, const MlpiContainerHandle handle, void *data, const ULONG dataSize)
MLPIRESULT	mlpiContainerDestroy (const MLPIHANDLE connection, MlpiContainerHandle *handle)

Detailed Description

Contains functions to create, update and destroy containers.

Attention

The addresses of the variables of the container content might change on every download, reset origin or online change of the PLC application, so you have to stop and destroy each regarding container before you load or change the PLC application!

Before you can use any other container function, you need to create a container using the function mlpiContainerCreate provided here. Update the container by using mlpiContainerUpdate and don't forget to release the container by calling mlpiContainerDestroy when you are finished.

Function Documentation

MLPIRESULT mlpiContainerCreate	(	const MLPIHANDLE	connection,
		const WCHAR16 *	tagList,
		const MlpiContainerAccess	accessFlag,
		MlpiContainerHandle *	handle,
		ULONG *	dataSize
	)

This function creates a new container. It has to be specified if the container is a read or write container. It is not possible to read and write using the same container. To specify which data to read or write, you have to give a tag list to the function. The tag list is a formatted string of one or multiple tags which are separated by a semicolon (;). Each tag is built of multiple arguments which are again separated by comma (,).

Please have a look at ContainerLib for an extensive introduction to the ContainerLib mechanism.

Attention

The addresses of the variables of the container content might change on every download, reset origin or online change of the PLC application, so you have to stop and destroy each regarding container before you load or change the PLC application!

Parameters

[in]	connection	Handle for multiple connections.
[in]	tagList	Configuration description of container. This is a string with multiple tags as described above. Tags are delimited by semicolons.
[in]	accessFlag	Configuration of container regarding read or write access.
[out]	handle	Handle for use of container.
[out]	dataSize	Data size of container in bytes.

Returns

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

Example:

// This example creates a read buffer which reads 4 bytes of input IO and four variables.
MlpiContainerHandle hContainer;
memset(&hContainer, 0, sizeof(hContainer));
ULONG containerSize = 0;

// build the tag list which describes which containerData to pack into the container
const WCHAR16 tagList[] =
{
  L"LOGICLIB_MEMORY_AREA,Application,INPUT,0,32;"
  L"LOGICLIB_SYMBOL,Application.PlcProg.varReal;"
  L"LOGICLIB_SYMBOL,Application.PlcProg.varUint;"
  L"LOGICLIB_SYMBOL,Application.PlcProg.varString;"
  L"LOGICLIB_SYMBOL,Application.PlcProg.varUintArray;"
};

// create the container
MLPIRESULT result = mlpiContainerCreate(connection, tagList, MLPI_CONTAINER_ACCESS_READ, &hContainer, &containerSize);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}
printf("\nContainer created. Size in bytes: %d", containerSize);

// read the container
UCHAR *containerData = new UCHAR[containerSize];
memset(containerData, 0, containerSize);
result = mlpiContainerUpdate(connection, hContainer, containerData, containerSize);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  delete [] containerData;
  return result;
}

// dump the data
printf("\ndumping container data:\n");
utilHexdump(containerData, containerSize);  // #include "util/mlpiGlobalHelper.h"

// delete container and free resources
mlpiContainerDestroy(connection, &hContainer);
delete [] containerData;

MLPIRESULT mlpiContainerUpdate	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		void *	data,
		const ULONG	dataSize
	)

This function updates a container. If you pass a handle to a write container, then you also need to pass the data and correct data size to the data argument of the function. If you pass a handle to a read container, then you will receive the data that gets read by the function in the buffer given to the data argument.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle that specifies the container to update. Use mlpiContainerCreate to create a container.
[in,out]	data	Data to be written in case of write-container. Data buffer to read data to in case of read-container.
[in]	dataSize	Size in bytes of data argument.

Returns

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

Example:

See mlpiContainerCreate

MLPIRESULT mlpiContainerDestroy	(	const MLPIHANDLE	connection,
		MlpiContainerHandle *	handle
	)

This function destroys a container which has been created using mlpiContainerCreate. Containers consume memory resources of the server. You should therefore destroy any containers your application no longer needs!

Attention

Please ensure you don't destroy a container when accessing it (update, read information e.g.)!

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container to destroy. Use mlpiContainerCreate to create a container.

Returns

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

Example:

See mlpiContainerCreate