═══ 1. Introduction ═══ 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.. Test Engine/2 is delivered as a multi-lingual product and can be started in any of installed languages. The language can also be dynamically changed on-line. The following languages are initially supplied : o English o French o German lm margin=1. The default start-up language can be set using the Options Notebook, from the command line by using the language parameter (see Startup Parameters)or from a program that starts Test Engine/2 through the C/C++ or REXX interface. The programming interface for Test Engine/2 is described in the Test Engine/2 Programming Guide INF. file. The function and MACRO API for Test Engine/2 are included in TSTNGEN.NDX which makes them available to the on-line help for editors such as epm, Source Link etc. that support on-line help using VIEW.EXE. ═══ 2. Test Tracing ═══ Tracing of messages is configurable from both the Test Engine/2 program interface and through the API. There are several possible modes of operation for test tracing. 1. Each thread of a process can be registered independently with Test Engine/2 with a unique name that is meaningful to the programmer and can have its own trace file. 2. Each thread of a process can be registered independently with Test Engine/2 with a unique name that is meaningful to the programmer and a trace file can be opened for the process. 3. Traces can be sent using the API functions and/or Macros without registering any threads. In this case the destination of the traces is determined from within Test Engine/2 by setting the default trace file and enabling the Global trace on/off menu item. 4. A mix of the above tracing modes may be used, some threads being registered with trace files, others registered with no file and some that are not registered at all. You can define the header that is inserted into the trace file at the beginning of a test run and the footer added to the end of a trace file using the Header and Footer entries in the Options Notebook. You can also define the format of a message, time and date strings using the Options Notebook. See Formatting Flags for a detailed description of formatting flags available for the message string, headers and footers. ═══ 3. Formatting Flags ═══ Special formatting flags, consisting of "$" followed by a Capital letter, are supplied for creating message format, header and footer templates. These templates can include any other literal characters or symbols. The following flags are available for defining the message format : o $N : prints the registered name of the thread or process. o $P : prints the process id of the process that sent the trace o $T : prints the process related thread id of the thread that sent the message, the main thread of a process always has id = 1. o $D : prints the date the message was sent in the format defined in the Options Notebook. o $I : prints the time the message was sent in the format defined in the Options Notebook. o $M : prints the actual message that was sent. Message Format Example $N ($P:$T) [$D $I] > $M This might give the following output. TESTPROC (261:2) [93.11.22 11:12:34:45] > The return from TstFunction was 23 The following flags are available for writing headers and footers : o $D : prints the date the message was sent in the format defined in the Options Notebook. o $I : prints the time the message was sent in the format defined in the Options Notebook. o $F : prints the full path name of the trace file. Header Example ********************************************************************** $F $D ($I) ADD Consulting ********************************************************************* giving an output ********************************************************************** D:\TESTPROJ\TESTTRACE\TEST.TRC 1993.11.22 (12:22:12:97) ADD Consulting ********************************************************************** ═══ 4. File Menu ═══ The file menu his used to control output from the Test Engine/2 window to files and printers, to trace incoming messages and to exit the program. For more information see one of the following topics : o Global trace on/off o Close global trace o Clear View o Save View o Print View o Choose Printer o Exit ═══ 4.1. Global trace on/off ═══ Hot Key Toggles the tracing of messages sent to Test Engine/2 into the global trace file. The first time this menu item is selected the trace file is opened in the Open files for append mode as defined in the Options Notebook. When tracing is active the menu item is marked and the name of the trace file appears in the title bar. To close the trace file use the menu item Close global trace The messages which are traced depend on the trace options set in the Options Notebook. Either all incoming messages are traced or only messages from unknown (un-registered) sources are traced. ═══ 4.2. Close global trace ═══ Hot Key Closes the global trace file and switches global tracing off. If no global trace file has been opened this action has no effect. ═══ 4.3. Clear View ═══ Hot Key Clears the monitor window of all visible trace messages. This action does not affect the tracing to either the global or local trace files. Note: a Save View action immediately following a clear view action will create an empty file containing only the header and footer as defined in the Options Notebook. ═══ 4.4. Save View ═══ Hot Key Saves the contents of the monitor buffer (up to 300 messages) to a file. You will be shown the standard file dialog where you can select a file to dump the contents of the Test Engine/2 monitor window. ═══ 4.5. Print View ═══ Hot Key Prints the contents of the monitor buffer (up to 300 messages) to the printer chosen with the Choose Printer dialog. If no printer has been chosen the Choose Printer dialog is popped up so that you can choose a printer. Note: All printing from Test Engine/2 is in PM_RAW mode. ═══ 4.6. Choose Printer ═══ Hot Key Displays the Choose Printer Dialog where you can select a printer from a list of all the printers currently available to your work-station. All subsequent print operations will then be sent to the chosen device. All the printers connected to you work-station including network devices can be selected from this dialog. The Choose Printer Dialog is described in the Test Engine/2 Programming reference as it forms part of the tools delivered with the Test Engine/2 package. ═══ 4.7. Exit ═══ Hot Key Displays the Exit Dialog so that you can quit Test Engine/2. WARNING: this action injects a message into the Test Engine/2 queue and there may be a delay while Test Engine/2 reads any outstanding messages from it's queue before the program actually terminates. DO NOT KILL Test Engine/2 until all activity has ceased. ═══ 5. Edit Menu ═══ Under this menu you can interactively edit the contents of the header file, footer file or any trace file of your choice. The editor that is called is defined in the Options Notebook. For more information, see one of the following topics : o Edit header o Edit footer o Edit trace file o Print trace file o Edit global trace file o Print global trace file ═══ 5.1. Edit header ═══ Calls the default editor to edit the header file defined in the Options Notebook. The header file is a block of text that is inserted into all trace files when they are opened and can contain Formatting Flags. If the file is opened in append mode, a Form Feed character is inserted preceding the header block. ═══ 5.2. Edit footer ═══ Calls the default editor to edit the footer file defined in the Options Notebook. The footer file is a block of text that is appended to all trace files when they are closed and can contain Formatting Flags. ═══ 5.3. Edit trace file ═══ Displays the standard file dialog to choose a file (usually a trace) and then calls the default editor to view or modify the file (see Options Notebook). ═══ 5.4. Print trace file ═══ Displays the standard file dialog to choose a file (usually a trace) that can then be printed on the default printer (see Choose Printer). If no printer has been defined then the Choose Printer Dialog is presented before the file dialog. If you do not choose a printer from this dialog then no file can be chosen for printing. ═══ 5.5. Edit global trace file ═══ Calls the default editor with the global trace file. see the Options Notebook ═══ 5.6. Print global trace file ═══ Prints the global trace file. If no printer has been defined then the Choose Printer Dialog is opened before calling the print function. If you do not choose a printer the global trace file is not printed. ═══ 6. Options Menu ═══ Under this menu you can change the settings and save them to the program profile. For more information see one of the following topics : o Default settings o Save Settings ═══ 6.1. Default settings ═══ Hot Key Displays the Options Notebook where all default settings for Test Engine/2 can be changed or viewed. ═══ 6.2. Save Settings ═══ Hot Key Saves all the settings from the Options Notebook in the profile TSTNGEN.INI ═══ 7. Actions Menu ═══ Under this menu you can manipulate child sessions and registered processes and threads that are tracing to Test Engine/2. For more detailed help see one of the following topics : o Processes and threads o Start sessions o Manage sessions ═══ 7.1. Processes and threads ═══ Hot Key Displays the Processes and Threads Dialog where you can control the processes and threads that are registered with Test Engine/2. You can open, close and change trace files for each registered thread or process, change the tracing mode (append), start or stop tracing of messages to the Test Engine/2 monitor window and kill any registered process. ═══ 7.2. Start sessions ═══ Displays the Start Sessions Dialog where you can start child sessions from Test Engine/2. These child sessions can be controlled using the Manage Sessions Dialog. Any programs that are started from Test Engine/2 using this dialog will be terminated by the Operating system when Test Engine/2 terminates. Child sessions do NOT inherit any files, pipes or other resources from Test Engine/2. However, a trace is made if they terminate and the termination code is returned to Test Engine/2 by the Operating System. Child sessions may also register with Test Engine/2 in which case they cannot be killed from the Manage Sessions Dialog only from the Processes and Threads Dialog. ═══ 7.3. Manage sessions ═══ Displays the Manage Sessions Dialog which shows a list of the currently active child sessions. From this dialog you can bring these child sessions to the foreground or kill them. ═══ 8. Tools Menu ═══ For more detailed help see one of the following topics : o OS/2 Window o Running Processes ═══ 8.1. OS/2 Window ═══ Hot Key Starts an OS/2 Command Window as an independent session. This command window will not be terminated by the Operating System when Test Engine/2 terminates. ═══ 8.2. Running Processes ═══ Displays the Running Processes Dialog which shows a list of all processes running on the work station. This list is sorted by PID and is extracted from the Operating System. By selecting an item from the list it is possible to kill that process using the Kill button. The list can be updated by pressing the Refresh button. ═══ 9. Exit Dialog ═══ Hot Keys To terminate the Test Engine/2 session press the Exit button. The size of the window will be saved if the Save Window Size check box is marked. To continue the Test Engine/2 session press the Continue button. ═══ 9.1. Save Window Size ═══ If you want to save the size and screen position of the Test Engine/2 window, you must ensure that this check box is marked. ═══ 10. Options Notebook ═══ Hot Key The Options Notebook allows you to choose and define the default settings for Test Engine/2. The notebook is composed of six pages, for more information see one of the following topics : o Files Page - Global Trace File - Choose Global Trace File - Header File Name - Choose Header File - Footer File Name - Choose Footer File o Editor Page - Default Editor - Editor Invocation String o Formats Page - Trace string mask - Date format mask - Time format mask o Trace Page - Trace by process - Trace by thread - Trace unregistered threads into process file - Use thread 1 file as process file - Global trace unregistered - Global trace all - Trace source changes - Open files for append - Monitor o Language Page - Languages o Display Page - Manual refresh only - Refresh rate - Choose monitor font ═══ 10.1. Global Trace File ═══ Enter the full path of the file that will be opened to receive global traces into this field. You may select the file by pressing the Choose Global Trace File button. This is the file that will be opened and traced to when Global trace on/off is selected from the file menu. ═══ 10.2. Choose Global Trace File ═══ This button displays the standard file dialog to choose the global trace file. The name of the selected file is inserted into the Global Trace File entry field. ═══ 10.3. Header File Name ═══ Enter the full path of the file that contains the header block that will be inserted at the top of any trace file. see Formatting Flags. You may select the file that will be used by pressing the Choose Header File button. ═══ 10.4. Choose Header File ═══ This button displays the standard file dialog to choose the header file. The name of the selected file is inserted into the Header File Name entry field. ═══ 10.5. Footer File Name ═══ Enter the full path of the file that contains the footer block that will be inserted at the end of any trace file. see also Formatting Flags. You may select the file that will be used by pressing the Choose Footer File button. ═══ 10.6. Choose Footer File ═══ This button displays the standard file dialog to choose the footer file. The name of the selected file is inserted into the Footer File Name entry field. ═══ 10.7. Default Editor ═══ Enter the name of the Editor program that should be called to edit header, footer and trace files from Test Engine/2. If the editor is not in a directory that appears in the PATH statement of CONFIG.SYS, then the full path name must be given. ═══ 10.8. Editor Invocation String ═══ Enter the invocation string for calling the editor. Use %s for the file name and include any other switches you may need. DO NOT include the program name in this invocation string as it is included by Test Engine/2. Example for epm : /o %s ═══ 10.9. Trace string mask ═══ Enter the trace string mask into this field. For more information about the special characters that you can enter, see Formatting Flags. ═══ 10.10. Date format mask ═══ Enter the date format mask into this field. The available format characters for a date are : o Y : year character o M : month character o D : day character Example : YY.MM.DD will give an output of 94.03.28, DD/MM/YYYY will give 28/03/1994. ═══ 10.11. Time format mask ═══ Enter the time format mask into this field. The format of a time format is : o h : hours character o m : minutes character o s : seconds character o t : hundredths character Example : hh.mm.ss.tt will give an output of 12.32.45.23. ═══ 10.12. Trace by process ═══ Check this radio button if you want to have your traces grouped by process rather than by thread. The choice made here is applicable to the whole test session. You can only change the running mode of Test Engine/2 if there are no registered processes or threads. ═══ 10.13. Trace by thread ═══ Check this radio button if you want to have your traces grouped by thread rather than by process. The choice made here is applicable to the whole test session. You can only change the running mode of Test Engine/2 if there are no registered processes or threads. ═══ 10.14. Trace unregistered threads into process file ═══ Check this box if you wish any messages from unregistered threads to be traced into the file opened by the owning process of the thread. This requires that a trace file is opened for the owning process in the Processes and Threads Dialog. ═══ 10.15. Use thread 1 file as process file ═══ Check this box if you wish any messages from unregistered threads to be traced into the file opened from the "main" function of the process (thread 1). This is only valid if Trace by thread is on. ═══ 10.16. Global trace unregistered ═══ Trace only messages from unregistered processes or threads to the Global Trace file. ═══ 10.17. Global trace all ═══ Trace all incoming messages to the Global Trace file. ═══ 10.18. Trace source changes ═══ If this box is checked, all changes in the source of the messages is noted in the Global trace on/off file (if active) and in the view window. ═══ 10.19. Open files for append ═══ Check this box to open all trace files in append mode. If this box is not checked, any trace file that already exists will be overwritten. This flag is off by default ═══ 10.20. Monitor ═══ Check this box if you want the messages from newly registered processes or threads to be automatically shown in the view window. This flag is on by default ═══ 10.21. Languages ═══ The current language will be highlighted. If you select another, you will be asked if you want to change to the new language on exiting the settings dialog. ═══ 10.22. Manual refresh only ═══ This check box allows you to disable the the atomatic refresh for the list diplayed in the Running Processes Dialog. If this check box is marked, you will only be able to refresh the display using the refresh button. ═══ 10.23. Refresh rate ═══ Using this spin button you can set the number of seconds between each refresh of the list displayed in the Running Processes Dialog from 1 to 65 seconds (maximum allowable delay for a window timer). Note: It is recommended to keep the refresh delay above 10 seconds, otherwise the selection of items from the list will be difficult. ═══ 10.24. Choose monitor font ═══ This option allows you to change the font used to display traces in the monitor window. The default is courier 8pt. Pressing the button will call the system font dialog where you can choose a different font. ═══ 11. Running Processes Dialog ═══ Hot Key A List of all the processes that are running on the work-station are shown in a list box. The initial display is the state of the work-station when the dialog was opened and will be refreshed periodically depending on the settings of the Refresh rate spin button in the Options Notebook. The display can be refreshed manually by pressing the Refresh button. If the Manual refresh only check box is marked you can only update the display with the Refresh button. Any process running on the work-station can be killed by selecting it and then pressing the Kill button. ═══ 12. Start Sessions Dialog ═══ From this dialog you can start child sessions from Test Engine/2. Note that any sessions started in this way will be terminated by OS/2 when Test Engine/2 is closed. For more information select one of the following topics : o Session Name o Program Name o Program Parameters o Choose program button o Start button ═══ 12.1. Program Name ═══ Enter the name of the program that is to be started. This can be selected using the Choose program button. If the program is not on the PATH for the system, the full path must be given. Any operable program or command file may be given ( *.EXE, *.COM, *.CMD). ═══ 12.2. Choose program button ═══ Pressing this button displays the standard file dialog to select the program that will run as a child session. The result is inserted into the Program Name field. ═══ 12.3. Program Parameters ═══ Enter the parameters, if any, that should be passed to the program. ═══ 12.4. Session Name ═══ Enter the name that the session will known under for Test Engine/2. This name will appear in the list of active sessions in the Manage Sessions Dialog. For a Command Window, this name is used for the title bar. ═══ 12.5. Start button ═══ Start the session defined in the fields of the dialog. If any of the required fields is empty, Test Engine/2 will emit a beep and the cursor will be sent to the first empty field. ═══ 13. Manage Sessions Dialog ═══ Use this dialog to control any sessions started with the Start Sessions Dialog. The list box contains a list of the sessions that have been started from the Start Sessions Dialog. When a session is selected in the list it can then be killed (if it has not registered with Test Engine/2) with the Kill session button. or brought to the foreground with the Select session button. ═══ 13.1. Kill session button ═══ If the child session has not registered with Test Engine/2, the selected session can be killed by pressing this button. ═══ 13.2. Select session button ═══ Use this button to bring a session selected from the list box to the foreground of the desktop. ═══ 14. Processes and Threads Dialog ═══ Hot Key This dialog shows all the processes and threads that are registered with Test Engine/2. For more information on the fields and buttons please select one of the following topics : o Trace on/off o Monitor o View threads o View processes o Trace file name o Choose trace file o Open trace file o Close trace file o Append trace file o Kill process ═══ 14.1. View threads ═══ This is the default viewing mode if the trace mode is set to Thread Tracing (see Options Notebook). It shows a list of the threads registered with Test Engine/2. This option is deactivated if trace mode is set to Process Tracing. ═══ 14.2. View processes ═══ This is the default viewing mode if the trace mode is set to Process Tracing (see the Options Notebook). It shows a list of the processes registered with Test Engine/2. To select a process for killing you must activate this mode. ═══ 14.3. Trace on/off ═══ If this box is checked, all messages from the selected thread or process will be traced to the file shown in the Trace file name entry field. ═══ 14.4. Monitor ═══ If this box is checked, all messages from the selected thread or process will be shown in the view window. ═══ 14.5. Trace file name ═══ This field can be used to enter the name of a file for tracing from the thread or process selected in the list box. If the selected thread or process has registered a trace file, its name will appear in this entry field. You may select a file from the file dialog by pressing the Choose trace file button. ═══ 14.6. Choose trace file ═══ This will display the standard file dialog where you can choose a trace file for the selected process or thread. The chosen file name will be inserted into the Trace file name entry field. ═══ 14.7. Open trace file ═══ To open the trace file shown in the Trace file name entry field, press this button. ═══ 14.8. Close trace file ═══ To close the trace file shown in the Trace file name entry field, press this button. ═══ 14.9. Append trace file ═══ If this button is checked the Trace file will be opened in append mode, otherwise it will be overwritten. ═══ 14.10. Kill process ═══ This button is only active when in process view mode (see View processes). It permits you to kill the selected process. ═══ 15. Accelerator Keys ═══ The following accelerator keys are available for use with Test Engine/2 : o on-line context sensitive help o Save View o Exit o Print View o Global trace on/off o Choose Printer o Default settings o Processes and threads o Clear View o Save Settings o OS/2 Window o Running Processes o Close global trace o De-selects the selected line from the monitor window and causes Test Engine/2 to show incoming messages at the bottom of the window as they are traced. ═══ 16. Startup Parameters ═══ Test Engine/2 can be started in any of the languages supplied. The Options Notebook will show a list of the available languages on the language page. To start Test Engine/2 in a specific language from the command line the following single character flags can be used o E : English o F : French o S : Spanish o G : German o I : Italian o P : Portugues o D : Dutch o A : Danish o N : Norwegian o V : Swedish o U : Finnish o O : Polish o Z : Czech o K : Greek o H : Hungarian o C : Iceland o M : Romanian o R : Russian o Y : Serbo-Croat lm margin=1. The character flag must be the first parameter on the command line and be preceded by a / example tstngen /s this will start Test Engine/2 in Spanish.