T r a c e P l u s / W I N S O C K Installation =============================================================================== Create a directory for TracePlus/WINSOCK, i.e. C:\XRAY. Copy all the files contained in this ZIP file to that directory. To run the TracePlus demonstration, select "Run..." from the "File" menu of the Program Manager and type: C:\XRAY\XRAYWINS Press Ok or to start TracePlus/Winsock. Getting Started =============================================================================== TracePlus/Winsock traces function calls of the Windows Socket (Winsock) implementation. The first time you run TracePlus/Winsock, follow the procedures below: 1. In the Help menu, select View README.WRI.... This command provides information that has become available since the manual was printed, and other vital information. 2. Select Options... (Trace menu) to set your trace preferences.. Alternatively, press Ctrl + O, or select the Trace icon in the tool bar. See "Setting Your Trace Preferences" below for more information. 3. Select Filters... (Trace menu) to set trace functions and tasks. Alternatively, press Ctrl + F, or select the Filters icon in the tool bar. See "Selecting Filters" below for more information. Once the menu bar is displayed, you can access help on any menu item by highlighting it and pressing F1. To access help from the TracePlus/Winsock window, press F1. This program is limited to storing up to 30 most recent trace records. The monochrome, file, and printer log options in the Options dialog box will also be disabled. The Winsock help facility is disabled. Other- wise all other features are fully functional. Note: This demonstration does not require WINSOCK.DLL on the system in order to execute. However, it won't be much of a demon- stration! Setting Your Trace Preferences =============================================================================== Select Options... (Trace menu) to access the Trace Options dialog box and set your trace preferences. Alternatively, press Ctrl + O, or select the Trace icon in the tool bar. Setting Output Options Trace log Displays trace information to only a window. Monochrome For a monochrome monitor. Display This option is grayed if you do not have a monochrome video card installed in your computer. Printer Outputs trace information to your printer. DBWin Outputs trace information to DBWin (a sample debugger available with Microsoft Windows SDK and Microsoft C/C++ (Visual C++TM)). This option also supports output to WinScopeTM by Periscope. X- Ray is compatible with any program capable of displaying messages sent by the function OutputDebugString( ). Be aware that this option can slow your system down if many trace events are being logged. File Outputs trace information to a log file. The default log file is C:\WINSOCK.LOG. However, you can enter another file in the Log File text box, or choose another log file by selecting the Browse button. The default is Append to existing file, which appends new trace information to the log file you specify. If you deselect the default, the log file is deleted and a new file is created when you run a trace on another function. Log Select this option if you want Exception to log Winsock functions that s only return errors only. Level of Select High to output detail information details to printer, DBWin, or the file you specified in the option above. Select Low to display only two lines of information to the Event Details dialog box. Setting Display Options Minimize Minimizes the TracePlus/Winsock when trace application window to an started icon. Stop trace Stops the trace when you when activate the TracePlus/Winsock activated window. Setting the Log File If you selected File in the Output Options field, and if you do not want to accept the default of C:\WINSOCK.LOG, enter the name of the file to which you want trace information stored, or choose another log file by selecting the Browse button. Setting Buffer Options The number in parentheses below the Buffer Size option is the amount of memory in kilobytes. Buffer Enter the number of records, Size between 25 to 2000 inclusive, that you want to buffer. Circular When the number of records is one more than the number you specified in the Buffer Size option, the buffer drops the oldest record, giving the appearance of an endless buffer. The larger the buffer size, the more records it can hold before losing the oldest record. Stop when The buffer stops accepting filled record when the number of records you specified in the Buffer Size option is reached. The trace is automatically stopped. Setting Your Preferences and Exiting the Dialog Box Select the Ok button, or press Enter to set your preferences and exit the dialog box. Selecting Filters =============================================================================== Select Filters... (Trace menu) to access the Filters dialog box and set filters. Alternatively, press Ctrl + F, or select the Filters icon in the tool bar. Selecting Trace Functions Select the trace functions you want to run in the API Functions list box. To select all functions in the list box, select the Select All button. To cancel the functions you selected, select the Clear button. For more information about these functions, refer to the documentation that accompanies the Winsock API. TracePlus does not trace the Winsock function WSAGetLastError( ). Selecting Tasks Select the applications for which you want trace information in the Active Application(s) list box. To select all tasks in the list box, select the Select All button. To cancel the tasks you selected, select the Clear button. Select Launch specified application if you want to run a trace on an application that is not displayed in the Active application(s) list box. To select the application, select the Choose application... button or enter the command line of the application. Skip if WSAWOULDBLOCK WSAWOULDBLOCK is returned if the recv, recvfrom, send, and/or sendto functions fail because no data could be received or sent. Select this option if you do not want WSAWOULDBLOCK logged. Exiting the Dialog Box To exit the dialog box without setting any filters, select the Cancel button. To set your filters and exit the dialog box, select the Ok button or press Enter. Running Traces =============================================================================== Once you have set your trace preferences and filters, you can run traces. This section discusses the following: Starting a trace Stopping a trace Viewing trace event details Continuing a trace Clearing the trace log and buffer Starting a Trace Select Start (Trace menu), or press Ctrl + S, or select the Start icon in the tool bar to start the trace. Stopping a Trace Select Pause (Trace menu), or press Ctrl + A, or select the Stop icon to pause tracing. Alternatively, If you selected the Stop trace when activated option in the Trace Options dialog box, tracing will stop when you activate X- Ray/Winsock. Viewing Trace Event Details =============================================================================== Select Event Details... (Trace menu) to access the Event Details dialog box and view details of trace events. Alternatively, double click on a trace record in the TracePlus/Winsock window, or press Ctrl + E, or select the Details icon in the tool bar. The Event Details dialog box can remain on the screen as long as the trace buffer is not cleared (by selecting the Clear icon or selecting Reset Events (Trace menu). Using the Event Details Dialog Box Detail This window displays detail of List Box a specified trace. You can specify the trace for which you want more detail by double clicking on a trace record in the TracePlus window, or by entering a number in the Record text box and pressing the Get button. Alternatively, you can scroll through the list box or select the Animate button to view other records. The following information is displayed for every trace detail: FUNCTION SUMMARY: A summary of the function, including record number, function, and the time it was called. PARAMETERS BEFORE CALL: Parameters in the code before the function is executed. RETURNS: Error codes or values that are returned by Winsock. PARAMETERS AFTER CALL: Values that may have been changed by Winsock. Close Select this button to close the Button dialog box. Help Select this button for help on Button the dialog box. Start Select this button if you want Button to automate scrolling through the detail list box. To set the animation delay, enter the number of seconds delay in the seconds text box. Speed Enter the number from 1 to 15. The higher the number, the slower the animation (that is, auto- mated scrolling through the detail list box). The range of values equates to .2 through 3 seconds. You can initiate animation by selecting the Animate key. Errors Select this option if you want Only to view error messages while animation is enabled. Backwards Select this option if you want to animate backwards. Find Select this button to find a Button record. The Find dialog box is displayed. You can search by any numeric or alphabetic characters. If you search alphabetically, you can do a case-sensitive search (if the word for which you are searching contains capital letters) by selecting the Match Case option. You can also search up or down through records. Get Select this button to retrieve Button details for a trace you specify in the Record text box. The record is the first field that is displayed in the X- Ray/Winsock window. You can also use the scroll buttons to scroll backward and forward through record numbers. Errors Select these scroll buttons to Scroll scroll backward and forward Buttons through errors. Continuing a Trace Select Continue (Trace menu) after you have stopped/paused the trace to save the current trace and continue tracing events. Clearing the Trace Log and Buffer Select Reset Events (Trace menu) or the Clear icon to clear all events from the trace log and buffer. If you select this command or the Clear icon, and the Event Details dialog box is displayed, the dialog box will close.