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:

• Install the API if it is not installed as yet (see API installation).
• Compile the SampleTabUtil.cxx (see the implementation below) and <wincc_oa_path>/api/ SampleTabUtil.hxx for creating a DLL.
  CAUTION: For the following example a catalog file "MYAES.cat" is required. The file filled with corresponding example entries can be found in the <wincc_oa_path>/api/SampleTabUtil folder and must be copied to the /msg folder of the project.
• 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.

• Copy SampleTabUtil.cxx and <wincc_oa_path>/api/ SampleTabUtil.hxx into your project <project-path>/bin.
• A user-defined column has to be created. The column calls the ”tabUtilTranslateDirection” function that is presented in the DLL.
• Register the DLL (C++) function first. Open the table configuration of the alert and event panel via System Management > Settings > AES setting 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.

  

• Add a new column through the button. Double-click on the new column. The column configuration panel is opened.

  

• 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 by clicking on the column.
• Create a new configuration named MyAES via System Management > Settings > AE Row/Screen since the standard configuration of the alert and event panel should not be changed.
• The new configuration is created through the New configuration button on the General AES settings tab.
• Set the MyAES configuration to default and click save.

  

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

  

• 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.

  

• Set the new column visible via the Visible tab of the properties panel:

  

• Save the properties via the Save property button (in the figure above).
  Note: For example, you can add a button to your application that opens your own screen configuration by using the openAES() function instead of the default configuration.
• Open the alert panel via System Management > Diagnostics > Alarm screen.
• Trigger an alarm. The acknowledgement state and alarm direction are shown in the new column.