Category : OS/2 Files
Archive   : LST102.ZIP
Filename : LST.DOC

LST: A File Viewing Utility for OS/2 Protected Mode
Version 1.02
13 September 1989

(c) Copyright Brady Flowers, 1989
All rights reserved


I. Restrictions

LST is supplied for personal, private use. Feel free to
distribute LST given these restrictions:

- the program shall be supplied in its original, unmodified
form, which includes this documentation;

- no fee is charged;

- use for profit without a license is prohibited;

- the program may not be included or bundled with other
goods or services. Exceptions may be granted upon written
request only.


If you are using LST and find it of value, your gift in any
amount ($15 suggested) will be greatly appreciated. Please make
checks payable in U.S. dollars to Brady R. Flowers. Canadian and
non-U.S. checks are not acceptable.

For use by corporations and other institutions, please contact
the author for a licensing arrangement.


II. System Requirements

LST is written for the IBM PC/AT, IBM PS/2, or any compatible
computer that can run MS OS/2 or IBM OS/2. LST will run in OS/2
Protected Mode only and may be run from either a full screen OS/2
session or on a Presentation Manager VIO window.


III. Using LST


A. The Command Line

Command line syntax for LST is as follows:

LST [options] filespec [filespec ...]

where:

"filespec" is a valid OS/2 file name or ambiguous file spec.
Examples are "lst.doc" or "c:\usr\*.txt".

"options" is a string which begins with the character "-" followed
by any of the following (in either upper or lower case):

"h" forces the first file to be loaded in Hex Mode. The
display mode, Hex or Text, may be altered from within
LST also with the restriction that certain files are
always displayed in Hex Mode (see discussion below).
If this option if omitted, it defaults to Text Mode
(with the exceptions noted below).

"s" causes the first file loaded to be read from standard
input rather than from disk. Other files may be given
on the command line and subsequently displayed however
the "stdin" file is not viewable in hex mode and the
presence of the "s" option will negate any occurrence
of the "h" option on the command line.

"m" followed by any non-negative decimal number, allows you |
to set the behavior of the mouse. If the number is |
zero, the mouse handler operates in "polled" mode |
which is bad as far as CPU usage goes but allows for |
you to easily use both the mouse and the keyboard |
interchangeably (this is the default setting). If the |
number is one, the mouse is not polled but key strokes |
from the keyboard will not be received in a timely |
manner (actually this setting is just there for my |
own debugging purposes). If the number is greater than |
one, the mouse is completely disabled and all commands |
must come from the keyboard. |
|
"z" followed by any non-negative decimal number, sets the |
number of milliseconds LST yields to the CPU between |
keystrokes and mouse events. If running LST seems to |
be slowing other tasks running on your system down, |
try setting this to a higher value. The default value |
is two. |

"t" followed by any non-negative decimal number, sets the
tab expansion to that value. If the number is zero,
tabs are not expanded and tab characters will be
displayed on screen. In the current version of LST,
this value is only alterable by the command line.
If this option if omitted, it defaults to 2.

"l" followed by any positive decimal number, sets the number
screen rows to that value. LST will attempt to reset
the video state to that number of rows. If the video
mode cannot be reset appropriately, LST defaults to the
current screen mode. In the current version of LST,
this value is only alterable by the command line.
If this option if omitted, it defaults to 43.

"c" followed by any positive decimal number, sets the number
screen columns to that value. LST will attempt to reset
the video state to that number of columns. If the video
mode cannot be reset appropriately, LST defaults to the
current screen mode. In the current version of LST,
this value is only alterable by the command line.
If this option if omitted, it defaults to 80.

"a" followed by nine hexadecimal bytes (eighteen characters
from the set "0123456789abcdef") which specify the screen
attributes for the following sections of LST's screen:

Screen Area Default Color
=================== ======= =============
Main Screen 03 Cyan on Black
Main Screen Hilight 0b Bright Cyan on Black
Menu and Menu Items 4e Yellow on Red
Selected Menu Items 4f Bright White on Black
Disabled Menu Items 43 Cyan on Red
Status Line Message 0b Bright Cyan on Black
Error Messages 0e Yellow on Black
Scroll Bars 60 Black on Brown
Modeless Dialog Boxes 31 Blue on Cyan

If this option is absent, values default according to the
above table. If it is present, it must either contain
all eighteen bytes or must be the last option in the list.
If an attribute is to retain its default value, any
character other than a Hex digit may be used as a place
holder.

Examples:

1) Force Hex mode and 25 line display:
LST -hl25 filespec
2) Tab stops at multiples of 8 columns and change Main screen to
Yellow on Blue:
LST -ta1e filespec
3) Change error to blinking Yellow on Black leaving everything
else default:
LST -a............8e filespec
4) Read the first display from the output of a program called
ARC2 and subsequently display all files matching *.c in the
current directory:
ARC2 v foo.arc | LST -s *.c
5) Disable the mouse handler and increase the yield time between |
keystrokes to 5 milliseconds: |
LST -m3z5 filespec |

Note: Options need not be the first thing on the command line, they
may be interspersed with the filespecs and any given option
may appear more than once, the last appearance of said option
will define it's value.

Note: See "The LST Environment Variable" below for a discussion on
how to semipermanently set these options.


B. The Menus

LST uses a menu interface very similar to that found in OS/2 Presentation
Manager applications or in Microsoft Windows applications. There is a menu
bar across the top of the screen containing the following items:

"File" "Search" "Options" "F1=Help"

each of which may be activated by either clicking on the word with the
mouse pointer or be typing Alt-F, Alt-S, Alt-O, or F1. The first three
activate pulldown menus while "Help" actives a dialog box containing infor-
mation concerning available keystrokes.

While the menu is active, you may move from item to item using the left
and right arrow keys or by clicking on another item. Typing the ESCape
key removes any pulldown menu but leaves the menu active, typing it again
deactivates the menu and returns you to file viewing mode. Clicking the
mouse anywhere but on a menu will also return you to file viewing mode.

While a pulldown menu is active, you may move the hilight on the pulldown
using the up and down arrows. Typing the ENTER key selects or activate the
hilit item. Typing the first letter of any item actives that item (if
there is more than on item with the same first letter, the first such item
is selected). Alternately, you may click the mouse pointer on any item to
select it. The results of selecting any item on a pulldown menu are
outlined below:

"File" Menu
"Open..." a dialog box appears and prompts you to enter a new
file name. The edit field contains a default value
(usually the current file name) which may be edited
using the left and right arrow keys, the Home and End
keys, and the Delete key or by clicking the mouse
pointer within the edit field. The filename may be
any valid OS/2 filespec, wildcards accepted. Type
ENTER to direct LST to read the file or files adding
it or them to the Pick List (see discussing of Pick
List below) after the current file, or type ESCape or
click the mouse pointer anywhere outside of the dialog
box to abort the command.

"Info" a dialog box appears containing the following infor-
mation: The name of the current file, the time and date
of its creation or last modification, and the file size
in bytes. Type any key or click the mouse pointer
anywhere to remove this dialog box.

"Prev File" reload the previous file in the Pick List (see
discussion on the Pick List below). This item will be
disabled if the current file is the first item (or only
item) on the Pick List.

"Next File" reload the next file in the Pick List (see discussion
on the Pick List below). This item will be disabled if
the current file is the last item (or only item) on the
Pick List.

"Pick List" displays a dialog box containing the current Pick List
(see discussion on the Pick List below). The current
file is hilighted. The hilight may be moved using the
up and down arrow or by clicking the mouse pointer on
the dialog boxes scroll bar. Select a filename from
this list by typing the ENTER key while the filename is
hilit or by clicking the mouse pointer on the name.
The indicated file is the reloaded into LST. Abort the
Pick List command by typing ESCape or by clicking the
mouse pointer anywhere outside of the dialog box.

"About Lst" displays a dialog box the name of the program (LST), its
author, and a copyright notice. Type any key or click
the mouse pointer anywhere to remove this dialog box.

"Exit" unconditionally exit LST, restoring the original screen
mode and contents.


"Search" Menu
"Exact Match" a dialog box appears and prompts for a search pattern.
The default value that appears may be edited using the
left and right arrow keys, Home, End, and Delete keys.
Type ENTER to begin a search in the current search
direction (see Search Fwd/Back below) for a string that
exactly matches the pattern. If found, the line is
displayed center screen in the screen hilight color,
else a "Pattern not found" error message is displayed.
Abort the dialog box by typing ESCape or by clicking the
mouse pointer anywhere outside of the dialog box.

"Ignore Case" behaves in the same manner as "Exact Match" above except
that the pattern will match any text that differs only
by upper or lower case, i.e., "Abc" matches pattern
"ABC".

"Grep" mechanically behaves the same as "Exact Match" and
"Ignore Case" above except that the search is based on
what is know as a "regular expression." See the discus-
sion on regular expressions below.

"Next" repeat the last search in a forward direction using the
same pattern and search method (Exact, Ignore Case, or
Grep).

"Previous" repeat the last search in a backward direction using the
same pattern and search method (Exact, Ignore Case, or
Grep).

"Search Back" reverse the default direction for searches. After
selected this option, the menu item becomes "Search Fwd"
and will toggle between the two.

"Search Fwd" see "Search Back" above.


"Options" Menu
"Hex Mode" causes the current file to be reread and displayed in
Hex Mode. If the current file already is in Hex Mode,
this item will be displayed "Text Mode" and selecting
it will cause the file to be reread and displayed in
Text Mode.

"Text Mode" see "Hex Mode" above.


C. Viewing the File

General:

While viewing the file, the following methods are available for navi-
gating your way around the file:

Keyboard:
Up Arrow Move the display up one line in the file
Down Arrow Move the display down one line in the file
PgUp Key Move the display up one page in the file
PgDn Key Move the display down one page in the file

Home Key Move the display to the top of the file
End Key Move the display to the end of the file
Right Arrow Move the display right five columns
Left Arrow Move the display left five columns
Control-Left Arrow Move the display to column one.

Note: there are other keystrokes that duplicate most of these
functions. See discussion on Accelerators and Aliases below.

Mouse:
Vertical movement: Clicking the mouse pointer on the up or down
arrow of the vertical scroll bar moves the display up or down
by one line respectively. Click the mouse pointer on the scroll
bar itself moves the display up by one page if the mouse pointer
is above the scroll bar "thumb", or down by one page if the mouse
pointer is below or on the "thumb".
Horizontal movement: Clicking the mouse pointer on the left arrow
of the horizontal scroll bar or on the scroll bar itself to the
left of the "thumb" moves the display five columns to the left.
Clicking the mouse pointer on the right arrow or on the scroll
bar to the right of or on the "thumb" moves the display five
columns to the right.

Note: A "page" is defined to be the number of lines in the current
file viewing window (three less than the number of screen lines).


Text Mode:

This is the default viewing mode for most files. The file appears on
screen in much the same manner as it would in a text editor. If the
Tab Stop setting (see discussion on command line options above) is
greater than zero, tabs are expanded so that tab stops fall on columns
which are multiples of that value (i.e., if tabs are set to 2, the default,
tab stops are at columns 3, 5, 7, etc.); no other text filtering is done.

Certain files will not look well presented in text mode and may not
read in correctly. Binary files will not, in general, be read correctly
in this mode. Thus files with any of the following extensions will
automatically put LST into Hex Mode (see below): ".COM", ".EXE", ".OBJ",
".BIN", ".DEV", ".LIB", ".DLL", ".ARC", ".PKA", and cannot be viewed
in Text Mode (unless of course they are renamed before executing LST).


Hex Mode:

This is the preferred viewing mode for binary (non-text) files. The
display is altered when in this mode to display the file in standard
"hex dump" format, that is:

offset bytes ascii
====== ===== =====
xxxxxx xx xx xx xx xx xx xx xx-xx xx xx xx xx xx xx xx *aaaaaaaaaaaaaaaa*

where offset is a six digit hexadecimal number indicating the current
offset into the file, bytes are a set of 16 hexadecimal numbers which
represent the next sixteen bytes of the file, and ascii is the ascii
representation of the printable characters in that sixteen byte section
of the file with non-printable characters represented as ".".

Note that files with any of the following extensions may be viewed
only in Hex Mode, ".COM", ".EXE", ".OBJ", ".BIN", ".DEV", ".LIB", ".DLL",
".ARC", and ".PKA".



D. Accelerators and Aliases

Certain menu functions may be accessed directly from the keyboard by use
of certain accelerator keys. What follows is a table of these accelerators
and their functions. Please refer to the "Menus" section for a description
of the functions.

Keystroke Function
========= ========
Q Exit
A Repeat Last Search (same direction)
\ Ignore Case Search
/ Exact Match Search
? Help
^N Search Next
^B Search Previous
^PgUp Previous File
^PgDn Next File
Alt-H Toggle Hex/Text Mode
F1 Help
F3 Search Next
F9 Search Previous
F10 Exit
Alt-I File Info
Alt-R File Open
Alt-X Exit

Certain keystrokes are aliases (perform the exact same function) as other
keystrokes. Note above that "Q", "Alt-X", and "F10" are aliases. What
follows is a list of aliases.

Keystroke Alias(es)
========= =========
Up Arrow ^E
Down Arrow ^X
Left Arrow ^S
Right Arrow ^D
Control Left Arrow ^A
PgUp ^R
PgDn ^C
Home ^Q
End ^Z
F1 ?
F3 ^N
F9 ^B
F10 Q, Alt-X



E. The Pick List

The Pick List is simply a list of files for LST to display. When LST
is executed, each file that matches the filespec of specs on the command
has its name added to the Pick List and the first file in the list is
loaded and displayed. Each time Next File is chosen from the menu, or
^PgDn is typed the next file in the list is loaded and displayed,
similarly, Prev File or ^PgUp loads and displays the previous file in the
list. Choosing the "Pick List" menu items displays a dialog box that
allows you to choose the next file to display.

When "File Open" is selected and a new file or files specified, the new
file names are added to the Pick List immediately after the current file.
It is possible to have the same file name in the list multiple times.


F. The LST Environment Variable

If you do not like the default color scheme of LST the "-a" option on the
command line provides a method for you to alter those colors. The syntax
of the option is, however, neither easy to remember nor easy to type. If
you wish to set any of LST's command line parameters on a semipermanent
basis you may do so by setting an environment variable called "LST". When
LST starts up it looks first for this variable in the environment and
processes its contents as it would command line options. It then continues
to process the command line so that options set in the environment may be
overridden by the command line.

For instance, if you want to force LST to always display 25 lines and
want the main screen to be black on white, you could execute the
following line from the OS/2 command prompt or from OS2INIT.CMD:

set LST=-l25a70


G. Regular Expressions

It is beyond the scope of this document to provide a thorough treatment
of regular expressions however we will attempt to give an introduction to
the topic here and to describe how this implementation should work.

You may think of an OS/2 ambiguous filename as a regular expression in
which the special character "?" matches any character in a filename and the
special character "*" matches any string of characters. An OS/2 ambiguous
filename is indeed a very restricted version of a regular expression.

In the LST implementation of regular expressions, there are special
characters that will match certain other characters:

"?" matches any one character except the newline character
"^" matches beginning of line
"$" matches end of line
"\" quotes a character, removes any special meaning.
(or specifies as ascii character value: \9 == tab)

Thus, using just these four, "^?$" would match any line that is exactly
one character long, "^a?c" would match "abc" if and only if it were the
first thing on a line, and "abc\$" matches only the string "abc$". The
search in LST is line based so the "^" and "$" characters only make sense
at the beginning and end of a pattern respectively.

Other special "wildcards" are:

":a" matches any alphabetic character
":d" matches any digit
":n" matches any alphanumeric character
": " matches whitespace, the space character or the tab character

And still more can be made up "on the fly" using classes. A class is a
group of characters inclosed in square brackets "[]" and will match any
single character which is listed in the class. "[abc]" will match "a", or
"b", or "c" and [abcABC] matches "a", "A", "b", "B", "c", or "C". When the
"^" character appears as the first character in a character class, it is
taken to indicate negation, i.e., "[^abc]" would match any character EXCEPT
lower case "a", "b", or "c".

Furthermore, groups of characters may be specified using the "-" char-
acter within a class designation: "[0-9]" matches any digit, "[^q-t]"
matches any character except lowercase "q", "r", "s", or "t".

Finally, we have the notion of closure. Any character followed by the
"+" character matches one or more occurrence of that character: "fo+" will
match "fo", "foo", "fooo", et cetera. Any character followed by the "@"
character matches zero or more occurrences of that character, thus "fo@"
matches everything that "fo+" did plus the string "f". The character "*"
is shorthand for "?+".

Examples:

"[Gg]o@d" matches "Gd", "gd", "God", "good", "Goooooooood", etc.
"[Gg]o+d" matches "God", "good", etc.
":d,:d:d:d" matches "1,000", "7,658", "9,999", etc.
"^void" matches "void" if it appears as the first thing on the line.
"\*/: @$" matches any line that ends with "*/" except for possible
trailing white space.

Exercise:
What does "^[^ #\9]?@(?@): @$" match?



IV. Limitations

In Text Mode, the maximum number of lines in the file is limited to
65532 lines. The maximum line length is 1024 bytes and longer lines will
be wrapped increasing the total number of lines in the file (in memory
that is, the file itself is not altered). LST relies on OS/2's virtual
memory management for loading the file itself into memory and it is
conceivable that with low system memory and/or insufficient space on the
swapping device, that a large file may be only partially read in even
though it may have fewer than 65532 lines.

In Hex Mode, each 16 byte "chunk" of the file becomes one line and is
subject to the 65532 line limit thus the absolute maximum size of a file
that may be completely read in Hex mode is 65532 times 16 bytes, or
1,048,512 bytes.



V. Disclaimer

Every care has been taken so that LST will perform as outlined in this
document and that it is as error free as the author can make it. We
should be aware however that no piece of software is ever totally bug
free.

Use of this software for any purpose whatsoever constitutes your
unqualified acceptance of the following statements.

The author makes no warranty or representation that the software will
be error free. The author disclaims any warranties, either express or
implied, including but not limited to any implied warranty of
merchantability or fitness for any particular purpose.

The user agrees to take full responsibility for the selection of and
any use whatsoever made of the software.


IN NO EVENT WILL THE AUTHOR BE LIABLE FOR ANY DAMAGES WHATSOEVER
(INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION OR THE LIKE)
ARISING OUT OF THE USE OF, INTERRUPTION IN THE USE OF, OR INABILITY
TO USE THIS SOFTWARE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF ANY
POSSIBILITY OR LIKELIHOOD OF SUCH DAMAGES.


________________________________________________________________


"IBM", "IBM PC/AT", "PS/2", "IBM OS/2" are all registered trademarks
of and copyright by International Business Machines.
"Microsoft", "Microsoft Windows", "MS OS/2" are all registered
trademarks of and copyright by the Microsoft Corporation.

________________________________________________________________


Brady Flowers
518 Blue Earth Street
Mankato MN 56001
Voice phone: 507/388-2848
Epitaph BBS: 507/243-3318
GEnie Mail address: B.FLOWERS