home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 11 Util
/
11-Util.zip
/
GETSCRN.EXE
/
USER.MAN
< prev
Wrap
Text File
|
1990-07-03
|
19KB
|
676 lines
User Manual
for
CAPTURE.EXE
A Full Screen, Protected Mode
Screen Capture Utility
by
Arthur Kevin McGrath
P. O. Box 128
Barboursville, VA. 22923
703/832-7025
User Manual for CAPTURE.EXE
Copyright (c) 1990 by: Arthur Kevin McGrath
P. O. Box 128
Barboursville, VA 22923
703/832-7025
ALL RIGHTS ARE RESERVED. You may not copy this document in any
way. If you copy this document for any reason without WRITTEN
PERMISSION from the above named copyright owner, you are breaking
the Copyright Laws of the United States. You will go to jail
for one year and pay a $50,000 fine.
LICENSE AGREEMENT
Both the software on the enclosed diskette and this document
are the intellectual property of Arthur Kevin McGrath who remains
its sole owner. Upon payment of the appropriate fee from the
list below, you are granted a license to use the software and
this manual in accordance with the terms of this license.
You must purchase a license for each machine on which you
plan to execute the software. You may not sell the software or
the documentation to anyone unless you purchase a Reseller's
License. The license fee schedule is as follows:
Number of Licenses Fee in U. S. Dollars
1 49.95
10 350.00
20 815.00
50 1,495.00
100 2,500.00
Reseller's License 5,000.00
The Reseller's License grants you the right to make
unlimited number of copies of both the software and the
documentation, and sell these copies for whatever price you
desire. You must reproduce my copyright notice on every copy you
sell.
In addition to the copies authorized by the above license
schedule, you are authorized to make one copy of the software and
the documentation for backup purposes.
Page i
User Manual for CAPTURE.EXE
Table of Contents
Executing CAPTURE.................................1
Syntax.......................................1
Capturing a Screen...........................2
System Requirements..........................2
Limitations..................................2
Theory of Operation...............................4
Character Monitors...........................4
Threads......................................5
Pop Ups......................................6
Capturing the Screen Under OS/2..............6
Index.............................................8
Page ii
User Manual for CAPTURE.EXE
Executing CAPTURE
Syntax
CAPTURE (options)
The following options decide what kind of characters will be
copied from the screen:
/A (default) Capture all screen text whether or not the
characters are considered printable.
/X Capture ONLY the printable ASCII characters.
The following options decide what file will receive the
characters captured from the screen:
/D What DRIVE will hold the file? (The default
drive is the current disk drive).
/P What PATH (directory) will hold the file?
(The default path is the current directory)
/F What is the file name? The default file
name is SCREEN.DAT
The following option causes CAPTURE.EXE to display a list of
legal options:
/? What are the legal options for CAPTURE.EXE?
You may use either upper or lower case. You must separate
each option by at least one space. For example:
CAPTURE /X
will set up CAPTURE.EXE to copy the printable characters on your
screen to a file called SCREEN.DAT in your current directory on
your current drive.
CAPTURE /D b /P screens /f lanman.vga
will set up CAPTURE.EXE to copy all characters in the ASCII
character set to a file called B:\SCREENS\LANMAN.VGA. Notice
that leading and trailing backslashes were added by CAPTURE.EXE
to the beginning and end of the path name. Notice that it was
not necessary to type a colon after the drive name. Notice the
space after the /D, /P, and /F.
CAPTURE /X /D d /p SOFTWARE\SCREENS /F FiRsT.Scr
will set up CAPTURE.EXE to copy all characters in the ASCII
character set to a file called D:\SOFTWARE\SCREENS\FIRST.SCR.
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 1
User Manual for CAPTURE.EXE
Notice that leading and trailing backslashes were added by
CAPTURE.EXE to the beginning and end of the path name. Notice
that it was not necessary to type a colon after the drive name.
Notice the space after the /D, /P, and /F. Notice that
CAPTURE.EXE is not case-sensitive.
Once you have started CAPTURE.EXE, you will see a message
from the operating system telling you which version of OS/2 you
are using. When you see that message, CAPTURE.EXE is ready to
record the screen display from a full screen, protected mode OS/2
session.
Capturing a Screen
At this point, you may capture the screen by typing
<CONTROL><PRINT SCREEN>. CAPTURE.EXE will prompt you for the
name of a file to hold a copy of the screen data. You may accept
the defaults by hitting the <ENTER> key at each prompt. If you
make a mistake, just type <N> (for NO) when CAPTURE.EXE asks you
if the file name you entered is correct.
When you want to terminate CAPTURE.EXE, hit the
<CONTROL><END> key. You will see a pop up screen telling you
that CAPTURE.EXE is no longer active on your system.
System Requirements
This version of CAPTURE.EXE was compiled and tested on IBM's
OS/2 version 1.2. I have enclosed the source code and the make
file I used to compile CAPTURE.EXE. If you have difficulties
with an earlier version of OS/2 feel free to recompile and re-
link this program.
The July 3, 1990 version of CAPTURE.EXE requires a little
less than 20,000 bytes of memory, four threads, and one queue in
order to run.
If you get a message that says "Out of system resources"
when you try to execute CAPTURE.EXE, you might want to change the
line in your CONFIG.SYS file that begins with the words
"THREADS=". Increase the number of threads available in your
system. If you do not have a line in your CONFIG.SYS that begins
with the words "THREADS=", add the following line to your
CONFIG.SYS file:
THREADS=255
Limitations
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 2
User Manual for CAPTURE.EXE
This screen capture program ONLY WORKS IN OS/2 PROTECTED
MODE FULL SCREEN SESSIONS.
You may NOT run more this utility in more than one session
at the same time. You will get a GENERAL PROTECTION FAULT (Trap
13). This limitation WILL be removed in a future version. It
comes from the way that CAPTURE.EXE frees memory it is no longer
using. A detailed explanation is in THEORY OF OPERATION under
threads.
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 3
User Manual for CAPTURE.EXE
Theory of Operation
CAPTURE.EXE is the OS/2 equivalent of what a Terminate and
Stay Resident program (TSR) was under PC/DOS. It runs in
parallel with whatever software you are running in the rest of
the system. It samples the raw data coming from the keyboard
waiting for one of two hot keys. When it detects <CONTROL><PRINT
SCREEN>, it copies the current screen to a file on your disk.
When it detects a <CONTROL><END>, it de-installs itself.
CAPTURE.EXE loads a second copy of the command processor
(usually CMD.EXE) in order to allow the user to run programs
while CAPTURE.EXE is monitoring the keyboard data stream. The
version message that the user sees when CAPTURE.EXE is started is
the second command processor telling the user that it has just
loaded. After the user terminates CAPTURE.EXE, that second
command processor is still resident in memory. To remove the
extra command processor, the user should type EXIT after
terminating CAPTURE.EXE. I could have killed the extra command
processor for you, but if I did that, I would automatically kill
whatever program you are running under that command processor.
Because I have no way of knowing if you are running a program
from that command processor, I chose to play it safe and let you
type EXIT.
This screen capture program ONLY WORKS IN OS/2 PROTECTED
MODE FULL SCREEN SESSIONS.
CAPTURE.EXE consists of the following modules:
CAPTURE.C the actual screen capture code
POPUP.C the code that puts the various
popup messages on the screen.
MONITOR.C a character monitor
THREAD.C the various functions used to
manage threads.
Character Monitors
A character monitor is a mechanism OS/2 provides to
intercept and modify data coming from a character device such as
the keyboard. The character monitor program is patched into the
character device driver. It receives every character that the
device driver produces. The character monitor has the option of:
1. passing the intercepted data back to the device
driver without any changes,
2. changing the intercepted character to one or more
different characters,
3. deleting the intercepted character altogether.
CAPTURE.EXE uses a character monitor to intercept data from
the keyboard. Any character except <CONTROL><PRINT SCREEN> and
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 4
User Manual for CAPTURE.EXE
<CONTROL><END> are returned unaltered to the keyboard device
driver. <CONTROL><PRINT SCREEN> triggers the screen capture
routine. <CONTROL><END> causes the monitor to de-install and
CAPTURE.EXE to end.
Threads
In OS/2, a thread is a subroutine that executes in parallel
with everything else. It is the basic unit of multitasking in
OS/2. Programs that choose to have several tasks execute at the
same time do so by creating threads.
Threads are extremely modular creatures. Because OS/2
handles the details of scheduling execution time for threads and
switching from thread to thread, it is possible to design several
simple threads each of which does one simple task well.
Extremely complex algorithms can be broken down into very simple
constructions in this fashion.
Because CAPTURE.EXE is intercepting every keystroke that
will ever be used by every other program in the full screen
session, it uses multiple threads to minimize the perceived
disruption to other programs. Two threads do nothing but
intercept keystrokes and decide if they should trigger a screen
capture. A third thread does nothing but the actual screen
capture. A fourth thread executes another copy of the OS/2
command processor so that the user will see a command line. The
fifth thread frees the stack of the other threads when they
terminate.
CAPTURE.EXE requires a total of five threads.
OS/2 architecture requires a program to allocate a stack (a
memory area) for each thread it creates and to free that stack
when the thread terminates. Finding out when a thread has ended
without consuming massive system resources is something of a
challenge to OS/2 programmers. Microsoft engineers recommend
setting a semaphore when a thread starts and having the thread
clear the semaphore just as it exits. As long as the thread
declares its exit processing to be part of a critical segment,
this approach works well.
The approach that CAPTURE.EXE uses is as follows. One
thread (the Stack Killer thread) sleeps in the background and
waits to be told that some other thread has ended. The Stack
Killer then wakes up, frees the stack, and goes back to sleep.
The beauty of this approach is that it does not limit the number
of instances of any thread, and it does not prevent a time
critical thread from being serviced by the CPU. This is
especially important on a server or any machine that has a lot of
multi-tasking. The cost of this approach is one extra thread and
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 5
User Manual for CAPTURE.EXE
one extra queue. The name of the queue is \\QUEUES\KILLSTK$$.$$$
If you have another queue by that name anywhere on your
computer, CAPTURE.EXE will not be able to run. If you try to run
two CAPTURE.EXE programs on the same computer, you will
automatically have this problem. There is a solution to this
problem. I just could not debug the solution in time for this
release of CAPTURE.EXE.
Pop Ups
OS/2 provides a way to create a small temporary screen for
the purpose of getting data from a user or for passing important,
immediate information to the user. This vehicle is called a pop
up.
CAPTURE.EXE uses three pop ups. The first gets a file name
from the user. The second tells the user if the file was
successfully created. The third tells the user when capture has
ended.
All the code between VioPopUp and the VioEndPopUp system
calls is very special code. All keyboard and screen I/O between
these two calls is part of a special session. It is NOT possible
to switch out of this session. This makes pop ups very difficult
to debug.
If you ever need to debug a pop up, do the following:
1. Always isolate your pop up code in separate
source files from the rest of your code.
2. Comment out the VioPopUp and VioEndPopUp
system calls.
3. Write a main() function that does nothing
but call your pop up code.
4. Compile your pop up code with this dummy
main().
5. Debug the code using your favorite debugger.
Without the calls to VioPopUp and VioEndPopUp,
this is just ordinary video calls.
6. When the code works properly, uncomment the
VioPopUp and VioEndPopUp system calls.
Capturing the Screen Under OS/2
Capturing the screen under OS/2 requires a little bit of
thought. OS/2 is a multi-tasking operating system. There could
be (and usually are) several programs writing to the screen at
any time. OS/2 is also a hardware independent operating system.
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 6
User Manual for CAPTURE.EXE
There is no guarantee that there will be a screen buffer at
address 0xB0000 or 0xB8000.
To capture the screen, you must call VioGetMode to find out
where the physical screen buffer is located and how long it is.
The Microsoft documentation of this call INCORRECTLY fails to
mention that this call returns both the length and location of
the physical screen buffer. The IBM documentation is correct.
Next, VioGetPhysBuf must be called to get a valid selector
to that address. Then the macro MAKEP is used to convert the
selector into a pointer that can be used in the C language.
The screen is then locked using VioScrLock so that no
program can change the screen while it is being copied. At this
point, the screen is copied. Then, VioScrUnLock is called so
that other programs can write to the screen.
After the screen has been captured, the user is prompted for
a file name and the screen data is written to a file.
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 7
User Manual for CAPTURE.EXE
Index
CAPTURE.C, 4
Character monitor, 4
Command processor, 4, 5
CONFIG.SYS, 2
Device driver, 4, 5
GENERAL PROTECTION FAULT, 3
Keyboard, 4, 5
LICENSE AGREEMENT, i
Modules, 4
MONITOR.C, 4
Options, 1
Out of system resources, 2
Pop up, 6
Pop up
hints for debugging, 6
Popup messages, 4
POPUP.C, 4
Queue, 6
Reseller's License, i
Screen capture, 4
Stack Killer, 5
Terminate and Stay Resident, 4
Threads, 4, 5
THREADS=, 2
THREAD.C, 4
Trap 13, 3
TSR, 4
VioEndPopUp, 6
VioGetMode, 7
VioGetPhysBuf, 7
VioPopUp, 6
VioScrLock, 7
VioScrUnLock, 7
/A, 1
/D, 1
/F, 1
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 8
User Manual for CAPTURE.EXE
/P, 1
/X, 1
/?, 1
<CONTROL><END>, 2, 4, 5
<CONTROL><PRINT SCREEN>, 2, 4, 5
\\QUEUES\KILLSTK$$.$$$, 6
Copyright, 1990 Arthur Kevin McGrath. All rights reserved.
Page 9
