Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / PGMUTL / SWITCH22.ZIP / SWITCH.DOC < prev next >

Wrap

Text File | 1989-02-04 | 40.0 KB | 1,387 lines

Switch! Copyright (C)1988, Curtis Little All Rights Reserved For IBM PCs XTs ATs and PS2s or 100% Compatibles Supports EMS (3.0+) Clipper is a trademark of the Nantucket Corp DesqView is a trademark of QuarterDeck MS-DOS/QuickBASIC/MS BASIC are trademarks of Microsoft IBM BASIC is a trademark of International Business Machines Turbo C/TLINK/Turbo Pascal are trademarks of Borland Intl. Chapter 1 Introduction 1.1 What you should read A lot of information about Switch! is in this manual. If you don't want to read everything you should AT LEAST read the entire chapter titled 'Using Switch!'. When you read the chapter 'Using Switch!' pay close attention to the different function names for the various languages supported by Switch! along with the instructions for linking Switch! into your applications. You should also read the license because by using Switch! you are bound by the terms in the license agreement. I personally recommend that you read the entire manual, but if you don't at least read the chapter about using Switch! you're probably going to have problems linking it to your application. 1.2 Ok, Back to the Introduction How many times have you wanted to shell out of one program and execute another only to find there isn't enough memory left? If only both programs could fit in memory together long enough to get the job done... Introducing Switch!. Switch! is a function written in 100% assembly (although Switch! itself is entirely assembly the Clipper version uses C to interface Clipper with Switch!) that allows a large application to load and run another program whose memory requirements are larger than the first application leaves free. Switch! swaps your application to disk or EMS to free memory to load and execute another program. If Switch! had been used in all commercial programs a DOS shell would not be missing from any of them and there would be more than enough memory to load another large application. 1.3 Program Requirements Switch! will work properly with most system setups. The main requirement is that DOS 2.0 or above is needed for proper operation. The other requirement is that a disk must be available that has enough space to save the switched application (or registered versions can use EMS 3.0+ instead). - 2 - 1.4 Languages Supported Switch! supports QuickBASIC, MS BASIC, IBM BASIC, C, Assembly, Turbo Pascal and Clipper applications. There are several OBJ files included that support the different languages as follows: o SWITCH.OBJ - Switch! for C and Assembly. o SWITCH87.OBJ - Switch! for Clipper Summer '87. o SWITCHQB.OBJ - Switch! for BASIC programs. o SWITCHTP.OBJ - Switch! for Turbo Pascal. Be sure to link in the right object file for the language you're using or Switch! will not work properly! 1.5 Models Supported The assembly code for Switch! was designed to support all of the standard memory models, but the shareware version only supports the LARGE model (unless the language being supported REQUIRES a different memory model i.e. the shareware QuickBASIC version of Switch! is in the medium model as required by QB). To get Switch! working with another model you either need to prototype it as far or register to get the source code. The models supported by the shareware version of Switch! are: Language Shareware Model -------- --------------- C/Assembly Switch! - LARGE model. QB, MS B, IBM B - MEDIUM model. Clipper - LARGE model. Turbo Pascal - LARGE model. (Registered users can assemble Switch! to any desired memory model providing you have MASM 5.0 or above). - 3 - Chapter 2 Registering Switch! Shareware is software that can be freely copied and shared with others. Although the software may be freely distributed in UNMODIFIED form it is still copyrighted software which the author supports. Shareware provides you a way to test software before spending your money. This helps you get more for your dollar by allowing you to test the software before paying. The cost of registering Switch! is $20.00. The registration form is in the file called SWITCH.REG. 2.1 Registration Benefits Registering Switch! provides the following benefits: o You will receive a disk containing the assembly source code for Switch!. (MASM 5.0 or above required to assemble the source). The source module can be assembled to support ANY of the languages Switch! works with. o No royalty fees!! o Once you've registered Switch! you are free to use it in any future executable applications you develop. o Bulletin Board Support. 2.1.1 Registration for Businesses My registration policy is pretty lax. If a business registers Switch! the business may use Switch! freely WITHIN the business (I don't want a registration for each machine or each person working in the business - the one $20.00 registration for the business is enough). If Switch! is used in commercial applications (by commercial I mean those programs distributed commercially. I'm not talking about a consultant developing a system for a client.) I do ask that I be given credit in the program documentation for developing the Switch! part. - 4 - Chapter 3 License I am offering you a license to use Switch! on a TRIAL BASIS. Unregistered versions may be used to write programs which will only be used by yourself. Distribution of programs developed with an UNREGISTERED version of Switch! is a direct violation of this license agreement. Registered versions of Switch! may be used by the REGISTERED OWNER to develop programs that may be given away or sold without additional license or fees. The source code for Switch! is provided to registered users to allow development of specialized functions that suit your needs. As a registered owner you have the right to edit or modify the source code for YOUR OWN USE, but you may not give it away or sell it in source or object form (this includes object libraries). You may incorporate the code into your EXECUTABLE programs (which may be given away or sold), as long as your programs do not compete (directly or indirectly) with Switch!. Distribution of Switch! or a derivative of Switch! in object or object library format requires prior written consent from the author (a special license/price agreement can be made to allow you to distribute Switch! in object/object library format. Please write if you're interested in this special license). Businesses, government institutions, and other commercial users of Switch! MUST register. If Switch! is used in a commercial application the documentation must give the author (Curtis Little) credit for the development of Switch!. - 5 - Chapter 4 Warranty With respect to the physical diskette sent to registered owners, the author warrants the same to be free from defects in materials and workmanship for a period of 60 days from the date of registration. In the event of notification within the warranty period of defects in material or workmanship the author will replace the defective diskette. The remedy for breach of this warranty shall be limited to replacement and shall not encompass any other damages, including but not limited to loss of profit, and special, incidental, consequential, or other similar claims. The author specifically disclaims all other warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose and the program license granted herein in particular, and without limiting operation of the program license with respect to any particular application, use, or purpose. In no event shall the author be liable for any loss of profit or any other commercial damage resulting from the use (or inability to use) Switch!, even if the author has been advised ahead of time that the possibility for damage exists. - 6 - Chapter 5 Using Switch! This chapter covers how to use Switch!. Before getting into the details of using it I'll briefly introduce you to what Switch! does for your applications. Afterwards the details for calling Switch! will be covered followed by an explanation of how to link Switch! in with your programs. 5.1 How It Works Switch! works by performing a little "magic" with the way DOS manages memory. When called it attempts to free up the amount of memory the program requires (or all possible if it can't save as much as specified) to disk or EMS. Switch! reduces the resident portion of a program while another is executed by temporarily storing the "parent" program to disk or EMS. After the "child" program is finished the "parent" is read back in memory by Switch! and execution resumes where it left off (resumes at the point after Switch! was called). Let's look at an example of how memory looks before you call Switch! vs how it looks right before Switch! is ready to load the second program. Before Calling Switch! After Calling Switch! (before 2nd program is loaded) +--------------+ +--------------+ | | | | | Free memory | | | +--------------+ | | |Application 1 | | | | (Block 2) | | | |--------------| | | | Free | | | |--------------| | | | Application 1| | Free memory | | | +--------------+ |(First Block) | | Application 1| +--------------+ +--------------+ | DOS Area | | DOS Area | | | | | +--------------+ +--------------+ - 7 - The example above graphically illustrates what Switch! does. As can be seen by the example a lot of memory is cleared by Switch! making it available to the program to be loaded. (Switch! can be called over and over from one application to another without problems!) - To see this execute the demo program and keep telling it to run itself. 5.2 Using Switch! The prototype for Switch! is as follows: (For examples of calling Switch! look in the Appendix at the back of this manual!). You will notice that the function names for the various languages are DIFFERENT! Please call the right one for the language you are using. ** For the QuickBASIC/MS BASIC/IBM BASIC Version ** SWITCH( drive%, memrequired%, command_line$, ret_val% ) ** For the C/Assembly Version ** int switch_( int drive, int memrequired, char *command_line ); ** For the Clipper Version ** SWITCH87( [drive] [,memrequired] [,command_line] ) ** For the Turbo Pascal Version ** SWITCH( drive, memrequired : integer; command_line : string80 ) : integer; The parameters and meanings are: drive - This parameter specifies the disk drive to store the temporary file on. A value of 0 specifies to save the file on the drive that is current when Switch! is called. A value of 1 specifies the A: drive, 2 the B: drive etc... NOTES: The drive parameter is optional for Clipper (all parameters are optional for the Clipper version of Switch!). If this parameter isn't specified it is assumed to be zero. With the registered version EMS will automatically be used instead of a disk file when possible. memrequired - This parameter specifies the amount of K memory required by the program to run. If the value you specify is more than can be saved Switch! will save as much memory as possible. A value of zero also causes Switch! to save all memory possible. NOTES: This parameter is optional when using the Clipper version. If you don't specify the amount of memory required a default of zero is assumed. - 8 - Switch! frees memory in an intelligent manner. Switch! first checks to see if the specified amount of memory is free. If the memory isn't already free Switch! will only free enough memory to reach the amount specified. For instance, if you specify 64K and there is already 60K free memory Switch! will only free 4K to reach the amount specified. command_line - This parameter specifies the command line to execute after memory is saved. For instance, a typical command line might look like: DIR /W /P or TC temp.c NOTES: For the C/Assembly version of Switch! a NULL pointer for the command line causes a DOS shell to be used. I.E. The statement: switch( 0, 0, NULL | "" ) (where either the NULL pointer or pointer to a NULL character is passed) would cause Switch! to save as much memory as possible and then execute a DOS shell. The command_line should be a MAXIMUM of 80 characters. If the command_line parameter is longer than 80 characters the excess is ignored. The command_line parameter is optional with the Clipper version of Switch!. If the command_line isn't specified when calling from Clipper the default DOS shell will be used. ret_val - This parameter is only used with the BASIC version of Switch!. This parameter is used to return the status back to BASIC programs (the BASIC version of Switch! is a subprogram instead of a function to make it compatible with QB 3.0). RETURN VALUE: The value returned by Switch! indicates whether or not an error occurred during the switch. Please see the list of error codes at the end of this document for a description of the different values returned by Switch! along with the suggested actions for each error. 5.2.1 CLIPPER NOTES Since all parameters are optional with Clipper you should be aware of how the parameters you do pass are interpreted by Switch87!. The first numeric parameter encountered is assumed to be the drive. The first character parameter encountered is assumed to be the command_line (parameters following the command_line parameter are ignored by Switch87!). Currently this function only works with the Summer 87 version of Clipper, but should be easy for you to interface with the Autumn 86 version of Clipper. - 9 - 5.3 Linking Switch! in Your Applications Switch! is distributed as an object file. The object file can be linked to applications you develop allowing Switch! to be called as a function. As mentioned several times throughout this document there are several versions of Switch!. The first version that is intended for use in programs written in C, assembly etc.. is called SWITCH.OBJ. The second version for Clipper Summer '87 is called SWITCH87.OBJ. The last version for use in BASIC programs is called SWITCHQB.OBJ. To link the files in with your application you simply include the proper module name for the language you are using on the link line. For example to link SWITCH.OBJ to a C application the command line might look like: link SC.OBJ SWITCH.OBJ,,,C:\MISC\MYLIB.LIB ^ ^ | | | This is the Switch! OBJ file for C/Assembly | This would be the first compiled C module for the program you are writing! An example link for the Clipper version of Switch! might look like: plink86 fi SC,SWITCH87 lib \clipper\clipper,\clipper\extend ^ ^ | | | This is the Switch! OBJ file for Clipper | This is the first compiled Clipper module! An example link for QuickBASIC would be: link SC.OBJ SWITCHQB.OBJ,,,BRUN30.LIB ^ ^ | | | This is the Switch! OBJ file for BASIC. | This is the first compiled BASIC module! Turbo Pascal doesn't use an external linker to link in OBJ files. Instead you declare the function as a far EXTERNAL function and use the $L directive to include the OBJ file. Please refer to the Turbo Pascal manual for details on how to include assembly object modules. Switch! is only able to free memory from the end of itself up. This means that where you place Switch! in the link line will - 10 - have a direct bearing on the maximum amount of memory Switch! will be able to free. For the best results you should write a small program that contains a single line (calling the main module of the program). For example: DO MAINMENU (in Clipper). Then you could specify Switch! on the link line immediately after the small program module. I.E. PLINK86 fi TEST,SWITCH87,MAINMENU ... Creating a small program as explained above will make it possible for Switch! to save as much memory as possible. When linked in 1 like this Switch! can free all but around 7-8K of memory (and you Clipper programmers know how much of a cut that is!). When EMS is used the save/restore of a 640K application is almost instant! Basically speaking the closer Switch! is to the start of the program (i.e. linked in first) the more memory it can free when called. Note that any modules that have interrupt handlers should be linked in the code BEFORE Switch! (See 'Tips for Using Switch!'). 5.4 Switch! on a Network Using Switch! on a Network is not a problem. It can access the network drives without a hitch since DOS is used for the file I/O. In addition there isn't a problem with multiple saves to the same drive because Switch! creates a temporary file (it never overwrites an existing file - instead a unique name is generated). Note that my saying it creates a temporary file doesn't mean that DOS 3.0 is required - it isn't because I wrote my own function to calculate a temporary file name to make Switch! work with older versions of DOS. 5.5 Should I Switch! to EMS or Disk? Actually this isn't a question you have to worry about. Non- registered versions of Switch! will only switch to disk. Registered versions automatically check for EMS memory and if there's enough memory to save the program it goes to EMS. If there isn't any EMS memory (or there isn't enough remaining to switch to) Switch! will create a disk file. This means you don't have to worry about whether the target machine has EMS. Switch! will automatically look for it when called. _________________________________________________________________ 1. The Turbo Linker ((TM) Borland International) was used with the demo program for Clipper to come up with the 7-8K value. - 11 - 5.6 Tips on Using Switch! Switch! can work in most applications, but some will require a little attention. If your program takes over any interrupts you should include the module containing the interrupt handler BEFORE Switch!. For example, assuming the ASYNC.OBJ module contained an interrupt handler: CORRECT: link ASYNC SWITCH,,, (etc...) INCORRECT: link SWITCH ASYNC,,, (etc...) The second example is incorrect because when Switch! is called it could free the memory used by the interrupt handler. While the memory is free an interrupt might be generated causing lockup since the interrupt handler no longer resides at the place pointed to by the interrupt address table. If you are sure no interrupts can occur while you are "Switched!" out there isn't a problem. - 12 - Chapter 6 Switch! Return Values The value returned by Switch! (and Switch87!) indicate whether an error occurred. There are many possible errors that fall into a few classifications of severity. This Chapter lists the return values, their meanings, and severity/classification of the error. The suggested corrective actions are simple. I'll list them by classification. Classification Suggested Action -------------- ---------------- Severe This is the type of error that occurs if Switch! can't successfully write the temp file to disk or EMS. You should either ignore this error or print a message advising the execution of the called program couldn't be completed. (These are Warning indicators). Critical The action suggested for this class of error is simple. You should IMMEDIATELY terminate the program. If a critical error occurs it is unpredictable how much if any of the memory was able to be properly restored. (You shouldn't call ANY functions linked in after SWITCH was in the application). Fatal The action suggested for this class is a reboot of the machine. If a fatal error occurs odds are high that execution will not even be able to get back to the part of the program that called Switch!. Out of the classes of errors listed above there is only one that can be reliably dealt with by your application - Severe. Critical errors may be able to be dealt with, but the odds are going against you. Okay, now that I've covered the various classes of errors let's go over the return values from Switch!. - 13 - Return Value Description ------ ----------- 0 No errors occurred. This is what you want! 4 Too many open files. This means that the DOS maximum number of files that can be open at once is exceeded by the request to open the temp file. The way to fix this is to increase the number of files in config.sys FILES=15, or to close some of the open files in your application. <SEVERE> 5 Access Denied. This means that the root directory of the disk to store the temp file is already full. Switch! creates the temp file in the root directory (the temp file is hidden). <SEVERE> 7 Memory control blocks are damaged. This means it's probably time to reboot the machine! <CRITICAL> 8 Not enough memory to reload the original program. This error could be caused if the user loads a TSR or other program and then exits back to the first application. <FATAL>. 249 Invalid Drive. This error means the drive specified to create the temp file on is invalid. <SEVERE> 250 Not enough disk space. This error means the drive to store the temp file on doesn't have enough free space save the file (Switch! checks the disk space before attempting to create the file). <SEVERE> 251 Error reading EMS. This error means that an error occurred while Switch! was restoring the program from EMS. <CRITICAL> 252 Can't locate COMMAND.COM. This error means that Switch! couldn't locate COMMAND.COM using the COMSPEC environment variable. (COMMAND.COM must be available for Switch! to execute a program). <SEVERE> 253 Temp file is missing on restore! This error means that the disk with the temp file was removed (or the user deleted the temp file). <CRITICAL> 254 Can't unallocate memory. This means that Switch! can't deallocate the memory used by your application. <SEVERE> 255 Unable to read file. This means that an error occurred while reading the temp file back to memory. <CRITICAL> - 14 - As you can see there are quite a few different return values. Luckily the odds are against the critical errors occurring (but they are possible). The odds against the fatal errors are even higher (with the exception of a user possibly loading a TSR while in the "shell"). - 15 - Chapter 7 Background There are several reasons why I developed Switch!. First off, I do systems analysis/programming for a living. A lot of work I do involves large data base applications in a network environment. By the time you add in the memory required by the average application I'm working on with the high overhead for the network software that is resident it is common to not even have enough memory left over to execute a DOS shell (that really hurts the application when you consider that to link to any of the network drives/printers a DOS command needs to be executed). Finally after getting frustrated with 640K not being enough memory I created Switch! to solve the memory shortage problems. - 16 - Appendix A Example Calls to Switch! This appendix will show an example of calling switch for C, assembly, and Clipper. C Example: drive = 0; /* assume current drive */ memrequired = 64; /* free 64K of memory */ /* call Switch! to execute TED to edit names.txt */ switch_( drive, memrequired, "TED names.txt" ); Assembly Example: ; ; This example assumes that DS:SI point to the command line ; to execute with Switch!. ; EXTRN _switch_ push si ;pass parameters in C convention push ds ;(backwards). Push command_line xor ax,ax ;address first. push ax ;push memrequired - 0 means save all possible. push ax ;push drive - 0 means current drive. call far ptr _switch_ ;execute the command or al,al ;check for error jne handle_error ;non-zero return means there was an ;error! Clipper Example: ** In this example I'll duplicate the C example using ** Clipper Code drive = 0 && Assume the current drive memrequired = 64 && Free 64K memory ** Now call switch87 to execute TED to edit names.txt ** Note that although the drive parameter is optional ** and defaults to 0 it is required in this example ** because the memrequired is being specified. Remember the - 17 - ** first numeric parameter is considered to be the drive. switch87( drive, memrequired, "TED names.txt" ) Turbo Pascal Example: (type CLINE is assumed to be defined as a string containing 80 characters!). {$F+} function Switch(drive : integer; mem : integer; command : CLINE) : integer; external; {$L switchtp} {$F-} drive := 0; (* assume current drive *) memrequired := 64; (* free 64K of memory *) (* call Switch! to execute TED to edit names.txt *) switch( drive, memrequired, "TED names.txt" ); The demo programs included with Switch! also show the use of Switch!. - 18 - Index B freeing BASIC more memory 10 example link line 10 function function name 8 name for BASIC 8 BASIC object file 3 name for C 8 C I C interrupts example link line 10 special function name 8 considerations 12 C/Assembly object file 3 L calling Switch! languages supported 3 examples 17 License agreement 5 Clipper link line example link line 10 example for BASIC 10 function name 8 example for C 10 version supported 9 example for Clipper Clipper object file 3 10 command_line parameter Linking Switch! to 9 applications 10 considerations interrupts 12 M memory D freeing more 10 description tips to free more 10 of parameters 8 memory models supported drive parameter 3 meaning 8 memrequired parameter 8 models supported 3 E EMS N support for 7, 11 name use of 11 function for BASIC 8 example function for C 8 calls to Switch! 17 function for Clipper link line for BASIC 8 10 function for Turbo link line for Pascal 8 Clipper 10 name for Clipper 8 name for Turbo Pascal 8 F Network use 11 files object 3 O object files 3 - 19 - linking 10 use on a network 11 optional SWITCH87.OBJ parameters for Clipper 3 Clipper 9 Switch! parameters 8 Switch! return value 9 P Switch! return values parameters 13 Clipper notes 9 SWITCH.OBJ command_line 9 C/Assembly 3 drive 8 SWITCHQB.OBJ memrequired 8 BASIC 3 ret_val (BASIC ONLY) SWITCHTP.OBJ 9 Turbo Pascal 3 parameters for Switch! system 8 requirements 2 R T requirements Turbo Pascal system 2 function name 8 ret_val parameter linking in Switch! (BASIC ONLY) 9 10 return value Turbo Pascal object for Switch! 9 file 3 return values meanings 13 V version S Clipper supported 9 Switch! tips 12 W Warranty 6 - 20 - Contents Chapter 1 Introduction 2 1.1 What you should read . . . . . . . . . . . . 2 1.2 Ok, Back to the Introduction . . . . . . . . 2 1.3 Program Requirements . . . . . . . . . . . . 2 1.4 Languages Supported . . . . . . . . . . . . . 3 1.5 Models Supported . . . . . . . . . . . . . . 3 Chapter 2 Registering Switch! 4 2.1 Registration Benefits . . . . . . . . . . . . 4 2.1.1 Registration for Businesses . . . . . . 4 Chapter 3 License 5 Chapter 4 Warranty 6 Chapter 5 Using Switch! 7 5.1 How It Works . . . . . . . . . . . . . . . . 7 5.2 Using Switch! . . . . . . . . . . . . . . . . 8 5.2.1 CLIPPER NOTES . . . . . . . . . . . . . 9 5.3 Linking Switch! in Your Applications . . . 10 5.4 Switch! on a Network . . . . . . . . . . . 11 5.5 Should I Switch! to EMS or Disk? . . . . . 11 5.6 Tips on Using Switch! . . . . . . . . . . . 12 Chapter 6 Switch! Return Values 13 Chapter 7 Background 16 Appendix A Example Calls to Switch! 17 Index 19 i