
###########################
#+------------------------#
#|                        #         (c) Copyright 1999 
#| L O G A N A L Y S E R  #    Arctan Computer Ventures Ltd
#|                        #
#|         F O R          #  ================================
#|                        #
#| M I C R O S O F T (tm) #      *** Reference Manual ***
#|                        #  
#|  S Q L   S E R V E R   #  ================================
#|                        #
#|        v 1 . 1         #   http://www.arctan.demon.co.uk
#|                        #
###########################


##############
## CONTENTS ##
##############

 1.   How to reach us
 2.   Copyright Issues
 3.   Introduction
 4.   Installation & Launching
 5.   Logging TRACE data from SQL Server
 6.   About Screen
 7.   Reading in log file
 8.   Status bar
 9.   Wrapping text
10.   AutoFilter / Manual Filter
11.   Viewing in chunks
12.   Writing out results
13.   Viewing everything
14.   Including Comments
15.   Including Connection details
16.   Capturing SQL Statements
17.   Restricting to a date / time
18.   Including/Excluding lines with specific text
19.   Reversing Logic
20.   Filter by User Id / Connection
21.   Changing Viewing Font
22.   Quitting the program


##########################
## 1.   How to reach us ##
##########################

For ordering details, or other information, please contact us
using one of the following means:-

Name:		Arctan Computer Ventures Ltd		
Address:	71 Prentice Court, Northampton NN3 8XR, UK
Fax:		(+44) (0)870 0520762
Email:		loganalyser@arctan.demon.co.uk
URL:		http://www.arctan.demon.co.uk/excel2ingres.htm

Arctan Computer Ventures produce general, specialist, and
bespoke software for a range of requirements.	

If you have any questions regarding our products, or if you 
have any suggestions on how to improve our existing products
or service, please feel free to contact us using any of the
above means.	


###########################
## 2.   Copyright Issues ##
###########################

Use of this product implies an acceptance of the below
conditions of use.

"LogAnalyser for SQL Server" is
 Copyright 1999 Arctan Computer Ventures Ltd.

Copyright is subject to international law.

The product is Shareware which means that you can use the
product for up to 30 days to try it out. If you wish to
use the product after this time, then you must pay for a
licensed copy of the program, for each person who wishes to use
the product. If you use the unlicensed product after 30 days,
you wil be breaking the terms of this copyright agreement.

You can only make copies of this unlicensed version, with the
sole purpose of distributing it for others to trial.
You cannot distribute this product as a "licensed" version, and
if you do distribute it, you must make it clear that is is
available on a trial basis only, as part of the Shareware
copyright agreement. You must always distribute this (unchanged)
file with the program file and any other accompanying files.
Any charge you make for distribution should be reasonable.

Copying is illegal by any means - disk copies, internet copies,
decompilation, and any other means you can imagine,
except for the express purposes of distributing the trial version
of the software for others to trial before purchasing.

"LogAnalyser for SQL Server" can be bought on a multi-license basis,
in which case it is legal to allow a number of people to make use it.
This does not mean, for example, that if you buy 5 license, 50 people
can make use of it so long as only 5 of them use it simultaneously.
If 50 people could potentially use it, you need 50 licenses.
For further information about licensing, please contact us using one
of the above means.

It's not all bleak, though. If you do have ideas for improvements,
additional features, etc., then please contact us, and we'll
try to incorporate your suggestions wherever feasible.


#######################
## 3.   Introduction ##
#######################

"LogAnalyser for SQL Server" gives the facility to take log or
script files produced by the SQL Server Trace program, and filter
through to pinpoint specific activity within the database.

For example, if you wish to see what information was changed by a
user on a given table on a given date, then this would be a few clicks:

  * Import the file - standard Open box
  * Click on "Insert", "Delete", and "Update" to pick up any Changes
  * Click on the required user Id listed in the User/Connections tree
  * Type in the date/month into the DATE box
  * Type the table name into the "Include lines with" box
  * Optionally (if you wish to see specific timings etc.) click on
    the Comments box to see comments associated with specific actions
  * Click on the "Filter" button to see the results

If you then want to output the results of the filter for proof, just
click on the "Save Results to" button. A suggested filename will be
given automatically, or you can change its name/location.

The program distinguishes between log and script files automatically,
and displays a script as text, and a log as columns of data.

The program is written in Delphi, and operates on Windows 95 and above,
and also Windows NT.


###################################
## 4.   Installation & Launching ##
###################################

The program can be located anywhere, and needs no initialisation files
or other external settings to operate correctly.

Thus installation is a simple process of UNZIPping the program,
placing it in the location you require (e.g. Program Files directory),
perhaps creating a shortcut to it on your desktop (right click over
desktop and select New and then Shortcut).

Launch the program by double-clicking on the shortcut icon.

The ZIP file should be called lgans110.ZIP.
In side this ZIP file should be:

 * sql_log_analyser.exe  - Program file (can be renamed if required)
 * readme.txt            - These instructions
 * example.sql           - Sample SQL Script to import for testing
 * example.log           - Sample log to import for testing
 * screen_shot.gif       - Sample picture of program in operation


#############################################
## 5.   Logging TRACE data from SQL Server ##
#############################################

This program takes the output of the SQL Server Trace utility,
whose purpose is to track any activity on a given database,
and dump the SQL commands executed, and accompanying comments,
to a log file for further analysis.

The further analysis bit is where SQL Server falls down, for
which you can turn to LogAnalyser.

The following section describes a sample session using the Trace
utility with SQL Server 6.5:-

  * Start / Programs / Micrsoft SQL Server Utilities / SQL Trace
  * Connect to Required server with Login Id and Password (e.g. sa)
  * Click on Connect button
  * Click on File menu, then choose New Filter option
  * Give Filter a name
  * Click on "Save to Script File" to check the option.
  * Choose a name and location for the log. This will be the import
    file for LogAnalyser.
  * If you wish to output a log as well, click on "Save as Log File"
    to check the option.
  * Click on the Add button.
  * Leave filter running whilst database operations are taking place.
  * You can pause, stop, and restart the filter using one of the
    video-player style buttons on the toolbar.


#######################
## 6.   About Screen ##
#######################

The screen is made up of two main sections

  * The Filter Tools
  * The Results Box

The filter tools are at the top of the screen, and control how to
filter the log so that only the required information is shown
at the bottom of the screen.

The results box displays either a text box if a Script file is being
imported, or a grid if a log file is being imported.


##############################
## 7.   Reading in log file ##
##############################

The log filename is the name of the log to be filtered. The [...]
button to the right displays a dialog box to change this filename.

The [Import] button reads in the log, and then automatically
filters the lines of the log according to any criteria selected.
The results will then be displayed in the results box.
Initially, no results will be displayed, as no filter tools have
been set.

The progress bar at the bottom of the [Import] button fills as
the log is read in to memory. This is generally very quick.

Note that once the data has been imported, it can be re-filtered
in any way - the data is not re-imported each time a filter option
is changed, and the data re-filtered.

You may wish to re-import data if the log is continually being
refreshed. In this case, just click on the [Import] button again.

The first time the data is filtered, user ids and their associated
connection IDs are automatically extracted into a tree for further
filtering, if required.


#####################
## 8.   Status bar ##
#####################

The status bar is made up of five sections.
From left-to-right, these are:-

  1. Number of unfiltered log lines read in during initial import
  2. Number of filtered lines found during the search
     (Nb. this is same as below (3.) if "Stop on full box" is checked)
  3. Number of filtered lines currently visible in the results box
     (the result box may not be able to display all results at once)
  4. Range of filtered lines currently in results box
  5. Currently selected User / Connection Id


########################
## 9.   Wrapping text ##
########################

Just above the results box appears the "Wrap Text?" check box.
Check this to allow text to wrap around the edge of the text
box during display, and thus remove the horizontal scroll bar.
This is useful if you wish to see the whole of a log line at
once (e.g. to analyse a whole query).
Uncheck it (default) to show each log line on one line of text
- useful for getting an overall view of what is going on, as
this looks less cluttered.

Note that this option is only available if viewing a script file.


######################################
## 10.   AutoFilter / Manual Filter ##
######################################

As standard, you will need to set the filter options to filter
through to the required results, and the click on the
[Filter] button to perform the filtering.
Alternatively, you can check the [AutoFilter] option so that
every filter option you change will automatically cause the
results to be refiltered. This can be useful when trying to
interactively "get a feel" for what is happening in a log.


#############################
## 11.   Viewing in chunks ##
#############################

The results box will only hold a certain amount of data.
When the log is filtered, the program will automatically
stop the filtering process in order for you to view the
results. This can also reduce the waiting time when
filtering a large amount of data.

This does mean that the number of lines found on the
status bar is the number of lines found up to the end
of the results box.

It also means that if you wish to save the results to
disk, only the data up to the end of the results box
will be output.

To force the program to filter through the entire log,
irrespective of the quantity of data that can be
displayed in the results box (e.g. if you wish to
save the entire set of results to a file), uncheck
the [Stop on full box] option.

You can also select which line of the results set to
start viewing from by changing the number in the
"Start Line" box. The first line is set at 0.
E.g. if the range displayed is from 0 to 659, then
to see the next set of information, you would type
660 into this box.

Alternatively, you can page forward and backwards
through the results set using the up and down arrows
next to the "Start Line" box.

Note that when viewing a log file, lines are read in
chunks of 500 if this option is unchecked, otherwise
the program will attempt to read ALL lines.


###############################
## 12.   Writing out results ##
###############################

To write out the results to another file, click on the
[Save results to...] button.

A dialog box will be displayed with a default file name,
which you are free to change.

Note that if the [Stop on full box] option is checked,
then only the results up to the end of what is displayed
in the results box, will be output.

Nb. If you wish, it is possible to import this results file
again to perform further filtering.
This is useful for complex requirements, or where the log
file is so large that filtering is taking a long time.

This is also useful for providing a fixed copy of the
extract taken, and could be printed out as evidence etc.


##############################
## 13.   Viewing Everything ##
##############################

To view the entire contents of the log without any filtering,
click on and thus check the [All] option.

Checking this option automatically unchecks most other options.

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.


##############################
## 14.   Including Comments ##
##############################

This option is only relevant if viewing a script file.

To view only comments (ie. lines starting with --) in the log,
check the [Comments] option.

N.b. If you select any non-commented SQL statements such as
     SELECT, INSERT, DROP etc., then only those comments
     which refer to these specific statements will be
     displayed, so that you can pick out any USER/time etc.
     details relevant to the commands you have filtered by.

Checking this option automatically unchecks the [All] option.

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.


#########################################
## 15.   Including Connection details  ##
#########################################

Some log lines relate specifically to when a connection was
made to the server by a given user, and when it was ended.

Note that many programs use multiple connections for a given
user, and many establish a new connection for each new query.

Active connections are those that were already in operation
when the SQL Server Trace program started executing - for
example, SQL Server Administrator is a common example.

To view Active Connection log lines, check the
[Active Connections] option.

To see log lines referring to new connections, check the
[New Connections] option.

To see log lines referring to the closure of connections,
check the [Ended Connections] option.

To see when the filter was started, click on the
[Filter Start] option.


####################################
## 16.   Capturing SQL statements ##
####################################

If you wish to track the activity on the database, it is
often useful to filter out only the type of statements
that you are interested in.

For example, if you wish to view only log lines
relating to the user reading information from the database,
check the [SELECT] filter option. This will pick up all
log lines which start with the SQL "SELECT" keyword.

Similarly, to view lines relating to changes made to
existing data in the database, check the [UPDATE] option.

The following is a list of filter options and what they
relate to:-

SELECT :  Reading data from the database
UPDATE :  Changing existing data in the database
INSERT :  Inserting new records of data into the database
DELETE :  Deleting records of data from the database
EXEC   :  Executing stored procedures in the database
GRANT  :  Granting access priveliges to a user of the DB
REVK   :  [REVOKE] - Remove access priveliges for a user
CREATE :  Create new tables in the database
DROP   :  Drop (Delete) tables from the database, and all
          associated data
KILL   :  Kill (stop and remove) a process running on
          SQL Server
SET    :  Enforce a setting for how SQL Server functions

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.


########################################
## 17.   Restricting to a date / time ##
########################################

To filter by a given date or time, type the text into the
"Date" box.

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.

E.g. to search for anything on 18th August, type in 18/08
(or 08/18 if using MDY format) or you may get away with
just typing "18/" without the quotes.
E.g. to search for something that happened at 04:30, type
"04:30" or just "4:30" or even "4:3"


########################################################
## 18.   Including/Excluding lines with specific text ##
########################################################

If you wish to filter the data further (not comments), then
you can enter a keyword in the "Include lines with" box
to only show lines containing that keyword.

For example, if you only wanted to find lines relating to
the field called "UserId" then you could type USERID in this
box. Note that the search treats UPPER and lower case as
the same, so "USERID" would pick up "USERID", "userid",
"UserId", or even "UsErId"!

If you wish to specifically EXCLUDE some lines from the
results, e.g. because they are irrelevant to your analysis,
and occur so often that they obscure other results, then
you can type in a keyword to exclude in the
"Exclude Lines With" box.
Any log lines that contain that text will be specifically
excluded from the results, including anything found with the
"Include lines with" option.


###########################
## 19.   Reversing Logic ##
###########################

If you wish to find everything EXCEPT for what you have specified
(often it is easier to express what you require in this form),
then check the "Reverse Logic?" option.

This does NOT reverse the logic of INCLUDE and EXCLUDE lines, or
the Comments option, or the DATE option, or the USER / ID option.

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.


##########################################
## 20.   Filter by User Id / Connection ##
##########################################

When you import data from the log, the program builds up a list of
Users and their associated connection IDs in a tree form.

To filter by either a specific user, or a specifid connection ID,
check the "Filter by User / Connection Id" option, and click on
a User ID or a connection ID to filter by.

The option that you have chosen will be shown in the fifth box along
on the status bar, at the bottom of the program screen.

If you do not have the [Autofilter] option checked, you will
then need to click on the [Filter] button.

Note that when you select a User, all available connections will
automatically be shown beneath it. if you do not wish to view by
a specific connection, you do not need to click on a connection ID.

#####################################
## 21.   Changing the Viewing Font ##
#####################################

To change the font used in the Results box to a fixed-width font,
right-click over the results box, and select a font from the dialog
box that appears.

Note that if viewing the log grid, you will need to re-filter to
adjust column widths to the new text size.


################################
## 22.   Quitting the program ##
################################

To quit the program, just click on the X at the top right hand
corner of the program window.
All data read in will be released cleanly from memory.



******************
If you have any questions, refer to section 1 for how to contact us.
******************
