OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cscout.zip/EXE/PMSCOUT.HLP

OS/2 Help File | 1995-07-17 | 24KB | 815 lines

ΓòÉΓòÉΓòÉ 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 <Insert>-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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> Cannot start tracing ΓòÉΓòÉΓòÉ

Explanation

PMScout cannot start tracing.

Recovery

Hit ok.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden> 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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A view contains all the required information concerning the programs to be
traced. The type of output required is also specified in the view.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The id of the process that originated the line of output.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The id of the thread that originated the line of output.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The trace level for the line of output corresponding to the level in the source
code.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

A timestamp of the form hh:mm:ss:dd where hh stands for hours, mm for minutes,
ss for seconds, and dd for hundredths.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The text of the line of output.