home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tstngn.zip / DISK1.ZIP / tstngen.inf (.txt) < prev    next >
OS/2 Help File  |  1995-02-28  |  72KB  |  2,721 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction to Test Engine/2 API ΓòÉΓòÉΓòÉ
  3.  
  4. Test Engine/2 is a programming tool designed for high level debugging and for 
  5. function, module and integration testing. 
  6.  
  7. Judicious use of Test Tracing within an application allows you to locate 
  8. functional and logical bugs quickly and efficiently. This allows you to reserve 
  9. the time consuming use of a debugger for tracking down complex problems such as 
  10. access violations, stack overflows, etc... 
  11.  
  12. The API interface for Test Engine/2 is composed of three parts : 
  13.  
  14.      o Tracing Interface functions and Macros 
  15.      o Script file handling functions 
  16.      o REXX interface functions 
  17.  
  18.  Tracing Functions and Macros 
  19.  
  20.  These functions are designed to be coded into the application that is to be 
  21.  tested. They communicate directly with the Test Engine/2 program. It is 
  22.  recommended that the MACROS be used within an application as these resolve to 
  23.  null statements when the application is compiled without the TST_NGEN define. 
  24.  In this way it is easy to create separate "debugging" and "production" 
  25.  versions of an application without having to re-write any code. 
  26.  
  27.  From the tracing API it is possible to register threads or processes with Test 
  28.  Engine/2, trace data, send comments, open and close trace files, stop and 
  29.  start trace mode and to start and stop global tracing. 
  30.  
  31.  By using correct formatting of the traces in the Test Engine/2 program and by 
  32.  placing traces intelligently within an application, well documented test 
  33.  results can be produced that not only can be of great help in testing the 
  34.  correct functioning of an application but can also be used to produce 
  35.  documentation in accordance with ISO (International Organization for 
  36.  Standardisation) quality control standards (ISO series 9000). 
  37.  
  38.  For more information on trace functions select one of the following items : 
  39.  
  40.      o TstAppendOnOff 
  41.      o TstCloseTrace 
  42.      o TstDeRegister 
  43.      o TstDumpOnOff 
  44.      o TstDumpClose 
  45.      o TstInitProcess 
  46.      o TstOpenTrace 
  47.      o TstRegisterProcess 
  48.      o TstStopProcess 
  49.      o TstTraceOnOff 
  50.      o TstWriteString 
  51.      o TstWriteTrace 
  52.      o TST_CLOSE 
  53.      o TST_DUMP 
  54.      o TST_DCLOSE 
  55.      o TST_END 
  56.      o TST_INIT 
  57.      o TST_ONOFF 
  58.      o TST_OPEN 
  59.      o TST_REG 
  60.      o TST_STOP 
  61.      o TST_TRACE 
  62.  
  63.  Script file handling functions 
  64.  
  65.  These API functions are designed for writing Test Programs for testing sets of 
  66.  functions from libraries (either .DLL or .OBJ files) by reading test protocols 
  67.  from Script Files. 
  68.  
  69.  For more information on script handling functions select one of the following 
  70.  items : 
  71.  
  72.      o TstCloseScript 
  73.      o TstGetFunctionNum 
  74.      o TstInitTest 
  75.      o TstOpenScriptFile 
  76.      o TstReadScriptLine 
  77.      o TstRegisterFunction 
  78.  
  79.  REXX interface functions 
  80.  
  81.  These functions have the same purpose as the Tracing Functions but are 
  82.  designed for use in the REXX programming environment. 
  83.  
  84.  For more information on REXX interface functions select one of the following 
  85.  items : 
  86.  
  87.      o TstRxLoadFuncs 
  88.      o TstRxDropFuncs 
  89.      o TstRxInit 
  90.      o TstRxStop 
  91.      o TstRxTrace 
  92.      o TstRxOpenTrace 
  93.      o TstRxCloseTrace 
  94.  
  95.  
  96. ΓòÉΓòÉΓòÉ 2. Test Tracing ΓòÉΓòÉΓòÉ
  97.  
  98. Placing traces correctly in an application is crucial to making the best use of 
  99. Test Engine/2. Depending on the test level different types of tracing are 
  100. required. For path coverage and domain edge testing many traces are required 
  101. that note each decision point in a function. However, at module testing and 
  102. integration testing levels, these same traces would produce such a mass of 
  103. output that the resulting files would be practically impossible to read. 
  104.  
  105. It is suggested, therefore, that programmers develop a set of macros using the 
  106. Test Engine/2 API that are activated by different #define statements in a 
  107. global header file or by editing tstngen.h, especially for the tracing 
  108. functions. 
  109.  
  110. Examples 
  111.  
  112. #ifdef TEST_LEVEL1
  113.   #define LEV1_TRACE( fmt, v1, v2, v3, v4)     TstWriteTrace(fmt, v1, v2, v3, v4);
  114. #else
  115.   #define LEV1_TRACE( fmt, v1, v2, v3, v4)     ;
  116. #endif
  117.  
  118. #ifdef TEST_LEVEL2
  119.   #define LEV2_TRACE( fmt, v1, v2, v3, v4)     TstWriteTrace(fmt, v1, v2, v3, v4);
  120. #else
  121.   #define LEV2_TRACE( fmt, v1, v2, v3, v4)     ;
  122. #endif
  123.  
  124. NOTE : The number of variables in the above definitions can be changed (See 
  125. TstWriteTrace). 
  126.  
  127. There are an almost infinite number of ways of setting up traces for tests, but 
  128. it is a good idea to keep certain principles in mind : 
  129.  
  130.      o Keep trace texts short and to the point (you have to read them 
  131.        afterwards!!). 
  132.  
  133.      o Note the function name from which the trace came in the trace text. 
  134.  
  135.                   e.g. TstWriteTrace( "ModMyFunction: ERROR - ulMyVar out of range (%lu )", ulMyVar);
  136.  
  137.      o State the kind of trace in the trace text (ERROR, WARNING, NOTE, etc.). 
  138.  
  139.      o Include the values of any data that may be relevant to the test in the 
  140.        trace string using the flags and a variable list. 
  141.  
  142.      o For path testing insert traces at all decision points (case, if, else). 
  143.  
  144.      o For domain testing dump all input parameters into a trace at the start 
  145.        of the function being tested. 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 3. Test Programs ΓòÉΓòÉΓòÉ
  149.  
  150. Test programs that use script files can be written using the Test Engine/2 API 
  151. functions and macros. 
  152.  
  153. Test programs are generally used for path and domain testing, but you can 
  154. develop test programs for many other types of test. 
  155.  
  156. These test programs can be written manually or generated using the code 
  157. generator included in Quality Assurance Manager/2 and should follow the format 
  158. of the template shown below. 
  159.  
  160. If you choose to write your own test programs you should take the following 
  161. points into consideration: 
  162.  
  163.      o Each function MUST be assigned a unique identification number which is 
  164.        then asiigned to the case statement 
  165.      o You must know how many arguments will be read from the script for each 
  166.        function 
  167.  
  168.  Example of a Test program Template 
  169.  
  170.  
  171.   #define   INCL_DOS
  172.   #include   <os2.h>
  173.   #include   <tstngen.h>
  174.  
  175.   /***********************************************************************/
  176.   /*                                   */
  177.   /* Include Header files for object to be tested here          */
  178.   /*                                   */
  179.   /* This assumes that all function prototypes are declared in the    */
  180.   /* header file.                             */
  181.   /*                                   */
  182.   /***********************************************************************/
  183.  
  184.  
  185.   #include  <myheader.h>
  186.  
  187.   void main(int argc, char *argv[])
  188.  
  189.     {
  190.     USHORT        res;
  191.     USHORT        ret_code;
  192.     USHORT        function;
  193.     char         teststr[128];
  194.     TST_ARRAY_TYPE    param;
  195.     HSCRIPT       hscript;
  196.  
  197.  
  198.     /***** Initialize The test ******************************************/
  199.  
  200.     hscript = TstInitTest( argc, argv);
  201.  
  202.     /***** Check that the script was opened correctly *******************/
  203.  
  204.     if (hscript == (HSCRIPT)0)
  205.       {
  206.       DosBeep( 1000, 5000);
  207.       DosExit(EXIT_PROCESS,1);
  208.       }
  209.  
  210.     /***** Main loop for test program ***********************************/
  211.  
  212.     res = TstReadScriptLine( hscript, teststr);
  213.     while (res == TST_OK)
  214.       {
  215.  
  216.       /***** extract function N┬░ and parameters from line *************/
  217.  
  218.       function = TstGetFunctionNum( hscript, teststr);
  219.  
  220.       /***** Process for each function call ***************************/
  221.  
  222.       switch(function)
  223.         {
  224.  
  225.         /***** invalid line in script *******************************/
  226.  
  227.         case TST_ERROR_INVALID_LINE :   /* 11116 */
  228.           TstWriteTrace("ERROR : Syntax error in script file.");
  229.           break;
  230.  
  231.         /***** Process function 1 (ModMyFunction) *******************/
  232.  
  233.         case 1 :
  234.           {
  235.           ULONG    ulvar1;
  236.  
  237.           /***** Extract the parameters (2 of them expected) ******/
  238.  
  239.           if ( TstRegisterFunction( hscript, 2, teststr, param))
  240.             break;
  241.  
  242.           /***** Convert the 1st parameter to a numeric ***********/
  243.  
  244.           ulvar1 = atoi( param[0]);
  245.  
  246.           /***** Make a note in the trace *************************/
  247.  
  248.           TstWriteTrace("Calling ModMyFunction( %s , %s);",param[0], param[1]);
  249.  
  250.           /***** Call the function under test *********************/
  251.  
  252.           ret-code = ModMyFunction( ulvar1, param[1]);
  253.  
  254.           /***** Trace the result *********************************/
  255.  
  256.           TstWriteTrace("ModMyFunction: NOTE - returned %d",ret_code);
  257.           }
  258.           break;
  259.  
  260.         /***** The script line contained an unknown instruction *****/
  261.  
  262.         default :
  263.           TstWriteTrace("ERROR : Invalid function N┬░ in script file.");
  264.           break;
  265.  
  266.         } /* end of switch() */
  267.  
  268.       res = TstReadScriptLine( hscript, teststr);
  269.  
  270.       } /* end of while() */
  271.  
  272.     /***** Close the Script file ****************************************/
  273.  
  274.     TstCloseScript( hscript);
  275.  
  276.     /***** Close the trace file *****************************************/
  277.  
  278.     TstCloseTrace();
  279.  
  280.     /***** De-register the process with Test Engine/2 *******************/
  281.  
  282.     TstStopProcess();
  283.  
  284.     /***** Terminate the program ****************************************/
  285.  
  286.     DosExit( EXIT_PROCESS, 0);
  287.     } /* end of main() */
  288.  
  289.  
  290. ΓòÉΓòÉΓòÉ 4. Script Files ΓòÉΓòÉΓòÉ
  291.  
  292. For testing functions, Test Engine/2 supplies a Script file interface. This 
  293. interface is designed to allow the test engineer to test functions in C/C++. 
  294. The principle is based on reading a script file that contains the instructions 
  295. about how a function is tested. 
  296.  
  297. The Script file is read by a program written in C/C++ that uses the script 
  298. interface functions. A template C program and Script files can be generated 
  299. from the definition of a Test stored in the database using the Quality 
  300. Assurance Manager/2. 
  301.  
  302. A script file is a standard ASCII file that can be created with any code 
  303. editor. Each line can contain one and only one of the following items 
  304.  
  305.      o Comment 
  306.      o Test Engine/2 command 
  307.      o Function call definition 
  308.      o An empty line 
  309.  
  310.  Comments 
  311.  
  312.  Comments are preceded by ';' and can only occur on one line. Trailing comments 
  313.  or inserted comments are not supported. 
  314.  
  315.  Example 
  316.  
  317.   ; This is a single line comment
  318.   ; and this is another
  319.  
  320.  Test Engine/2 Commands 
  321.  
  322.  Test Engine/2 commands are preceded by ':' and only one command is supported 
  323.  on any line. The following commands are supported 
  324.  
  325.  :REGNAME                      This MUST be the first statement in a script 
  326.                                file. It takes one or two parameters. The first 
  327.                                parameter is the name of the test that will 
  328.                                appear in the monitor window and the second 
  329.                                parameter is the startup language for Test 
  330.                                Engine/2. 
  331.  
  332.  :TRACEAPP                     Set the open mode for the trace file defined by 
  333.                                :TRACETO or :TRACEAUTO to append. 
  334.  
  335.  :TRACETO                      This command takes as a parameter the full path 
  336.                                to a trace file where the output from the test 
  337.                                will be stored. This command should not be 
  338.                                present if :TRACEAUTO is included. 
  339.  
  340.  :TRACEAUTO                    This command takes a parameter that is a mask 
  341.                                for a trace file. The command will generate a 
  342.                                file name from the mask by replacing any '?' 
  343.                                characters with random numbers. 
  344.  
  345.  :GLOBALTRACEON                Switches global tracing on. If the global trace 
  346.                                file has not been opened, it is created and the 
  347.                                header is written into it. 
  348.  
  349.  :GLOBALTRACEOFF               Switches global tracing off but leaves the 
  350.                                global trace file open. 
  351.  
  352.  :GLOBALTRACECLOSE             Closes the global trace file. 
  353.  
  354.  :TRACEON                      Switches tracing to the local trace file defined 
  355.                                by :TRACETO or :TRACEAUTO on. 
  356.  
  357.  :TRACEOFF                     Switches tracing to the local trace file defined 
  358.                                by :TRACETO or :TRACEAUTO off. 
  359.  
  360.  :NOTRACESCRIPT                Normally the lines from the script file are 
  361.                                traced into the file defined by :TRACETO or 
  362.                                :TRACEAUTO, this command switches the tracing 
  363.                                off. 
  364.  
  365.  :TRACESCRIPT                  Switch the tracing of lines from the script file 
  366.                                on. 
  367.  
  368.  Example. 
  369.  
  370.   :REGNAME TSTTEST S
  371.  
  372.  This registers the process and/or function with Test Engine/2 with name 
  373.  "TSTTEST" and if Test Engine/2 is not started, starts it in Spanish. 
  374.  
  375.  Function call definitions 
  376.  
  377.  Any line that does not start with either ';' or ':' is treated as a function 
  378.  call definition. 
  379.  
  380.   the format of a function call definition is 
  381.  
  382.      func_num, <param 1>, <param 2>,...,<param n> 
  383.  
  384.      func_num            A unique number assigned to represent the function. 
  385.      param               A parameter passed to the function, literal strings 
  386.                          must be enclosed within double quotes. 
  387.  
  388.      Example. 
  389.  
  390.           ;2, 1, "Hello world", 23
  391.  
  392.  Script File Example 
  393.  
  394.   :REGNAME TESTSCRIPT S
  395.   :TRACETO C:\TSTNGEN\CODE\TRACE\TSTSPT.TRC
  396.   ;***************************************************************
  397.   ;
  398.   ; Script for testing script commands
  399.   ;
  400.   ;***************************************************************
  401.   2, "Stop tracing the script file"
  402.   :NOTRACESCRIPT
  403.   2, "Open the global trace file and start tracing"
  404.   :GLOBALTRACEON
  405.   1, 2
  406.   1, 2
  407.   2, "Switch local trace off"
  408.   :TRACEOFF
  409.   2, "This trace message should only go to the global trace"
  410.   2, "and so should this one"
  411.   :TRACEON
  412.   2, "This message should go to both files"
  413.   1, 2
  414.   2, "Switch global tracing off"
  415.   :GLOBALTRACEOFF
  416.   2, "Close the global trace file"
  417.   :GLOBALTRACECLOSE
  418.   2, "Short delay..."
  419.   1, 2
  420.   2, "Script ends"
  421.   ;***************************************************************
  422.   ;    END OF SCRIPT
  423.   ;***************************************************************
  424.  
  425.  Where function 1 is a call to DosSleep and function 2 is a call to 
  426.  TstWriteTrace. 
  427.  
  428.  The associated code file is shown below 
  429.  
  430.  C Program File Example 
  431.  
  432.   #define   INCL_DOS
  433.   #include   <os2.h>
  434.   #include   <stdlib.h>
  435.   #include   <tstngen.h>
  436.  
  437.   void main(int argc, char *argv[])
  438.  
  439.     {
  440.     USHORT        res;
  441.     USHORT        ret_code;
  442.     USHORT        function;
  443.     char         teststr[128];
  444.     TST_ARRAY_TYPE    param;
  445.     HSCRIPT       hscript;
  446.  
  447.  
  448.     /***** Initialize The test ******************************************/
  449.  
  450.     hscript = TstInitTest( argc, argv);
  451.  
  452.     /***** Check the initialisation was successful **********************/
  453.  
  454.     if (hscript == (HSCRIPT)0)
  455.       {
  456.       DosBeep( 1000, 5000);
  457.       DosExit(EXIT_PROCESS,1);
  458.       }
  459.  
  460.     /***** Main loop for test *******************************************/
  461.  
  462.     res = TstReadScriptLine( hscript, teststr);
  463.     while (res == TST_OK)
  464.       {
  465.  
  466.       /***** Trace input string ***************************************/
  467.  
  468.       TstWriteString( teststr);
  469.  
  470.       /***** Extract the function number and parameters ***************/
  471.  
  472.       function = TstGetFunctionNum( hscript, teststr);
  473.  
  474.       /***** Process for each function call ***************************/
  475.  
  476.       switch(function)
  477.         {
  478.         case TST_ERROR_INVALID_LINE :/* invalid line in script */
  479.           TstWriteTrace("ERROR : Syntax error in script file.");
  480.           break;
  481.  
  482.         /***** Function 1 = DosSleep ********************************/
  483.  
  484.         case 1 :
  485.           {
  486.           ULONG    millisecs;
  487.  
  488.           if (TstRegisterFunction( hscript, 1, teststr, param))
  489.             break;
  490.  
  491.           millisecs = atoi( param[ 0]) * 1000;
  492.           TstWriteTrace("Delay function called for %s seconds", param[ 0]);
  493.  
  494.           DosSleep( millisecs);
  495.           }
  496.           break;
  497.  
  498.         /***** Function 2 = call TstWriteTrace **********************/
  499.  
  500.         case 2 :
  501.           if (TstRegisterFunction( hscript, 1, teststr, param))
  502.             break;
  503.  
  504.           TstWriteTrace("%s", param[ 0]);
  505.  
  506.           break;
  507.  
  508.         default :
  509.           TstWriteTrace("ERROR : Invalid function N┬░ in script file.");
  510.           break;
  511.         }
  512.  
  513.       res = TstReadScriptLine( hscript, teststr);
  514.       }
  515.  
  516.     /***** Clean up at end **********************************************/
  517.  
  518.     TstCloseScript( hscript);
  519.     TstCloseTrace();
  520.     TstStopProcess();
  521.     DosExit( EXIT_PROCESS, 0);
  522.     }
  523.  
  524.  This combination produces the following trace files 
  525.  
  526.   ********************************************************************************
  527.  
  528.   C:\TSTNGEN\CODE\TRACE\TSTSPT.TRC    1994.10.10 (11.53.46.03)
  529.  
  530.   ********************************************************************************
  531.  
  532.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0004) ;***************************************************************
  533.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0005) ;
  534.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0006) ; Script for testing script commands
  535.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0007) ;
  536.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0008) ;***************************************************************
  537.   TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0009) 2, "Stop tracing the script file"
  538.   TESTSCRIPT (523:1) [11.53.45.71] > 2,Stop tracing the script file
  539.   TESTSCRIPT (523:1) [11.53.45.71] > Stop tracing the script file
  540.   TESTSCRIPT (523:1) [11.53.45.75] > TSTSPT1.SPT (0010) :NOTRACESCRIPT
  541.   TESTSCRIPT (523:1) [11.53.45.75] > 1,2
  542.   TESTSCRIPT (523:1) [11.53.45.75] > Delay function called for 2 seconds
  543.   TESTSCRIPT (523:1) [11.53.47.75] > 1,2
  544.   TESTSCRIPT (523:1) [11.53.47.75] > Delay function called for 2 seconds
  545.   TESTSCRIPT (523:1) [11.53.49.75] > 2,Switch local trace off
  546.   TESTSCRIPT (523:1) [11.53.49.75] > Switch local trace off
  547.   TESTSCRIPT (523:1) [11.53.49.75] > 2,This message should go to both files
  548.   TESTSCRIPT (523:1) [11.53.49.75] > This message should go to both files
  549.   TESTSCRIPT (523:1) [11.53.49.75] > 1,2
  550.   TESTSCRIPT (523:1) [11.53.49.75] > Delay function called for 2 seconds
  551.   TESTSCRIPT (523:1) [11.53.51.75] > 2,Switch global tracing off
  552.   TESTSCRIPT (523:1) [11.53.51.75] > Switch global tracing off
  553.   TESTSCRIPT (523:1) [11.53.51.75] > 2,Close the global trace file
  554.   TESTSCRIPT (523:1) [11.53.51.75] > Close the global trace file
  555.   TESTSCRIPT (523:1) [11.53.51.75] > 2,Short delay...
  556.   TESTSCRIPT (523:1) [11.53.51.75] > Short delay...
  557.   TESTSCRIPT (523:1) [11.53.51.75] > 1,2
  558.   TESTSCRIPT (523:1) [11.53.51.75] > Delay function called for 2 seconds
  559.   TESTSCRIPT (523:1) [11.53.53.75] > 2,Script ends
  560.   TESTSCRIPT (523:1) [11.53.53.75] > Script ends
  561.   ************************************************************************
  562.   Test Result       o  : Passed     o  : Failed
  563.  
  564.  
  565.   ADD Consulting      signature : ...........................
  566.   ************************************************************************
  567.  
  568.   ********************************************************************************
  569.  
  570.   C:\TSTNGEN\GLOBAL.TRC    1994.10.10 (11.53.47.21)
  571.  
  572.   ********************************************************************************
  573.  
  574.   TESTSCRIPT (523:1) [11.53.47.75] > 1,2
  575.   TESTSCRIPT (523:1) [11.53.47.75] > Delay function called for 2 seconds
  576.   TESTSCRIPT (523:1) [11.53.49.75] > 2,Switch local trace off
  577.   TESTSCRIPT (523:1) [11.53.49.75] > Switch local trace off
  578.   TESTSCRIPT (523:1) [11.53.49.75] > 2,This trace message should only go to the global trace
  579.   TESTSCRIPT (523:1) [11.53.49.75] > This trace message should only go to the global trace
  580.   TESTSCRIPT (523:1) [11.53.49.75] > 2,and so should this one
  581.   TESTSCRIPT (523:1) [11.53.49.75] > and so should this one
  582.   TESTSCRIPT (523:1) [11.53.49.75] > 2,This message should go to both files
  583.   TESTSCRIPT (523:1) [11.53.49.75] > This message should go to both files
  584.   TESTSCRIPT (523:1) [11.53.49.75] > 1,2
  585.   TESTSCRIPT (523:1) [11.53.49.75] > Delay function called for 2 seconds
  586.   TESTSCRIPT (523:1) [11.53.51.75] > 2,Switch global tracing off
  587.   TESTSCRIPT (523:1) [11.53.51.75] > Switch global tracing off
  588.   ************************************************************************
  589.   Test Result       o  : Passed     o  : Failed
  590.  
  591.  
  592.   ADD Consulting      signature : ...........................
  593.   ************************************************************************
  594.  
  595.  
  596. ΓòÉΓòÉΓòÉ 5. Data Types ΓòÉΓòÉΓòÉ
  597.  
  598. The following sections describe the data types exported by Test Engine/2. For a 
  599. better idea of these please see the header file tstngen.h. The two exported 
  600. types TST_ARRAY_TYPE and HSCRIPT are used for writing Test Programs. 
  601.  
  602.  
  603. ΓòÉΓòÉΓòÉ 5.1. TST_ARRAY_TYPE ΓòÉΓòÉΓòÉ
  604.  
  605. typedef PSZ   TST_ARRAY_TYPE[ TST_PARAM_SIZE + 1];
  606.  
  607. This data type is used to hold the parameters that will be passed to a function 
  608. after they have been parsed from a line in the script file. 
  609.  
  610.  
  611. ΓòÉΓòÉΓòÉ 5.2. HSCRIPT ΓòÉΓòÉΓòÉ
  612.  
  613. typedef PVOID  HSCRIPT;
  614.  
  615. Used to identify a script file. 
  616.  
  617. When running a multi-thread test program with multiple Script Files, each 
  618. script file should be assigned to a unique HSCRIPT variable. 
  619.  
  620.  
  621. ΓòÉΓòÉΓòÉ 6. Test Engine/2 Functions ΓòÉΓòÉΓòÉ
  622.  
  623. The following sections describe the interface function API for Test Engine/2. 
  624.  
  625.  
  626. ΓòÉΓòÉΓòÉ 6.1. TstAppendOnOff ΓòÉΓòÉΓòÉ
  627.  
  628. VOID APIENTRY TstAppendOnOff( PSZ   on_off);
  629.  
  630. Parameters 
  631.  
  632.  on_off              One of the Test Engine/2 Macros TST_TRON or TST_TROFF. 
  633.  
  634.  Description 
  635.  
  636.  Sets the Trace file opening mode for the current thread or process. If the 
  637.  parameter is TST_TRON the trace file will be opened in append mode, if it is 
  638.  TST_TROFF it is overwritten. 
  639.  
  640.   CAUTION:
  641.  The append mode is overridden by the append parameter in TstOpenTrace. 
  642.  
  643.  
  644. ΓòÉΓòÉΓòÉ 6.2. TstCloseScript ΓòÉΓòÉΓòÉ
  645.  
  646. VOID APIENTRY TstCloseScript( HSCRIPT   hscript)
  647.  
  648. Parameters 
  649.  
  650.  hscript             Handle to the script file that should be closed. 
  651.  
  652.  Description 
  653.  
  654.  Closes a script file for a test program. This function should be called for 
  655.  each script file that is opened by a test program. 
  656.  
  657.  Example 
  658.  
  659.   VOID ThreadFunction( PVOID  pdata)
  660.     {
  661.     PSZ     script_name = "d:\\addtools\\test.spt";
  662.     HSCRIPT   hscript;
  663.     .
  664.     .
  665.     .
  666.  
  667.     /***** Open the script file *****************************************/
  668.  
  669.     hscript = TstOpenScriptFile( script_name);
  670.  
  671.     .
  672.     . Body of thread function
  673.     .
  674.  
  675.     TstCloseScript( hcript);
  676.     _endthread;
  677.  
  678.     } /* end of function */
  679.  
  680.  Related Functions 
  681.  
  682.      o TstInitTest. 
  683.      o TstOpenScriptFile. 
  684.  
  685.  
  686. ΓòÉΓòÉΓòÉ 6.3. TstCloseTrace ΓòÉΓòÉΓòÉ
  687.  
  688. VOID APIENTRY TstCloseTrace();
  689.  
  690. Parameters 
  691.  
  692.  None 
  693.  
  694.  Description 
  695.  
  696.  Sends a message to Test Engine/2 which then closes the trace file for the 
  697.  current thread (if in trace by thread mode) or for the current process (if in 
  698.  trace by process mode). When the file is closed the Footer is written to file 
  699.  prior to closing. 
  700.  
  701.  Example 
  702.  
  703.   VOID ThreadFunction( PVOID  pdata)
  704.     {
  705.     PSZ     trace_name = "d:\\addtools\\test.trc";
  706.     .
  707.     .
  708.     .
  709.  
  710.     /***** Register the thread ******************************************/
  711.  
  712.     TstRegisterProcess( "TEST1");
  713.  
  714.     /***** Open a trace file in append mode *****************************/
  715.  
  716.     TstOpenTrace( trace_name, TRUE);
  717.  
  718.     .
  719.     . Body of thread function
  720.     .
  721.  
  722.     TstCloseTrace();
  723.     _endthread;
  724.  
  725.     } /* end of function */
  726.  
  727.  Related Functions 
  728.  
  729.      o TstOpenTrace 
  730.      o TstTraceOnOff 
  731.      o TstAppendOnOff 
  732.  
  733.  
  734. ΓòÉΓòÉΓòÉ 6.4. TstDeRegister ΓòÉΓòÉΓòÉ
  735.  
  736. VOID APIENTRY TstDeRegister();
  737.  
  738. Parameters 
  739.  
  740.  None 
  741.  
  742.  Description 
  743.  
  744.  De registers the current thread with Test Engine/2. This function should be 
  745.  called at the end of any thread function that registers the thread with Test 
  746.  Engine/2. 
  747.  
  748.  Example 
  749.  
  750.   VOID ThreadFunction( PVOID  pdata)
  751.     {
  752.     .
  753.     .
  754.     .
  755.  
  756.     /***** Register the thread ******************************************/
  757.  
  758.     TstRegisterProcess( "TEST1");
  759.     .
  760.     . Body of thread function
  761.     .
  762.  
  763.     /***** Close Trace file and deregister ******************************/
  764.  
  765.     TstCloseTrace();
  766.     TstDeRegister();
  767.  
  768.     _endthread;
  769.  
  770.     } /* end of function */
  771.  
  772.  Related Functions 
  773.  
  774.      o TstInitProcess 
  775.      o TstRegisterProcess 
  776.      o TstStopProcess 
  777.  
  778.  
  779. ΓòÉΓòÉΓòÉ 6.5. TstDumpOnOff ΓòÉΓòÉΓòÉ
  780.  
  781. VOID APIENTRY TstDumpOnOff( PSZ  on_off);
  782.  
  783. Parameters 
  784.  
  785.  on_off              One of the Test Engine/2 Macros TST_TRON or TST_TROFF 
  786.  
  787.  Description 
  788.  
  789.  Sends a message to Test Engine/2 that causes the Global Trace functionality to 
  790.  be switched on (parameter = TST_TRON) or off (parameter = TST_TROFF). 
  791.  
  792.  This function may be called from anywhere, even if the process or thread has 
  793.  not registered with Test Engine/2. 
  794.  
  795.   CAUTION:
  796.  The Global Trace File is not closed by this function. It can be closed from 
  797.  the Test Engine/2 program itself or by calling TstDumpClose. 
  798.  
  799.  Related Functions 
  800.  
  801.      o TstDumpClose 
  802.      o TstTraceOnOff 
  803.      o TstCloseTrace 
  804.  
  805.  
  806. ΓòÉΓòÉΓòÉ 6.6. TstDumpClose ΓòÉΓòÉΓòÉ
  807.  
  808. VOID APIENTRY TstDumpClose( );
  809.  
  810. Parameters 
  811.  
  812.  None 
  813.  
  814.  Description 
  815.  
  816.  Sends a message to Test Engine/2 that causes the Global Trace file to be 
  817.  closed. 
  818.  
  819.  This function may be called from anywhere, even if the process or thread has 
  820.  not registered with Test Engine/2. 
  821.  
  822.  Related Functions 
  823.  
  824.      o TstDumpOnOff 
  825.  
  826.  
  827. ΓòÉΓòÉΓòÉ 6.7. TstGetFunctionNum ΓòÉΓòÉΓòÉ
  828.  
  829. USHORT APIENTRY TstGetFunctionNum( HSCRIPT hscript, PSZ script_line);
  830.  
  831. Parameters 
  832.  
  833.  hscript             Handle to a previously opened script file. 
  834.  script_line         Null terminated string read from the same script file 
  835.                      using TstReadScriptLine. 
  836.  
  837.  Description 
  838.  
  839.  This function extracts the function number (unique identifier for a function) 
  840.  from the line and converts it to a numeric which is returned. If the first 
  841.  element on the line is not a numeric character a value of 
  842.  TST_ERROR_INVALID_LINE is returned. 
  843.  
  844.  The variable script_line is modified so that it points to the start of the 
  845.  parameter list. 
  846.  
  847.  Example 
  848.  
  849.     .
  850.     .
  851.     .
  852.     res = TstReadScriptLine( hscript, teststr);
  853.     while (res == TST_OK)
  854.       {
  855.  
  856.       /***** extract function N┬░ from line ****************************/
  857.  
  858.       function = TstGetFunctionNum( hscript, teststr);
  859.       .
  860.       .
  861.       } /* end of while */
  862.     .
  863.     .
  864.  
  865.  Related Functions 
  866.  
  867.      o TstOpenScriptFile 
  868.           o TstInitTest
  869.  
  870.  
  871. ΓòÉΓòÉΓòÉ 6.8. TstInitProcess ΓòÉΓòÉΓòÉ
  872.  
  873. BOOL APIENTRY TstInitProcess( PSZ   proc_name, char lang_char);
  874.  
  875. Parameters 
  876.  
  877.  proc_name           NULL terminated character string representing a unique 
  878.                      name for the thread. 
  879.  lang_char           Single character denoting the language Test Engine/2 
  880.                      should start in. 
  881.  
  882.  Description 
  883.  
  884.  If Test Engine/2 is not active it is started in the specified language. The 
  885.  current process is then registered with the given name. lang_char can be any 
  886.  of the following characters: 
  887.  
  888.  E | e     English. 
  889.  F | f     French. 
  890.  S | s     Spanish. 
  891.  G | g     German. 
  892.  I | i     Italian. 
  893.  
  894.  The function returns TRUE if the functions succeeds otherwise it returns 
  895.  FALSE. 
  896.  
  897.   CAUTION:
  898.  This function should only be called from the main thread (TID = 1) of a 
  899.  process. 
  900.  
  901.  Example 
  902.  
  903.   int main(int argc, char *argv[]);
  904.     {
  905.     .
  906.     .
  907.     .
  908.  
  909.     /***** start Test Engine/2 in Spanish *******************************/
  910.  
  911.     if ( !TstInitProcess( "PRUEBA", 'S'))
  912.       {
  913.       /* handle the error */
  914.       }
  915.     .
  916.     .
  917.     TstStopProcess();
  918.     exit(0);
  919.  
  920.     } /* end of main() */
  921.  
  922.  Related Functions 
  923.  
  924.      o TstRegisterProcess 
  925.      o TstDeRegister 
  926.      o TstStopProcess 
  927.  
  928.  
  929. ΓòÉΓòÉΓòÉ 6.9. TstInitTest ΓòÉΓòÉΓòÉ
  930.  
  931. HSCRIPT APIENTRY TstInitTest( int argc, char*[] argv);
  932.  
  933. Parameters 
  934.  
  935.  argc                Number of arguments passed. 
  936.  argv                Array of NULL terminated argument strings. 
  937.  
  938.  Description 
  939.  
  940.  This function should only be called from the main function of a test program. 
  941.  The arguments passed are usually the arguments passed to the program on the 
  942.  command line. The first argument (argv[1]) must be the name of the script file 
  943.  that should be read. 
  944.  
  945.  The function will extract the program file name from the environment, open the 
  946.  script file and start to read it. 
  947.  
  948.  The function returns a handle to the script file if it succeeds otherwise 
  949.  (HSCRIPT)0 is returned. You should always check for a valid script handle as 
  950.  this will be used to read lines from the script file. 
  951.  
  952.  Example 
  953.  
  954.  
  955.   void main(int argc, char *argv[])
  956.  
  957.     {
  958.     USHORT        res;
  959.     USHORT        ret_code;
  960.     USHORT        function;
  961.     char         teststr[128];
  962.     TST_ARRAY_TYPE    param;
  963.     HSCRIPT       hscript;
  964.  
  965.  
  966.     /***** Initialize The test ******************************************/
  967.  
  968.     hscript = TstInitTest( argc, argv);
  969.  
  970.     /***** Check the initialisation was successful **********************/
  971.  
  972.     if (hscript == (HSCRIPT)0)
  973.       {
  974.       /* Handle the error */
  975.       DosExit( EXIT_PROCESS, code);
  976.       }
  977.  
  978.     .
  979.     .
  980.     } /* end of main */
  981.  
  982.  Related Functions 
  983.  
  984.      o TstOpenScriptFile 
  985.      o TstReadScriptLine 
  986.  
  987.  
  988. ΓòÉΓòÉΓòÉ 6.10. TstOpenScriptFile ΓòÉΓòÉΓòÉ
  989.  
  990. HSCRIPT APIENTRY TstOpenScriptFile( PSZ file_name);
  991.  
  992. Parameters 
  993.  
  994.  file_name           NULL terminated string containing the fully qualified file 
  995.                      name for the script file. 
  996.  
  997.  Description 
  998.  
  999.  This function opens the named script file and returns a handle to the script. 
  1000.  If the file cannot be opened (HSCRIPT)0 is returned. You should always check 
  1001.  the return value and handle any errors as the script handle is used to read 
  1002.  the script. 
  1003.  
  1004.  Example 
  1005.  
  1006.  
  1007.     /***** Open the script file *****************************************/
  1008.  
  1009.     hscript = TstOpenScriptFile( file_name);
  1010.  
  1011.     /***** Check the initialisation was successful **********************/
  1012.  
  1013.     if (hscript == (HSCRIPT)0)
  1014.       {
  1015.  
  1016.       /* Handle the error */
  1017.  
  1018.       }
  1019.  
  1020.     .
  1021.     .
  1022.     } /* end of function */
  1023.  
  1024.  Related Functions 
  1025.  
  1026.      o TstInitTest 
  1027.      o TstReadScriptLine 
  1028.  
  1029.  
  1030. ΓòÉΓòÉΓòÉ 6.11. TstOpenTrace ΓòÉΓòÉΓòÉ
  1031.  
  1032. VOID APIENTRY TstOpenTrace( PSZ  file_name, BOOL  append);
  1033.  
  1034. Parameters 
  1035.  
  1036.  file_name           Full path of the file to open for tracing. 
  1037.  append              If set to true the file file_name is opened for appending 
  1038.                      otherwise it is overwritten. 
  1039.  
  1040.  Description 
  1041.  
  1042.  The function sends a message to Test Engine/2 which causes Test Engine/2 to 
  1043.  open file_name in the defined mode. All further messages from the thread (if 
  1044.  in trace by thread mode) or process (if in trace by process mode) will be 
  1045.  dumped into this file. When the file is opened, the Header is written into the 
  1046.  file. 
  1047.  
  1048.  Example 
  1049.  
  1050.   VOID ThreadFunction( PVOID  pdata)
  1051.     {
  1052.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1053.     .
  1054.     .
  1055.     .
  1056.  
  1057.     /***** Register the thread ******************************************/
  1058.  
  1059.     TstRegisterProcess( "TEST1");
  1060.  
  1061.     /***** Open a trace file in append mode *****************************/
  1062.  
  1063.     TstOpenTrace( trace_name, TRUE);
  1064.  
  1065.     .
  1066.     . Body of thread function
  1067.     .
  1068.  
  1069.     TstCloseTrace();
  1070.     _endthread;
  1071.  
  1072.     } /* end of function */
  1073.  
  1074.  Related Functions 
  1075.  
  1076.      o TstCloseTrace 
  1077.      o TstAppendOnOff 
  1078.      o TstTraceOnOff 
  1079.  
  1080.  
  1081. ΓòÉΓòÉΓòÉ 6.12. TstReadScriptLine ΓòÉΓòÉΓòÉ
  1082.  
  1083. USHORT APIENTRY TstReadScriptLine( HSCRIPT hscript, PSZ  line);
  1084.  
  1085. Parameters 
  1086.  
  1087.  hscript             Handle to a previously opened script file. 
  1088.  line                Pointer to a buffer to contain the line read from the 
  1089.                      script file. This buffer MUST be previously allocated. The 
  1090.                      function DOES NOT ALLOCATE ANY MEMORY FOR THE STRING. 
  1091.  
  1092.  Description 
  1093.  
  1094.  This function reads lines from the script file until a function call 
  1095.  definition is found and returns a pointer to the string containing the 
  1096.  function call definition. Any commands found in the lines read from the script 
  1097.  are executed and if script tracing is ON all the lines read are traced to Test 
  1098.  Engine/2. 
  1099.  
  1100.  The returned string is stripped of any white space. 
  1101.  
  1102.  If the function reaches the end of the file TST_ERROR_EOF is returned. If 
  1103.  there a system file error occurs TST_ERROR_FILE_READ is returned otherwise the 
  1104.  function returns 0. 
  1105.  
  1106.  Example 
  1107.  
  1108.  
  1109.     res = TstReadScriptLine( hscript, teststr);
  1110.     while (res == TST_OK)
  1111.       {
  1112.  
  1113.       /***** extract function N┬░ and parameters from line *************/
  1114.  
  1115.       function = TstGetFunctionNum( hscript, teststr);
  1116.  
  1117.       /***** Process for each function call ***************************/
  1118.  
  1119.       switch(function)
  1120.         {
  1121.         .
  1122.         .
  1123.         .
  1124.         } /* end of switch() */
  1125.  
  1126.       res = TstReadScriptLine( hscript, teststr);
  1127.  
  1128.       } /* end of while() */
  1129.  
  1130.  Related Functions 
  1131.  
  1132.      o TstOpenScriptFile 
  1133.      o TstInitTest 
  1134.  
  1135.  
  1136. ΓòÉΓòÉΓòÉ 6.13. TstRegisterFunction ΓòÉΓòÉΓòÉ
  1137.  
  1138. USHORT APIENTRY TstRegisterFunction( HSCRIPT     hscript,
  1139.                    USHORT     num_params,
  1140.                    PSZ       script_line,
  1141.                    TST_ARRAY_TYPE params);
  1142.  
  1143. Parameters 
  1144.  
  1145.  hscript             Handle to script file from which the line was read. 
  1146.  num_params          The expected number of parameters that should be found in 
  1147.                      the script statement. 
  1148.  script_line         The string read from the script file. 
  1149.  params              Array of strings that will contain the parameters to be 
  1150.                      passed to the function. 
  1151.  
  1152.  Description 
  1153.  
  1154.  The function parses the line read from a script file and extracts the 
  1155.  arguments which are placed into the array of string pointers. These parameters 
  1156.  can then be converted if necessary and passed to the function under test. 
  1157.  
  1158.  The function returns 0 if it succeeds otherwise TST_ERROR_PARAMS if the number 
  1159.  of parameters found does not coincide with the expected number of parameters. 
  1160.  If an error occurs there is a trace made to Test Engine/2. 
  1161.  
  1162.  Note The function MUST be called after TstGetFunctionNum 
  1163.  
  1164.  Example 
  1165.  
  1166.  
  1167.     /***** Main loop for test program ***********************************/
  1168.  
  1169.     res = TstReadScriptLine( hscript, teststr);
  1170.     while (res == TST_OK)
  1171.       {
  1172.  
  1173.       /***** extract function N┬░ and parameters from line *************/
  1174.  
  1175.       function = TstGetFunctionNum( hscript, teststr);
  1176.  
  1177.       /***** Process for each function call ***************************/
  1178.  
  1179.       switch(function)
  1180.         {
  1181.  
  1182.         /***** invalid line in script *******************************/
  1183.  
  1184.         case TST_ERROR_INVALID_LINE :   /* 11116 */
  1185.           TstWriteTrace("ERROR : Syntax error in script file.");
  1186.           break;
  1187.  
  1188.         /***** Process function 1 (ModMyFunction) *******************/
  1189.  
  1190.         case 1 :
  1191.           {
  1192.           ULONG    ulvar1;
  1193.  
  1194.           /***** Extract the parameters (2 of them expected) ******/
  1195.  
  1196.           if ( TstRegisterFunction( hscript, 2, teststr, param))
  1197.             break;
  1198.           .
  1199.           .
  1200.           }
  1201.           break;
  1202.         .
  1203.         .
  1204.         } /* end of switch */
  1205.  
  1206.        } /* end of while */
  1207.  
  1208.  Related Functions 
  1209.  
  1210.      o TstReadScriptLine 
  1211.      o TstGetFunctionNum 
  1212.  
  1213.  
  1214. ΓòÉΓòÉΓòÉ 6.14. TstRegisterProcess ΓòÉΓòÉΓòÉ
  1215.  
  1216. BOOL APIENTRY TstRegisterProcess( PSZ   proc_name);
  1217.  
  1218. Parameters 
  1219.  
  1220.  proc_name           NULL terminated character string representing a unique 
  1221.                      name for the thread in Test Engine/2 
  1222.  
  1223.  Description 
  1224.  
  1225.  Registers the current thread (if in trace by thread mode) or process (if in 
  1226.  trace by process mode) with Test Engine/2 under the name proc_name 
  1227.  
  1228.  The function returns TRUE if successful, else FALSE. 
  1229.  
  1230.   CAUTION:
  1231.  The function will fail if Test Engine/2 is not active. 
  1232.  
  1233.  Example 
  1234.  
  1235.   VOID ThreadFunction( PVOID  pdata)
  1236.     {
  1237.     .
  1238.     .
  1239.     .
  1240.  
  1241.     /***** Register the thread ******************************************/
  1242.  
  1243.     if( !TstRegisterProcess( "TEST1"))
  1244.       DosBeep( 440, 1000);
  1245.     .
  1246.     . Body of thread function
  1247.     .
  1248.  
  1249.     /***** deregister the thread ****************************************/
  1250.  
  1251.     TstDeRegister();
  1252.  
  1253.     _endthread;
  1254.  
  1255.     } /* end of function */
  1256.  
  1257.  Related Functions 
  1258.  
  1259.      o TstInitProcess 
  1260.      o TstDeRegister 
  1261.      o TstStopProcess 
  1262.  
  1263.  
  1264. ΓòÉΓòÉΓòÉ 6.15. TstStopProcess ΓòÉΓòÉΓòÉ
  1265.  
  1266. VOID APIENTRY TstStopProcess();
  1267.  
  1268. Parameters 
  1269.  
  1270.  None 
  1271.  
  1272.  Description 
  1273.  
  1274.  De registers the current process and all threads from the current process with 
  1275.  Test Engine/2. 
  1276.  
  1277.  It is recomended that this call, or its Macro (TST_STOP) be placed in any exit 
  1278.  function of a program that uses Test Engine/2. 
  1279.  
  1280.  Related Functions 
  1281.  
  1282.      o TstInitProcess 
  1283.      o TstRegisterProcess 
  1284.      o TstDeRegister 
  1285.  
  1286.  
  1287. ΓòÉΓòÉΓòÉ 6.16. TstTraceOnOff ΓòÉΓòÉΓòÉ
  1288.  
  1289. VOID APIENTRY TstTraceOnOff( PSZ  on_off);
  1290.  
  1291. Parameters 
  1292.  
  1293.  on_off              One of the Test Engine/2 Macros TST_TRON or TST_TROFF. 
  1294.  
  1295.  Description 
  1296.  
  1297.  Sends a message to Test Engine/2 that causes tracing for the current thread 
  1298.  (if in trace by thread mode) or the current process (if in trace by process 
  1299.  mode) to be switched on (parameter = TST_TRON) or off (parameter = TST_TROFF). 
  1300.  
  1301.  Example 
  1302.  
  1303.   VOID ThreadFunction( PVOID  pdata)
  1304.     {
  1305.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1306.     .
  1307.  
  1308.     /***** Register the thread etc. *************************************/
  1309.  
  1310.     TstRegisterProcess( "TEST1");
  1311.     TstOpenTrace( trace_name, FALSE);
  1312.     .
  1313.     .
  1314.  
  1315.     /***** Switch Tracing from this thread off **************************/
  1316.  
  1317.     TstTraceOnOff( TST_TROFF);
  1318.     .
  1319.     .
  1320.  
  1321.     /***** Switch tracing from this thread on again *********************/
  1322.  
  1323.     TstTraceOnOff( TST_TRON);
  1324.     .
  1325.     .
  1326.     _endthread;
  1327.  
  1328.     } /* end of function */
  1329.  
  1330.  Related Functions 
  1331.  
  1332.      o TstOpenTrace 
  1333.      o TstCloseTrace 
  1334.      o TstAppendOnOff 
  1335.  
  1336.  
  1337. ΓòÉΓòÉΓòÉ 6.17. TstWriteString ΓòÉΓòÉΓòÉ
  1338.  
  1339. VOID APIENTRY TstWriteString( PSZ string);
  1340.  
  1341. Parameters 
  1342.  
  1343.  string              Pointer to a NULL terminated string. 
  1344.  
  1345.  Description 
  1346.  
  1347.  Sends a message to Test Engine/2 consisting of the string, a time stamp and 
  1348.  the id of the sending thread. 
  1349.  
  1350.  Example 
  1351.  
  1352.   VOID TestFunction()
  1353.     {
  1354.     PSZ     file_name = "d:\\addtools\\test.txt";
  1355.     HFILE    hfile = (HFILE)0;
  1356.  
  1357.     /***** Open a file to write some text *******************************/
  1358.  
  1359.     hfile = Reset( file_name);
  1360.  
  1361.     if( hfile != (HFILE)0)
  1362.       TstWriteString( "TestFunction : Opened the file successfully");
  1363.     else
  1364.       TstWriteString( "TestFunction : Failed to open the file");
  1365.  
  1366.     } /* end of function */
  1367.  
  1368.  Related Functions 
  1369.  
  1370.      o None 
  1371.  
  1372.  
  1373. ΓòÉΓòÉΓòÉ 6.18. TstWriteTrace ΓòÉΓòÉΓòÉ
  1374.  
  1375. VOID TstWriteTrace( PSZ  format_str, ...);
  1376.  
  1377. Parameters 
  1378.  
  1379.  format_str          Pointer to a NULL terminated character string containing 
  1380.                      text and formatting flags. The formatting flags are the 
  1381.                      same as those used for printf. 
  1382.  ...                 Variable list conforming to the flags in format_str. 
  1383.  
  1384.  Description 
  1385.  
  1386.  The function treats the input parameters in the same way as printf or sprintf 
  1387.  and then sends a message to Test Engine/2 consisting of the formatted string, 
  1388.  a time stamp and the id of the sending thread. 
  1389.  
  1390.  Example 
  1391.  
  1392.   VOID TestFunction()
  1393.     {
  1394.     PSZ     file_name = "d:\\addtools\\test.txt";
  1395.     HFILE    hfile = (HFILE)0;
  1396.  
  1397.     /***** Open a file to write some text *******************************/
  1398.  
  1399.     hfile = Reset( file_name);
  1400.  
  1401.     if( hfile != (HFILE)0)
  1402.       TstWriteTrace( "TestFunction : Opened file '%s' returned handle %lu", file_name, hfile);
  1403.     else
  1404.       TstWriteTrace( "TestFunction : Failed to open file '%s'", file_name);
  1405.  
  1406.     } /* end of function */
  1407.  
  1408.  Related Functions 
  1409.  
  1410.      o TstWriteString 
  1411.      o TstOpenTrace 
  1412.      o TstTraceOnOff 
  1413.  
  1414.  
  1415. ΓòÉΓòÉΓòÉ 7. Test Engine/2 Function Macros ΓòÉΓòÉΓòÉ
  1416.  
  1417. The following sections describe each of the Macros from Test Engine/2. All the 
  1418. Macros for Test Engine/2 resolve to function calls when #define TST_NGEN is 
  1419. activated, otherwise they resolve to w NULL statement. 
  1420.  
  1421.  
  1422. ΓòÉΓòÉΓòÉ 7.1. TST_CLOSE ΓòÉΓòÉΓòÉ
  1423.  
  1424. TST_CLOSE()
  1425.  
  1426. Parameters 
  1427.  
  1428.  None 
  1429.  
  1430.  Description 
  1431.  
  1432.  Closes the trace file for the curent thread or process. See TstCloseTrace. 
  1433.  
  1434.  Example 
  1435.  
  1436.   VOID ThreadFunction( PVOID  pdata)
  1437.     {
  1438.   #ifdef TST_NGEN
  1439.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1440.   #endif
  1441.     .
  1442.     .
  1443.     .
  1444.  
  1445.     /***** Register the thread etc. *************************************/
  1446.  
  1447.     TST_REG( "TEST1")
  1448.     TST_OPEN( trace_name, FALSE)
  1449.     .
  1450.     .
  1451.     .
  1452.  
  1453.     TST_CLOSE()
  1454.     TST_END()
  1455.     _endthread;
  1456.  
  1457.     } /* end of function */
  1458.  
  1459.  
  1460. ΓòÉΓòÉΓòÉ 7.2. TST_DUMP ΓòÉΓòÉΓòÉ
  1461.  
  1462. TST_DUMP( PSZ  on_off)
  1463.  
  1464. Parameters 
  1465.  
  1466.  on_off              One of the Test Engine/2 Macros TST_TRON or TST_TROFF. 
  1467.  
  1468.  Description 
  1469.  
  1470.  Switches global tracing on or off in Test Engine/2. If TST_TRON is passed then 
  1471.  tracing is switched on, if TST_TROFF is passed the tracing is switched off. 
  1472.  See TstDumpOnOff. 
  1473.  
  1474.  NOTE The global trace file is NOT CLOSED when tracing is set to OFF. 
  1475.  
  1476.  
  1477. ΓòÉΓòÉΓòÉ 7.3. TST_DCLOSE ΓòÉΓòÉΓòÉ
  1478.  
  1479. TST_DCLOSE()
  1480.  
  1481. Parameters 
  1482.  
  1483.  None 
  1484.  
  1485.  Description 
  1486.  
  1487.  Closes the global trace file in Test Engine/2. See TstDumpClose 
  1488.  
  1489.  
  1490. ΓòÉΓòÉΓòÉ 7.4. TST_END ΓòÉΓòÉΓòÉ
  1491.  
  1492. TST_END()
  1493.  
  1494. Parameters 
  1495.  
  1496.  None 
  1497.  
  1498.  Description 
  1499.  
  1500.  De registers the current thread. See TstDeRegister. 
  1501.  
  1502.  Example 
  1503.  
  1504.   VOID ThreadFunction( PVOID  pdata)
  1505.     {
  1506.   #ifdef TST_NGEN
  1507.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1508.   #endif
  1509.     .
  1510.     .
  1511.     .
  1512.  
  1513.     /***** Register the thread etc. *************************************/
  1514.  
  1515.     TST_REG( "TEST1")
  1516.     TST_OPEN( trace_name, FALSE)
  1517.     .
  1518.     .
  1519.     .
  1520.  
  1521.     TST_CLOSE()
  1522.     TST_END()
  1523.     _endthread;
  1524.  
  1525.     } /* end of function */
  1526.  
  1527.  
  1528. ΓòÉΓòÉΓòÉ 7.5. TST_INIT ΓòÉΓòÉΓòÉ
  1529.  
  1530. TST_INIT( proc_name, lang_char)
  1531.  
  1532. Parameters 
  1533.  
  1534.  proc_name           NULL terminated string representing a unique name for the 
  1535.                      thread. 
  1536.  lang_char           Single character denoting the language Test Engine/2 
  1537.                      should start in. 
  1538.  
  1539.  Description 
  1540.  
  1541.  If Test Engine/2 is not active, it is started in the language denoted by 
  1542.  lang_char. The current thread is then registered with the name proc_name. See 
  1543.  TstInitProcess. lang_char can be any of the following characters: 
  1544.  
  1545.  E | e     English 
  1546.  F | f     French. 
  1547.  S | s     Spanish. 
  1548.  G | g     German. 
  1549.  I | i     Italian. 
  1550.  
  1551.   CAUTION:
  1552.  This function should only be called from the main thread (TID = 1) of a 
  1553.  process. 
  1554.  
  1555.  Example 
  1556.  
  1557.   int main(int argc, char *argv[]);
  1558.     {
  1559.     .
  1560.     .
  1561.     .
  1562.  
  1563.     /***** Start Test Engine/2 in Spanish *******************************/
  1564.  
  1565.     TST_INIT( "PRUEBA", 'S');
  1566.     .
  1567.     .
  1568.     TST_STOP();
  1569.     exit(0);
  1570.  
  1571.     } /* end of main() */
  1572.  
  1573.  
  1574. ΓòÉΓòÉΓòÉ 7.6. TST_ONOFF ΓòÉΓòÉΓòÉ
  1575.  
  1576. TST_ONOFF( on_off)
  1577.  
  1578. Parameters 
  1579.  
  1580.  on_off              One of the Test Engine/2 Macros TST_TRON or TST_TROFF. 
  1581.  
  1582.  Description 
  1583.  
  1584.  Switches tracing for the curent thread or process on or off. If TST_TRON is 
  1585.  passed then tracing is switched on, if TST_TROFF is passed the tracing is 
  1586.  switched off. See TstTraceOnOff. 
  1587.  
  1588.  Example 
  1589.  
  1590.   VOID ThreadFunction( PVOID  pdata)
  1591.     {
  1592.   #ifdef TST_NGEN
  1593.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1594.   #endif
  1595.     .
  1596.     .
  1597.     .
  1598.  
  1599.     /***** Register the thread etc. *************************************/
  1600.  
  1601.     TST_REG( "TEST1")
  1602.     TST_OPEN( trace_name, TRUE)
  1603.     .
  1604.     .
  1605.  
  1606.     /***** switch tracing off for the thread ****************************/
  1607.  
  1608.     TST_ONOFF( TST_TROFF)
  1609.     .
  1610.     .
  1611.  
  1612.     /***** switch tracing on again **************************************/
  1613.  
  1614.     TST_ONOFF( TST_TRON)
  1615.     .
  1616.     .
  1617.  
  1618.     TST_CLOSE()
  1619.     TST_END()
  1620.     _endthread;
  1621.  
  1622.     } /* end of function */
  1623.  
  1624.  
  1625. ΓòÉΓòÉΓòÉ 7.7. TST_OPEN ΓòÉΓòÉΓòÉ
  1626.  
  1627. TST_OPEN( file_name, append)
  1628.  
  1629. Parameters 
  1630.  
  1631.  file_name           NULL terminated string containing the full path name of 
  1632.                      the trace file to open. 
  1633.  append              If TRUE then the file is opened for appending else it is 
  1634.                      overwritten. 
  1635.  
  1636.  Description 
  1637.  
  1638.  Opens a named trace file through Test Engine/2 with the given mode. See 
  1639.  TstOpenTrace. 
  1640.  
  1641.  Example 
  1642.  
  1643.   VOID ThreadFunction( PVOID  pdata)
  1644.     {
  1645.   #ifdef TST_NGEN
  1646.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1647.   #endif
  1648.     .
  1649.     .
  1650.     .
  1651.  
  1652.     /***** Register the thread ******************************************/
  1653.  
  1654.     TST_REG( "TEST1")
  1655.  
  1656.     /***** Open a trace file in append mode *****************************/
  1657.  
  1658.     TST_OPEN( trace_name, TRUE)
  1659.  
  1660.     .
  1661.     . Body of thread function
  1662.     .
  1663.  
  1664.     TST_CLOSE()
  1665.     TST_END()
  1666.     _endthread;
  1667.  
  1668.     } /* end of function */
  1669.  
  1670.  
  1671. ΓòÉΓòÉΓòÉ 7.8. TST_REG ΓòÉΓòÉΓòÉ
  1672.  
  1673. TST_REG( proc_name)
  1674.  
  1675. Parameters 
  1676.  
  1677.  proc_name           NULL terminated string containing a unique name for the 
  1678.                      thread. 
  1679.  
  1680.  Description 
  1681.  
  1682.  Registers the thread or process with Test Engine/2 under the specified name. 
  1683.  See TstRegisterProcess. 
  1684.  
  1685.  Example 
  1686.  
  1687.   VOID ThreadFunction( PVOID  pdata)
  1688.     {
  1689.   #ifdef TST_NGEN
  1690.     PSZ     trace_name = "d:\\addtools\\test.trc";
  1691.   #endif
  1692.     .
  1693.     .
  1694.     .
  1695.  
  1696.     /***** Register the thread ******************************************/
  1697.  
  1698.     TST_REG( "TEST1")
  1699.  
  1700.     /***** Open a trace file in append mode *****************************/
  1701.  
  1702.     TST_OPEN( trace_name, TRUE)
  1703.  
  1704.     .
  1705.     . Body of thread function
  1706.     .
  1707.  
  1708.     TST_CLOSE()
  1709.     TST_END()
  1710.     _endthread;
  1711.  
  1712.     } /* end of function */
  1713.  
  1714.  
  1715. ΓòÉΓòÉΓòÉ 7.9. TST_STOP ΓòÉΓòÉΓòÉ
  1716.  
  1717. TST_STOP()
  1718.  
  1719. Parameters 
  1720.  
  1721.  None 
  1722.  
  1723.  Description 
  1724.  
  1725.  De registers all the threads from the current process. See TstStopProcess. 
  1726.  
  1727.  Example 
  1728.  
  1729.   int main(int argc, char *argv[]);
  1730.     {
  1731.     .
  1732.     .
  1733.     .
  1734.  
  1735.     /***** Start Test Engine/2 in German *******************************/
  1736.  
  1737.     TST_INIT( "DINGSBUMS", 'g');
  1738.     .
  1739.     .
  1740.     TST_STOP();
  1741.     exit(0);
  1742.  
  1743.     } /* end of main() */
  1744.  
  1745.  
  1746. ΓòÉΓòÉΓòÉ 7.10. TST_TRACE ΓòÉΓòÉΓòÉ
  1747.  
  1748. TST_TRACE( fmt_str, var1, var2, var3, var4)
  1749.  
  1750. Parameters 
  1751.  
  1752.  fmt_str             NULL terminated format string. 
  1753.  var1 .. var4        Any variable that can be flagged by a printf flag (%s,%lu 
  1754.                      etc..). 
  1755.  
  1756.  Description 
  1757.  
  1758.  Resolves to a call to TstWriteTrace with 4 parameters. 
  1759.  
  1760.   CAUTION:
  1761.  Any unused parameters should be replaced by '0'. 
  1762.  
  1763.  Example 
  1764.  
  1765.     USHORT    a,b;
  1766.     ULONG    c;
  1767.     PSZ     d;
  1768.     .
  1769.     .
  1770.     /***** Trace only 2 variables ***************************************/
  1771.  
  1772.     TST_TRACE( "The value of a is %u, the value of c is %lu", a, c, 0, 0);
  1773.  
  1774.     /***** trace all 4 vars *********************************************/
  1775.  
  1776.     TST_TRACE( "%s when a is %u, b is %u and c is %lu", d, a, b, c);
  1777.  
  1778.  
  1779. ΓòÉΓòÉΓòÉ 8. Test Engine/2 REXX Functions ΓòÉΓòÉΓòÉ
  1780.  
  1781. The following sections describe each of the REXX interface functions from Test 
  1782. Engine/2. 
  1783.  
  1784.  
  1785. ΓòÉΓòÉΓòÉ 8.1. TstRxLoadFuncs ΓòÉΓòÉΓòÉ
  1786.  
  1787. TstRxLoadFuncs( );
  1788.  
  1789. Parameters 
  1790.  
  1791.  None 
  1792.  
  1793.  Description 
  1794.  
  1795.  Registers the Test Engine/2 DLL with the REXX environment and loads all the 
  1796.  Test Engine/2 REXX functions. 
  1797.  
  1798.  The function returns 0 if successful, else 1. 
  1799.  
  1800.   CAUTION:
  1801.  This function should be called before any other Test Engine/2 REXX functions 
  1802.  
  1803.  Example 
  1804.  
  1805.  
  1806.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  1807.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  1808.       call TstRxLoadFuncs
  1809.     end
  1810.  
  1811.  Related Functions 
  1812.  
  1813.      o TstRxDropFuncs 
  1814.  
  1815.  
  1816. ΓòÉΓòÉΓòÉ 8.2. TstRxDropFuncs ΓòÉΓòÉΓòÉ
  1817.  
  1818. TstRxDropFuncs()
  1819.  
  1820. Parameters 
  1821.  
  1822.  None 
  1823.  
  1824.  Description 
  1825.  
  1826.  De registers the Test Engine/2 DLL with the REXX environment and unloads all 
  1827.  the Test Engine/2 REXX functions. 
  1828.  
  1829.  The function returns 0 if successful, else 1. 
  1830.  
  1831.  Example 
  1832.  
  1833.  
  1834.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  1835.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  1836.       call TstRxLoadFuncs
  1837.     end
  1838.  
  1839.     /* Body of rexx program */
  1840.  
  1841.     call TstRxDropFuncs
  1842.  
  1843.     exit
  1844.  
  1845.  Related Functions 
  1846.  
  1847.      o TstRxLoadFuncs 
  1848.  
  1849.  
  1850. ΓòÉΓòÉΓòÉ 8.3. TstRxInit ΓòÉΓòÉΓòÉ
  1851.  
  1852. TxtRxInit( reg_name, language)
  1853.  
  1854. Parameters 
  1855.  
  1856.  reg_name            Name for the registering process or thread. This is the 
  1857.                      name that will appear on traces. 
  1858.  language            Single character denoting the language Test Engine/2 
  1859.                      should be started in. 
  1860.  
  1861.  Description 
  1862.  
  1863.  Registers the current thread or process with Test Engine/2. This is the REXX 
  1864.  equivalent of TstInitProcess. 
  1865.  
  1866.  The function returns 0 if successful, else 1. 
  1867.  
  1868.  Example 
  1869.  
  1870.  
  1871.     /***** Load the functions if necessary **********************************/
  1872.  
  1873.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  1874.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  1875.       call TstRxLoadFuncs
  1876.     end
  1877.  
  1878.     /***** Register the process and start test engine in spanish ************/
  1879.  
  1880.     call TstInit 'MYPROG', 'S'
  1881.     .
  1882.     /* Body of rexx program */
  1883.     .
  1884.     call TstRxStop
  1885.     call TstRxDropFuncs
  1886.  
  1887.     exit
  1888.  
  1889.  Related Functions 
  1890.  
  1891.      o TstRxStop 
  1892.      o TstRxTrace 
  1893.  
  1894.  
  1895. ΓòÉΓòÉΓòÉ 8.4. TstRxStop ΓòÉΓòÉΓòÉ
  1896.  
  1897. TstRxStop()
  1898.  
  1899. Parameters 
  1900.  
  1901.  None 
  1902.  
  1903.  Description 
  1904.  
  1905.  De registers the current thread or process with Test Engine/2. This is the 
  1906.  REXX equivalent of TstStopProcess. 
  1907.  
  1908.  The function returns 0 if successful, else 1. 
  1909.  
  1910.  Example 
  1911.  
  1912.  
  1913.     /***** Load the functions if necessary **********************************/
  1914.  
  1915.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  1916.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  1917.       call TstRxLoadFuncs
  1918.     end
  1919.  
  1920.     /***** Register the process and start test engine in spanish ************/
  1921.  
  1922.     call TstInit 'MYPROG', 'S'
  1923.     .
  1924.     /* Body of rexx program */
  1925.     .
  1926.     call TstRxStop
  1927.     call TstRxDropFuncs
  1928.  
  1929.     exit
  1930.  
  1931.  Related Functions 
  1932.  
  1933.      o TstRxInit 
  1934.      o TstRxTrace 
  1935.  
  1936.  
  1937. ΓòÉΓòÉΓòÉ 8.5. TstRxTrace ΓòÉΓòÉΓòÉ
  1938.  
  1939. TstRxTrace( trace_flag, trace_string)
  1940.  
  1941. Parameters 
  1942.  
  1943.  trace_flag          Numeric variable used as a flag to switch the trace on or 
  1944.                      off. 0 = tracing OFF, 1 = tracing ON. 
  1945.  trace_string        String or values to be traced to Test Engine/2. 
  1946.  
  1947.  Description 
  1948.  
  1949.  Sends a trace message to Test Engine/2. This is the REXX equivalent of 
  1950.  TstWriteString. 
  1951.  
  1952.  The function returns 0 if successful, else 1. 
  1953.  
  1954.  Example 
  1955.  
  1956.  
  1957.     /***** Flag to turn tracing on or off ***********************************/
  1958.  
  1959.     tst = 1   /* tracing on */
  1960.  
  1961.     /***** Load the functions if necessary **********************************/
  1962.  
  1963.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  1964.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  1965.       call TstRxLoadFuncs
  1966.     end
  1967.  
  1968.     /***** Register the process and start test engine in spanish ************/
  1969.  
  1970.     if tst then
  1971.       call TstInit 'MYPROG', 'S'
  1972.     .
  1973.     call TstRxTrace tst, 'The value from some operation =' var_name
  1974.     .
  1975.     if tst then
  1976.       call TstRxStop
  1977.  
  1978.     call TstRxDropFuncs
  1979.  
  1980.     exit
  1981.  
  1982.  Related Functions 
  1983.  
  1984.      o TstRxOpenTrace 
  1985.      o TstRxCloseTrace 
  1986.  
  1987.  
  1988. ΓòÉΓòÉΓòÉ 8.6. TstRxOpenTrace ΓòÉΓòÉΓòÉ
  1989.  
  1990. TstRxOpenTrace( trace_name)
  1991.  
  1992. Parameters 
  1993.  
  1994.  trace_name          Full file name of the trace file to open. 
  1995.  
  1996.  Description 
  1997.  
  1998.  Opens a trace file with Test Engine/2 for the current thread or process. This 
  1999.  is the REXX equivalent of TstOpenTrace 
  2000.  
  2001.  The function returns 0 if successful, else 1. 
  2002.  
  2003.  Example 
  2004.  
  2005.  
  2006.     /***** Flag to turn tracing on or off ***********************************/
  2007.  
  2008.     tst = 1   /* tracing on */
  2009.  
  2010.     /***** Load the functions if necessary **********************************/
  2011.  
  2012.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  2013.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  2014.       call TstRxLoadFuncs
  2015.     end
  2016.  
  2017.     /***** Register the process and start test engine in spanish ************/
  2018.  
  2019.     if tst then
  2020.       call TstInit 'MYPROG', 'S'
  2021.  
  2022.     /***** Open the trace file **********************************************/
  2023.  
  2024.     if tst then
  2025.       call TstRxOpenTrace 'c:\mypath\mytrace.trc'
  2026.     .
  2027.     call TstRxTrace tst, 'The value from some operation =' var_name
  2028.     .
  2029.     if tst then do
  2030.       call TxtRxCloseTrace
  2031.       call TstRxStop
  2032.     end
  2033.  
  2034.     call TstRxDropFuncs
  2035.  
  2036.     exit
  2037.  
  2038.  Related Functions 
  2039.  
  2040.      o TstRxTrace 
  2041.      o TstRxInit 
  2042.  
  2043.  
  2044. ΓòÉΓòÉΓòÉ 8.7. TstRxCloseTrace ΓòÉΓòÉΓòÉ
  2045.  
  2046. TstRxCloseTrace( )
  2047.  
  2048. Parameters 
  2049.  
  2050.  None 
  2051.  
  2052.  Description 
  2053.  
  2054.  Closes the trace file for the current thread or process. This is the REXX 
  2055.  equivalent of TstCloseTrace 
  2056.  
  2057.  The function returns 0 if successful, else 1. 
  2058.  
  2059.  Example 
  2060.  
  2061.  
  2062.     /***** Flag to turn tracing on or off ***********************************/
  2063.  
  2064.     tst = 1   /* tracing on */
  2065.  
  2066.     /***** Load the functions if necessary **********************************/
  2067.  
  2068.     if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
  2069.       call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
  2070.       call TstRxLoadFuncs
  2071.     end
  2072.  
  2073.     /***** Register the process and start test engine in spanish ************/
  2074.  
  2075.     if tst then
  2076.       call TstInit 'MYPROG', 'S'
  2077.  
  2078.     /***** Open the trace file **********************************************/
  2079.  
  2080.     if tst then
  2081.       call TstRxOpenTrace 'c:\mypath\mytrace.trc'
  2082.     .
  2083.     call TstRxTrace tst, 'The value from some operation =' var_name
  2084.     .
  2085.     if tst then do
  2086.       call TxtRxCloseTrace
  2087.       call TstRxStop
  2088.     end
  2089.  
  2090.     call TstRxDropFuncs
  2091.  
  2092.     exit
  2093.  
  2094.  Related Functions 
  2095.  
  2096.      o TstRxTrace 
  2097.      o TstRxInit 
  2098.  
  2099.  
  2100. ΓòÉΓòÉΓòÉ 9. Tools and Utility functions ΓòÉΓòÉΓòÉ
  2101.  
  2102. Test Engine/2 is delivered with 3 utility DLLs that can be freely integrated 
  2103. into your software products. 
  2104.  
  2105.      o FILES.DLL 
  2106.  
  2107.      o CALC.DLL 
  2108.  
  2109.      o PRTREXX.DLL 
  2110.  
  2111.  The FILES.DLL supplies PASCAL type functions for manipulating text files, a 
  2112.  File Dialog that sets the current path and drive when you select a file, a 
  2113.  printer selection dialog which shows all attached printers and simple RAW mode 
  2114.  text printing functions. 
  2115.  
  2116.  The PRTREXX.DLL supplies a REXX interface to simple RAW mode text printing 
  2117.  functions. 
  2118.  
  2119.  The CALC.DLL supplies a simple maths integer calculation function which is 
  2120.  used by IPFPC.EXE. 
  2121.  
  2122.  Two utility programs are also supplied : 
  2123.  
  2124.      o IPFPC.EXE 
  2125.  
  2126.      o XDEL.EXE 
  2127.  
  2128.  IPFPC is a pre-compiler originally written for pre-compiling Information 
  2129.  Presentation text files where the res= statements contain constants from 
  2130.  header files. This program can also be used to pre-compile script files that 
  2131.  are written with constants from header files. This file and the on-line help 
  2132.  for Test Engine/2 and Quality Assurance Manager/2 were pre-compiled using 
  2133.  IPFPC. 
  2134.  
  2135.  XDEL.EXE is a simple and VERY brutal utility for destroying directory trees. 
  2136.  To see the supported parameters run xdel from the command line with no 
  2137.  parameters. 
  2138.  
  2139.  
  2140. ΓòÉΓòÉΓòÉ 9.1. FileDllInit ΓòÉΓòÉΓòÉ
  2141.  
  2142. VOID APIENTRY FileDllInit( );
  2143.  
  2144. Parameters 
  2145.  
  2146.  None 
  2147.  
  2148.  Description 
  2149.  
  2150.  This call should be made before you use any of the file access functions or 
  2151.  printing functions. It initialises per process data and loads the resources 
  2152.  for the two dialog functions in the DLL. 
  2153.  
  2154.  
  2155. ΓòÉΓòÉΓòÉ 9.2. FileDllRelease ΓòÉΓòÉΓòÉ
  2156.  
  2157. VOID APIENTRY FileDllRelease( );
  2158.  
  2159. Parameters 
  2160.  
  2161.  None 
  2162.  
  2163.  Description 
  2164.  
  2165.  This function should be called before terminating a program. 
  2166.  
  2167.  
  2168. ΓòÉΓòÉΓòÉ 9.3. FileSetWriteThru ΓòÉΓòÉΓòÉ
  2169.  
  2170. VOID APIENTRY FileSetWriteThru( BOOL on);
  2171.  
  2172. Parameters 
  2173.  
  2174.  on                  Boolean variable or literal. If TRUE file write mode is 
  2175.                      set to Write Through for the process. 
  2176.  
  2177.  Description 
  2178.  
  2179.  Sets the file write mode to Write Through or to use buffering. Test Engine/2 
  2180.  uses Write Through mode to ensure that all data is written to the trace files 
  2181.  if a program crashes the system. 
  2182.  
  2183.  
  2184. ΓòÉΓòÉΓòÉ 9.4. FileRewrite ΓòÉΓòÉΓòÉ
  2185.  
  2186. HFILE APIENTRY FileRewrite( PSZ file_name);
  2187.  
  2188. Parameters 
  2189.  
  2190.  file_name           Null terminated string representing the name of the file 
  2191.                      to open for writing. 
  2192.  
  2193.  Description 
  2194.  
  2195.  Opens the named text file for writing. If the file exists any data in it is 
  2196.  destroyed. The file pointer is set to 0. 
  2197.  
  2198.  The function returns a valid handle if successful, else (HFILE)0. 
  2199.  
  2200.  
  2201. ΓòÉΓòÉΓòÉ 9.5. FileAppend ΓòÉΓòÉΓòÉ
  2202.  
  2203. HFILE APIENTRY FileAppend( PSZ  file_name);
  2204.  
  2205. Parameters 
  2206.  
  2207.  file_name           Null terminated string representing the name of a file to 
  2208.                      open for writing. 
  2209.  
  2210.  Description 
  2211.  
  2212.  Opens the named text file for writing. If the file exists the file pointer is 
  2213.  set to the end of the file. 
  2214.  
  2215.  The function returns a valid handle if successful, else (HFILE)0. 
  2216.  
  2217.  
  2218. ΓòÉΓòÉΓòÉ 9.6. FileReset ΓòÉΓòÉΓòÉ
  2219.  
  2220. HFILE APIENTRY FileReset( PSZ  file_name);
  2221.  
  2222. Parameters 
  2223.  
  2224.  file_name           Null terminated string representing the name of a file to 
  2225.                      open for reading. 
  2226.  
  2227.  Description 
  2228.  
  2229.  Opens the named text file for reading. If the file exists the file pointer is 
  2230.  set to the beginning of the file. 
  2231.  
  2232.  The function returns a valid handle if successful, else (HFILE)0. 
  2233.  
  2234.  
  2235. ΓòÉΓòÉΓòÉ 9.7. FileWriteLn ΓòÉΓòÉΓòÉ
  2236.  
  2237. APIRET APIENTRY FileWriteLn( HFILE  hfile, PSZ string);
  2238.  
  2239. Parameters 
  2240.  
  2241.  hfile               Handle to the text file to write to. The file must be 
  2242.                      open. 
  2243.  string              NULL terminated string to write to the file. 
  2244.  
  2245.  Description 
  2246.  
  2247.  Writes the given text to the file and appends and End-Of_Line. The return is 0 
  2248.  if successful otherwise either FILE_BLK_SIZE_ERR if the string was not written 
  2249.  completely or a DOS error. 
  2250.  
  2251.  
  2252. ΓòÉΓòÉΓòÉ 9.8. FileReadLn ΓòÉΓòÉΓòÉ
  2253.  
  2254. APIRET APIENTRY FileReadLn( HFILE  hfile, PSZ  string);
  2255.  
  2256. Parameters 
  2257.  
  2258.  hfile               Handle to the text file to read from. The file must be 
  2259.                      open. 
  2260.  string              NULL terminated string read from the file. This variable 
  2261.                      MUST be pre-allocated. 
  2262.  
  2263.  Description 
  2264.  
  2265.  Reads a line of text from the given file into the variable string. The return 
  2266.  is 0 if successful otherwise either FILE_BLK_SIZE_ERR if the string was not 
  2267.  read completely or a DOS error. 
  2268.  
  2269.  
  2270. ΓòÉΓòÉΓòÉ 9.9. FileDlg ΓòÉΓòÉΓòÉ
  2271.  
  2272. USHORT APIENTRY FileDlg(   HWND   hWndOwner,
  2273.               PSZ   title,
  2274.               PSZ   dir,
  2275.               PSZ   file_mask,
  2276.               BOOL   exists,
  2277.               PSZ   file_name);
  2278.  
  2279. Parameters 
  2280.  
  2281.  hWndOwner           Handle to the parent window. 
  2282.  title               NULL terminated string representing the title that will 
  2283.                      appear in the dialog. 
  2284.  dir                 Directory where to look for the file. If this string is 
  2285.                      NULL the current directory will be searched. 
  2286.  file_mask           NULL terminated string representing the file mask to 
  2287.                      search for, e.g. "*.exe". 
  2288.  exists              Boolean flag, if TRUE then the file must exist, if FALSE 
  2289.                      the user may enter a new name. 
  2290.  file_name           NULL terminated string that will contain the fully 
  2291.                      qualified path of the selected file. 
  2292.  
  2293.  Description 
  2294.  
  2295.  This function forms a shell to the standard File Dialog. When a file is 
  2296.  selected, the current path and drive are set to those of the file, allowing 
  2297.  further file selections to search on the same path and drive. 
  2298.  
  2299.  
  2300. ΓòÉΓòÉΓòÉ 9.10. FileGetFullPath ΓòÉΓòÉΓòÉ
  2301.  
  2302. BOOL APIENTRY FileGetFullPath( PSZ  rel_path, PSZ  full_path);
  2303.  
  2304. Parameters 
  2305.  
  2306.  rel_path            NULL terminated string representing the relative path from 
  2307.                      which to obtain a fully qualified file name. 
  2308.  full_path           NULL terminated string that will contain the fully 
  2309.                      qualified path name. This variable MUST be pre-allocated. 
  2310.  
  2311.  Description 
  2312.  
  2313.  Coverts a relative path to a fully qualified path containing the drive. 
  2314.  
  2315.  Example 
  2316.  
  2317.  ..\mypath\myfile.exe would be converted to C:\dir1\mypath\myfile.exe if the 
  2318.  current directory were C:\dir1\dir2. 
  2319.  
  2320.  
  2321. ΓòÉΓòÉΓòÉ 9.11. FileSetDefaultExtension ΓòÉΓòÉΓòÉ
  2322.  
  2323. VOID APIENTRY FileSetDefaultExtension( PSZ  file_name, PSZ  extension);
  2324.  
  2325. Parameters 
  2326.  
  2327.  file_name           NULL terminated string representing the name of a file 
  2328.                      with an unknown extension. This variable is returned 
  2329.                      modified if there is no extension present. 
  2330.  extension           NULL terminated string representing the default extension 
  2331.                      to be added to the file name if none exists. 
  2332.  
  2333.  Description 
  2334.  
  2335.  Adds a default extension to a file name. 
  2336.  
  2337.  
  2338. ΓòÉΓòÉΓòÉ 9.12. FileForceDefaultExtension ΓòÉΓòÉΓòÉ
  2339.  
  2340. VOID APIENTRY FileForceDefaultExtension( PSZ   file_name, PSZ  extension);
  2341.  
  2342. Parameters 
  2343.  
  2344.  file_name           NULL terminated string representing the name of a file 
  2345.                      with an unknown extension. This variable is returned 
  2346.                      modified. 
  2347.  extension           NULL terminated string representing the extension to be 
  2348.                      added to the file name. 
  2349.  
  2350.  Description 
  2351.  
  2352.  Forces a new extension onto a file name. 
  2353.  
  2354.  
  2355. ΓòÉΓòÉΓòÉ 9.13. FileJustFileName ΓòÉΓòÉΓòÉ
  2356.  
  2357. PSZ APIENTRY FileJustFileName( PSZ  file_name);
  2358.  
  2359. Parameters 
  2360.  
  2361.  file_name           NULL terminated string representing the name of a file. 
  2362.  
  2363.  Description 
  2364.  
  2365.  Returns a pointer to the file name part of a qualified or relative path. 
  2366.  
  2367.  Example 
  2368.  
  2369.  An input of C:\dir1\mypath\myfile.exe will return myfile.exe. 
  2370.  
  2371.  
  2372. ΓòÉΓòÉΓòÉ 9.14. FileParsePath ΓòÉΓòÉΓòÉ
  2373.  
  2374. VOID APIENTRY FileParsePath(  PSZ      path_str,
  2375.                PULONG     pdrv_num,
  2376.                PSZ      pdrv_char,
  2377.                PSZ      directory
  2378.                PSZ      file_name)
  2379.  
  2380. Parameters 
  2381.  
  2382.  path_str            NULL terminated string representing the path to a file. 
  2383.  pdrv_num            Pointer to an unsigned long that will contain the drive 
  2384.                      number on returning. 
  2385.  pdrv_char           Pointer to a character variable that will contain the 
  2386.                      drive letter on returning. 
  2387.  directory           NULL terminated string that will contain the path part of 
  2388.                      the input. This variable MUST be pre-allocated. 
  2389.  file_name           NULL terminated string representing the name of the file. 
  2390.  
  2391.  Description 
  2392.  
  2393.  Parses an input path into the drive, path and file name. 
  2394.  
  2395.  Example 
  2396.  
  2397.  An input of C:\dir1\mypath\myfile.exe will return 
  2398.  
  2399.      o *pdrv_num = 3 
  2400.  
  2401.      o *pdrv_char = 'C' 
  2402.  
  2403.      o drectory = "dir1\mypath" 
  2404.  
  2405.      o file_name = "myfile.exe" 
  2406.  
  2407.  
  2408. ΓòÉΓòÉΓòÉ 9.15. FileUniqueName ΓòÉΓòÉΓòÉ
  2409.  
  2410. PSZ APIENTRY FileUniqueName( PSZ   file_mask);
  2411.  
  2412. Parameters 
  2413.  
  2414.  file_name           NULL terminated string representing a file mask containing 
  2415.                      ? characters. 
  2416.  
  2417.  Description 
  2418.  
  2419.  Returns a pointer to a unique file name where any ocurrences of "?" are 
  2420.  replaced with random numbers. The function checks that the name is really 
  2421.  unique. 
  2422.  
  2423.  Example 
  2424.  
  2425.  An input of C:\dir1\mypath\myfil?.??? could return C:\dir1\mypath\myfil1.384. 
  2426.  
  2427.  
  2428. ΓòÉΓòÉΓòÉ 9.16. PrtSelectPrinter ΓòÉΓòÉΓòÉ
  2429.  
  2430. PPRTDESC APIENTRY PrtSelectPrinter( HAB  hab, HWND  hWndOwner)
  2431.  
  2432. Parameters 
  2433.  
  2434.  hab                 Handle to the anchor block of the calling process or 
  2435.                      thread. 
  2436.  hWndOwner           Handle to the owner window (from the calling process). 
  2437.  
  2438.  Description 
  2439.  
  2440.  Calls the Select Printer Dialog and returns a PPRTDESC which can be used to 
  2441.  open a print job on that printer. 
  2442.  
  2443.  
  2444. ΓòÉΓòÉΓòÉ 9.17. PrtOpenPrintJob ΓòÉΓòÉΓòÉ
  2445.  
  2446. USHORT APIENTRY PrtOpenPrintJob( PPRTDESC  printer,
  2447.                  PSZ     job_title,
  2448.                  HPRINT   *hjob)
  2449.  
  2450. Parameters 
  2451.  
  2452.  printer             PPRTDESC variable previously obtained from a call to 
  2453.                      PrtSelectPrinter. 
  2454.  job_title           NULL terminated string containing the name of the print 
  2455.                      job as it will appear in the spooler queue. 
  2456.  hjob                HPRINT variable that will receive a handle to the print 
  2457.                      job which can be used to write to the job and close it. 
  2458.  
  2459.  Description 
  2460.  
  2461.  Opens a print job on the current printer with the given title. Returns 0 if 
  2462.  successful otherwise PRT_ERROR_OPEN_SPOOL. 
  2463.  
  2464.  
  2465. ΓòÉΓòÉΓòÉ 9.18. PrtWriteLn ΓòÉΓòÉΓòÉ
  2466.  
  2467. VOID APIENTRY PrtWriteLn( HPRINT  hjob, PSZ  string)
  2468.  
  2469. Parameters 
  2470.  
  2471.  hjob                Handle to the print job obtained from a call to 
  2472.                      PrtopenPrintJob. 
  2473.  string              NULL terminated string to written to the document. 
  2474.  
  2475.  Description 
  2476.  
  2477.  Writes the given string to the document with an appended Carriage return Line 
  2478.  feed. 
  2479.  
  2480.  
  2481. ΓòÉΓòÉΓòÉ 9.19. PrtClosePrintJob ΓòÉΓòÉΓòÉ
  2482.  
  2483. VOID APIENTRY PrtClosePrintJob( HPRINT    hjob)
  2484.  
  2485. Parameters 
  2486.  
  2487.  hjob                Handle to the print job obtained from a call to 
  2488.                      PrtopenPrintJob. 
  2489.  
  2490.  Description 
  2491.  
  2492.  Closes the print job represented by the handle. 
  2493.  
  2494.  
  2495. ΓòÉΓòÉΓòÉ 9.20. PrtRxLoadFuncs ΓòÉΓòÉΓòÉ
  2496.  
  2497. PrtRxLoadFuncs( )
  2498.  
  2499. Parameters 
  2500.  
  2501.  None 
  2502.  
  2503.  Description 
  2504.  
  2505.  Loads the PRTREXX DLL and loads all the functions. 
  2506.  
  2507.  
  2508. ΓòÉΓòÉΓòÉ 9.21. PrtRxOpenPrintJob ΓòÉΓòÉΓòÉ
  2509.  
  2510. print_job = PrtRxOpenPrintJob( queue, driver, job_title)
  2511.  
  2512. Parameters 
  2513.  
  2514.  queue               Name of the print queue. 
  2515.  driver              Name of the printer driver. 
  2516.  job_title           String containing the name of the print job as it will 
  2517.                      appear in the spooler queue. 
  2518.  
  2519.  Description 
  2520.  
  2521.  Opens a print job on the current printer with the given title. Returns Numeric 
  2522.  variable that identifies the print job that should be used to write to and 
  2523.  close the print job. If the return is 0 then an error occured opening the 
  2524.  print job. 
  2525.  
  2526.  
  2527. ΓòÉΓòÉΓòÉ 9.22. PrtRxWriteln ΓòÉΓòÉΓòÉ
  2528.  
  2529. PrtWriteLn( print_job, string)
  2530.  
  2531. Parameters 
  2532.  
  2533.  print_job           Handle to the print job obtained from a call to 
  2534.                      PrtRxOpenPrintJob. 
  2535.  string              String to written to the document. 
  2536.  
  2537.  Description 
  2538.  
  2539.  Writes the given string to the document with an appended Carriage return Line 
  2540.  feed. 
  2541.  
  2542.  
  2543. ΓòÉΓòÉΓòÉ 9.23. PrtRxClosePrintJob ΓòÉΓòÉΓòÉ
  2544.  
  2545. PrtRxClosePrintJob( print_job)
  2546.  
  2547. Parameters 
  2548.  
  2549.  print_job           Handle to the print job obtained from a call to 
  2550.                      PrtRxOpenPrintJob. 
  2551.  
  2552.  Description 
  2553.  
  2554.  Closes the print job represented by the handle. 
  2555.  
  2556.  
  2557. ΓòÉΓòÉΓòÉ 9.24. RxWinAlarm ΓòÉΓòÉΓòÉ
  2558.  
  2559. RxWinAlarm( alarm_tone)
  2560.  
  2561. Parameters 
  2562.  
  2563.  alarm_tone          Number denoting the kind of alarm to create: 
  2564.                      1 = WA_NOTE 
  2565.                      2 = WA_WARNING 
  2566.                      3 = WA_ERROR. 
  2567.  
  2568.  Description 
  2569.  
  2570.  Makes a call to WinAlarm() with the given tone. This permits a REXX program to 
  2571.  create error tones that will interface atomatically to the OS/2 multi-media if 
  2572.  present. 
  2573.  
  2574.  
  2575. ΓòÉΓòÉΓòÉ 9.25. PrtRxDropFuncs ΓòÉΓòÉΓòÉ
  2576.  
  2577. PrtRxDropFuncs( )
  2578.  
  2579. Parameters 
  2580.  
  2581.  None 
  2582.  
  2583.  Description 
  2584.  
  2585.  Releases the PRTREXX DLL from REXX environment. 
  2586.  
  2587.  
  2588. ΓòÉΓòÉΓòÉ 9.26. IPFPC ΓòÉΓòÉΓòÉ
  2589.  
  2590. IPFPC is an IPF pre-compiler. It allows you to insert constants from a program 
  2591. header file into an IPF text file for resolving Cross references, setting res 
  2592. values etc.. 
  2593.  
  2594. The relevant header files are declared at the start of the document by 
  2595. inserting: 
  2596.  
  2597. #include   <myheader.h>
  2598.  
  2599. or
  2600.  
  2601. #include   "myheader.h"
  2602.  
  2603. The header files are recursed, and #ifdef, #elseif and #endif statements are 
  2604. taken into consideration. 
  2605.  
  2606. You may include header files that perform integer maths on constants or literal 
  2607. numbers; these calculations will be resolved by IPFPC. 
  2608.  
  2609. Example 
  2610.  
  2611.  
  2612. in header file
  2613.  
  2614.   #define   OTHER_CONST   8
  2615.   #define   SOME_CONST    7
  2616.   #define   MY_CONST     (OTHER_CONST /4) * SOME_CONST
  2617.  
  2618. MY_CONST will be resolved to 14 after pre-compilation.
  2619.  
  2620. Command Line or Make File Syntax 
  2621.  
  2622.      IPFPC [switches] <Input Text File> [Output Text File] 
  2623.  
  2624.  Switches :   NOTE: Switches are not case sensitive 
  2625.  
  2626.  -I Γûî /I             Include path, may follow IBM or Borland format. The 
  2627.                      INCLUDE environment variable is also searched. 
  2628.                      Examples 
  2629.                      -ID:\TOOLKT21\OS2H (IBM format) 
  2630.                      -ID:\TOOLKT21\OS2INC;C:\BCOS2\INC; (Borland format) 
  2631.  -O Γûî /O             Output directory : MUST NOT HAVE TRAILING \. 
  2632.  -H Γûî /H             Shows a help screen. 
  2633.  
  2634.  Example 
  2635.  
  2636.      IPFPC -Id:\myincdir;c:\tools\incdir; -oobj test.htx test.ipf 
  2637.  
  2638.  Input file default extension .HTX. 
  2639.  Output file default extension .IPF. If no output file is specified the input 
  2640.  file name is used with the extension changed to .IPF. 
  2641.  
  2642.  
  2643. ΓòÉΓòÉΓòÉ 10. Runtime DLLs and licence information ΓòÉΓòÉΓòÉ
  2644.  
  2645. To integrate Test Engine/2 into your software products you must integrate the 
  2646. following DLLs into your package: 
  2647.  
  2648.      o ADD_TST.DLL 
  2649.      o FILES.DLL 
  2650.  
  2651.  These DLLs and the other tools DLLs and programs supplied with Test Engine/2 
  2652.  are free of any restrictions and can be redistributed as you wish with no 
  2653.  license fees. 
  2654.  
  2655.  The following programs and Dynamic Link Libraries can be redistributed freely: 
  2656.  
  2657.      o ADD_TST.DLL 
  2658.      o FILES.DLL 
  2659.      o PRTREXX.DLL 
  2660.      o CALC.DLL 
  2661.      o IPFPC.EXE 
  2662.      o XDEL.EXE 
  2663.  
  2664.  LICENSE RESTRICTION 
  2665.  
  2666.  Test Engine/2 and Quality Assurance Manager/2 are the property of ADD 
  2667.  Consulting and are protected by international copyright law. 
  2668.  
  2669.  You may NOT in any way redistribute either Test Engine/2 or Quality Assurance 
  2670.  Manager/2 without prior agreement with ADD Consulting. 
  2671.  
  2672.  You can contact ADD Consulting at the addresses below: 
  2673.  
  2674.           ADD Consulting (CH)
  2675.           Mr. Peter Kanis
  2676.           Via Suro 84
  2677.           7403 Rh╨öz╨æns
  2678.           Switzerland
  2679.  
  2680.           Tel: +41 (0)81 630 2011
  2681.           Fax: +41 (0)81 630 2015
  2682.           CompuServe: 100275,350 (Peter Kanis)
  2683.           INTERNET: kanis@ibm.net
  2684.  
  2685.           ADD Consulting (RUS)
  2686.           Mr. Michael Schelkin
  2687.           18-29 Molodezhnaya Street
  2688.           Jukovsky
  2689.           140160 Moscow Region
  2690.           Russia
  2691.  
  2692.           Tel: +7 095 556 8533
  2693.  
  2694.  
  2695. ΓòÉΓòÉΓòÉ 11. Rights And Limitations ΓòÉΓòÉΓòÉ
  2696.  
  2697. ADD Consulting makes no warranties as to the information in this guide. 
  2698. Additionally, ADD Consulting is not responsible or liable for any loss or 
  2699. damage of any kind resulting from use of this product. 
  2700.  
  2701. The Software is protected by international copyright laws.  All rights 
  2702. reserved.  No part of the Test Engine/2 computer program, documentation or 
  2703. related files may be reproduced photocopied, stored on a retrieval system, or 
  2704. transmitted except as provided by copyright law or by express permission of the 
  2705. copyright owner. 
  2706.  
  2707.  
  2708. ΓòÉΓòÉΓòÉ 12. Disclaimer ΓòÉΓòÉΓòÉ
  2709.  
  2710. DISCLAIMER - AGREEMENT 
  2711.  
  2712. Users of Test Engine/2 shall accept this disclaimer of warranty: 
  2713.  
  2714. ADD CONSULTING SUPPLIES THIS PRODUCT AS IS WITHOUT WARANTY OF ANY KIND, EITHER 
  2715. EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARANTIES OF 
  2716. MERCANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. ADD CONSULTING ASSUMES NO 
  2717. LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE 
  2718. OF THE PRODUCT. 
  2719.  
  2720. Some jurisdictions do not allow the exclusion or limitations for consequential 
  2721. or incidental damages, so the above may not apply to you.