Frostbyte's 1980s DOS Shareware Collection

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

/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / USCX / DOSUT-19.ZIP / PARTNER.DOC < prev next >

Wrap

Text File | 1987-01-15 | 28KB | 618 lines

________________________________ P A R T N E R Version 1.1 ________________________________ C o m p u C a m 45 Parklea Drive Toronto, Ontario Canada M4G 2J7 (416)421-9430 (evenings after 7:00 EDT) PARTNER is distributed as a freeware program. That is, you may use it, copy it and distribute it. You may not, however, sell it. PARTNER, and the original ideas behind it, remain the property of Jim Camelford and CompuCam. If you have found the program useful, we would appreciate a donation of $15.00 us. Please send us your personal cheque, a bank draft or your VISA card number and card expiry date. PARTNER's source code and documentation (in machine-readable form) are available at a nominal cost to cover handling charges. If you are interested, please contact the author at the above address. PARTNER is written in TURBO (tm) Pascal. You may wish to obtain the source code if you want to see how it's done, modify the program's operation to add features of your own or generate different versions that use less memory. This version of Partner, (1.1), is available as FreeWare but the current version (3.2) is available only as a commercial product directly from CompuCam. The total price of the package is $49.95 US + $3.00 S/H. PC-Sig users that have forwarded a $15.00 donation may acquire the package for $34.95 + s/h. Version 3.2 has many exciting new features, including: . fixes to some bugs in this release - including some hang-up problems . a ram-resident, ASCII file editor . a ream-resident, file catalogging system . ability to invoke DOS for commands from within most any application . capability to interrupt graphics applications and properly restore their screens . ability to 'un-load' Partner if you tire of having it ram-resident . improved access to sub-directories . double-protection to prevent accidentally erasing files . 2 diskettes of software, including object and full source code . 70-page user manual . TIPS - Tehnical Information Points explaining how Partner is implemented, how to write ram-resident programs in Turbo Pascal and how to extend and modify Partner . and because of the program's size, CompuCam's own program listing and cross-reference analysis tool is included free ! This on-line documentation, however, only describes release 1.1 of the program. CompuCam accepts phone orders with your VISA card (sorry, we are not setup for either MasterCard or American Express). Please leave your name, address, phone number, VISA card number and your card's expiry date, and, please mention PC-Sig when ordering. Of course, we would be delighted to hear your comments and will attempt to fix any reported bugs in either the documentation or the program. English isn't exactly free of glitches either! Write us! PARTNER is not, however, warranted in any way nor are any claims made as to the suitability of the program for your application. PARTNER Copyright (c) 1985, 1986, 1987 James R. Camelford and CompuCam ________________________________________________________________________ PARTNER - What is It ? ====================== PARTNER is a useful utility program that resides permanently in your system's memory yet is available at any time with the touch of a key. It provides a set of useful diskette and directory maintenance facilities that can enhance most programs running on your PC. For example, it provides: o multiple-window access to the directories on your diskettes or hard disk; o an ability to remove, copy and rename files; o a technique to move files from one sub-directory to another on the same volume without copying and removing; o a capability for displaying (ie: typing) text files on your screen; o reports of space usage for individual files and for the volume as a whole; What it Doesn't Do ================== Because PARTNER uses colour extensively, it requires a colour/graphics adapter. In its conventional form, it requires about 52kb of permanent memory. PARTNER could easily be modified to sense which type of display it's using and to use only monochrome. It is not currently compatible with 40-column or graphics display modes. It's been tested on true IBM PC's, PC's with hard disks, AT's and the Advanced Colour/Graphics adapter and found to work well. PARTNER works well with a variety of programs. However, it is known to be incompatible with some. A list and technical description is provided at the end of this document. How you Start the Program ========================= You invoke PARTNER from the DOS command prompt using the following command. (The square brackets indicate optional parameters just like in the DOS manual.) PARTNER [/load] [/nnn] /load causes PARTNER to be permanently retained in memory as an extension to DOS. If you do not use the /load option, then PARTNER runs as a utility program and exits normally when you are done. When PARTNER is run as a utility, it waits for 5 seconds to display its logo before allowing you to enter a command). /nnn the scancode of the keystroke you want to use to invoke PARTNER once it is loaded, either from the DOS command prompt or from within a running program. By default, PARTNER uses shift-F9 (that is: 92). You can set the signalling keystroke to any convenient key. PARTNER - How to Use it ======================= PARTNER is pretty simple to use! (Of course that may be construed as literary license on my part ... but the approach we will take for teaching you how to use it is by taking you through a step-by-step sequence ...) Bring PARTNER up as a utility program first. That is, just run it from the DOS command prompt using the command: PARTNER Do not specify any options. PARTNER will display its logo, wait 5 seconds and then offer you a small window in the upper left corner of your screen. (Yes, you can change its shape and location but let's leave that until later ...) PARTNER prompts you for a Directory Name. Enter a directory name using the same syntax as you would for DOS' DIR command. In this state, PARTNER understands drive letters, wildcard constructs using * and ? and sub-directories -- so use them if you like. Alternatively, you can simply strike the RETURN key (without typing anything) if you want a display of all filenames on the default directory on the default drive. PARTNER displays a list of filenames on the volume until either it fills the window (ie: runs out of space) or runs out of filenames. At this point, it pauses and highlights the filename in the upper left corner of the window. You can "operate" on this file using the features described below. Now the fun starts, since now all the options are available to you ... and there are lots of them. But first, look at the bottom line of the window. This is know as the Help line. It lists some of the functions now available (eg: Remove, Rename, Change Directory ...). Watch the help line from time to time as it will contain additional, explanatory information to assist you when entering a command. The functions now available are briefly listed below; more detail follows later: Enter Specify a different wildcard sequence, drive, filename or sub-directory F2 Remove this file F4 Copy this file somewhere F6 Rename this file F8 Change the default sub-directory for this window to something else F10 Display additional information about this file (ie: creation timestamp, file size, file attributes etc). F9 Display (ie: type) this file on the screen now F1, F3 Shrink or grow the window's horizontal size F5, F7 Shrink or grow the window's vertical size You can move about the window, selecting different files, using the normal cursor movement keys. That is: -> <- Moves the "file pointer cursor" right or left ^ | Moves up or down | v home Moves to the upper left corner PgUp Starts the display of filenames all over again from the first file in the directory (that is, it's a "start over" key rather than "display the previous page" key). PgDn Displays the next window-full of file names End Returns to the previous window or DOS. Hold it ... ! What's that, returns to the previous window? How did we get to another. Ah Ah, you say! Multiple windows? Yes indeed ... To bring up another window, strike shift-F9 again. A second (third, fourth) window will spring up on the screen. You can carry out all the same manoeuvres here that you did on the preceeding window and then, when you're done, depress End to return to the "invoking window". The windows "stack" ... that is, when you invoke a new window and return, everything will be absolutely as you left it. (Special note: when shift-F9 is used as the invoking keystroke, the \ key carries out the same function for convenience allowing you to bring up subsequent windows with just 1 keystroke). Accessing PARTNER from Within Another Program ============================================= First you must load PARTNER as a permanent part of DOS; you do this using the following DOS command. (This command can be included in an AUTOEXEC batch file so that it is done each time you start your system.) PARTNER/load Then you can invoke PARTNER from within another program by just depressing shift + F9. PARTNER opens a window in the upper left corner of the screen and you carry on exactly as described before. When you depress End for the last time, PARTNER returns to where you invoked it - leaving the screen and operating environment exactly as you left it. There are, however, two known exceptions. PARTNER does not work with: o screens in graphics mode o screens in 40-column text mode The window position, size and sub-directory settings are remembered so you won't have to re-specify them the next time you enter PARTNER. Moving the Windows About ======================== Ctrl + one of the cursor movement keys (Home, End, left-arrow, right-arrow, PgUp or PgDn) causes the window to move about the screen in the direction you designate. (Literary license again: Ctrl+PgUp and Ctrl+PgDn are used in place of the more obvious Ctrl+up/down arrow because the keys in the middle, vertical row of the numeric keypad on this machine (@#$%^) don't register through the normal BIOS calls). You can place the windows virtually anywhere on the screen and change their size using the F1, F3, F5 and F7 keys. The settings are remembered from one use to the next. You can overlap them ... or not ... as you desire. By default, windows 1-3 don't overlap and windows 1-2 leave the bottom of the screen un-obstructed. But, the choice is ultimately yours. Just the Enter Key ================== The Enter Key is powerful. When the "file pointer cursor" is highlighting a filename, you indicate that you want to examine a new set of files by just depressing the Enter key. The top of the window is opened, allowing you to type a new directory search specification. You can enter a new drive, sub-directory or filename in conjunction with any wildcard pattern (ie: ? and *) and that will be used as the target for the next directory display. If you have "logged" this window into a particular sub-directory using the F8-Change Directory key, then you may temporarily override this by specifying a different drive or sub-directory. All actions like Removing, Displaying (ie: typing) and Renaming are now relevant to this directory and not the one you specified using the F8-Change Directory command. Of course, the default assigned to the window is used when you don't specify a "path" in the request line. That's just like in DOS, where you can CD to a particular sub-directory, yet operate on files outside that directory by using the appropriate syntax on a Del command. Here, the override "sticks" until you depress the Enter key again to request a new directory display. The override most definitely "sticks" while using the PgUp, PgDn and "window invocation" keys (ie: Shift-F9) ... would you really want it to work any other way? If you want to display the contents of a sub-directory, then the directory request must terminate with a \. For example: e:\wv\correspondance\ displays the contents of the files in that sub-directory (the trailing *.* is assumed), whereas e:\wv\correspondance only tests e:\wv for the presence of the sub-directory "correspondance". If you do not specify a drive or pathname then the search is assumed to occur in the current, default sub-directory on the default drive. F2 - Remove a File ================== Touching F2 removes the file. Be careful out there! If you slip you'll need some assistance from Mr. Norton. F4 - Copy a File ================ Touching F4 will copy the file. You are prompted for the name of the destination -- enter a new filename. The filename can contain a drive letter but no sub-directory or pathname. You can specify a drive letter alone (leaving the filename blank) and the file will be copied to the destination drive retaining its name. Now this copy isn't exactly the same as the DOS copy and there are some restrictions. o the output filename cannot specify a sub-directory; you can only specify an optional drive letter (ie: A:, B: etc) o you can specify a whole new filename or leave the filename blank. You cannot use any form of DOS wildcard construct with * and ?. If the filename is left blank, then of course it is copied to the output drive using the same name. If you want to copy a file from one sub-directory to another on the same drive then use F6-Rename, instead. If you want to copy a file from one sub-directory to another on different drives then use the following procedure. o "Log" this window onto the desired, destination drive and sub-directory using the F8-Change Directory function You will obtain a list of filenames on that drive. o Now, strike the Enter key to request the display of a new directory. o Enter the name of the directory containing your desired source file or the specific source filename. Press Enter to display the contents of that directory and then move the cursor on top of the source filename. o Press F4-copy. Enter the drive letter and, optionally, a new name for the file you want to copy. Because you have set the default directory on this window for the desired destination drive and sub- directory the output will be directed there. If you are only working with drive names (that is, you don't use sub- directories) then the above isn't necessary since you can use any drive letter in the destination filname and select any drive letter using the Enter key request display. Yes, this is a bit complicated! A bit you say ... !!! Well, we'll fix it when we receive the 3.0 version of Turbo. In the meantime, think of all the fun you'll have moving files about from within 1-2-3 (tm) that you could never access before! F6 - Rename a File ================== PARTNER makes it easy. Touch F6, you will be prompted for a new name. Type any name you wish, including a sub-directory that may be different from the one you are displaying. The file will be renamed and, possibly, moved from one sub-directory to another in the process. You must type a full filename. No wildcard constructs are allowed. F8 - "Log into a new Sub-Directory" =================================== Each window refers to a default drive and sub-directory. When you access a window for the first time, the directory and drive default to the one in use in the "invoking window". This makes it easy for you to set up some defaults to quickly obtain directories and perform file maintenance work for sub-directories without having to type-in the whole tree-structured name for most accesses. You change the default value for a window using the F8-Change Directory command. When you press F8, PARTNER prompts you for the name of a new directory. You enter a new directory and optional drive designator in the usual DOS format, eg: d:\sub1\sub2\sub3 Now all directory requests made in this window will, by default, refer to this "path". But, you can override this at any time when providing a new search request after striking the Enter key. For example, suppose you had entered this in response to the F8-Change Directory prompt: d:\wv\correspondance All further requests in this window that do not specify a drive- letter and path will revert to d:\wv\correspondance. But, you can enter any other drive, path and filename to temporarily override this when requesting a directory display by striking the Enter key. If you think about it, that's exactly the way DOS operates too. You can specify a default path and drive and yet always override it on DIR requests. Getting a bit technical, remember that if you specify d: and not d:\ the d: request indicates the sub-directory now in default effect and not the root directory on the volume. Of course, if all this is complicated and you really don't use a lot of sub-directories you can ignore all of this and just stick to using drive letters. Remember that a window can have a particular drive letter as its default if you just respond with d: to the F8-Change Directory prompt. The default directory and drive are always shown on the 25th line of the display. You are referring to this when you do not specify an override. F10 - More Information ====================== F10 - More displays detailed information about the file's size, timestamp and attributes. F9 - Display (Type) the File ============================ A handy feature ... a quick touch of the F9 key will open a window and display the ASCII contents on the screen. If you use this on non-text files it could send your display awry. PARTNER - Some Technical Notes ============================== PARTNER was written to demonstrate how to use Turbo Pascal's interrupt, BIOS and MS-DOS access facilities. Principally, o PARTNER attaches the keyboard interrupt, when permanently loaded as part of DOS, and watches for the shift-F9 keystroke. o It saves the registers and manipulates the stack so that the CPU can run in "Turbo space". o It carefully ensures that the external environment including the registers, screen and Disk Transfer Area (DTA) are left un-altered when control is finally returned to the interrupted program. Of course, files may have been removed, re-named or copied. o PARTNER sometimes terminates if you get a device timeout on a non-ready disk drive. This can occur if you do a directory on a drive letter that is defined but not ready (eg: non-existant RamDisk). If you reply "I" to ignore the error several times you may clear it. Responding "A" to abort will return you to the DOS command prompt terminating your application too! We don't like it either but we thought we'd be honest and warn you. We'd welcome any thoughts on how to easily improve this. PARTNER intercepts the keyboard interrupt vector (vector[$09]). However, it must "call" the BIOS keyboard handler each time a keystroke occurs so that the BIOS can decode the input ScanCodes and place the character into the DOS keyboard buffer. To perform the "call", the original contents of vector[$09] are stored in vector[111] and accessed via an Int 111 instruction. If the use of vector[111] conflicts with some hardware or other software you have installed, you can obtain the program source and change this to some other un-used location. PARTNER could have a lot of extra bells and whistles. In fact you might want to obtain the program's Turbo (tm) source code and try adding them yourself. We kept it as small as we could since we wanted to run it most of the time yet not have PARTNER be the dominant application in the machine. PARTNER requires some 52k of memory by default. Actually, the maximum it can use for the time being is 64k since that is the limit imposed by the DOS $27 lock-program-in-core interrupt service. Each window invocation requires about 5k (equivalent to $138, 16-byte paragraphs in 8088 terminology). Therefore, memory use can be summarized as follows: Turbo runtime routines 11k PARTNER program code 16k Stack / Heap space 25k ----- Total 52k approx You can reduce this by re-compiling the program using Borland's version 2.0 Pascal compiler and specifying a smaller Stack / Heap space. That is, use the following series of keystrokes to set the Options: Key Stroke Means O options C COM file I0 Stack is minimum of 0 bytes A620 Stack is maximum of 25k bytes Q Quit options C Compile to floppy By specifying the A option as a smaller multiple of $138, you can generate a system capable of displaying at most 1, 2 or 3 windows. Remember that the F10-More and F9-Display commands require a full 5k stack-frame to operate within as well. Techniques you might try to reduce memory, at the expense of execution speed, (if you're adventurous) would be to: o write the screen images to a diskfile rather than hold them within the program stack (at a saving of 5000 bytes per panel) o turn some of the procedures into overlays allowing you to write gallons more code at negligible memory cost Both of these techniques would require you to ensure that the original disk was always available (ie: not a floppy) so that it would not overwrite data or load improperly. For those interested in studying the interrupt invocation code: you will notice that Borland's Turbo manual leaves a bit to be desired in terms of completeness in this area. In short, the instructions in Borland's manual flatly don't work! Much more code is needed and the Inline statements incorporated within PARTNER provide a proper, "cookbook" solution. See the March-June '85 issues of Tug Lines for a description or contact the author. Incompatibilities ================= PARTNER was written as an educational exercise ... and that it was. We found lots of areas where additional sophisticated programming would be required to make it work perfectly in all cases. PARTNER works by replacing the DOS keyboard interrupt vector with the address of its own code. Early during execution of the interrupt procedure, PARTNER calls the "original vector" to ensure that whatever was supposed to happen before happens too. That's why keyboard I/O works at all with PARTNER running. In this way, PARTNER acts as an interceder ... getting into the middle of the action but not taking part unless it specifically sees the shift-F9 sequence. Consequently, it is comptatable with lots of programs. However, we know of the following problems: 1. Bruce and James' WordVision and SmartTerm 100 also choose to execute when a keyboard interrupt occurs ... but they, unlike PARTNER, don't act as interceders - they take the interrupt for keeps and do not pass control to other programs that may have intercepted the interrupt vector. Consequently PARTNER never gets a chance to see the interrupt and is locked out until the programs terminate and restore the vector's contents. You can use PARTNER with these programs but it won't be accessible again until you terminate them. 2. Prokey(tm) (from RoseSoft) is a little more consistent in that it too acts as an interceder. The two work together ... for a while. Finally one or the other seems to mix up the "true" contents of the keyboard's interrupt vector, causing a loop and a re-boot is required. Don't use PARTNER in conjunction with ProKey. 3. SideKick from Borland is a truly interesting case. Sidekick handles the problem posed in case 1 since it periodically examines the contents of the keyboard vector (presumably from within the timer interrupt) and forcibly restores its own address over anything else that was there (in vector[$09]) if some other program has possessed the audaucity to change it ! Sidekick, having thus ensured it will always control the keyboard, kindly passes control down the keyboard interrupt chain if it doesn't want to react to the keys pressed. Great, SideKick works from within WordVision ! However the bad news is that the wholesale confusion over exactly who own the hardware vector address, what its contents really should be when various programs terminate and what to restore it to at any given time when returning from the interrupt handler causes the machine to lock up in a series of mysterious ways after operating for a while. Don't use PARTNER in conjunction with SideKick and especially don't use it in conjuction with SideKick + WordVision + ProKey. 4. PARTNER seems to work fine with DOSEDIT ... that little guy obeys the rules. (DOSEDIT is a bulletin board program that provides enhanced editing capabilities on the DOS command prompt line). You can use PARTNER with DOSEDIT. 5. No problems from within: BASIC watch out for 40-column screens 1-2-3 watch out for the graphics screen Turbo that's why we wrote it because Turbo, excellent environment that it is, can't do this stuff when you really, really need it.