OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / graphic / capture / user.man < prev

Wrap

Text File | 1990-07-03 | 18.6 KB | 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