:gdoc sec='IBM INTERNAL USE ONLY' :frontm :titlep :title.FlashDOS Version 2.1 :title.DOS Gateway :title.User's Guide :title. :title.(For IBM AT,PCC,PS2) .*etitle. :date.Jul 26,1989 :author.Pedro E. Colla :author.VM(MARVM1/COLLA) :address :aline.Application Development & Maintenance :aline.Martinez Plant :aline.IBM Argentina :eaddress :etitlep .* :toc :body. .*--- NEWS .*--- Introduction :h1.Introduction :p.:hp2.FlashDOS:ehp2. is a Resident program that lets the user to access the DOS environment from inside other applications. :p.The functional principle is to start a secondary DOS Command Processor from a TSR program. :p.Once under the secondary command processor, any DOS command or program could be runned as like as from the regular DOS prompt subjected to the memory available. :p.In this way a simplified form of serial multitasking is possible. :p.An option is provided to attach any non-TSR program to the :hp2.FlashDOS :ehp2. execution, provided that sufficient memory is allocated at loading time it can be invoked as a regular TSR. :p.:hp2.FlashDOS:ehp2. is NOT a multitasking environment nor an aplication switcher. .sp 2 :p.Some of the features are: :ul. :li.PopUp using a Hot-Key (Alt-BackSpace). :li.Both in-memory and swap to disk options available. :li.Memory reserved can be shrinked down to a minimun of 16K under user request when this resource is needed to another task (Memory swap only). :li.Memory allocation can be changed after initial installation. :li.This Program is carefully designed to avoid conflict with another TSR's on machine and other packages. :eul. .*--- Hardware and Software requirements. :h1.Hardware and Software requirements. .sp 2 :p.:hp2.FlashDOS:ehp2. uses 17K for its own code and a minimun of 40K to let a secondary processor to start and execute internal commands (such as DIR or COPY), so virtually any true IBM PC/PS should qualify to use it. :p.At the start the program will take care of any environmental or PC installation factor that could impact it. :p.See appendix for detected hardware/software incompatibilities. :p.To run a specific program instead of regular DOS Command Processor an adequate amount of memory must be allocated. :p.DOS 3.0 or greater is adequate to run this program. :h1.Using the program. :p.The following sections deals with several aspects related to the program like it scope, use and technical details. :p.I expect that this information would be sufficient to any user but any additional information can be surveyed from a brief walkthru around the code. .*--- Invocation :h2.Invocation :p.:hp2.FlashDOS:ehp2. can be invoked by just enter :hp2.FLASHDOS:ehp2. at DOS prompt. :p.After :hp2.FlashDOS:ehp2. is invoked the program will run some housekeeping code like: :ul. :li.DOS Version Checking. :li.Ensure that not another copy of the program is already loaded. :li.Validate and process specified command switchs. :li.Allocate required memory workspace (Internal memory swap only). :li.Trap required interruption handlers. :li.Become a TSR extension of DOS. :eul. :p.The user could tell the program to work with an internal or external workspace. :p.On the internal workspace option a block of memory (user specified, default 64K) are reserved in top of its own code needs netting up around 80K. :p.If external (disk) swap option is specified, no memory is reserved and the workspace is made swapping the current application in memory (or part of it) to disk, provided that enough space is available on any of the defined drives (including RAM-Disk such as VDISK). :p.Also, the program lets the user to specify configuration options by means of 'switches' passed as a parameters. :p.Using switches the format is: .fo off +------------------+ | | |FLASHDOS /{switch}| | | +------------------+ .fo on :p.Where {switch} may be the following: :ol. :li.:hp2.A:ehp2. Switch. :p.This switch tell :hp2.FlashDOS:ehp2. to search for a copy of itself in memory and if it is inactivated try to activate them. :p.The workspace is claimed back and if it cann't a message error is given and the program remains on inactive state. :p.If there are not a copy of the program installed in memory when this switch is specified an error message is displayed and no action is taken. :p.Example:: FLASHDOS /A :li.:hp2.I:ehp2. Switch. :p.This switch tell :hp2.FlashDOS:ehp2. to search for a copy of itself in memory and if it is founded active at this time inactivate them. :p.When become inactive the workspace memory is released and the space occupied is shrinked down to the minimun amount needed to keep the code (around 7K). :p.When in inactive mode :hp2.FlashDOS:ehp2. will not popup upon request and exception given by the installed code acts as if there are not any copy in memory at all. :p.Example:: FLASHDOS /I :li.:hp2.E:ehp2. Switch. :p.This switch tell :hp2.FlashDOS:ehp2. to select :hp2.External:ehp2 swap in which the current application or part of it is dumped to the first drive in which the required space is available. :p.If this switch is not specified the workspace is reserved :hp2.in memory :ehp2. :p.The current application :hp2.must:ehp2. have a memory allocation greater or equal than the amount of memory defined to :hp2.FlashDOS:ehp2. as a workspace size by the user (or default). :p.Example: FLASHDOS /E :li.:hp2.H:ehp2. Switch. :p.This switch tell :hp2.FlashDOS:ehp2. to select the :hp2.Huge Swap Mode :ehp2. in which the current application is swapped entirely to disk at the popup momemnt regardless the workspace indicated by the user. :p.The workspace is allways set as the memory used by the current application minus 256 bytes (16 paragraphs). :p.The external swap mode is also forced when this option is indicated. :p.Example: FLASHDOS /H :li.:hp2.U:ehp2. Switch. :p.This switch tell :hp2.FlashDOS:ehp2. to search a copy of itself in memory and either active or inactive try to desinstall and release the memory used for it. :p.There are some situations where the Uninstall request cann't progress without crash the entire system, in such a situation a message is given and an Inactivation process is started, more of this later. :p.Example:: FLASHDOS /U :li.:hp2.9999:ehp2. Switch. :p.Really not a switch is a way to tell FlashDOS the amount of memory that must be used as a workspace. :p.The memory is indicated in terms of :hp2.paragraphs:ehp2. used as a workspace, a paragraph is the DOS allocation unit and is composed by a fixed quantity of 16 bytes. :p.Using this option if another copy is detected already installed a change in the size of the workspace is attempted, if there are not suficient memory to satisfy the request the program is placed on :hp2.Inactive:ehp2. mode (as if the :hp2./I:ehp2. were invoked). :p.If not specified :hp2.FlashDOS:ehp2. will assume 4096 paragraphs (64K) as a workspace size. :p.The need and optimun size of this workspace is discussed later in this document. :p.If this switch is used and another copy of the program is present in memory the status is checked and if it is :hp2.Inactive:ehp2. an attempt is made to change the size of the workspace area provided that adequate quantity of memory can be released by DOS. :p.If several switches are used specify the size one at last, otherwise the switches after it will be ignored. :p.The number of paragraphs must be informed with 5 digits format, the leftmost positions must be padded with zeroes as needed. :p.Example: FLASHDOS /04096 :li.:hp2.?:ehp2. Switch. :p.This switch tells :hp2.FlashDOS:ehp2. to display a short online help. :p.When using this facility the program is not installed after termination no matter if the program is already installed or not. :P.Example: FLASHDOS /? :li.:hp2.C {d:}{path}{filename}:ehp2. Switch. :p.This switch can be used at loading time to indicate to start an specific task when :hp2.FlashDOS:ehp2. is Poped Up. :p.This switch, if specified, must be used :hp2.only:ehp2. at loading time; if a copy of :hp2.FlashDOS:ehp2. is detected in memory a warning message is given and the indication of the switch are discarded. :p.The task may be a program (.COM or .EXE types) or a .BAT file. :p.The task invoked in this way :hp2.cann't:ehp2. be any kind of resident DOS extension. :p.No check is done at loading time to ensure that the file supporting the task really exist, an attempt to load the program under popup request is made using the drive, path and filename information and if it is not sucefull a error message is given. :p.This parameter can be specified together with the memory size option to specify both initial values in one shot. :p.In such a case the /C switch :hp2.MUST BE:ehp2. specified first, otherwise it will be ignored. :p.Example (1): FLASHDOS /C DEBUG (Will load DEBUG program at popup). :p.Example (2): FLASHDOS /C BASICA /08000 (Will load BASICA with 128K space). :eol. .*--- History :h1.Functional Description. :p.After the short description given above about how to install :hp2.FlashDOS :ehp2. and its main options some functional description is in place. :h2.Usage Notes. :p.The way of do things with a PC could be quite different between my own case and anyone else, the conclusions given below could not be partially aplicable nor not aplicable at all. :p.The vast majority of times that I need to interrupt my work with the PC is to do something trivial, mostly using a DOS command like copy a file from/to anyone else or gives to the already started DOS's PRINT something to print. :p.Also I use to run in this situation one of the zillion utilities that quickly do something and terminate, like shown the directory tree, found a file or set something to anything different than what currently is. :p.I really do not need (nor want) to run several 'power' task at the same time. :p.The rational behind is that I cann't handle several complex things at the same time with a reasonable degree of proficiency. :p.The definitively right mix is a somewhat difficult task and a esporadic trivial thing. :p.In order to load a secondary :hp2.DOS Command Processor:ehp2. a piece of memory must be free (45K minimun). :p.:hp2.FlashDOS:ehp2. have two ways to clear the memory space required; using his own reserved workspace (Internal WorkSpace Option) and swapping to disk part or all the current application (External WorkSpace Option). :p.Both methods will be explained briefly. :h3.Internal WorkSpace Option. :p.This option (assumed as a default) forces :hp2.FlashDOS:ehp2. to reserve at loading time a block of memory given by the user (default 64K). :p.The first thing that the program do when is invoked with the hot key is to release this memory to general DOS use, this ensure that there are sufficient memory space to start a secondary DOS command processor and depending upon the size of the workspace to start another task using it. :p.After termination the space is claimed again and puts under the property of :hp2.FlashDOS:ehp2. again, this action will ensure the next popup request to be sucefully performed. :p.As more large is the space owned by :hp2.FlashDOS:ehp2. a greater program could be started within it, but when :hp2.FlashDOS:ehp2. is not active the space is reserved and cann't be used for anything else. :p.So a tradeoff is in place depending of the kind of task that is expected to be runned while in popup mode. :p.I found myself confortable to work with the default workspace (64K) that was sufficient to cover my usual needs, this is sufficient to let DOS to load the secondary COMMAND.COM and run any of the most common DOS commands or short utilities that I normally use in such a case. :p.For this purpose the internal swap option has the advantage of a very fast switching time and the memory penalization is not too strong. :p.Obviously, the space reserved as a workspace is no longer useful to run other things. :p.If a resident program is installed when :hp2.FlashDOS:ehp2. is in charge a lot of problems should be expected, so this action must be avoided. :p.The initial size of the workspace could be changed once installed to any other greater or lower than the original one, provided that there are enough memory to do that; to change the workspace size the program status must be previously set to inactive. :p.This technique should be used in a spartan way because some memory fragmentation could be expected on each memory size change, at the limit you can convert your PC's addressing space in a lot of small and unuseable chunks of memory and probably the only way to solve this situation is to re-boot the entire system. :h3.External WorkSpace Option. :p.If there are a need to run programs that requires memory spaces bigger than 20-30K probably the selection of the External WorkSpace Option should be used. :p.This option is selected at loading time by means of the :hp2./E:ehp2. switch. :p.Under this working mode :hp2.FlashDOS:ehp2. will only reserve memory space for itself and the video swap buffer, netting up around 14K. :p.When the hot-key is detected and if the conditions are OK to pop-up, a fraction of the current application is swapped to disk and the space is released for general DOS use. :p.In order to swap all the available drives (F: thru A:) are scanned for sufficient space, the first drive with enough space is selected and the memory portion is swapped under the name :hp2.FLASHDOS.SWP:ehp2., this file is created as a :hp2.hidden file:ehp2. so you cann't see this with the normal DOS DIR command, but the decrease in the free disk space will reflect the space used. :p.When the :hp2.FlashDOS:ehp2. session is ended (typing EXIT at the DOS prompt), the memory of the current (interrupted) application is restored back to his original position from the previously created swap file. :p.Upon completion, the swap file is erased. :p.Using this option a bigger workspace size becomes practical, but an excesive allocation for workspace means a bigger switching time. :p.A practical tradeoff is to define a 128K workspace size under this option (/E /08000), with it a 1-5 sec. switching time would be expected. :p.An extension of this mode is the :hp2.Huge Swap Mode:ehp2. in which the workspace size is not defined at load time and the :hp2.entire:ehp2. space used by the current application is used instead. :p.This mode (selected by the :hp2./H:ehp2. switch) could be used to run massive applications under :hp2.FlashDOS:ehp2. , but you would be aware about the switching time that becomes noticeable. :p.Also, this option should be avoided on machines that lacks a hard disk because the swap file will tipically use 500-600K; impossible to handle with a no-hard-disk PC-1 and barely handled with a PCC using an ad-hoc empty 3.50" diskette. :p.A big difference between :hp2.Internal:ehp2. and :hp2.External:ehp2. workspace options is that under :hp2.External:ehp2. you can run any kind of terminate-and-stay-resident kind of program, once finished those programs are wiped out the memory. :p.But, as a balance, when :hp2.FlashDOS:ehp2. is in charge any TSR program loaded after its initial load will be inactive. :p.The amount of memory allocated as a workspace to acomplish a lot of useful task is small, but if one of these packages that need a huge amount of memory is runned the best thing to do is to put the program on inactive status. :h2.De-Installing the program. :p.If the ability to uninstall :hp2.FlashDOS:ehp2. is wanted, this program must be last in the TSR chain, otherwise is far more safe to keep the program in place and inactivate them. :p.To avoid conflicts due to un-installation, :hp2.FlashDOS:ehp2. checks if :hp2.All:ehp2. the interrupts vectors trapped by it still pointing to his segment; if not, the un-installation request is discarded. :h2.Programming Details. :p.The technical aspects involved in writing a program like :hp2.FlashDOS :ehp2. will be probably somewhat dark to the non-technical oriented user. :p.On the other side, for the experienced and technical oriented user the concepts may be a deceptive repetition of a well knowed list of techniques. :p.Trying to write down all the aspects involved in the coding of a TSR program under DOS probably would be far beyond the scope of this manual anyway. :p.The source code of this program is provided with the package in order to let the interested user to walk thru it. :h1.Final Notes. :p.All the :hp2.FlashDOS:ehp2. test was done using DOS 4.0, but the program uses well consolidated functions since DOS 3.1 so I'm not expect any problem if :hp2.FlashDOS:ehp2. is loading under a previous DOS release, provided that it must be greater or equal 3.1. :p.Other PCTOOLS and commercial packages works in a similar way than :hp2.FlashDOS:ehp2. does, but none of it was used partially or fully to develop this program. :p.The program was done in my own time and equipment, some 'user test' was done on my office PS-50 under DOS 4.0 and in my PCC running under DOS 4.0. :p.During the test conflictive situations with another programs was solved or are documented here, but I only tested the program in my usual environments (home & office). :p.The program is :hp2.IBM Internal Use:ehp2. and :hp2.IBM's employees Internal Use:ehp2. :p.Please if you have any comments, compatibility problem or enhancement suggestion don't hesitate to drop me a note. .sp 2 .ce Pedro E. Colla .ce Martinez Plant .ce IBM Argentina .ce COLLA @ MARVM1 .ce 61322772 @ TOROHON1 :appendix. :h1.Messages. :p.Errors are reflected by means of error messages, each message is displayed on certain event. :p.Also, some messages are informative ones, so given to inform the user that something happen. :p.Following is the list of all the messages defined on :hp2.FlashDOS:ehp2. and a short explanation about it meaning. :ol. :li.Invalid Function Code :p.This is an error returned by the DOS Loader when an invocation other than :hp2.Load & Execute:ehp2. or :hp2.Load Overlay:ehp2. is done, never should happen exception given by a corrupted load module. :li.Access Denied :p.An attempt to load a file locked to another purpose was done, try later. :li.Memory Blocks Destroyed :p.The DOS memory control blocks are corrupted, re-boot the computer. :li.Insufficient memory :p.No sufficient memory is available to load the desired program. :li.Invalid Memory Block Address :p.An attempt to access a DOS control block corresponding to an inexistent memory block was done, never should happen exception given by a corrupted load module. :li.Invalid Media :p.The indicated drive contains a media that is not recognized by DOS. :li.Invalid Format :p.The indicated drive contains a media that is unformatted. :li.Protection Exception :p.:hp2.FlashDOS:ehp2. attempted to access a memory zone not belonging to it, reboot the computer. :li.Something wrong occurs :p.An unexpected and unspecified error was founded, reboot the computer. :li.Now Inactive :p.Informative message, tells the user that a copy of the program was founded on memory and now is changed to inactive status. :li.Ended :p.Informative message displayed whenever the popup end. :li.Secondary COMMAND cann't start :p.A COMMAND.COM file is not founded in the path indicated by the COMSPEC variable at load time. :li.Cann't claim memory :p.The amount of memory released at popup time cann't be claimed back, usually because some of the programs loaded lets a resident portion, put on inactive mode and change the memory size to popup again. :li.Not Loaded :p.Informative message displayed whenever the program didn't terminate on a 'stay resident mode'. :li.Loaded sucefully :p.Informative message displayed whenever the program becames a resident DOS extension. :li.Already Loaded :p.Informative message that tell the user that another copy of the program was founded somewhere in the memory, use DOS's MEM utilty with /DEBUG option to check it (DOS 4.0) or PCTOOLS's SYSMAP package. :li.Already Active :p.Informative message, an activation request was done and the copy of the program present in memory was already active, not action is taken. :li.Already Inactive :p.Same as above but for an inactive request when the program is already inactive. :li.Now Active :p.Informative message that tell the user that his Activation request end sucefully. :li.Uninstalled sucefully :p.Informative message that indicates that an un-installation request was done sucefully. :li.Memory area allocated at 9999:0000h :p.Informative message given at first load telling about the starting address of the allocated workspace. :li.Memory size 9999h Paragraphs. :p.Informative message given at first load telling about the size of the defined workspace area. :li.User File Defined :p.This informative message tell the user that a file to execute at popup time (see /C switch) was detected and sucefully processed. :li.Incorrect DOS Level :p.An attempt to load the program under a version of DOS previous to 3.0 was done, the loading end inmediately. :li.Unable to restore Int 09h. :p.An un-installation request was done but the Int 09h point now to somewhere different of the :hp2.FlashDOS:Ehp2. code segment indicating that another TSR program grabbed away the interrupt. :p.The un-installation request is aborted and a regular Inactivation request is done. :li.Unable to restore Int 13h. :p.Same as above but to BIOS Int 13h. :li.Unable to restore Int 21h. :p.Same as above but to DOS Int 21h. :li.Not previously loaded. :p.Informative message, an attempt to change the current status was done and no copy of the program can be founded on memory. :li.Incorrect parameter, type FlashDOS /? for help" :p.An invalid switch was specified. :li.Memory mgmt error. :p.The DOS memory block has been destroyed, reboot the computer ASAP. :li.PSP do not belong to Usr Program. :p.Some problems to identify which program is the main one has been detected. :li.Disk error, Can not swap out. :p.Disk error during the swap process. :li.Not enough space to swap. :p.None of the available drives have enough space to swap the memory required by the workspace. :li.User memory not enough. :p.The current program memory allocation must be equal or bigger than the required workspace memory space, otherwise it cann't be swapped. :li.Can not open swap file. :p.Some problem arises when the swap file open was attempted. :li.Can not swap to file. :p.Some problem arises when the swap file write was attempted. :li.Can not shrink Usr memory. :p.The user memory cann't be shrinked down by DOS. :li.User program swapped OK. :p.Informative message, swap process end sucefully. :li.Can not retrieve memory. :p.The original user memory size cann't be restored to his original size. :li.Can not close swap file. :p.Some problem arise when the swap file close was attempted. :li.Can not erase swap file. :p.Some problem arise when the swap file erase was attempted. :li.Huge Mode Selected. :p.Informative message, the huge mode was selected. :eol. :h1.Detected Incompabilities. :p.The following incompabilities and depart of peaceful co-existence has been detected: :ol. :li.:hp2.MYTE:ehp2. (Migreatable Yorktown Terminal Emulator). :p.For some reason under study MYTE must be loaded :hp2.before:ehp2. FlashDOS, otherwise the first switch to terminal mode the system becames crashed. :p.No problem was detected if :hp2.FlashDOS:ehp2. is loaded :hp2.after:ehp2. MYTE, even on a un-installation request. :li.:hp2.PC-1/PC-XT:ehp2. :p.Several test done on PC-1s and PC-XT under DOS 3.0 thru DOS 3.3 exposed a erratic behavior, frecuently ended with a machine crash. :p.The sympthoms ranges from an sporadic hang-up to a guaranteed crash at the first pop up invocation (even, sometimes, at load time). :p.This kind of behavior are not showed at all on the PCC or the PS-2s in which the program was tested. :p.The reasons for that remains unexplained and are under examination. :li.:hp2.DOS 4.0 SHELL:ehp2. :p.Sometimes after a popup under the DOS 4.0 Shell some extraneous effects appears. :p.Those effects are no consistent nor repetitive and doesn't appear when the internal workspace is used; till the discovery of the reason, if you are a DOS 4.0 Shell beloving user please avoid to use :hp2.FlashDOS:ehp2. with the :hp2./E:ehp2. switch or at least avoid to popup from them. :eol. :p.I check incompatibilites on my working (and home) software environment, so if you detect another one please drop me a note. :h1.Release History. :ol. :li.:hp2.Version 0.1:ehp2. :p.Basic release, alfa test version. :li.:hp2.Version 0.7:ehp2. :p.Beta test version, features added: :ul. :li.DOS Version check. :li.Get COMMAND.COM path from COMSPEC environmental variable. :li.Switch to specify memory workspace other than 64K added. :li.Inactive/Active option. :li.Remove option. :li.Help facility added. :eul. :li.:hp2.Version 1.0:ehp2. :p.PCTOOLS release version, features added: :ul. :li.Change installed memory size option added. :li.Attach a program to popup mode added. :eul. :li.:hp2.Version 2.0:ehp2. :p.Features added: :ul. :li.Wait for a key to be pressed when an error occurs. :li.Option to create the workspace swapping the current application to disk. :li.Swap back and forth the interrupt vector table at popup time. :li.Create a program own stack in order to avoid conflicts with other programs. :li.The screen is not cleared when a program is attached to the :hp2.FlashDOS :ehp2. popup (/C option). :eol. :li.:hp2.Version 2.1:ehp2. :p.Features added: :ul. :li.Huge swap mode added, under it the current application is swapped entirely. :li.Resident code memory usage optimization. :li.Pop-Up error messages optimized. :eul. :egdoc.