Jump to content

FFSTProbe: Difference between revisions

From EDM2
← Older editNewer edit →
Ak120 (talk | contribs)
35,819 edits
m Ak120 moved page OS2:API:FFST:FFSTProbe to FFSTProbe
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Line 1: Line 1:
==Description==
FFSTProbe performs the requested services and returns control to the caller. This function provides a series of functions that includes logging and dump creation.  
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==
==Syntax==
<PRE>
FFSTProbe (pProductInfo, pFFSTParms)
#define INCL_FFST
#include <os2.h>


PPRODUCTINFO    pProductInfo;
PFFSTPARMS      pFFSTParms;
APIRET          rc;            /*  Return code. */
rc = FFSTProbe(pProductInfo, pFFSTParms);
</PRE>
==Parameters==
==Parameters==
; pProductInfo (PPRODUCTINFO) - input : Pointer to the product-information packet.  
;pProductInfo (PPRODUCTINFO) - input : Pointer to the product-information packet.
 
;pFFSTParms (PFFSTPARMS) - input : A parameter packet that describes the information provided with the FFSTProbe.
; pFFSTParms (PFFSTPARMS) - input : A parameter packet that describes the information provided with the FFSTProbe.


==Return Code==
==Return Code==
  rc (APIRET) - returns
rc (APIRET) - returns
 
Return code.
Return code.


Line 26: Line 15:


From FFSTProbe to application
From FFSTProbe to application
 
:1000000      No error
        1000000      No error
 


Invalid Pointers passed in by the API user
Invalid Pointers passed in by the API user
 
:1000005      Invalid product address
        1000005      Invalid product address
:1000010      Invalid FFST address
        1000010      Invalid FFST address
:1000015      Invalid proddata address
        1000015      Invalid proddata address
:1000016      Invalid message address
        1000016      Invalid message address
:1000017      Invalid pmsginsdata address
        1000017      Invalid pmsginsdata address
:1000020      Invalid DMI address
        1000020      Invalid DMI address
:1000025      Invalid dump address
        1000025      Invalid dump address
:1000026      Invalid pdumpuserdata address
        1000026      Invalid pdumpuserdata address
:1000030      Invalid user area address
        1000030      Invalid user area address
:1000035      Invalid log data address
        1000035      Invalid log data address
:1000040      Invalid insert messages address
 
:1000045      Invalid vendor tag address
        1000040      Invalid insert messages address
:1000050      Invalid tag address
        1000045      Invalid vendor tag address
:1000055      Invalid modulename address
        1000050      Invalid tag address
:1000060      Invalid revision address
        1000055      Invalid modulename address
:1000065      Invalid product id address
        1000060      Invalid revision address
:1000070      Invalid DMI fixlvl address
        1000065      Invalid product id address
:1000075      Invalid tempfn address
        1000070      Invalid DMI fixlvl address
:1000080      Invalid user structure title address
        1000075      Invalid tempfn address
:1000085      Invalid config subproddata address
 
:1000090      Invalid DMI modification level address
        1000080      Invalid user structure title address
        1000085      Invalid config subproddata address
        1000090      Invalid DMI modification level address
 


Invalid Packet Revision Numbers
Invalid Packet Revision Numbers
 
:1000095      Invalid product revision
        1000095      Invalid product revision
:1000100      Invalid DMI revision
        1000100      Invalid DMI revision
:1000105      Invalid FFST revision
        1000105      Invalid FFST revision
 


Invalid severity
Invalid severity
 
:1000110      Invalid severity
        1000110      Invalid severity
 


Invalid number of dumps specified by user
Invalid number of dumps specified by user
 
:1000115      Invalid user dump number
        1000115      Invalid user dump number
 


Invalid number of insert texts
Invalid number of insert texts
 
:1000120      Invalid inserts number
        1000120      Invalid inserts number
:1000125      Invalid insert text address
        1000125      Invalid insert text address
 


Invalid probe flags
Invalid probe flags
 
:1000130      Invalid probe flags
        1000130      Invalid probe flags
 


Invalid PSTAT data and process environment data
Invalid PSTAT data and process environment data
 
:1000135      Invalid PSTAT data
        1000135      Invalid PSTAT data
:1000140      Invalid process environment
        1000140      Invalid process environment
 


Invalid packet sizes
Invalid packet sizes
 
:1000145      Invalid PRODUCTDATA packet size
        1000145      Invalid PRODUCTDATA packet size
:1000150      Invalid DMIDATA packet size
        1000150      Invalid DMIDATA packet size
:1000155      Invalid FFSTPARMS packet size
        1000155      Invalid FFSTPARMS packet size
 


DLL load and query
DLL load and query
 
:1000160      DLL query proc error
        1000160      DLL query proc error
:1000165      DLL load error
        1000165      DLL load error
 


FFSTProbe pipe errors
FFSTProbe pipe errors
 
:1000170      Client pipe not created
        1000170      Client pipe not created
:1000175      Client pipe not opened
        1000175      Client pipe not opened
 


Multiple errors occurring during probe processing
Multiple errors occurring during probe processing
 
:1000180      Multiple system errors
        1000180      Multiple system errors
 


Misc. Return codes
Misc. Return codes
 
:1000185      Client proc in exit list processing
        1000185      Client proc in exit list processing
:1000186      UniCode conversion error
        1000186      UniCode conversion error
 


FFSTProbe not active
FFSTProbe not active


Returned to application and not to ERRLOG.
Returned to application and not to ERRLOG.
 
:1000190      FFST not active
        1000190      FFST not active


         /*-----------------------------------------------------*/  
         /*-----------------------------------------------------*/  
Line 552: Line 512:
   }
   }
</PRE>
</PRE>
==Related Functions==
*


[[Category:The OS/2 API Project]]
[[Category:The OS/2 API Project]]

Revision as of 16:47, 1 March 2017

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;
  }
Retrieved from "https://www.edm2.com/index.php?title=FFSTProbe&oldid=44870"