Example of how to add a user-defined column

This chapter describes how to add a user-defined column to the alert and event panel and how to implement a DLL that shows a value in the user-defined column.

This example combines the content of the "Direction" and "Acknowledgement state" columns. The user-defined column should show the text ”Alarm active - not acked”, ”Alarm active – acked” and so on.

To add the column proceed as follows:

  1. Install the API if it is not installed as yet (see API installation).

  2. Install the DLL ”TabUtilEx.dll” in <project-path>/bin. A sample of this DLL can be found in the API directory in <wincc_oa_path>/api/SampleTabUtil.

    CAUTION:

    If you update your WinCC OA version from 3.0 to 3.01 and want to use own functions, you must recompile the TabUtilEx.dll (also see the chapter Example of how to add a user-defined column).

    CAUTION:

    For the following example a catalog file "MYAES.cat" is required. The file filled with corresponding example entries can be fount in the <wincc_oa_path>/api/SampleTabUtil folder and must be copied to the /msg folder of the project.

  3. Implement the function, in the SampleTabUtil.cxx,which combines the two columns. The function gets the following two arguments:

    _ack_state = acknowledgement status of an alert

    and

    _direction = alert direction

    The following code shows the implemented function:

    TABUTIL_EXPORT int tabUtilTranslateDirection(const DynVar &in, DynVar &out )
// Arguments passed to the function
// Return value of the function
{
  // Local data
  IntegerVar *pAckStateValue; // First argument is the _ack_state
  BitVar *pDirectionBit; // Second argument is the _direction
  int t; //Counter to go through the arguments passed to this function
  char szBuffer[ 100 ]; //Buffer used to format the response
  CharString strActive; /* Text that is shown when an item is active/inactive */
  CharString strAcked; // Text that is shown when an item is acknowledged
  bool bFound;
  //2 valid arguments are expected
  //Assure that valid pointers with valid data type are returned
  for( t=1; t <= 2; t++)
  {
    if( !in[t] ) //if there is no valid pointer
      return -1; // then exit

    if( in[t]->isA() != ANYTYPE_VAR )  /* All arguments should be ANYTYPE_VAR */
      return -1; //else just exit
  }

  //Convert the first argument to an INTEGER_VAR.
  //This will be the _ack_state.
  if( ((AnyTypeVar *)in[1])->getVar()->convert( INTEGER_VAR, (Variable *&) pAckStateValue ) != Variable::OK )
  {
    return -1;
  }

  /* Convert the second argument to a BIT_VAR. This will be the direction "Came" or "Went"*/
  if( ((AnyTypeVar *)in[2])->getVar()->convert( BIT_VAR, (Variable *&) pDirectionBit ) != Variable::OK )
  {
    /* when the conversion fails then make sure to delete the arguments allocated earlier */
    delete pAckStateValue;
    return -1;
  }

  /* Locate the appropriate language entry in the catalogue file "MYAES.CAT"*/
  //the right text is needed for "Active/Inactive" and "Acked/Unacked"
  strActive = StrUtil::catgets("MYAES",(PVSSshort)*pDirectionBit ? "active" : "inactive", bFound );

  if( !bFound )
    strActive = "Catalogue file ?";
  strAcked = StrUtil::catgets("MYAES", (PVSSshort)*pAckStateValue ? "acked" : "not_acked", bFound );

  if( !bFound )
    strAcked = "Catalogue file ?";
  //Format the actual string that should be shown in the AES panel
  sprintf( szBuffer,"%s - %s",(const char *)strActive, (const char *) strAcked );
  //Allocate the string that should be returned
  out.append( new AnyTypeVar (new TextVar( szBuffer )));
  //Free any allocated variables
  delete pDirectionBit;
  delete pAckStateValue;
  return 1;
}

    The section shown in bold shows how the two arguments are combined into one string and are returned.

  4. A user-defined column has to be created. The column calls the ”r;tabUtilTranslateDirection” function that is presented in the DLL.

  5. Register the DLL (C++) function first. Open the table configuration of the alert and event panel by way of System Management -> Settings -> AES settings. Open the alert tab and click the "Configure functions" button. Specify the function name "tabUtilTranslateDirection". Choose the arguments "_alert_hdl.._ack_state" and "_alert_hdl..._direction" for the function by clicking the "..." button.
    Figure 1. Configure Functions

  6. Add a new column through the button. Double-click on the new column. The column configuration panel opens.

    Figure 2. Column Configuration
  7. Select the API functions and your own function tabUtilTranslateDirection from the combo box. Select doAcknowledge from the OnClick() combobox. This means that an alert can be acknowledged with clicking on the column.
  8. Create a new configuration named "MyAES" by way of System Management -> Settings -> AES settings since the standard configuration of the alert and event panel should not be changed.
  9. The new configuration is created through the New configuration button on the General AES settings tab.
  10. Set the "MyAES" configuration to default and click save.

  11. Unselect the checkbox "active" for the bottom table since the AES panel should only show alerts.

    Figure 3. MyAES Screen Configuration

  12. Click on the properties of top table button to define new properties. In the properties panel click on the New property button and specify a name for your properties.

    Figure 4. Properties Panel
  13. Set the new column visible via the Visibletab of the properties panel.

  14. Save the properties via the "Save property" button (in the figure above).

    Note:

    You can include in your application, for example, a button that opens, instead of the default configuration, your own screen configuration by means of the openAES() function.

  15. Open the alert panel via System Management -> Diagnostics -> Alert panel.

  16. Generate an alert. The acknowledgement state and alert direction are shown in the new column.

    Figure 5. AEScreen and the new Column