FFSTProbe

FFSTProbe performs the requested services and returns control to the caller. This function provides a series of functions that includes logging and dump creation.

Syntax

FFSTProbe (pProductInfo, pFFSTParms)

Parameters

pProductInfo (PPRODUCTINFO) - input

Pointer to the product-information packet.

pFFSTParms (PFFSTPARMS) - input

A parameter packet that describes the information provided with the FFSTProbe.

Return Code

rc (APIRET) - returns

Return code.

FFSTProbe returns one of the following values:

From FFSTProbe to application

1000000 No error

Invalid Pointers passed in by the API user

1000005 Invalid product address

1000010 Invalid FFST address

1000015 Invalid proddata address

1000016 Invalid message address

1000017 Invalid pmsginsdata address

1000020 Invalid DMI address

1000025 Invalid dump address

1000026 Invalid pdumpuserdata address

1000030 Invalid user area address

1000035 Invalid log data address

1000040 Invalid insert messages address

1000045 Invalid vendor tag address

1000050 Invalid tag address

1000055 Invalid modulename address

1000060 Invalid revision address

1000065 Invalid product id address

1000070 Invalid DMI fixlvl address

1000075 Invalid tempfn address

1000080 Invalid user structure title address

1000085 Invalid config subproddata address

1000090 Invalid DMI modification level address

Invalid Packet Revision Numbers

1000095 Invalid product revision

1000100 Invalid DMI revision

1000105 Invalid FFST revision

Invalid severity

1000110 Invalid severity

Invalid number of dumps specified by user

1000115 Invalid user dump number

Invalid number of insert texts

1000120 Invalid inserts number

1000125 Invalid insert text address

Invalid probe flags

1000130 Invalid probe flags

Invalid PSTAT data and process environment data

1000135 Invalid PSTAT data

1000140 Invalid process environment

Invalid packet sizes

1000145 Invalid PRODUCTDATA packet size

1000150 Invalid DMIDATA packet size

1000155 Invalid FFSTPARMS packet size

DLL load and query

1000160 DLL query proc error

1000165 DLL load error

FFSTProbe pipe errors

1000170 Client pipe not created

1000175 Client pipe not opened

Multiple errors occurring during probe processing

1000180 Multiple system errors

Misc. Return codes

1000185 Client proc in exit list processing

1000186 UniCode conversion error

FFSTProbe not active

Returned to application and not to ERRLOG.

1000190 FFST not active

Return codes from FFSTProbe, FFSTQueryConfiguration, FFSTSetConfiguration or other FFST processing.

Return codes for shared memory errors

0x16580 Get shared mem error

0x16581 Alloc shared mem error

0x16582 Free shared mem error

Return codes for semaphore errors

0x1658A Semaphore timeout error

0x1658B Semaphore open error

0x1658C Semaphore release error

0x1658D Semaphore close error

0x1658E Semaphore request error

0x17111 Semaphore g error

Return codes for dump engine processing which may be posted to the SysLog.

0x16595 Dump hdr file open error

0x16596 Index file open error

0x16597 Dump file open error

0x16598 Memory allocation error

0x16599 Queryfs error

0x1659a Dump wrap error

0x1659b Trace rename error

0x17222 Proc dump rename error

Return codes that may be in the SysLog during Worker bringup

0x165a1 Create config semaphore error

0x165a2 Create dump semaphore error

0x165a3 Worker alloc shared mem error

0x165a4 Worker get shared mem error

0x165a5 Create pct semaphore error

0x165a6 File already exists

0x165a7 Specified file not found

0x165a8 Dump validation error

0x165a9 Config memory filled

0x165aa Worker setconfig error

0x165ab Worker pipe not created

0x17005 Worker ffst config not okay

0x165ac Worker mutexsem not released

0x17010 Worker already active

0x17015 Worker initworker failed

0x17050 Worker not active

Remarks

The library FFST.LIB must be linked with object files that use FFSTProbe.

The packet_revision_number parameter defines if pointers point to ASCII or UniCode character data.

Example Code

The following example adds an error (235) to the Default Log file for this service. The error has no message inserts, user data, dump file, or extra data. Product information will be retrieved from the DMI database entry that was created when the product (TEST PRODUCT) was installed.

 /**************************************************************************/
 /* probe.c: FFSTProbe sample                                              */
 /*                                                                        */
 /* This test program gives an example of using the FFSTProbe API and the  */
 /* TraceCreateEntry API by using 'wrapper' functions.  The dummy API      */
 /* My_Dummy_Api returns a return code which is then used as the basis of  */
 /* firing a FFSTProbe via the wrapper function, callFFST.  callFFST can   */
 /* be modified to include more or less data as needed.                    */
 /*                                                                        */
 /**************************************************************************/

 #define INCL_DOS
 #define INCL_DOSMEMMGR
 #define INCL_DOSPROCESS
 #define INCL_FFST
 #define NO_ERROR 0

 #include <os2.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <FFST.h>
 #include <trace.h>

 /**************************************************************************/
 /* Define probe ID for FFSTProbe called when dummy API fails.  Probe ID   */
 /* is the unique identifier you use later to find the source of the       */
 /* failure.  It should be unique within a DMI triplet (explained later)   */
 /* or within your product                                                 */
 /**************************************************************************/
 #define DUMMY_API_PROBE 22222

 void callFFST ( ULONG input_version,           /* FFST 'Wrapper' Function */
              /* input version lets you change the wrapper     */
              /* without changing each call, just make sure    */
              /* the wrapper still treats the 'old' version    */
              /* the same and that any new code is             */
              /* conditioned on a new input_version #          */

                  ULONG input_probe_flags,         /* FFSTProbe probe flags */
                  ULONG input_severity,               /* FFSTProbe severity */
                  ULONG input_probe_id,                     /* FFSTProbe ID */
                  CHAR* input_module_name,   /* module name passed to probe */
                  ULONG input_log_data_length, /* log data length for the
                                                  system error log          */
                  PVOID input_pError_log_data,  /* pointer to the data for
                                                   system error log         */
                  int   argc);

 /*****************************************************/
 /* This is for a common trace entry routine          */
 /*****************************************************/
  #define HKWD_TEST            220        /* major code */
  #define hkwd_test_entry      0x0001     /* minor code for entry */
  #define hkwd_test_exit       0x8001     /* minor code for exit */

  struct
  {
    int count;
    char text[12];
  } trace_capture_start, trace_capture_end;

  APIRET trace_out(ULONG major, ULONG minor, void *trace_data,
                    ULONG data_len);      /* trace wrapper function */

  /**************************************/
  /* End of trace declarations for Main */
  /**************************************/

  ULONG My_Dummy_API(ULONG Mydata);

  /**************************************************************************/
  /*                                                                        */
  /*  Main Application (this uses the callFFST wrapper function).           */
  /*                                                                        */
  /**************************************************************************/

  int main ( int argc, char * argv[], char * envp )
  {
     ULONG  rc          = 0;
     ULONG  Mydata      = 2;
     ULONG  userDataLen = 0;
     PVOID  pUserData   = NULL;

     printf ( "Starting FFSTProbe Sample \n" );

  /**************************************/
  /* Do the trace entry point           */
  /**************************************/

     trace_capture_start.count = 3; /* just a number */
     strncpy(trace_capture_start.text, "Start main", 12);

  /******** CALL TraceCreateEntry function ****/
     trace_out(HKWD_TEST,
        hkwd_test_entry,
        &trace_capture_start,
        sizeof(trace_capture_start));

     /***********************************************************************/
     /* call the 'dummy'  API so it returns a non-zero rc                   */
     /***********************************************************************/
     rc = My_Dummy_API ( Mydata );
     if ( rc != NO_ERROR )
     {
        /********************************************************************/
        /* The API has failed. Setup the userData to contain the failing rc */
        /********************************************************************/
        pUserData = calloc ( 2, sizeof ( ULONG ) );
        memcpy ( pUserData, &rc, sizeof ( ULONG ) );
        memcpy ( ( PBYTE ) pUserData + sizeof ( ULONG )
               , &Mydata, sizeof ( ULONG ) );
  /****************************************************************************/
  /* Call the FFSTProbe wrapper function with a version of 1,                 */
  /* Have FFST post the process status and environment variables in the       */
  /* syslog, a severity of 4, a probe id of DUMMY_API_PROBE which was         */
  /* previously defined as 22222, a module name of 'my_module_1', the length  */
  /* of logusrdta, the logUserData (equal to the failing rc (1) as            */
  /* setup above) and Argc is passed in to determine whether or not data      */
  /* should be retrieved from DMI.                                            */
  /****************************************************************************/

           callFFST ( 1
                 , PSTAT_FLAG º PROC_ENV_FLAG
                 , SEVERITY4
                 , DUMMY_API_PROBE
                 , "my_module_1"
                 , 2 * sizeof ( ULONG )
                 , pUserData
                 , argc );
     }

     if (pUserData != NULL)
     {
       free(pUserData);
       pUserData = NULL;
     }

     if (argc > 1)
     {
        printf("\nFFSTProbe sample ended not using DMI component:\n\n\n");
     }
     else
     {
        printf("\nFFSTProbe sample ended using DMI component:\n\n\n");
     }

  /**************************************/
  /* Do the trace end point             */
  /**************************************/

     trace_capture_end.count = 99;
     strncpy(trace_capture_end.text, "End main", 12);

  /******** CALL TraceCreateEntry function ****/
     trace_out(HKWD_TEST,
        hkwd_test_entry,
        &trace_capture_end,
        sizeof(trace_capture_end));

     return 0;
  }

  /**************************************************************************/
  /* callFFST is the FFSTProbe wrapper function. It allows you to code the  */
  /* FFSTProbe API once with data that is static as far as your usage is    */
  /* concerned and allows you to pass in dynamic data.   It also helps      */
  /* insulate your code if you decide to change your 'static' options       */
  /**************************************************************************/

  void callFFST ( ULONG input_version,           /* FFST 'Wrapper' Function */
                  ULONG input_probe_flags,         /* FFSTProbe probe flags */
                  ULONG input_severity,               /* FFSTProbe severity */
                  ULONG input_probe_id,                     /* FFSTProbe ID */
                  CHAR* input_module_name,   /* module name passed to probe */
                  ULONG input_log_data_length, /* log data length for the
                                                  system error log          */
                  PVOID input_pError_log_data,   /* pointer to the data for
                                                    system error log        */
                  int   argc)
  {
    APIRET  rc = 0;
    PVOID   pvar_n0;
    ULONG   pvar_n1;

    /***********************************************************************/
    /* FFSTProbe API structures.    Described in the API Guide             */
    /***********************************************************************/
    FFSTPARMS     FFSTParms;
    PRODUCTINFO   productInfo;
    PRODUCTDATA   productData;
    DMIDATA       DMIData;
    DUMPUSERDATA  dumpUserData;
    MSGINSDATA    msgInsData;

    /***********************************************************************/
    /* The PRODUCTDATA structure defines the DMI triplet which allows      */
    /* additional product information, including template repository       */
    /* filename, to be retrieved from DMI.   DMI is a industry standard    */
    /* for desktop mgt                                                     */
    /***********************************************************************/
    productData.packet_size            = sizeof ( productData );
    productData.packet_revision_number = PRODUCTDATA_ASCII;
                                               /* data can be ASCII or UNI */
    productData.DMI_tag                = "FFSTProbe Sample";
                                             /* Customize for your program */
    productData.DMI_vendor_tag         = "IBM";
                                              /*Customize for your company */
    productData.DMI_revision           = "1.00";             /* Customize  */

    /***********************************************************************/
    /* The DMIDATA structure below is the information which can either be  */
    /* retrieved by DMI or passed in by the FFSTProbe function. The        */
    /* preferred method is to use DMI. In the example below, you can see   */
    /* the use of either depending on whether or not a parm was passed on  */
    /* call to this program                                                */
    /***********************************************************************/

    if ( !(argc > 1) )
    {
       /********************************************************************/
       /* Setting this structure to NULL indicates that the information is */
       /* to be retrieved from DMI using the DMI triplet as defined in the */
       /* productData structure.  This is the preferred method.            */
       /* Other files in this example show how to build your own DMI       */
       /********************************************************************/
       productInfo.pDMIData = NULL;

       /********************************************************************/
       /* Note: This shows the usage of message insert text and is NOT part*/
       /* of the information that could or could not be retrieved from DMI */
       /* This is included as an example of MsgInsTxt and how it can be    */
       /* used to send probe specific data to the SYSLOG (System Error Log)*/
       /********************************************************************/
       msgInsData.MsgInsTxt[0].insert_number = 1;
       msgInsData.MsgInsTxt[0].insert_text   = "We did use a DMI component";
    }
    else
     {
       /********************************************************************/
       /* fill the DMI data structure - useful only in test environments   */
       /********************************************************************/
       DMIData.packet_size              = sizeof ( DMIData );
       DMIData.packet_revision_number   = DMIDATA_ASCII;
                                               /* could be unicode instead */
       DMIData.DMI_product_ID           = "FFST_toolkt_sample";
                                        /* note this is different than tag */
       DMIData.DMI_modification_level   = "000000";
       DMIData.DMI_fix_level            = "010101";
       DMIData.template_filename        = "PROBE.REP";
                                         /* this file must be on the DPATH */
       DMIData.template_filename_length = strlen (DMIData.template_filename)
                                                 * sizeof ( char );
                                              /* since ascii is being used */
       productInfo.pDMIData             = &DMIData;

       /********************************************************************/
       /* Note: This shows the usage of message insert text and is NOT a   */
       /* of the information that could or could not be retrieved from DMI */
       /********************************************************************/
       msgInsData.MsgInsTxt[0].insert_number = 1;
       msgInsData.MsgInsTxt[0].insert_text   = "We did not use a DMI component";
      }

     /***********************************************************************/
     /* set the pointers up for PRODUCTINFO                                 */
     /***********************************************************************/

     productInfo.pProductData = &productData;   /* This points to the DMI
                                                   related data             */

     /***********************************************************************/
     /* set up some DUMPUSERDATA items                                      */
     /***********************************************************************/
     pvar_n0 = "Dump user data";              /* Anything can be dumped
                                                 here up to 32 Kbytes       */
     pvar_n1 = 2;
     dumpUserData.no_of_variables = 2;
     dumpUserData.DumpDataVar[0].var_n_length = strlen(pvar_n0) + 1;
     dumpUserData.DumpDataVar[0].var_n        = pvar_n0;
     dumpUserData.DumpDataVar[1].var_n_length = sizeof(ULONG);
     dumpUserData.DumpDataVar[1].var_n        = (PVOID)(&pvar_n1);

     /***********************************************************************/
     /* set up a couple of MSGINSDATA messages- just to show it can be done */
     /***********************************************************************/
     msgInsData.no_inserts   = 2;
     msgInsData.MsgInsTxt[1].insert_number = 2;
     msgInsData.MsgInsTxt[1].insert_text   = "Message insert variable 2";

     /***********************************************************************/
     /* set the FFSTPARMS structure, most values from DEFINEs above.        */
     /* See API GUIDE for details on each field and their possible values   */
     /***********************************************************************/
     FFSTParms.packet_size            = sizeof ( FFSTParms );
     FFSTParms.packet_revision_number = FFSTPARMS_OS2_ASCII;
                                                    /* ASCII vs UNICODE data */
     FFSTParms.module_name            = input_module_name;
     FFSTParms.probe_ID               = input_probe_id;
     FFSTParms.severity               = input_severity;
     FFSTParms.template_record_ID     = input_probe_id;
     FFSTParms.pMsgInsData            = &msgInsData;
     FFSTParms.probe_flags            = input_probe_flags;
     FFSTParms.pDumpUserData          = &dumpUserData;
                                       /* dump data is stored in .DMP files */
     FFSTParms.log_user_data_length   = input_log_data_length;
     FFSTParms.log_user_data          = input_pError_log_data;
                          /* log data is stored as part of the SYSLOG entry */

     /***********************************************************************/
     /* Call the FFSProbe API                                               */
     /***********************************************************************/
     if ( input_version == 1)
     {
        rc = FFSTProbe ( &productInfo, &FFSTParms);
     }

     printf("\n----- Fired the FFSTProbe, rc=%d\n",rc);
                 /* for example only, do not do this in customer level code */
  }

  /**************************************************************************/
  /*  This is the dummy  API for use in the example.  It can easily set     */
  /*  non-zero rc's                                                         */
  /**************************************************************************/

  ULONG My_Dummy_API ( ULONG Mydata )
  {
     if ( Mydata != 123456 )
     {
        return 1;
     }
     else
     {
        return 0;
     }
  }

  /**************************************************************************/
  /*  Trace events function                                                 */
  /**************************************************************************/
  APIRET trace_out(ULONG major, ULONG minor, void *trace_data, ULONG data_len)
  {
    TCEREQUEST packet;
    APIRET      rc;

    packet.packet_size = sizeof packet;      /* Size of packet in bytes       */
    packet.packet_revision_number = TRACE_RELEASE; /* Revision level of trace */
    packet.major_event_code = major;         /* Major code event to be logged */
    packet.minor_event_code = minor;         /* Minor code event to be logged */
    packet.event_data_length = data_len;     /* Length of callers event buffer*/
    packet.event_data = trace_data;          /* Pointer to callers buffer     */

    /* call the TraceCreateEntry function */
    rc = TraceCreateEntry(&packet);
    return rc;
  }