home *** CD-ROM | disk | FTP | other *** search
-
- ΓòÉΓòÉΓòÉ 1. Introduction to Test Engine/2 API ΓòÉΓòÉΓòÉ
-
- Test Engine/2 is a programming tool designed for high level debugging and for
- function, module and integration testing.
-
- Judicious use of Test Tracing within an application allows you to locate
- functional and logical bugs quickly and efficiently. This allows you to reserve
- the time consuming use of a debugger for tracking down complex problems such as
- access violations, stack overflows, etc...
-
- The API interface for Test Engine/2 is composed of three parts :
-
- o Tracing Interface functions and Macros
- o Script file handling functions
- o REXX interface functions
-
- Tracing Functions and Macros
-
- These functions are designed to be coded into the application that is to be
- tested. They communicate directly with the Test Engine/2 program. It is
- recommended that the MACROS be used within an application as these resolve to
- null statements when the application is compiled without the TST_NGEN define.
- In this way it is easy to create separate "debugging" and "production"
- versions of an application without having to re-write any code.
-
- From the tracing API it is possible to register threads or processes with Test
- Engine/2, trace data, send comments, open and close trace files, stop and
- start trace mode and to start and stop global tracing.
-
- By using correct formatting of the traces in the Test Engine/2 program and by
- placing traces intelligently within an application, well documented test
- results can be produced that not only can be of great help in testing the
- correct functioning of an application but can also be used to produce
- documentation in accordance with ISO (International Organization for
- Standardisation) quality control standards (ISO series 9000).
-
- For more information on trace functions select one of the following items :
-
- o TstAppendOnOff
- o TstCloseTrace
- o TstDeRegister
- o TstDumpOnOff
- o TstDumpClose
- o TstInitProcess
- o TstOpenTrace
- o TstRegisterProcess
- o TstStopProcess
- o TstTraceOnOff
- o TstWriteString
- o TstWriteTrace
- o TST_CLOSE
- o TST_DUMP
- o TST_DCLOSE
- o TST_END
- o TST_INIT
- o TST_ONOFF
- o TST_OPEN
- o TST_REG
- o TST_STOP
- o TST_TRACE
-
- Script file handling functions
-
- These API functions are designed for writing Test Programs for testing sets of
- functions from libraries (either .DLL or .OBJ files) by reading test protocols
- from Script Files.
-
- For more information on script handling functions select one of the following
- items :
-
- o TstCloseScript
- o TstGetFunctionNum
- o TstInitTest
- o TstOpenScriptFile
- o TstReadScriptLine
- o TstRegisterFunction
-
- REXX interface functions
-
- These functions have the same purpose as the Tracing Functions but are
- designed for use in the REXX programming environment.
-
- For more information on REXX interface functions select one of the following
- items :
-
- o TstRxLoadFuncs
- o TstRxDropFuncs
- o TstRxInit
- o TstRxStop
- o TstRxTrace
- o TstRxOpenTrace
- o TstRxCloseTrace
-
-
- ΓòÉΓòÉΓòÉ 2. Test Tracing ΓòÉΓòÉΓòÉ
-
- Placing traces correctly in an application is crucial to making the best use of
- Test Engine/2. Depending on the test level different types of tracing are
- required. For path coverage and domain edge testing many traces are required
- that note each decision point in a function. However, at module testing and
- integration testing levels, these same traces would produce such a mass of
- output that the resulting files would be practically impossible to read.
-
- It is suggested, therefore, that programmers develop a set of macros using the
- Test Engine/2 API that are activated by different #define statements in a
- global header file or by editing tstngen.h, especially for the tracing
- functions.
-
- Examples
-
- #ifdef TEST_LEVEL1
- #define LEV1_TRACE( fmt, v1, v2, v3, v4) TstWriteTrace(fmt, v1, v2, v3, v4);
- #else
- #define LEV1_TRACE( fmt, v1, v2, v3, v4) ;
- #endif
-
- #ifdef TEST_LEVEL2
- #define LEV2_TRACE( fmt, v1, v2, v3, v4) TstWriteTrace(fmt, v1, v2, v3, v4);
- #else
- #define LEV2_TRACE( fmt, v1, v2, v3, v4) ;
- #endif
-
- NOTE : The number of variables in the above definitions can be changed (See
- TstWriteTrace).
-
- There are an almost infinite number of ways of setting up traces for tests, but
- it is a good idea to keep certain principles in mind :
-
- o Keep trace texts short and to the point (you have to read them
- afterwards!!).
-
- o Note the function name from which the trace came in the trace text.
-
- e.g. TstWriteTrace( "ModMyFunction: ERROR - ulMyVar out of range (%lu )", ulMyVar);
-
- o State the kind of trace in the trace text (ERROR, WARNING, NOTE, etc.).
-
- o Include the values of any data that may be relevant to the test in the
- trace string using the flags and a variable list.
-
- o For path testing insert traces at all decision points (case, if, else).
-
- o For domain testing dump all input parameters into a trace at the start
- of the function being tested.
-
-
- ΓòÉΓòÉΓòÉ 3. Test Programs ΓòÉΓòÉΓòÉ
-
- Test programs that use script files can be written using the Test Engine/2 API
- functions and macros.
-
- Test programs are generally used for path and domain testing, but you can
- develop test programs for many other types of test.
-
- These test programs can be written manually or generated using the code
- generator included in Quality Assurance Manager/2 and should follow the format
- of the template shown below.
-
- If you choose to write your own test programs you should take the following
- points into consideration:
-
- o Each function MUST be assigned a unique identification number which is
- then asiigned to the case statement
- o You must know how many arguments will be read from the script for each
- function
-
- Example of a Test program Template
-
-
- #define INCL_DOS
- #include <os2.h>
- #include <tstngen.h>
-
- /***********************************************************************/
- /* */
- /* Include Header files for object to be tested here */
- /* */
- /* This assumes that all function prototypes are declared in the */
- /* header file. */
- /* */
- /***********************************************************************/
-
-
- #include <myheader.h>
-
- void main(int argc, char *argv[])
-
- {
- USHORT res;
- USHORT ret_code;
- USHORT function;
- char teststr[128];
- TST_ARRAY_TYPE param;
- HSCRIPT hscript;
-
-
- /***** Initialize The test ******************************************/
-
- hscript = TstInitTest( argc, argv);
-
- /***** Check that the script was opened correctly *******************/
-
- if (hscript == (HSCRIPT)0)
- {
- DosBeep( 1000, 5000);
- DosExit(EXIT_PROCESS,1);
- }
-
- /***** Main loop for test program ***********************************/
-
- res = TstReadScriptLine( hscript, teststr);
- while (res == TST_OK)
- {
-
- /***** extract function N┬░ and parameters from line *************/
-
- function = TstGetFunctionNum( hscript, teststr);
-
- /***** Process for each function call ***************************/
-
- switch(function)
- {
-
- /***** invalid line in script *******************************/
-
- case TST_ERROR_INVALID_LINE : /* 11116 */
- TstWriteTrace("ERROR : Syntax error in script file.");
- break;
-
- /***** Process function 1 (ModMyFunction) *******************/
-
- case 1 :
- {
- ULONG ulvar1;
-
- /***** Extract the parameters (2 of them expected) ******/
-
- if ( TstRegisterFunction( hscript, 2, teststr, param))
- break;
-
- /***** Convert the 1st parameter to a numeric ***********/
-
- ulvar1 = atoi( param[0]);
-
- /***** Make a note in the trace *************************/
-
- TstWriteTrace("Calling ModMyFunction( %s , %s);",param[0], param[1]);
-
- /***** Call the function under test *********************/
-
- ret-code = ModMyFunction( ulvar1, param[1]);
-
- /***** Trace the result *********************************/
-
- TstWriteTrace("ModMyFunction: NOTE - returned %d",ret_code);
- }
- break;
-
- /***** The script line contained an unknown instruction *****/
-
- default :
- TstWriteTrace("ERROR : Invalid function N┬░ in script file.");
- break;
-
- } /* end of switch() */
-
- res = TstReadScriptLine( hscript, teststr);
-
- } /* end of while() */
-
- /***** Close the Script file ****************************************/
-
- TstCloseScript( hscript);
-
- /***** Close the trace file *****************************************/
-
- TstCloseTrace();
-
- /***** De-register the process with Test Engine/2 *******************/
-
- TstStopProcess();
-
- /***** Terminate the program ****************************************/
-
- DosExit( EXIT_PROCESS, 0);
- } /* end of main() */
-
-
- ΓòÉΓòÉΓòÉ 4. Script Files ΓòÉΓòÉΓòÉ
-
- For testing functions, Test Engine/2 supplies a Script file interface. This
- interface is designed to allow the test engineer to test functions in C/C++.
- The principle is based on reading a script file that contains the instructions
- about how a function is tested.
-
- The Script file is read by a program written in C/C++ that uses the script
- interface functions. A template C program and Script files can be generated
- from the definition of a Test stored in the database using the Quality
- Assurance Manager/2.
-
- A script file is a standard ASCII file that can be created with any code
- editor. Each line can contain one and only one of the following items
-
- o Comment
- o Test Engine/2 command
- o Function call definition
- o An empty line
-
- Comments
-
- Comments are preceded by ';' and can only occur on one line. Trailing comments
- or inserted comments are not supported.
-
- Example
-
- ; This is a single line comment
- ; and this is another
-
- Test Engine/2 Commands
-
- Test Engine/2 commands are preceded by ':' and only one command is supported
- on any line. The following commands are supported
-
- :REGNAME This MUST be the first statement in a script
- file. It takes one or two parameters. The first
- parameter is the name of the test that will
- appear in the monitor window and the second
- parameter is the startup language for Test
- Engine/2.
-
- :TRACEAPP Set the open mode for the trace file defined by
- :TRACETO or :TRACEAUTO to append.
-
- :TRACETO This command takes as a parameter the full path
- to a trace file where the output from the test
- will be stored. This command should not be
- present if :TRACEAUTO is included.
-
- :TRACEAUTO This command takes a parameter that is a mask
- for a trace file. The command will generate a
- file name from the mask by replacing any '?'
- characters with random numbers.
-
- :GLOBALTRACEON Switches global tracing on. If the global trace
- file has not been opened, it is created and the
- header is written into it.
-
- :GLOBALTRACEOFF Switches global tracing off but leaves the
- global trace file open.
-
- :GLOBALTRACECLOSE Closes the global trace file.
-
- :TRACEON Switches tracing to the local trace file defined
- by :TRACETO or :TRACEAUTO on.
-
- :TRACEOFF Switches tracing to the local trace file defined
- by :TRACETO or :TRACEAUTO off.
-
- :NOTRACESCRIPT Normally the lines from the script file are
- traced into the file defined by :TRACETO or
- :TRACEAUTO, this command switches the tracing
- off.
-
- :TRACESCRIPT Switch the tracing of lines from the script file
- on.
-
- Example.
-
- :REGNAME TSTTEST S
-
- This registers the process and/or function with Test Engine/2 with name
- "TSTTEST" and if Test Engine/2 is not started, starts it in Spanish.
-
- Function call definitions
-
- Any line that does not start with either ';' or ':' is treated as a function
- call definition.
-
- the format of a function call definition is
-
- func_num, <param 1>, <param 2>,...,<param n>
-
- func_num A unique number assigned to represent the function.
- param A parameter passed to the function, literal strings
- must be enclosed within double quotes.
-
- Example.
-
- ;2, 1, "Hello world", 23
-
- Script File Example
-
- :REGNAME TESTSCRIPT S
- :TRACETO C:\TSTNGEN\CODE\TRACE\TSTSPT.TRC
- ;***************************************************************
- ;
- ; Script for testing script commands
- ;
- ;***************************************************************
- 2, "Stop tracing the script file"
- :NOTRACESCRIPT
- 2, "Open the global trace file and start tracing"
- :GLOBALTRACEON
- 1, 2
- 1, 2
- 2, "Switch local trace off"
- :TRACEOFF
- 2, "This trace message should only go to the global trace"
- 2, "and so should this one"
- :TRACEON
- 2, "This message should go to both files"
- 1, 2
- 2, "Switch global tracing off"
- :GLOBALTRACEOFF
- 2, "Close the global trace file"
- :GLOBALTRACECLOSE
- 2, "Short delay..."
- 1, 2
- 2, "Script ends"
- ;***************************************************************
- ; END OF SCRIPT
- ;***************************************************************
-
- Where function 1 is a call to DosSleep and function 2 is a call to
- TstWriteTrace.
-
- The associated code file is shown below
-
- C Program File Example
-
- #define INCL_DOS
- #include <os2.h>
- #include <stdlib.h>
- #include <tstngen.h>
-
- void main(int argc, char *argv[])
-
- {
- USHORT res;
- USHORT ret_code;
- USHORT function;
- char teststr[128];
- TST_ARRAY_TYPE param;
- HSCRIPT hscript;
-
-
- /***** Initialize The test ******************************************/
-
- hscript = TstInitTest( argc, argv);
-
- /***** Check the initialisation was successful **********************/
-
- if (hscript == (HSCRIPT)0)
- {
- DosBeep( 1000, 5000);
- DosExit(EXIT_PROCESS,1);
- }
-
- /***** Main loop for test *******************************************/
-
- res = TstReadScriptLine( hscript, teststr);
- while (res == TST_OK)
- {
-
- /***** Trace input string ***************************************/
-
- TstWriteString( teststr);
-
- /***** Extract the function number and parameters ***************/
-
- function = TstGetFunctionNum( hscript, teststr);
-
- /***** Process for each function call ***************************/
-
- switch(function)
- {
- case TST_ERROR_INVALID_LINE :/* invalid line in script */
- TstWriteTrace("ERROR : Syntax error in script file.");
- break;
-
- /***** Function 1 = DosSleep ********************************/
-
- case 1 :
- {
- ULONG millisecs;
-
- if (TstRegisterFunction( hscript, 1, teststr, param))
- break;
-
- millisecs = atoi( param[ 0]) * 1000;
- TstWriteTrace("Delay function called for %s seconds", param[ 0]);
-
- DosSleep( millisecs);
- }
- break;
-
- /***** Function 2 = call TstWriteTrace **********************/
-
- case 2 :
- if (TstRegisterFunction( hscript, 1, teststr, param))
- break;
-
- TstWriteTrace("%s", param[ 0]);
-
- break;
-
- default :
- TstWriteTrace("ERROR : Invalid function N┬░ in script file.");
- break;
- }
-
- res = TstReadScriptLine( hscript, teststr);
- }
-
- /***** Clean up at end **********************************************/
-
- TstCloseScript( hscript);
- TstCloseTrace();
- TstStopProcess();
- DosExit( EXIT_PROCESS, 0);
- }
-
- This combination produces the following trace files
-
- ********************************************************************************
-
- C:\TSTNGEN\CODE\TRACE\TSTSPT.TRC 1994.10.10 (11.53.46.03)
-
- ********************************************************************************
-
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0004) ;***************************************************************
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0005) ;
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0006) ; Script for testing script commands
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0007) ;
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0008) ;***************************************************************
- TESTSCRIPT (523:1) [11.53.45.71] > TSTSPT1.SPT (0009) 2, "Stop tracing the script file"
- TESTSCRIPT (523:1) [11.53.45.71] > 2,Stop tracing the script file
- TESTSCRIPT (523:1) [11.53.45.71] > Stop tracing the script file
- TESTSCRIPT (523:1) [11.53.45.75] > TSTSPT1.SPT (0010) :NOTRACESCRIPT
- TESTSCRIPT (523:1) [11.53.45.75] > 1,2
- TESTSCRIPT (523:1) [11.53.45.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.47.75] > 1,2
- TESTSCRIPT (523:1) [11.53.47.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.49.75] > 2,Switch local trace off
- TESTSCRIPT (523:1) [11.53.49.75] > Switch local trace off
- TESTSCRIPT (523:1) [11.53.49.75] > 2,This message should go to both files
- TESTSCRIPT (523:1) [11.53.49.75] > This message should go to both files
- TESTSCRIPT (523:1) [11.53.49.75] > 1,2
- TESTSCRIPT (523:1) [11.53.49.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.51.75] > 2,Switch global tracing off
- TESTSCRIPT (523:1) [11.53.51.75] > Switch global tracing off
- TESTSCRIPT (523:1) [11.53.51.75] > 2,Close the global trace file
- TESTSCRIPT (523:1) [11.53.51.75] > Close the global trace file
- TESTSCRIPT (523:1) [11.53.51.75] > 2,Short delay...
- TESTSCRIPT (523:1) [11.53.51.75] > Short delay...
- TESTSCRIPT (523:1) [11.53.51.75] > 1,2
- TESTSCRIPT (523:1) [11.53.51.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.53.75] > 2,Script ends
- TESTSCRIPT (523:1) [11.53.53.75] > Script ends
- ************************************************************************
- Test Result o : Passed o : Failed
-
-
- ADD Consulting signature : ...........................
- ************************************************************************
-
- ********************************************************************************
-
- C:\TSTNGEN\GLOBAL.TRC 1994.10.10 (11.53.47.21)
-
- ********************************************************************************
-
- TESTSCRIPT (523:1) [11.53.47.75] > 1,2
- TESTSCRIPT (523:1) [11.53.47.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.49.75] > 2,Switch local trace off
- TESTSCRIPT (523:1) [11.53.49.75] > Switch local trace off
- TESTSCRIPT (523:1) [11.53.49.75] > 2,This trace message should only go to the global trace
- TESTSCRIPT (523:1) [11.53.49.75] > This trace message should only go to the global trace
- TESTSCRIPT (523:1) [11.53.49.75] > 2,and so should this one
- TESTSCRIPT (523:1) [11.53.49.75] > and so should this one
- TESTSCRIPT (523:1) [11.53.49.75] > 2,This message should go to both files
- TESTSCRIPT (523:1) [11.53.49.75] > This message should go to both files
- TESTSCRIPT (523:1) [11.53.49.75] > 1,2
- TESTSCRIPT (523:1) [11.53.49.75] > Delay function called for 2 seconds
- TESTSCRIPT (523:1) [11.53.51.75] > 2,Switch global tracing off
- TESTSCRIPT (523:1) [11.53.51.75] > Switch global tracing off
- ************************************************************************
- Test Result o : Passed o : Failed
-
-
- ADD Consulting signature : ...........................
- ************************************************************************
-
-
- ΓòÉΓòÉΓòÉ 5. Data Types ΓòÉΓòÉΓòÉ
-
- The following sections describe the data types exported by Test Engine/2. For a
- better idea of these please see the header file tstngen.h. The two exported
- types TST_ARRAY_TYPE and HSCRIPT are used for writing Test Programs.
-
-
- ΓòÉΓòÉΓòÉ 5.1. TST_ARRAY_TYPE ΓòÉΓòÉΓòÉ
-
- typedef PSZ TST_ARRAY_TYPE[ TST_PARAM_SIZE + 1];
-
- This data type is used to hold the parameters that will be passed to a function
- after they have been parsed from a line in the script file.
-
-
- ΓòÉΓòÉΓòÉ 5.2. HSCRIPT ΓòÉΓòÉΓòÉ
-
- typedef PVOID HSCRIPT;
-
- Used to identify a script file.
-
- When running a multi-thread test program with multiple Script Files, each
- script file should be assigned to a unique HSCRIPT variable.
-
-
- ΓòÉΓòÉΓòÉ 6. Test Engine/2 Functions ΓòÉΓòÉΓòÉ
-
- The following sections describe the interface function API for Test Engine/2.
-
-
- ΓòÉΓòÉΓòÉ 6.1. TstAppendOnOff ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstAppendOnOff( PSZ on_off);
-
- Parameters
-
- on_off One of the Test Engine/2 Macros TST_TRON or TST_TROFF.
-
- Description
-
- Sets the Trace file opening mode for the current thread or process. If the
- parameter is TST_TRON the trace file will be opened in append mode, if it is
- TST_TROFF it is overwritten.
-
- CAUTION:
- The append mode is overridden by the append parameter in TstOpenTrace.
-
-
- ΓòÉΓòÉΓòÉ 6.2. TstCloseScript ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstCloseScript( HSCRIPT hscript)
-
- Parameters
-
- hscript Handle to the script file that should be closed.
-
- Description
-
- Closes a script file for a test program. This function should be called for
- each script file that is opened by a test program.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- PSZ script_name = "d:\\addtools\\test.spt";
- HSCRIPT hscript;
- .
- .
- .
-
- /***** Open the script file *****************************************/
-
- hscript = TstOpenScriptFile( script_name);
-
- .
- . Body of thread function
- .
-
- TstCloseScript( hcript);
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstInitTest.
- o TstOpenScriptFile.
-
-
- ΓòÉΓòÉΓòÉ 6.3. TstCloseTrace ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstCloseTrace();
-
- Parameters
-
- None
-
- Description
-
- Sends a message to Test Engine/2 which then closes the trace file for the
- current thread (if in trace by thread mode) or for the current process (if in
- trace by process mode). When the file is closed the Footer is written to file
- prior to closing.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- PSZ trace_name = "d:\\addtools\\test.trc";
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- TstRegisterProcess( "TEST1");
-
- /***** Open a trace file in append mode *****************************/
-
- TstOpenTrace( trace_name, TRUE);
-
- .
- . Body of thread function
- .
-
- TstCloseTrace();
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstOpenTrace
- o TstTraceOnOff
- o TstAppendOnOff
-
-
- ΓòÉΓòÉΓòÉ 6.4. TstDeRegister ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstDeRegister();
-
- Parameters
-
- None
-
- Description
-
- De registers the current thread with Test Engine/2. This function should be
- called at the end of any thread function that registers the thread with Test
- Engine/2.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- TstRegisterProcess( "TEST1");
- .
- . Body of thread function
- .
-
- /***** Close Trace file and deregister ******************************/
-
- TstCloseTrace();
- TstDeRegister();
-
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstInitProcess
- o TstRegisterProcess
- o TstStopProcess
-
-
- ΓòÉΓòÉΓòÉ 6.5. TstDumpOnOff ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstDumpOnOff( PSZ on_off);
-
- Parameters
-
- on_off One of the Test Engine/2 Macros TST_TRON or TST_TROFF
-
- Description
-
- Sends a message to Test Engine/2 that causes the Global Trace functionality to
- be switched on (parameter = TST_TRON) or off (parameter = TST_TROFF).
-
- This function may be called from anywhere, even if the process or thread has
- not registered with Test Engine/2.
-
- CAUTION:
- The Global Trace File is not closed by this function. It can be closed from
- the Test Engine/2 program itself or by calling TstDumpClose.
-
- Related Functions
-
- o TstDumpClose
- o TstTraceOnOff
- o TstCloseTrace
-
-
- ΓòÉΓòÉΓòÉ 6.6. TstDumpClose ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstDumpClose( );
-
- Parameters
-
- None
-
- Description
-
- Sends a message to Test Engine/2 that causes the Global Trace file to be
- closed.
-
- This function may be called from anywhere, even if the process or thread has
- not registered with Test Engine/2.
-
- Related Functions
-
- o TstDumpOnOff
-
-
- ΓòÉΓòÉΓòÉ 6.7. TstGetFunctionNum ΓòÉΓòÉΓòÉ
-
- USHORT APIENTRY TstGetFunctionNum( HSCRIPT hscript, PSZ script_line);
-
- Parameters
-
- hscript Handle to a previously opened script file.
- script_line Null terminated string read from the same script file
- using TstReadScriptLine.
-
- Description
-
- This function extracts the function number (unique identifier for a function)
- from the line and converts it to a numeric which is returned. If the first
- element on the line is not a numeric character a value of
- TST_ERROR_INVALID_LINE is returned.
-
- The variable script_line is modified so that it points to the start of the
- parameter list.
-
- Example
-
- .
- .
- .
- res = TstReadScriptLine( hscript, teststr);
- while (res == TST_OK)
- {
-
- /***** extract function N┬░ from line ****************************/
-
- function = TstGetFunctionNum( hscript, teststr);
- .
- .
- } /* end of while */
- .
- .
-
- Related Functions
-
- o TstOpenScriptFile
- o TstInitTest
-
-
- ΓòÉΓòÉΓòÉ 6.8. TstInitProcess ΓòÉΓòÉΓòÉ
-
- BOOL APIENTRY TstInitProcess( PSZ proc_name, char lang_char);
-
- Parameters
-
- proc_name NULL terminated character string representing a unique
- name for the thread.
- lang_char Single character denoting the language Test Engine/2
- should start in.
-
- Description
-
- If Test Engine/2 is not active it is started in the specified language. The
- current process is then registered with the given name. lang_char can be any
- of the following characters:
-
- E | e English.
- F | f French.
- S | s Spanish.
- G | g German.
- I | i Italian.
-
- The function returns TRUE if the functions succeeds otherwise it returns
- FALSE.
-
- CAUTION:
- This function should only be called from the main thread (TID = 1) of a
- process.
-
- Example
-
- int main(int argc, char *argv[]);
- {
- .
- .
- .
-
- /***** start Test Engine/2 in Spanish *******************************/
-
- if ( !TstInitProcess( "PRUEBA", 'S'))
- {
- /* handle the error */
- }
- .
- .
- TstStopProcess();
- exit(0);
-
- } /* end of main() */
-
- Related Functions
-
- o TstRegisterProcess
- o TstDeRegister
- o TstStopProcess
-
-
- ΓòÉΓòÉΓòÉ 6.9. TstInitTest ΓòÉΓòÉΓòÉ
-
- HSCRIPT APIENTRY TstInitTest( int argc, char*[] argv);
-
- Parameters
-
- argc Number of arguments passed.
- argv Array of NULL terminated argument strings.
-
- Description
-
- This function should only be called from the main function of a test program.
- The arguments passed are usually the arguments passed to the program on the
- command line. The first argument (argv[1]) must be the name of the script file
- that should be read.
-
- The function will extract the program file name from the environment, open the
- script file and start to read it.
-
- The function returns a handle to the script file if it succeeds otherwise
- (HSCRIPT)0 is returned. You should always check for a valid script handle as
- this will be used to read lines from the script file.
-
- Example
-
-
- void main(int argc, char *argv[])
-
- {
- USHORT res;
- USHORT ret_code;
- USHORT function;
- char teststr[128];
- TST_ARRAY_TYPE param;
- HSCRIPT hscript;
-
-
- /***** Initialize The test ******************************************/
-
- hscript = TstInitTest( argc, argv);
-
- /***** Check the initialisation was successful **********************/
-
- if (hscript == (HSCRIPT)0)
- {
- /* Handle the error */
- DosExit( EXIT_PROCESS, code);
- }
-
- .
- .
- } /* end of main */
-
- Related Functions
-
- o TstOpenScriptFile
- o TstReadScriptLine
-
-
- ΓòÉΓòÉΓòÉ 6.10. TstOpenScriptFile ΓòÉΓòÉΓòÉ
-
- HSCRIPT APIENTRY TstOpenScriptFile( PSZ file_name);
-
- Parameters
-
- file_name NULL terminated string containing the fully qualified file
- name for the script file.
-
- Description
-
- This function opens the named script file and returns a handle to the script.
- If the file cannot be opened (HSCRIPT)0 is returned. You should always check
- the return value and handle any errors as the script handle is used to read
- the script.
-
- Example
-
-
- /***** Open the script file *****************************************/
-
- hscript = TstOpenScriptFile( file_name);
-
- /***** Check the initialisation was successful **********************/
-
- if (hscript == (HSCRIPT)0)
- {
-
- /* Handle the error */
-
- }
-
- .
- .
- } /* end of function */
-
- Related Functions
-
- o TstInitTest
- o TstReadScriptLine
-
-
- ΓòÉΓòÉΓòÉ 6.11. TstOpenTrace ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstOpenTrace( PSZ file_name, BOOL append);
-
- Parameters
-
- file_name Full path of the file to open for tracing.
- append If set to true the file file_name is opened for appending
- otherwise it is overwritten.
-
- Description
-
- The function sends a message to Test Engine/2 which causes Test Engine/2 to
- open file_name in the defined mode. All further messages from the thread (if
- in trace by thread mode) or process (if in trace by process mode) will be
- dumped into this file. When the file is opened, the Header is written into the
- file.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- PSZ trace_name = "d:\\addtools\\test.trc";
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- TstRegisterProcess( "TEST1");
-
- /***** Open a trace file in append mode *****************************/
-
- TstOpenTrace( trace_name, TRUE);
-
- .
- . Body of thread function
- .
-
- TstCloseTrace();
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstCloseTrace
- o TstAppendOnOff
- o TstTraceOnOff
-
-
- ΓòÉΓòÉΓòÉ 6.12. TstReadScriptLine ΓòÉΓòÉΓòÉ
-
- USHORT APIENTRY TstReadScriptLine( HSCRIPT hscript, PSZ line);
-
- Parameters
-
- hscript Handle to a previously opened script file.
- line Pointer to a buffer to contain the line read from the
- script file. This buffer MUST be previously allocated. The
- function DOES NOT ALLOCATE ANY MEMORY FOR THE STRING.
-
- Description
-
- This function reads lines from the script file until a function call
- definition is found and returns a pointer to the string containing the
- function call definition. Any commands found in the lines read from the script
- are executed and if script tracing is ON all the lines read are traced to Test
- Engine/2.
-
- The returned string is stripped of any white space.
-
- If the function reaches the end of the file TST_ERROR_EOF is returned. If
- there a system file error occurs TST_ERROR_FILE_READ is returned otherwise the
- function returns 0.
-
- Example
-
-
- res = TstReadScriptLine( hscript, teststr);
- while (res == TST_OK)
- {
-
- /***** extract function N┬░ and parameters from line *************/
-
- function = TstGetFunctionNum( hscript, teststr);
-
- /***** Process for each function call ***************************/
-
- switch(function)
- {
- .
- .
- .
- } /* end of switch() */
-
- res = TstReadScriptLine( hscript, teststr);
-
- } /* end of while() */
-
- Related Functions
-
- o TstOpenScriptFile
- o TstInitTest
-
-
- ΓòÉΓòÉΓòÉ 6.13. TstRegisterFunction ΓòÉΓòÉΓòÉ
-
- USHORT APIENTRY TstRegisterFunction( HSCRIPT hscript,
- USHORT num_params,
- PSZ script_line,
- TST_ARRAY_TYPE params);
-
- Parameters
-
- hscript Handle to script file from which the line was read.
- num_params The expected number of parameters that should be found in
- the script statement.
- script_line The string read from the script file.
- params Array of strings that will contain the parameters to be
- passed to the function.
-
- Description
-
- The function parses the line read from a script file and extracts the
- arguments which are placed into the array of string pointers. These parameters
- can then be converted if necessary and passed to the function under test.
-
- The function returns 0 if it succeeds otherwise TST_ERROR_PARAMS if the number
- of parameters found does not coincide with the expected number of parameters.
- If an error occurs there is a trace made to Test Engine/2.
-
- Note The function MUST be called after TstGetFunctionNum
-
- Example
-
-
- /***** Main loop for test program ***********************************/
-
- res = TstReadScriptLine( hscript, teststr);
- while (res == TST_OK)
- {
-
- /***** extract function N┬░ and parameters from line *************/
-
- function = TstGetFunctionNum( hscript, teststr);
-
- /***** Process for each function call ***************************/
-
- switch(function)
- {
-
- /***** invalid line in script *******************************/
-
- case TST_ERROR_INVALID_LINE : /* 11116 */
- TstWriteTrace("ERROR : Syntax error in script file.");
- break;
-
- /***** Process function 1 (ModMyFunction) *******************/
-
- case 1 :
- {
- ULONG ulvar1;
-
- /***** Extract the parameters (2 of them expected) ******/
-
- if ( TstRegisterFunction( hscript, 2, teststr, param))
- break;
- .
- .
- }
- break;
- .
- .
- } /* end of switch */
-
- } /* end of while */
-
- Related Functions
-
- o TstReadScriptLine
- o TstGetFunctionNum
-
-
- ΓòÉΓòÉΓòÉ 6.14. TstRegisterProcess ΓòÉΓòÉΓòÉ
-
- BOOL APIENTRY TstRegisterProcess( PSZ proc_name);
-
- Parameters
-
- proc_name NULL terminated character string representing a unique
- name for the thread in Test Engine/2
-
- Description
-
- Registers the current thread (if in trace by thread mode) or process (if in
- trace by process mode) with Test Engine/2 under the name proc_name
-
- The function returns TRUE if successful, else FALSE.
-
- CAUTION:
- The function will fail if Test Engine/2 is not active.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- if( !TstRegisterProcess( "TEST1"))
- DosBeep( 440, 1000);
- .
- . Body of thread function
- .
-
- /***** deregister the thread ****************************************/
-
- TstDeRegister();
-
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstInitProcess
- o TstDeRegister
- o TstStopProcess
-
-
- ΓòÉΓòÉΓòÉ 6.15. TstStopProcess ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstStopProcess();
-
- Parameters
-
- None
-
- Description
-
- De registers the current process and all threads from the current process with
- Test Engine/2.
-
- It is recomended that this call, or its Macro (TST_STOP) be placed in any exit
- function of a program that uses Test Engine/2.
-
- Related Functions
-
- o TstInitProcess
- o TstRegisterProcess
- o TstDeRegister
-
-
- ΓòÉΓòÉΓòÉ 6.16. TstTraceOnOff ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstTraceOnOff( PSZ on_off);
-
- Parameters
-
- on_off One of the Test Engine/2 Macros TST_TRON or TST_TROFF.
-
- Description
-
- Sends a message to Test Engine/2 that causes tracing for the current thread
- (if in trace by thread mode) or the current process (if in trace by process
- mode) to be switched on (parameter = TST_TRON) or off (parameter = TST_TROFF).
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- PSZ trace_name = "d:\\addtools\\test.trc";
- .
-
- /***** Register the thread etc. *************************************/
-
- TstRegisterProcess( "TEST1");
- TstOpenTrace( trace_name, FALSE);
- .
- .
-
- /***** Switch Tracing from this thread off **************************/
-
- TstTraceOnOff( TST_TROFF);
- .
- .
-
- /***** Switch tracing from this thread on again *********************/
-
- TstTraceOnOff( TST_TRON);
- .
- .
- _endthread;
-
- } /* end of function */
-
- Related Functions
-
- o TstOpenTrace
- o TstCloseTrace
- o TstAppendOnOff
-
-
- ΓòÉΓòÉΓòÉ 6.17. TstWriteString ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY TstWriteString( PSZ string);
-
- Parameters
-
- string Pointer to a NULL terminated string.
-
- Description
-
- Sends a message to Test Engine/2 consisting of the string, a time stamp and
- the id of the sending thread.
-
- Example
-
- VOID TestFunction()
- {
- PSZ file_name = "d:\\addtools\\test.txt";
- HFILE hfile = (HFILE)0;
-
- /***** Open a file to write some text *******************************/
-
- hfile = Reset( file_name);
-
- if( hfile != (HFILE)0)
- TstWriteString( "TestFunction : Opened the file successfully");
- else
- TstWriteString( "TestFunction : Failed to open the file");
-
- } /* end of function */
-
- Related Functions
-
- o None
-
-
- ΓòÉΓòÉΓòÉ 6.18. TstWriteTrace ΓòÉΓòÉΓòÉ
-
- VOID TstWriteTrace( PSZ format_str, ...);
-
- Parameters
-
- format_str Pointer to a NULL terminated character string containing
- text and formatting flags. The formatting flags are the
- same as those used for printf.
- ... Variable list conforming to the flags in format_str.
-
- Description
-
- The function treats the input parameters in the same way as printf or sprintf
- and then sends a message to Test Engine/2 consisting of the formatted string,
- a time stamp and the id of the sending thread.
-
- Example
-
- VOID TestFunction()
- {
- PSZ file_name = "d:\\addtools\\test.txt";
- HFILE hfile = (HFILE)0;
-
- /***** Open a file to write some text *******************************/
-
- hfile = Reset( file_name);
-
- if( hfile != (HFILE)0)
- TstWriteTrace( "TestFunction : Opened file '%s' returned handle %lu", file_name, hfile);
- else
- TstWriteTrace( "TestFunction : Failed to open file '%s'", file_name);
-
- } /* end of function */
-
- Related Functions
-
- o TstWriteString
- o TstOpenTrace
- o TstTraceOnOff
-
-
- ΓòÉΓòÉΓòÉ 7. Test Engine/2 Function Macros ΓòÉΓòÉΓòÉ
-
- The following sections describe each of the Macros from Test Engine/2. All the
- Macros for Test Engine/2 resolve to function calls when #define TST_NGEN is
- activated, otherwise they resolve to w NULL statement.
-
-
- ΓòÉΓòÉΓòÉ 7.1. TST_CLOSE ΓòÉΓòÉΓòÉ
-
- TST_CLOSE()
-
- Parameters
-
- None
-
- Description
-
- Closes the trace file for the curent thread or process. See TstCloseTrace.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- #ifdef TST_NGEN
- PSZ trace_name = "d:\\addtools\\test.trc";
- #endif
- .
- .
- .
-
- /***** Register the thread etc. *************************************/
-
- TST_REG( "TEST1")
- TST_OPEN( trace_name, FALSE)
- .
- .
- .
-
- TST_CLOSE()
- TST_END()
- _endthread;
-
- } /* end of function */
-
-
- ΓòÉΓòÉΓòÉ 7.2. TST_DUMP ΓòÉΓòÉΓòÉ
-
- TST_DUMP( PSZ on_off)
-
- Parameters
-
- on_off One of the Test Engine/2 Macros TST_TRON or TST_TROFF.
-
- Description
-
- Switches global tracing on or off in Test Engine/2. If TST_TRON is passed then
- tracing is switched on, if TST_TROFF is passed the tracing is switched off.
- See TstDumpOnOff.
-
- NOTE The global trace file is NOT CLOSED when tracing is set to OFF.
-
-
- ΓòÉΓòÉΓòÉ 7.3. TST_DCLOSE ΓòÉΓòÉΓòÉ
-
- TST_DCLOSE()
-
- Parameters
-
- None
-
- Description
-
- Closes the global trace file in Test Engine/2. See TstDumpClose
-
-
- ΓòÉΓòÉΓòÉ 7.4. TST_END ΓòÉΓòÉΓòÉ
-
- TST_END()
-
- Parameters
-
- None
-
- Description
-
- De registers the current thread. See TstDeRegister.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- #ifdef TST_NGEN
- PSZ trace_name = "d:\\addtools\\test.trc";
- #endif
- .
- .
- .
-
- /***** Register the thread etc. *************************************/
-
- TST_REG( "TEST1")
- TST_OPEN( trace_name, FALSE)
- .
- .
- .
-
- TST_CLOSE()
- TST_END()
- _endthread;
-
- } /* end of function */
-
-
- ΓòÉΓòÉΓòÉ 7.5. TST_INIT ΓòÉΓòÉΓòÉ
-
- TST_INIT( proc_name, lang_char)
-
- Parameters
-
- proc_name NULL terminated string representing a unique name for the
- thread.
- lang_char Single character denoting the language Test Engine/2
- should start in.
-
- Description
-
- If Test Engine/2 is not active, it is started in the language denoted by
- lang_char. The current thread is then registered with the name proc_name. See
- TstInitProcess. lang_char can be any of the following characters:
-
- E | e English
- F | f French.
- S | s Spanish.
- G | g German.
- I | i Italian.
-
- CAUTION:
- This function should only be called from the main thread (TID = 1) of a
- process.
-
- Example
-
- int main(int argc, char *argv[]);
- {
- .
- .
- .
-
- /***** Start Test Engine/2 in Spanish *******************************/
-
- TST_INIT( "PRUEBA", 'S');
- .
- .
- TST_STOP();
- exit(0);
-
- } /* end of main() */
-
-
- ΓòÉΓòÉΓòÉ 7.6. TST_ONOFF ΓòÉΓòÉΓòÉ
-
- TST_ONOFF( on_off)
-
- Parameters
-
- on_off One of the Test Engine/2 Macros TST_TRON or TST_TROFF.
-
- Description
-
- Switches tracing for the curent thread or process on or off. If TST_TRON is
- passed then tracing is switched on, if TST_TROFF is passed the tracing is
- switched off. See TstTraceOnOff.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- #ifdef TST_NGEN
- PSZ trace_name = "d:\\addtools\\test.trc";
- #endif
- .
- .
- .
-
- /***** Register the thread etc. *************************************/
-
- TST_REG( "TEST1")
- TST_OPEN( trace_name, TRUE)
- .
- .
-
- /***** switch tracing off for the thread ****************************/
-
- TST_ONOFF( TST_TROFF)
- .
- .
-
- /***** switch tracing on again **************************************/
-
- TST_ONOFF( TST_TRON)
- .
- .
-
- TST_CLOSE()
- TST_END()
- _endthread;
-
- } /* end of function */
-
-
- ΓòÉΓòÉΓòÉ 7.7. TST_OPEN ΓòÉΓòÉΓòÉ
-
- TST_OPEN( file_name, append)
-
- Parameters
-
- file_name NULL terminated string containing the full path name of
- the trace file to open.
- append If TRUE then the file is opened for appending else it is
- overwritten.
-
- Description
-
- Opens a named trace file through Test Engine/2 with the given mode. See
- TstOpenTrace.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- #ifdef TST_NGEN
- PSZ trace_name = "d:\\addtools\\test.trc";
- #endif
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- TST_REG( "TEST1")
-
- /***** Open a trace file in append mode *****************************/
-
- TST_OPEN( trace_name, TRUE)
-
- .
- . Body of thread function
- .
-
- TST_CLOSE()
- TST_END()
- _endthread;
-
- } /* end of function */
-
-
- ΓòÉΓòÉΓòÉ 7.8. TST_REG ΓòÉΓòÉΓòÉ
-
- TST_REG( proc_name)
-
- Parameters
-
- proc_name NULL terminated string containing a unique name for the
- thread.
-
- Description
-
- Registers the thread or process with Test Engine/2 under the specified name.
- See TstRegisterProcess.
-
- Example
-
- VOID ThreadFunction( PVOID pdata)
- {
- #ifdef TST_NGEN
- PSZ trace_name = "d:\\addtools\\test.trc";
- #endif
- .
- .
- .
-
- /***** Register the thread ******************************************/
-
- TST_REG( "TEST1")
-
- /***** Open a trace file in append mode *****************************/
-
- TST_OPEN( trace_name, TRUE)
-
- .
- . Body of thread function
- .
-
- TST_CLOSE()
- TST_END()
- _endthread;
-
- } /* end of function */
-
-
- ΓòÉΓòÉΓòÉ 7.9. TST_STOP ΓòÉΓòÉΓòÉ
-
- TST_STOP()
-
- Parameters
-
- None
-
- Description
-
- De registers all the threads from the current process. See TstStopProcess.
-
- Example
-
- int main(int argc, char *argv[]);
- {
- .
- .
- .
-
- /***** Start Test Engine/2 in German *******************************/
-
- TST_INIT( "DINGSBUMS", 'g');
- .
- .
- TST_STOP();
- exit(0);
-
- } /* end of main() */
-
-
- ΓòÉΓòÉΓòÉ 7.10. TST_TRACE ΓòÉΓòÉΓòÉ
-
- TST_TRACE( fmt_str, var1, var2, var3, var4)
-
- Parameters
-
- fmt_str NULL terminated format string.
- var1 .. var4 Any variable that can be flagged by a printf flag (%s,%lu
- etc..).
-
- Description
-
- Resolves to a call to TstWriteTrace with 4 parameters.
-
- CAUTION:
- Any unused parameters should be replaced by '0'.
-
- Example
-
- USHORT a,b;
- ULONG c;
- PSZ d;
- .
- .
- /***** Trace only 2 variables ***************************************/
-
- TST_TRACE( "The value of a is %u, the value of c is %lu", a, c, 0, 0);
-
- /***** trace all 4 vars *********************************************/
-
- TST_TRACE( "%s when a is %u, b is %u and c is %lu", d, a, b, c);
-
-
- ΓòÉΓòÉΓòÉ 8. Test Engine/2 REXX Functions ΓòÉΓòÉΓòÉ
-
- The following sections describe each of the REXX interface functions from Test
- Engine/2.
-
-
- ΓòÉΓòÉΓòÉ 8.1. TstRxLoadFuncs ΓòÉΓòÉΓòÉ
-
- TstRxLoadFuncs( );
-
- Parameters
-
- None
-
- Description
-
- Registers the Test Engine/2 DLL with the REXX environment and loads all the
- Test Engine/2 REXX functions.
-
- The function returns 0 if successful, else 1.
-
- CAUTION:
- This function should be called before any other Test Engine/2 REXX functions
-
- Example
-
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- Related Functions
-
- o TstRxDropFuncs
-
-
- ΓòÉΓòÉΓòÉ 8.2. TstRxDropFuncs ΓòÉΓòÉΓòÉ
-
- TstRxDropFuncs()
-
- Parameters
-
- None
-
- Description
-
- De registers the Test Engine/2 DLL with the REXX environment and unloads all
- the Test Engine/2 REXX functions.
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /* Body of rexx program */
-
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxLoadFuncs
-
-
- ΓòÉΓòÉΓòÉ 8.3. TstRxInit ΓòÉΓòÉΓòÉ
-
- TxtRxInit( reg_name, language)
-
- Parameters
-
- reg_name Name for the registering process or thread. This is the
- name that will appear on traces.
- language Single character denoting the language Test Engine/2
- should be started in.
-
- Description
-
- Registers the current thread or process with Test Engine/2. This is the REXX
- equivalent of TstInitProcess.
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- /***** Load the functions if necessary **********************************/
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /***** Register the process and start test engine in spanish ************/
-
- call TstInit 'MYPROG', 'S'
- .
- /* Body of rexx program */
- .
- call TstRxStop
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxStop
- o TstRxTrace
-
-
- ΓòÉΓòÉΓòÉ 8.4. TstRxStop ΓòÉΓòÉΓòÉ
-
- TstRxStop()
-
- Parameters
-
- None
-
- Description
-
- De registers the current thread or process with Test Engine/2. This is the
- REXX equivalent of TstStopProcess.
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- /***** Load the functions if necessary **********************************/
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /***** Register the process and start test engine in spanish ************/
-
- call TstInit 'MYPROG', 'S'
- .
- /* Body of rexx program */
- .
- call TstRxStop
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxInit
- o TstRxTrace
-
-
- ΓòÉΓòÉΓòÉ 8.5. TstRxTrace ΓòÉΓòÉΓòÉ
-
- TstRxTrace( trace_flag, trace_string)
-
- Parameters
-
- trace_flag Numeric variable used as a flag to switch the trace on or
- off. 0 = tracing OFF, 1 = tracing ON.
- trace_string String or values to be traced to Test Engine/2.
-
- Description
-
- Sends a trace message to Test Engine/2. This is the REXX equivalent of
- TstWriteString.
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- /***** Flag to turn tracing on or off ***********************************/
-
- tst = 1 /* tracing on */
-
- /***** Load the functions if necessary **********************************/
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /***** Register the process and start test engine in spanish ************/
-
- if tst then
- call TstInit 'MYPROG', 'S'
- .
- call TstRxTrace tst, 'The value from some operation =' var_name
- .
- if tst then
- call TstRxStop
-
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxOpenTrace
- o TstRxCloseTrace
-
-
- ΓòÉΓòÉΓòÉ 8.6. TstRxOpenTrace ΓòÉΓòÉΓòÉ
-
- TstRxOpenTrace( trace_name)
-
- Parameters
-
- trace_name Full file name of the trace file to open.
-
- Description
-
- Opens a trace file with Test Engine/2 for the current thread or process. This
- is the REXX equivalent of TstOpenTrace
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- /***** Flag to turn tracing on or off ***********************************/
-
- tst = 1 /* tracing on */
-
- /***** Load the functions if necessary **********************************/
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /***** Register the process and start test engine in spanish ************/
-
- if tst then
- call TstInit 'MYPROG', 'S'
-
- /***** Open the trace file **********************************************/
-
- if tst then
- call TstRxOpenTrace 'c:\mypath\mytrace.trc'
- .
- call TstRxTrace tst, 'The value from some operation =' var_name
- .
- if tst then do
- call TxtRxCloseTrace
- call TstRxStop
- end
-
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxTrace
- o TstRxInit
-
-
- ΓòÉΓòÉΓòÉ 8.7. TstRxCloseTrace ΓòÉΓòÉΓòÉ
-
- TstRxCloseTrace( )
-
- Parameters
-
- None
-
- Description
-
- Closes the trace file for the current thread or process. This is the REXX
- equivalent of TstCloseTrace
-
- The function returns 0 if successful, else 1.
-
- Example
-
-
- /***** Flag to turn tracing on or off ***********************************/
-
- tst = 1 /* tracing on */
-
- /***** Load the functions if necessary **********************************/
-
- if RxFuncQuery( 'TstRxLoadFuncs') = 0 then do
- call RxFuncAdd 'TstRxLoadFuncs', 'ADD_TST', 'TstRxLoadFuncs'
- call TstRxLoadFuncs
- end
-
- /***** Register the process and start test engine in spanish ************/
-
- if tst then
- call TstInit 'MYPROG', 'S'
-
- /***** Open the trace file **********************************************/
-
- if tst then
- call TstRxOpenTrace 'c:\mypath\mytrace.trc'
- .
- call TstRxTrace tst, 'The value from some operation =' var_name
- .
- if tst then do
- call TxtRxCloseTrace
- call TstRxStop
- end
-
- call TstRxDropFuncs
-
- exit
-
- Related Functions
-
- o TstRxTrace
- o TstRxInit
-
-
- ΓòÉΓòÉΓòÉ 9. Tools and Utility functions ΓòÉΓòÉΓòÉ
-
- Test Engine/2 is delivered with 3 utility DLLs that can be freely integrated
- into your software products.
-
- o FILES.DLL
-
- o CALC.DLL
-
- o PRTREXX.DLL
-
- The FILES.DLL supplies PASCAL type functions for manipulating text files, a
- File Dialog that sets the current path and drive when you select a file, a
- printer selection dialog which shows all attached printers and simple RAW mode
- text printing functions.
-
- The PRTREXX.DLL supplies a REXX interface to simple RAW mode text printing
- functions.
-
- The CALC.DLL supplies a simple maths integer calculation function which is
- used by IPFPC.EXE.
-
- Two utility programs are also supplied :
-
- o IPFPC.EXE
-
- o XDEL.EXE
-
- IPFPC is a pre-compiler originally written for pre-compiling Information
- Presentation text files where the res= statements contain constants from
- header files. This program can also be used to pre-compile script files that
- are written with constants from header files. This file and the on-line help
- for Test Engine/2 and Quality Assurance Manager/2 were pre-compiled using
- IPFPC.
-
- XDEL.EXE is a simple and VERY brutal utility for destroying directory trees.
- To see the supported parameters run xdel from the command line with no
- parameters.
-
-
- ΓòÉΓòÉΓòÉ 9.1. FileDllInit ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileDllInit( );
-
- Parameters
-
- None
-
- Description
-
- This call should be made before you use any of the file access functions or
- printing functions. It initialises per process data and loads the resources
- for the two dialog functions in the DLL.
-
-
- ΓòÉΓòÉΓòÉ 9.2. FileDllRelease ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileDllRelease( );
-
- Parameters
-
- None
-
- Description
-
- This function should be called before terminating a program.
-
-
- ΓòÉΓòÉΓòÉ 9.3. FileSetWriteThru ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileSetWriteThru( BOOL on);
-
- Parameters
-
- on Boolean variable or literal. If TRUE file write mode is
- set to Write Through for the process.
-
- Description
-
- Sets the file write mode to Write Through or to use buffering. Test Engine/2
- uses Write Through mode to ensure that all data is written to the trace files
- if a program crashes the system.
-
-
- ΓòÉΓòÉΓòÉ 9.4. FileRewrite ΓòÉΓòÉΓòÉ
-
- HFILE APIENTRY FileRewrite( PSZ file_name);
-
- Parameters
-
- file_name Null terminated string representing the name of the file
- to open for writing.
-
- Description
-
- Opens the named text file for writing. If the file exists any data in it is
- destroyed. The file pointer is set to 0.
-
- The function returns a valid handle if successful, else (HFILE)0.
-
-
- ΓòÉΓòÉΓòÉ 9.5. FileAppend ΓòÉΓòÉΓòÉ
-
- HFILE APIENTRY FileAppend( PSZ file_name);
-
- Parameters
-
- file_name Null terminated string representing the name of a file to
- open for writing.
-
- Description
-
- Opens the named text file for writing. If the file exists the file pointer is
- set to the end of the file.
-
- The function returns a valid handle if successful, else (HFILE)0.
-
-
- ΓòÉΓòÉΓòÉ 9.6. FileReset ΓòÉΓòÉΓòÉ
-
- HFILE APIENTRY FileReset( PSZ file_name);
-
- Parameters
-
- file_name Null terminated string representing the name of a file to
- open for reading.
-
- Description
-
- Opens the named text file for reading. If the file exists the file pointer is
- set to the beginning of the file.
-
- The function returns a valid handle if successful, else (HFILE)0.
-
-
- ΓòÉΓòÉΓòÉ 9.7. FileWriteLn ΓòÉΓòÉΓòÉ
-
- APIRET APIENTRY FileWriteLn( HFILE hfile, PSZ string);
-
- Parameters
-
- hfile Handle to the text file to write to. The file must be
- open.
- string NULL terminated string to write to the file.
-
- Description
-
- Writes the given text to the file and appends and End-Of_Line. The return is 0
- if successful otherwise either FILE_BLK_SIZE_ERR if the string was not written
- completely or a DOS error.
-
-
- ΓòÉΓòÉΓòÉ 9.8. FileReadLn ΓòÉΓòÉΓòÉ
-
- APIRET APIENTRY FileReadLn( HFILE hfile, PSZ string);
-
- Parameters
-
- hfile Handle to the text file to read from. The file must be
- open.
- string NULL terminated string read from the file. This variable
- MUST be pre-allocated.
-
- Description
-
- Reads a line of text from the given file into the variable string. The return
- is 0 if successful otherwise either FILE_BLK_SIZE_ERR if the string was not
- read completely or a DOS error.
-
-
- ΓòÉΓòÉΓòÉ 9.9. FileDlg ΓòÉΓòÉΓòÉ
-
- USHORT APIENTRY FileDlg( HWND hWndOwner,
- PSZ title,
- PSZ dir,
- PSZ file_mask,
- BOOL exists,
- PSZ file_name);
-
- Parameters
-
- hWndOwner Handle to the parent window.
- title NULL terminated string representing the title that will
- appear in the dialog.
- dir Directory where to look for the file. If this string is
- NULL the current directory will be searched.
- file_mask NULL terminated string representing the file mask to
- search for, e.g. "*.exe".
- exists Boolean flag, if TRUE then the file must exist, if FALSE
- the user may enter a new name.
- file_name NULL terminated string that will contain the fully
- qualified path of the selected file.
-
- Description
-
- This function forms a shell to the standard File Dialog. When a file is
- selected, the current path and drive are set to those of the file, allowing
- further file selections to search on the same path and drive.
-
-
- ΓòÉΓòÉΓòÉ 9.10. FileGetFullPath ΓòÉΓòÉΓòÉ
-
- BOOL APIENTRY FileGetFullPath( PSZ rel_path, PSZ full_path);
-
- Parameters
-
- rel_path NULL terminated string representing the relative path from
- which to obtain a fully qualified file name.
- full_path NULL terminated string that will contain the fully
- qualified path name. This variable MUST be pre-allocated.
-
- Description
-
- Coverts a relative path to a fully qualified path containing the drive.
-
- Example
-
- ..\mypath\myfile.exe would be converted to C:\dir1\mypath\myfile.exe if the
- current directory were C:\dir1\dir2.
-
-
- ΓòÉΓòÉΓòÉ 9.11. FileSetDefaultExtension ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileSetDefaultExtension( PSZ file_name, PSZ extension);
-
- Parameters
-
- file_name NULL terminated string representing the name of a file
- with an unknown extension. This variable is returned
- modified if there is no extension present.
- extension NULL terminated string representing the default extension
- to be added to the file name if none exists.
-
- Description
-
- Adds a default extension to a file name.
-
-
- ΓòÉΓòÉΓòÉ 9.12. FileForceDefaultExtension ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileForceDefaultExtension( PSZ file_name, PSZ extension);
-
- Parameters
-
- file_name NULL terminated string representing the name of a file
- with an unknown extension. This variable is returned
- modified.
- extension NULL terminated string representing the extension to be
- added to the file name.
-
- Description
-
- Forces a new extension onto a file name.
-
-
- ΓòÉΓòÉΓòÉ 9.13. FileJustFileName ΓòÉΓòÉΓòÉ
-
- PSZ APIENTRY FileJustFileName( PSZ file_name);
-
- Parameters
-
- file_name NULL terminated string representing the name of a file.
-
- Description
-
- Returns a pointer to the file name part of a qualified or relative path.
-
- Example
-
- An input of C:\dir1\mypath\myfile.exe will return myfile.exe.
-
-
- ΓòÉΓòÉΓòÉ 9.14. FileParsePath ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY FileParsePath( PSZ path_str,
- PULONG pdrv_num,
- PSZ pdrv_char,
- PSZ directory
- PSZ file_name)
-
- Parameters
-
- path_str NULL terminated string representing the path to a file.
- pdrv_num Pointer to an unsigned long that will contain the drive
- number on returning.
- pdrv_char Pointer to a character variable that will contain the
- drive letter on returning.
- directory NULL terminated string that will contain the path part of
- the input. This variable MUST be pre-allocated.
- file_name NULL terminated string representing the name of the file.
-
- Description
-
- Parses an input path into the drive, path and file name.
-
- Example
-
- An input of C:\dir1\mypath\myfile.exe will return
-
- o *pdrv_num = 3
-
- o *pdrv_char = 'C'
-
- o drectory = "dir1\mypath"
-
- o file_name = "myfile.exe"
-
-
- ΓòÉΓòÉΓòÉ 9.15. FileUniqueName ΓòÉΓòÉΓòÉ
-
- PSZ APIENTRY FileUniqueName( PSZ file_mask);
-
- Parameters
-
- file_name NULL terminated string representing a file mask containing
- ? characters.
-
- Description
-
- Returns a pointer to a unique file name where any ocurrences of "?" are
- replaced with random numbers. The function checks that the name is really
- unique.
-
- Example
-
- An input of C:\dir1\mypath\myfil?.??? could return C:\dir1\mypath\myfil1.384.
-
-
- ΓòÉΓòÉΓòÉ 9.16. PrtSelectPrinter ΓòÉΓòÉΓòÉ
-
- PPRTDESC APIENTRY PrtSelectPrinter( HAB hab, HWND hWndOwner)
-
- Parameters
-
- hab Handle to the anchor block of the calling process or
- thread.
- hWndOwner Handle to the owner window (from the calling process).
-
- Description
-
- Calls the Select Printer Dialog and returns a PPRTDESC which can be used to
- open a print job on that printer.
-
-
- ΓòÉΓòÉΓòÉ 9.17. PrtOpenPrintJob ΓòÉΓòÉΓòÉ
-
- USHORT APIENTRY PrtOpenPrintJob( PPRTDESC printer,
- PSZ job_title,
- HPRINT *hjob)
-
- Parameters
-
- printer PPRTDESC variable previously obtained from a call to
- PrtSelectPrinter.
- job_title NULL terminated string containing the name of the print
- job as it will appear in the spooler queue.
- hjob HPRINT variable that will receive a handle to the print
- job which can be used to write to the job and close it.
-
- Description
-
- Opens a print job on the current printer with the given title. Returns 0 if
- successful otherwise PRT_ERROR_OPEN_SPOOL.
-
-
- ΓòÉΓòÉΓòÉ 9.18. PrtWriteLn ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY PrtWriteLn( HPRINT hjob, PSZ string)
-
- Parameters
-
- hjob Handle to the print job obtained from a call to
- PrtopenPrintJob.
- string NULL terminated string to written to the document.
-
- Description
-
- Writes the given string to the document with an appended Carriage return Line
- feed.
-
-
- ΓòÉΓòÉΓòÉ 9.19. PrtClosePrintJob ΓòÉΓòÉΓòÉ
-
- VOID APIENTRY PrtClosePrintJob( HPRINT hjob)
-
- Parameters
-
- hjob Handle to the print job obtained from a call to
- PrtopenPrintJob.
-
- Description
-
- Closes the print job represented by the handle.
-
-
- ΓòÉΓòÉΓòÉ 9.20. PrtRxLoadFuncs ΓòÉΓòÉΓòÉ
-
- PrtRxLoadFuncs( )
-
- Parameters
-
- None
-
- Description
-
- Loads the PRTREXX DLL and loads all the functions.
-
-
- ΓòÉΓòÉΓòÉ 9.21. PrtRxOpenPrintJob ΓòÉΓòÉΓòÉ
-
- print_job = PrtRxOpenPrintJob( queue, driver, job_title)
-
- Parameters
-
- queue Name of the print queue.
- driver Name of the printer driver.
- job_title String containing the name of the print job as it will
- appear in the spooler queue.
-
- Description
-
- Opens a print job on the current printer with the given title. Returns Numeric
- variable that identifies the print job that should be used to write to and
- close the print job. If the return is 0 then an error occured opening the
- print job.
-
-
- ΓòÉΓòÉΓòÉ 9.22. PrtRxWriteln ΓòÉΓòÉΓòÉ
-
- PrtWriteLn( print_job, string)
-
- Parameters
-
- print_job Handle to the print job obtained from a call to
- PrtRxOpenPrintJob.
- string String to written to the document.
-
- Description
-
- Writes the given string to the document with an appended Carriage return Line
- feed.
-
-
- ΓòÉΓòÉΓòÉ 9.23. PrtRxClosePrintJob ΓòÉΓòÉΓòÉ
-
- PrtRxClosePrintJob( print_job)
-
- Parameters
-
- print_job Handle to the print job obtained from a call to
- PrtRxOpenPrintJob.
-
- Description
-
- Closes the print job represented by the handle.
-
-
- ΓòÉΓòÉΓòÉ 9.24. RxWinAlarm ΓòÉΓòÉΓòÉ
-
- RxWinAlarm( alarm_tone)
-
- Parameters
-
- alarm_tone Number denoting the kind of alarm to create:
- 1 = WA_NOTE
- 2 = WA_WARNING
- 3 = WA_ERROR.
-
- Description
-
- Makes a call to WinAlarm() with the given tone. This permits a REXX program to
- create error tones that will interface atomatically to the OS/2 multi-media if
- present.
-
-
- ΓòÉΓòÉΓòÉ 9.25. PrtRxDropFuncs ΓòÉΓòÉΓòÉ
-
- PrtRxDropFuncs( )
-
- Parameters
-
- None
-
- Description
-
- Releases the PRTREXX DLL from REXX environment.
-
-
- ΓòÉΓòÉΓòÉ 9.26. IPFPC ΓòÉΓòÉΓòÉ
-
- IPFPC is an IPF pre-compiler. It allows you to insert constants from a program
- header file into an IPF text file for resolving Cross references, setting res
- values etc..
-
- The relevant header files are declared at the start of the document by
- inserting:
-
- #include <myheader.h>
-
- or
-
- #include "myheader.h"
-
- The header files are recursed, and #ifdef, #elseif and #endif statements are
- taken into consideration.
-
- You may include header files that perform integer maths on constants or literal
- numbers; these calculations will be resolved by IPFPC.
-
- Example
-
-
- in header file
-
- #define OTHER_CONST 8
- #define SOME_CONST 7
- #define MY_CONST (OTHER_CONST /4) * SOME_CONST
-
- MY_CONST will be resolved to 14 after pre-compilation.
-
- Command Line or Make File Syntax
-
- IPFPC [switches] <Input Text File> [Output Text File]
-
- Switches : NOTE: Switches are not case sensitive
-
- -I Γûî /I Include path, may follow IBM or Borland format. The
- INCLUDE environment variable is also searched.
- Examples
- -ID:\TOOLKT21\OS2H (IBM format)
- -ID:\TOOLKT21\OS2INC;C:\BCOS2\INC; (Borland format)
- -O Γûî /O Output directory : MUST NOT HAVE TRAILING \.
- -H Γûî /H Shows a help screen.
-
- Example
-
- IPFPC -Id:\myincdir;c:\tools\incdir; -oobj test.htx test.ipf
-
- Input file default extension .HTX.
- Output file default extension .IPF. If no output file is specified the input
- file name is used with the extension changed to .IPF.
-
-
- ΓòÉΓòÉΓòÉ 10. Runtime DLLs and licence information ΓòÉΓòÉΓòÉ
-
- To integrate Test Engine/2 into your software products you must integrate the
- following DLLs into your package:
-
- o ADD_TST.DLL
- o FILES.DLL
-
- These DLLs and the other tools DLLs and programs supplied with Test Engine/2
- are free of any restrictions and can be redistributed as you wish with no
- license fees.
-
- The following programs and Dynamic Link Libraries can be redistributed freely:
-
- o ADD_TST.DLL
- o FILES.DLL
- o PRTREXX.DLL
- o CALC.DLL
- o IPFPC.EXE
- o XDEL.EXE
-
- LICENSE RESTRICTION
-
- Test Engine/2 and Quality Assurance Manager/2 are the property of ADD
- Consulting and are protected by international copyright law.
-
- You may NOT in any way redistribute either Test Engine/2 or Quality Assurance
- Manager/2 without prior agreement with ADD Consulting.
-
- You can contact ADD Consulting at the addresses below:
-
- ADD Consulting (CH)
- Mr. Peter Kanis
- Via Suro 84
- 7403 RhДzБns
- Switzerland
-
- Tel: +41 (0)81 630 2011
- Fax: +41 (0)81 630 2015
- CompuServe: 100275,350 (Peter Kanis)
- INTERNET: kanis@ibm.net
-
- ADD Consulting (RUS)
- Mr. Michael Schelkin
- 18-29 Molodezhnaya Street
- Jukovsky
- 140160 Moscow Region
- Russia
-
- Tel: +7 095 556 8533
-
-
- ΓòÉΓòÉΓòÉ 11. Rights And Limitations ΓòÉΓòÉΓòÉ
-
- ADD Consulting makes no warranties as to the information in this guide.
- Additionally, ADD Consulting is not responsible or liable for any loss or
- damage of any kind resulting from use of this product.
-
- The Software is protected by international copyright laws. All rights
- reserved. No part of the Test Engine/2 computer program, documentation or
- related files may be reproduced photocopied, stored on a retrieval system, or
- transmitted except as provided by copyright law or by express permission of the
- copyright owner.
-
-
- ΓòÉΓòÉΓòÉ 12. Disclaimer ΓòÉΓòÉΓòÉ
-
- DISCLAIMER - AGREEMENT
-
- Users of Test Engine/2 shall accept this disclaimer of warranty:
-
- ADD CONSULTING SUPPLIES THIS PRODUCT AS IS WITHOUT WARANTY OF ANY KIND, EITHER
- EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARANTIES OF
- MERCANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. ADD CONSULTING ASSUMES NO
- LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE
- OF THE PRODUCT.
-
- Some jurisdictions do not allow the exclusion or limitations for consequential
- or incidental damages, so the above may not apply to you.