═══ 1. The Main Window ═══ The main window consists of a container which holds all view objects. Click on one of the following items. o Creating a view o Changing a view o Starting tracing o Restarting tracing o Stopping tracing ═══ 2. Creating a view ═══ To create a new view, select either "Views, New..." in the menu bar, or press Ctrl-N or the -key, or select "New View..." in the container's context menu. A settings notebook will appear where you can enter the settings for the new view. ═══ 3. Changing a view ═══ Select the view for which you want to change the settings, and then select either "Views, Change..." in the menu bar, or press Ctrl-O, or select "Change Settings..." in the view's context menu. A settings notebook will appear where you can change the settings for the selected view. ═══ 4. Starting tracing ═══ To start tracing, select the view for which you want to start tracing, and then select either "Views, Start Trace" in the menu bar, or press + (the plus-sign), or select "Start Trace" in the view's context menu. If the view is already tracing, pressing "Start trace" has no effect. You can determine the state of the view by means of its icon. If you selected a logfile for the view, you will get asked whether you want to append to or overwrite an existing logfile. If you selected "display" as trace destination for the selected view, the view window will automatically be opened. See also o Restarting tracing o Output format ═══ 5. Restarting tracing ═══ To restart tracing, select the view for which you want to restart tracing, and then select either "Views, Restart Trace" in the menu bar, or select "Restart Trace" in the view's context menu. If the view is already tracing, pressing "Restart trace" has no effect. If you selected "display" as trace destination for the selected view, the view window will automatically be opened. The difference between start trace and restart trace is, that restart will not ask you whether you want to overwrite or append to an existing logfile (if any), but will always append. Restarting will only work, if you previously started and stopped tracing for the selected view. See also o Starting tracing o Output format ═══ 6. Stopping tracing ═══ To stop tracing, select the view for which you want to stop tracing, and then select either "Views, Stop Trace" in the menu bar, or press - (the minus-sign), or select "Stop Trace" in the view's context menu. If the view is not tracing, pressing "Stop trace" has no effect. You can determine the state of the view by means of its icon. ═══ 7. The output format ═══ The output in the view window as well as in the logfile contains the following information: o Seq. Nr. o PID o TID o Level o Ordinal o Timestamp o Text ═══ 8. View Object ═══ Each view is represented by an icon, which indicates the state of the view: If this icon appears, tracing is currently active. If this icon appears, tracing is currently not active. If this icon appears, the view is currently changing its state from active to inactive or vice versa. ═══ 9. Exit ═══ Press Exit All logfiles and view windows will be closed, tracing is stopped, the settings are saved, and the program will terminate. If you selected Confirm Exit in the settings notebook, you will get a confirmation dialog. ═══ 10. Font ═══ Press here to choose another font for the view windows. A font dialog will appear and you may select a fixed-width font. ═══ 11. New View ═══ Press here to create a new view. ═══ 12. Tile Windows ═══ Press here to tile any open view windows. ═══ 13. Cascade Windows ═══ Press here to cascade any open view windows. ═══ 14. Show all views ═══ Press here to show all open but hidden view windows. ═══ 15. Hide all views ═══ Press here to hide all open view windows. ═══ 16. Close all views ═══ Press here to close all open view windows. If you selected Confirm close all in the settings notebook, you will get a confirmation dialog. ═══ 17. Icon View ═══ Press here to switch from details to icon view. Like in details view, each view is represented by an icon, indicating the state of the view. ═══ 18. Details View ═══ Press here to switch from icon to details view. The details view consists of four columns: 1. An icon indicating the state of the view: Trace is active. Trace is not active. In between. 2. The name of the view. 3. The name of the logfile (if any). 4. The comment (if any). ═══ 19. Sort ═══ Press here to sort the view objects by name. ═══ 20. Close selected ═══ Press here to close the selected view. This is the same as double-clicking the view window's system-menu. ═══ 21. Start trace ═══ Press here to start tracing for the selected view. If you selected "Trace to display" for the selected view, and the view window is not yet open, it will be opened automatically. If you selected a logfile for this view, and the logfile already exists, you will get prompted whether you want to overwrite the logfile or append to the existing logfile. See also Restart trace. ═══ 22. Restart trace ═══ Press here to restart tracing for the selected view. The difference between start trace and restart trace is, that restart will not ask you whether you want to overwrite or append to an existing logfile (if any), but will always append. ═══ 23. Stop trace ═══ Press here to stop tracing for the selected view. The logfile - if any - will be closed. ═══ 24. Open view ═══ Press here to open the view window. This is the same as double-clicking on the view icon. You may want to selected "Start on Open" in the global settings notebook to start the trace automatically when you open a view. ═══ 25. View Settings ═══ Press here to change the settings of the selected view. ═══ 26. Product Information ═══ Press here to view product information. ═══ 27. Edit logfile ═══ Press here to edit the logfile of the view. If the trace is running, PMScout will start the browser instead. ═══ 28. Browse logfile ═══ Press here to browse the logfile of the view. ═══ 29. Next view ═══ Press here to switch to the next open view. ═══ 30. Global Options ═══ Press here to change the global settings of PMScout. ═══ 31. Format ═══ Press here to convert a trace file generated by VIOScout into a logfile. ═══ 32. Edit ═══ Press here edit any logfile. ═══ 33. Options file ═══ Press here to write the current view's options to a file. The file can be read by VIOScout. ═══ 34. View ═══ The view window mainly consists of a listbox which displays the trace output. By default, the listbox scrolls up as new lines are inserted, so you can always see the most recent lines. See also Output format ═══ 35. View Options ═══ Select one of the following options: Keep current If this option is checked, PMScout will scroll down after each line, so you can always see the most recent lines. Clear Click here to clear the contents of the listbox. This is the same as pressing the ESC key when the view window is active. Auto Clear If this option is checked, PMScout will clear the listbox when it is full. If this option is not checked, PMScout will only drop the first few lines until there is enough room to insert any new lines. Hint: To get fastest throughput, check the "Auto Clear" item and uncheck the "Keep Current" item. Change Font Click here to change the font of only the current view window. The font is not saved between two sessions of PMScout. To change the font of all view windows, select the global "Change Font" action. ═══ Exit ═══ Explanation You selected Exit to leave PMScout and PMScout wants this action to be confirmed. Recovery Press Yes to leave or No to stay. Note: This messagebox only appears when Confirmation of Exit in the global settings notebook is selected. ═══ Close all open views ═══ Explanation You selected Close all to close all open views and PMScout wants this action to be confirmed. Recovery Press Yes to close all open views or No to cancel the operation. Note: This messagebox only appears when Confirm close all in the global settings notebook is selected. ═══ Cannot start Editor ═══ Explanation You tried to start the editor but PMScout cannot start it when trace is active. Recovery PMScout starts the browser instead. If you actually want to edit the logfile, first stop the tracing, then select Edit ═══ Cannot start Editor ═══ Explanation PMScout could not start the editor. Recovery Probably you entered a wrong executable's name or the editor is not in your PATH statement. Open the Settings notebook and select a valid editor. ═══ Cannot start Browser ═══ Explanation PMScout could not start the browser. Recovery Probably you entered a wrong executable's name or the browser is not in your PATH statement. Open the Settings notebook and select a valid browser. ═══ Cannot write to profile ═══ Explanation PMScout could not write to the profile. Recovery Probably the profile is corrupted. If PMScout runs in a network environement, check whether you have write permission. ═══ Invalid Location ═══ Explanation You entered an invalid location for the ini-file, i.e. PMScout cannot write the ini-file to the given location. Recovery Enter another path. You can enter either relative or absolute paths. To choose the current path, enter a single period. If you wait a few seconds, PMScout will expand the given path to a full path, so you can check whether the given path was valid. Do not enter a filename. ═══ Cannot start tracing ═══ Explanation PMScout cannot start tracing. Recovery Hit ok. ═══ Duplicate view name ═══ Explanation PMScout has found you entered a name of a view that already exists. Recovery Change the name of the view on the third page of the settings notebook. ═══ Invalid trace levels ═══ Explanation PMScout has found you entered invalid trace levels. Recovery Change the trace levels of the view on the first page of the settings notebook. Make sure the "From"-level is less than or equal to the "To"-level for each process you selected. ═══ 36. Global settings ═══ The notebook for the global settings contains two pages: o On the Editor and Browser page you can select the editor and browser PMScout should use. o On the Global options page you can select the global options of PMScout. Press OK to have the changes in effect. ═══ 36.1. Editor and Browser ═══ On this page you can select the editor and the browser PMScout should use to edit or browse the logfiles. To select an editor, press the "Select" button next to the editor field. To select a browser, press the "Select" button next to the browser field. ═══ 36.2. Global options ═══ This page contains PMScout's global options you can choose from. Check Display only first 16 Bytes of hex data to display only the first 16 bytes of hex data in a view window. If this option is checked, output of hex data to a view window will be truncated to the first 16 bytes. However, the logfile - if any - will contain the complete hex data, independent of this switch. This option can be used to speed up the tracing to a view window. Start on open to automatically start tracing when the view window is opened. Stop on close to automatically stop tracing when the view window is closed. Confirm Exit if you want to be asked "Are you sure?" when you leave PMScout. Confirm close all if you want to be asked "Are you sure?" when you select "Close all views". Use small icons if you want to use small icons for the views. ═══ 37. Running processes ═══ This listbox conatains the processes that are currently running. To add a process to the process list, select one item and press OK. ═══ 38. Logfile ═══ Select one of the following buttons: Overwrite Press this button to overwrite an existing logfile. Append Press this button to append to an existing logfile. Cancel Press this button if you do not want to start tracing. ═══ 39. Location of ini-File ═══ This dialog is used to enter a valid location for the ini-File, where PMScout stores its information between the sessions. You may enter a relative or an absolute path here. ═══ 40. Formatter ═══ The formatter dialog allows you to format tracefiles that were previously created by the VIOScout program. You can enter valid names for the source and target files directly, or press one of the following buttons: Select sourcefile to select a sourcefile. The sourcefile must have been generated by the VIOScout program and should normally have the extension .trc. Select targetfile to select a targetfile. If the targetfile already exists, the output is appended to the existing file. Format to start formatting Cancel to abort the operation ═══ 41. Product Information ═══ The product information shows you the versions of the modules belonging to PMScout. Press OK to close the dialog. ═══ 42. Keys ═══ Key Description F1 Help Ctrl+O View Options Ctrl+F Change Font F3 Exit Tab Next View Ctrl+I Icon view Ctrl+D Details view Ctrl+E Edit logfile Ctrl+B Browse logfile Ctrl+N, Ins New view Delete Delete view Ctrl+A Show all views Ctrl+H Hide all views Ctrl+S Global Settings + (plus sign) Start trace - (minus sign) Stop trace ESC Clear listbox Alt+F Change font of only the current view Alt+K Toggle Keep current Alt+C Toggle Auto Clear ═══ 43. Settings Notebook ═══ The settings notebook contains three pages: o On the process page you can add or remove processes to the process list and change the trace levels for each process seperately. o On the options page you can change the options for the selected view. o On the general page you can change the name and description of the selected view. Note: The options page is only available, if tracing is not active. Press OK to have the changes in effect. If the OK button is disabled, PMScout is missing some information for the selected view. Make sure you o added at least one process on the first page, o selected at least one of the options "Display" or "Logfile" on the second page, and o entered a view name on the third page. ═══ 43.1. Processes ═══ On this page you can add or remove processes you want to trace. Select Add running to add a process that is currently running. Add other to add any process to the process list. Add DLL to add a DLL to the process list. In this case all processes will be traced. The user should take extra care to specify only those trace levels which are used by the DLL which he wishes to trace. Remove selected to remove the currently selected process from the list. Use the "From"- and "To"-fields to change the trace level of the selected process. If you want to trace one process with different trace levels, add that process multiple times and select different levels for each instance. Developers should ensure when coding that the trace levels are unique to the EXE or DLL. This is particularly important when tracing DLLs. ═══ 43.2. Options ═══ This page contains per-view settings. Select Logfile to have a logfile for this view. If you select this option you must either enter a logfile name or press the "Select logfile" button to select a logfile. Display to trace to the display. Synchronous trace to trace synchronously, that is, to suspend the traced process until the trace statement is written to the display and/or to the logfile. Note that selecting this option will slow down the traced process. Save settings to save the settings of this view between the sessions of PMScout. Note: At least one of the options "Logfile" or "Display" must be selected. If "Logfile" is selected, a filename must be provided. ═══ 43.3. General ═══ On this page you can change the name and comment of the selected view. You may enter up tp 64 characters for the name and up to 255 characters for the description. You may leave the description field empty, but you must enter a view name. However, PMScout will provide a unique default name for the view. ═══ 44. General ═══ On this page you can change the title and the bitmap of the item you are editing. An item must have at least one of the two. Use the Title-field to enter the text you want to appear below the bitmap. Select one of the following buttons to change the bitmap: No Bitmap To have no bitmap for this item. Built-in... To select one of the built-in bitmaps for this item. Load file... To load a bitmap file of your choice. Create... To create a new bitmap using the iconeditor that comes with OS/2. Edit... To edit the bitmap with the iconeditor. Note: Editing does not work with the built-in bitmaps. Press the Undo-button to undo your changes. ═══ 45. Position ═══ You can create an item at the End of the toolbar, Before or After the current item. Note: If you did not display the context menu over an item, you can just chose End. If you select the Non selectable item button, the created item will not be selectable and will just be used as a decoration. If you select the Spacer button, the created item will be an item without text, bitmap or frame, which can be used as a separator. Press the Undo-button to undo your changes. ═══ 46. Action ═══ On this page you can select the action associated with the item. For the item you want to create or edit, choose one of the functions from the function list. When you select a function, the description field shows you a short description of what the selected function does. Press the Undo-button to undo your changes. ═══ 47. Style ═══ You can check the following items to change the general style of the Toolbar: Show the text Display the text. Frame the items Draw a 3D frame around each item. Autosize If checked, the items are sized according to the bitmaps. If not checked, use the Width and Height fields to specify the size in pixels you want to give to each item. If the item is smaller, it is centered. If the item is bigger, the bitmap is shrunk. There are three shrink modes: Ignore Ignore the lost lines and columns, works best for bitmaps with lots of colors. And Works best for bitmaps with dark drawings on light backgrounds. Or Works best for bitmaps with light drawings on dark backgrounds. ═══ 48. Toolbar Menu ═══ You can select an action which will affect either one item or the whole toolbar. Press Edit item... to display a notebook to select the bitmap, text and action associated to the item. Create item... to display a notebook to select the bitmap, text, action and position of the new item. Delete to delete the item on which the context menu was popped up. Change style... to display a dialog to modify the appearance of the toolbar. Load default to switch back to the original toolbar. Import... to restore a toolbar from a file. Export... to save a toolbar to a file. ═══ ═══ A view contains all the required information concerning the programs to be traced. The type of output required is also specified in the view. ═══ ═══ The sequence number is used to uniquely identify the output statement. It is initialized to 1 when the DATT.DLL is first loaded into memory and incremented on a system-wide basis. ═══ ═══ The id of the process that originated the line of output. ═══ ═══ The id of the thread that originated the line of output. ═══ ═══ The trace level for the line of output corresponding to the level in the source code. ═══ ═══ The ordinal is used to match output from a TX macro. Before the TX macro evaluates the given expression, information pertaining to this expression will be displayed. After evaluation of the expression, further information including the result of the expression will be displayed using the same ordinal. The ordinal is only used by the TX macro and is incremented on a system-wide basis. It is initialized to 1 when the DATT.DLL is first loaded into memory. ═══ ═══ A timestamp of the form hh:mm:ss:dd where hh stands for hours, mm for minutes, ss for seconds, and dd for hundredths. ═══ ═══ The text of the line of output.