IApplication Interface Reference

Inherits IDispatch.

Collaboration diagram for IApplication:

Public Member Functions
HRESULT	StartApplication (void)
HRESULT	StopApplication (void)
HRESULT	ResetApplication ([in] ApplicationResetMode mode)
HRESULT	GetStateOfApplication ([out, retval] ApplicationState *state)
HRESULT	GetOperationStateOfApplication ([out, retval] struct ApplicationOpState *state)
HRESULT	GetTaskInfoOfApplication ([out, retval] SAFEARRAY(struct ApplicationTaskInfo)*taskInfo)
HRESULT	GetInfoOfApplication ([out, retval] struct ApplicationInfo *info)
HRESULT	SaveRetainOfApplication ([in] BSTR path)
HRESULT	RestoreRetainOfApplication ([in] BSTR path)
HRESULT	GetSymbolsOfApplication ([out, retval] SAFEARRAY(BSTR)*symbols)
HRESULT	WriteMemoryAreaAsByteArray ([in] ApplicationMemoryArea area, [in] LONG byteOffset, [in] LONG byteLength, [in] SAFEARRAY(BYTE) data)
HRESULT	ReadMemoryAreaAsByteArray ([in] ApplicationMemoryArea area, [in] LONG byteOffset, [in] LONG byteLength, [out, retval] SAFEARRAY(BYTE)*data)

Properties
BSTR	NameOfApplication [get]

Detailed Description

Definition of the IApplication interface used to access settings of a single PLC application.

Use the IApplication interface to access the settings, configuration and status of a single application object.

Definition at line 69 of file IApplication.idl.

Member Function Documentation

HRESULT IApplication::StartApplication

(

void

)

This function starts the given application on the target.

Note

You can start all applications by using the method StartApplication in the interface ILogic.

Returns

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

Example C#:

...
try
{
  // try starting application.
  // Note: An application which has already been loaded has to be available!
  connection.Logic.Applications["Application"].StartApplication();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::StopApplication

(

void

)

This function stops the given application on the target.

Note

You can stop all applications by using the method StopApplication in the interface ILogic.

Returns

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

Example C#:

...
try
{
  // try stopping application.
  // Note: An application which is already running has to be available!
  connection.Logic.Applications["Application"].StopApplication();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::ResetApplication

(

[in] ApplicationResetMode

mode

)

This function resets the given application on the target.

Note

You can reset all applications by using the method ResetApplication in the interface IApplications.

Parameters

[in]

mode

Reset mode ILogic::ApplicationResetMode (0==RESET_WARM, 1==RESET_COLD, 2==RESET_ORIGIN).

Returns

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

Note

RESET_WARM: All global data except retain data are reset to their default values.

RESET_COLD: All global data and (!) retain data are reset to their default values.

RESET_ORIGIN: Delete the application, delete all application files (boot project, etc.), reset all global and retain data.

Example C#:

...
try
{
  // try resetting warm on application.
  // Note: An application has to be available!
  connection.Logic.Applications["Application"].ResetApplication(ApplicationResetMode.RESET_WARM);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::GetStateOfApplication

(

[out, retval] ApplicationState *

state

)

This function will restore the state of an application using enum ILogic::ApplicationState.

Parameters

[out]

state

Returns an enumeration showing the current state of the application (RUN, STOP, etc...).

Returns

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

Example C#:

...
try
{
  ApplicationState appState = connection.Logic.Applications["Application"].GetStateOfApplication();
  Console.WriteLine("Current ApplicationState: " + appState.ToString());
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::GetOperationStateOfApplication

(

[out, retval] struct ApplicationOpState *

state

)

This function restores the extended operation state of an application using struct ApplicationOpState.

Parameters

[out]

state

Returns a struct containing several elements describing the current operation state of the application.

Returns

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

Example C#:

...
try
{
  ApplicationOpState appState = connection.Logic.Applications["Application"].GetStateOfApplication();
  Console.WriteLine("Current ApplicationState: " + appState.ToString());
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::GetTaskInfoOfApplication

(

[out, retval] SAFEARRAY(struct ApplicationTaskInfo)*

taskInfo

)

This function returns information about all IEC tasks running on an application using struct ILogic::ApplicationTaskInfo.

Parameters

[out]

taskInfo

Returns an array of structs. Each structure element gives you information about an application task.

Returns

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

Example C#:

...
try
{
  // read task info of application with name "Application"
  ApplicationTaskInfo[] appTaskInfos = (ApplicationTaskInfo[])connection.Logic.Applications["Application"].GetTaskInfoOfApplication();

  // write info of each task to console
  Console.WriteLine("Found " + appTaskInfos.Length + " task(s) in application");
  foreach (ApplicationTaskInfo appTaskInfo in appTaskInfos)
  {
    Console.WriteLine("->Name: " + appTaskInfo.name);
    Console.WriteLine("  Priority: " + appTaskInfo.priority.ToString());
    Console.WriteLine("  CycleCount: " + appTaskInfo.cycleCount);
    Console.WriteLine("  CycleTime: " + appTaskInfo.cycleTime);
    Console.WriteLine("  MinCycleTime: " + appTaskInfo.minCycleTime);
    Console.WriteLine("  MaxCycleTime: " + appTaskInfo.maxCycleTime);
    Console.WriteLine("  AverageCycleTime: " + appTaskInfo.averageCycleTime);
  }
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::GetInfoOfApplication

(

[out, retval] struct ApplicationInfo *

info

)

This function returns miscellaneous information about the given application using struct ILogic::ApplicationInfo. This includes its name, author, etc...

Parameters

[out]

info

Returns a struct with miscellaneous information about the given application.

Returns

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

Example C#:

...
try
{
  ApplicationInfo appInfo = connection.Logic.Applications["Application"].GetInfoOfApplication();
  Console.WriteLine("Name: " + appInfo.name);
  Console.WriteLine("Author: " + appInfo.author);
  Console.WriteLine("Description: " + appInfo.description);
  Console.WriteLine("Profile: " + appInfo.profile);
  Console.WriteLine("DateTime: " + appInfo.dateTime.day + "." + appInfo.dateTime.month + "." + appInfo.dateTime.year);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::SaveRetainOfApplication

(

[in] BSTR

path

)

This function saves the retain data of an application to default storage or a user-defined file.

Parameters

[in]

path

Path and name of retain data file. Use NULL to select default storage to load it on next reboot.

Returns

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

Example C#:

...
try
{
  const String retainFilename = "retaindata.dat";

  // retrieve path to user partition and build absolute file path
  String userPath = connection.System.GetSpecialPath(SpecialPath.PATH_USER);
  String retainPath = System.IO.Path.Combine(userPath, retainFilename);

  // now save retain data to file system
  Console.Write("Saving retain data to " + retainPath + "... ");
  connection.Logic.Applications["Application"].SaveRetainOfApplication(retainPath);
  Console.WriteLine("DONE");

  // ... and load again
  Console.Write("Restoring retain data from " + retainPath + "... ");
  connection.Logic.Applications["Application"].RestoreRetainOfApplication(retainPath);
  Console.WriteLine("DONE");
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

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

HRESULT IApplication::RestoreRetainOfApplication

(

[in] BSTR

path

)

This function restores the retain data of an application from a user-defined file.

Parameters

[in]

path

Path and name of retain data file.

Returns

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

Example C#:

See SaveRetainOfApplication.

Note:

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

HRESULT IApplication::GetSymbolsOfApplication

(

[out, retval] SAFEARRAY(BSTR)*

symbols

)

This function reads all symbols in an application and returns a string array.

Parameters

[out]

symbols

Returns a string array containing a symbol for each element.

Returns

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

Example C#:

...
// This example reads all exported symbols in the application found first on the target.
// The name of each symbol is written on the console.
// It then tries to read the variable value of each symbol. If the variable type is supported by the
// MLPI, the value is also printed to the console.

// check for existing project
if (connection.Logic.GetNumberOfApplications() < 1)
{
   Console.WriteLine("Error: No application loaded on target. Please load application first!");
   return;
}

// get name of first application
string applicationName = connection.Logic.GetNameOfApplication(0);

// read all symbols
string[] symbols = (string[])connection.Logic.Applications[applicationName].GetSymbolsOfApplication();

// print list of all symbols and try to read the value
Console.WriteLine("Found " + symbols.Length + " symbol(s) in application ");

for (int i=0; i<symbols.Length; i++ )
{
   // print symbol name
   Console.WriteLine(symbols[i]);

   // try to read the data
   string value="";
   try
   {
     object data = connection.Logic.ReadVariableBySymbol(symbols[i]);

     // convert read data to string
     if (data is System.Array)
     {
       // data is array
       foreach (object element in (System.Array)data)
         value += element.ToString() + ", ";
     }
     else
     {
       // data is single value
       value = data.ToString();
     }
  }
   catch (System.Exception ex)
   {
     value = "unsupported type: " + ex.Message;
   }

   // print value
   Console.WriteLine(" --> " + value);
}

Note:

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

HRESULT IApplication::WriteMemoryAreaAsByteArray	(	[in] ApplicationMemoryArea	area,
		[in] LONG	byteOffset,
		[in] LONG	byteLength,
		[in] SAFEARRAY(BYTE)	data
	)

This function writes a byte array to the PLC memory area of the application.

Parameters

[in]	area	Memory area to access (ILogic::ApplicationMemoryArea : AREA_INPUT, AREA_OUTPUT, AREA_MARKER).
[in]	byteOffset	Byte offset based on zero (e.g. IB0).
[in]	byteLength	Number of bytes to write from data array to the memory area.
[in]	data	Input data array of bytes to be written to the given area in given byteOffset. Array must be greater than or equal to byteLength.

Returns

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

Example C#:

...
// we want to read the memory area of the application found first
string applicationName = connection.Logic.GetNameOfApplication(0);

// create array of 256 bytes and fill with example data
byte[] myMarkerData = new byte[256];
for (int i = 0; i < myMarkerData.Length; i++)
  myMarkerData[i] = (byte)i;

// write data to marker area
connection.Logic.Applications[applicationName].WriteMemoryAreaAsByteArray(ApplicationMemoryArea.AREA_MARKER, 0, 256, myMarkerData);

// read back data
Array myMarkerArea = connection.Logic.Applications[applicationName].ReadMemoryAreaAsByteArray(ApplicationMemoryArea.AREA_MARKER, 0, 256);

Console.WriteLine("Dumping MarkerMemoryArea from byte %MB0.0 to %MB255.0");
foreach (byte input in myMarkerArea)
  Console.Write(" 0x" + input.ToString("00"));

Note:

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

HRESULT IApplication::ReadMemoryAreaAsByteArray	(	[in] ApplicationMemoryArea	area,
		[in] LONG	byteOffset,
		[in] LONG	byteLength,
		[out, retval] SAFEARRAY(BYTE)*	data
	)

This function reads a byte array from the PLC memory area of the application.

Parameters

[in]	area	Memory area to access (ILogic::ApplicationMemoryArea : AREA_INPUT, AREA_OUTPUT, AREA_MARKER).
[in]	byteOffset	Byte offset based on zero (e.g. IB0).
[in]	byteLength	Number of bytes to read from memory area.
[out]	data	Returns an array of bytes containing the requested memory area. Index starts at 0.

Returns

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

Example C#:

...
// we want to read the memory area of the application found first
string applicationName = connection.Logic.GetNameOfApplication(0);

// read 256 bytes of input area
Array myInputArea = connection.Logic.Applications[applicationName].ReadMemoryAreaAsByteArray(ApplicationMemoryArea.AREA_INPUT, 0, 256);

// write data array to console
Console.WriteLine("Dumping InputMemoryArea from byte %IB0.0 to %IB255.0");
foreach (byte input in myInputArea)
  Console.Write(" 0x" + input.ToString("00"));

Note:

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

Property Documentation

BSTR IApplication::NameOfApplication

get

This method returns the application name of this IApplication object.

Returns

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

Example C#:

Console.WriteLine(connection.Logic.Applications["Application"].NameOfApplication);

---

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

• IApplication.idl