Category : Miscellaneous Language Source Code
Archive   : SWITCH26.ZIP
Filename : SWITCHCL.DOC

 
Output of file : SWITCHCL.DOC contained in archive : SWITCH26.ZIP





























Switch!
Copyright (C)1988-1989 By Curtis Little
All Rights Reserved













For IBM PCs XTs ATs and PS2s or 100% Compatibles
Supports EMS (3.2+)




Clipper is a trademark of the Nantucket Corp
dBASE is a trademark of Ashton-Tate
FoxBase is a trademark of Fox Software
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.
StarLan is a trademark of AT&T
NetWare is a trademark of Novell


















Chapter 1

Switch! Features


Switch! has a large number of features that make it the best
memory switching function available at any price. After you see
what Switch! can do I believe you'll agree that Switch! is
setting the new standard for memory switching programs. The
features currently supported by Switch! are:

* Switch! to EMS or disk!

(NEW)* Automatic detection of interrupts in areas to be
deallocated for the child process - Returns an error
indicator if there's a problem instead of leaving your
computer in an UNSAFE state!

(NEW)* Automatically handles several of the interrupts so you
don't have to shut them off first!

(NEW)* Automatically saves ALL interrupt addresses and then
restores them AFTER the child process is complete.

(NEW) Handles up to 40 MCBs!

(NEW) Allows you to specify the path and/or the filename to
use for the temporary file.

(NEW) Has a built in fatal error handler!

(NEW)* The minimum size of the application that remains
resident was reduced by 30% with the new version
Switch!. (Test based on one of the demo programs
compared with the same demo linked with the new version
of Switch!).

(NEW) Saves extended handle table.

(NEW)* Allows a command line of up to 127 characters counting
the trailing carriage return.

(NEW) Switch! now has a utility function that returns the
error level of the last child process ran by Switch!

(NEW) Switch! has functions to allow you to turn on/off (or
read the current setting) the flag indicating whether













it should automatically restore the drive and directory
after the child program is finished.

(NEW) New versions of Switch! have been developed to support
dBASE III+, FoxBase, and dBASE IV!!!!

(NEW) A path specification is allowed now instead of the
drive making Switch! compatible with Netware and other
networks other than StarLan which I use. (The path
specification allows you to specify the drive,
directory, filename, or any combination of the three
for the temp file.)

(NEW)* The path specification can have multiple paths
specified similar to the DOS search path!!!!

(NEW)* Switch! has a flag (settable by a utility function
provided) that tells it whether it's ok to overwrite a
filename you SPECIFY for the temp file. (Switch!
doesn't EVER overwrite a file if you don't specify the
name).

The features marked with a '*' are features I haven't seen in any
other available memory switcher to date. All these features
clearly make Switch! the leader in the memory switching field.
Try the new version, I believe you'll be impressed with what you
see!






























Page 2 Switch! - Clipper Version User's Guide














Chapter 2

Introduction


2.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 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, and if you do link it in you will be missing
half the power Switch! provides.


2.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.


2.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 enough EMS (3.2+) to store the switched application.




Chapter 2, Introduction Page 3








2.4 Languages Supported


Switch! supports QuickBASIC, MS BASIC, IBM BASIC, C, Assembly,
Turbo Pascal, dBASE III, FoxBase, dBASE IV and Clipper
applications.



















































Page 4 Switch! - Clipper Version User's Guide














Chapter 3

Registering Switch!


The demonstration version of Switch! along with this
documentation can be freely copied and shared with
others. Although the demonstration version of the software may
be freely distributed in UNMODIFIED form it is still copyrighted
software which the author supports.

The demo version provides you a way to test software before
spending your money. This helps you get more for your dollar by
allowing you to "test drive" the software before paying.

The cost of registering Switch! depends on what you want. Please
see the file SWITCH.REG for a price list.

NOTE: The demonstration version of Switch! is limited to only
allow up to two calls. After the demo version of Switch! has
been called two times it will no longer attempt to Switch! until
you reload your application. This limitation is ONLY in the DEMO
version of Switch!. The registered version has no such
limitation.


3.1 Registration Benefits


Registering Switch! provides the following benefits:

o You'll receive a disk containing a non-demo version of
Switch!. Two OBJ files are provided for each language you
order Switch! for. The first OBJ has the top line
banners, and the second doesn't.

o No royalty fees!!

o Once you've registered Switch! you are free to use it in
any future EXECUTABLE applications you develop.

o Free upgrades.

o Bulletin Board Support.







Chapter 3, Registering Switch! Page 5








3.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 registration for the business
is enough). If Switch! is used in commercial applications I ask
that I be given credit in the program documentation for
developing the Switch! part.

NOTE: If you need a custom version of Switch! please give me a
call. I'll be happy to accommodate any requests for customized
versions that I can.












































Page 6 Switch! - Clipper Version User's Guide














Chapter 4

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. By using Switch! you acknowledge that
you have read this agreement, understand it and agree to be bound
by it's terms and conditions.

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.

You may not give away or sell the non-demo version of Switch! in
object form (or any form from which the object code can be
derived). You may incorporate the object 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 (or format that object code can be derived
from) 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).

You may not transfer in whole or in part the possesion of Switch!
to any other person or entity without the prior written consent
of the author (Curtis Little).

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!.










Chapter 4, License Page 7














Chapter 5

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, LOST SAVINGS, COMMERCIAL
DAMAGE, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT
OF THE USE OR INABILITY TO USE SWITCH! EVEN IF THE AUTHOR (Curtis
Little) OR AN AUTHORIZED DISTRIBUTOR OF SWITCH! HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER
PARTY.

This agreement shall be governed by the laws of the state of
California.





















Page 8 Switch! - Clipper Version User's Guide














Chapter 6

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 Clipper applications. Afterwards the details for
calling Switch! will be covered followed by an explanation of how
to link Switch! in with your programs.


6.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 |
| | | |
+--------------+ +--------------+



Chapter 6, Using Switch! Page 9








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.

Simply put, that's what Switch! does. There are a lot of options
available, and several utility functions provided with Switch! to
control how Switch! operates.


6.2 Using Switch!


The prototype for Switch! is as follows:

** For the Clipper Version **
SWITCH87( [paths] [,memrequired] [,command_line] )

The parameters and meanings are:

PATHS - This parameter specifies the path(s) to try to create
the temp file on. This parameter has the same format as the
DOS search path. For example, you can specify multiple paths
as follows:

mPATH = "C:\SWITCH;C:\;D:\STUFF"
^
|
NOTE: Each individual path specification
is seperated by a single ;

Each seperate path specification within this parameter can
contain the drive, directory, file name, or any combination of
those three. For instance, if you wanted Switch! to call the
temp file SWITCH.$$$ and store it on the C: drive the
specification would be:

mPATH = "C:SWITCH.$$$; ... ETC "

If you don't specify the filename in the path Switch! will create
a temporary (and yes this works under DOS 2.X also!) file making
sure no file is overwritten. However, if you specify the
filename Switch!'s behavior depends on the setting of the
overwrite flag (See the subsection 'Utility Functions' on page 13
for information about setting the overwrite flag). If the
overwrite flag is turned on Switch! will automatically overwrite
the file you specified if it exists. On the other hand, when the
flag is off Switch! will NOT overwrite an existing file, instead
it will consider that path invalid and check the next specified
path (or return error #5 if no more paths were specified).
Because of the possibility for lost data when a file is




Page 10 Switch! - Clipper Version User's Guide








overwritten this flag defaults to OFF, but you can change it at
any time using the SETOVWR() function provided with Switch!.

You may be wondering why you'd ever want to use the multiple path
feature supported by Switch!. To show one use of this I'll
explain an example. Let's say you have a system with a hard
drive called C:, and a 384K ramdrive called E:. Since Switching!
to the ramdrive is many times faster than Switching! to the hard
drive you'd naturally prefer to Switch! to the ramdrive.
Consider what happens if Switch! is asked to save more memory
than can fit on the ramdrive. If you only specified to go to the
ramdrive Switch! would have no alternative except to return an
error saying the ramdrive doesn't have enough space for the temp
file. To get around this problem and cause Switch! to use the
ramdrive when possible you can specify a path with the ramdrive
specified first followed by the harddrive. For example:

mPATH = "E:;C:"

The path shown above would cause Switch! to try the ramdrive and
if it failed Switch! would try the C: drive next.

Switch! tries the path specifications in the order you specified
them until it finds one that it can store the temporary file to.

If you want Switch! to attempt to create the temporary file in
the current directory before trying other paths simply put a
semi-colon as the first character in the path. For instance:

mPATH = ";C:\SWITCH\"

The above path specification causes Switch! to first try creating
the temp file on the current drive and directory, and then try
the C:\SWITCH\ directory if unable to create on the current
drive/dir.

Note that this parameter is not used if enough EMS is available
to Switch!

This parameter is OPTIONAL with Clipper. If you don't specify
the paths parameter Switch! assumes the current drive and
directory.


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.

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 the




Chapter 6, Using Switch! Page 11








program to run needs 64K and there is already 60K free memory
Switch! will only free 4K to reach the amount specified.

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.


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

The command line can be ANY valid DOS command line. Switch!
treats the command line as if it were typed at the DOS prompt.


NOTES: The command_line can be a MAXIMUM of 126 characters. If
the command_line parameter is longer than 126 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.


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. Note that if you use multiple paths
Switch! will only return an error having to do with no disk space
etc. if none of the specified paths can be used.

When Switch! returns to your application it can optionally
restore the drive and directory that were current when it was
first called. There is a flag that tells Switch! whether or not
it should restore the directory. At default this flag is turned
off. Please see the subsection titled 'Utility Functions' for
information on how to set the restore directory flag.

6.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!. Be aware that any parameters passed must be in the
same order as shown in the prototype above. For instance, to
call Switch! and only specify the memrequired and path
parameters:

CORRECT: SWITCH87( mPATH, mMEM )




Page 12 Switch! - Clipper Version User's Guide








INCORRECT: SWITCH87( mMEM, mPATH )

The second example is incorrect because when the path is
specified it MUST come before the memory specified as shown in
the Switch! prototype.

6.2.2 Utility Functions

Switch! has several utility functions provided with the Clipper
version to allow you to configure how Switch! operates and
retrieve the error level returned by the child process.

The utility functions are:

CHILDRET() - Returns the error level of the last child
process executed while Switched! out.

SETOVWR() - Sets the value of the overwrite flag.

GETOVWR() - Gets the current setting of the overwrite flag.

SETRESTDIR() - Sets the value of the restore directory flag.

GETRESTDIR() - Gets the current setting of the restore
directory flag.

The following describes the utility functions in detail.

----------------------------------------------------------------

CHILDRET( )

This function gets the value of the last child process executed
from Switch!.

RETURN VALUE: This function returns an integer value. A return
value of -1 indicates that no child processes were executed by
Switch! (this also happens if you call a DOS shell and the user
doesn't execute any programs while in the DOS shell). Any other
value indicates the error level of the LAST child process
executed by Switch!. Note that if you call Switch! to do a DOS
shell and the user executes more than one program while in the
shell this function will only return the error level of the last
one executed!

----------------------------------------------------------------

SETOVWR( [flag] )

This function sets the value of the overwrite flag. The
overwrite flag is only used if you SPECIFY A FILE NAME for the
temp file that already exists. If the overwrite flag is ON and
you specify a file name that already exists it will be




Chapter 6, Using Switch! Page 13








overwritten by Switch!. At default the overwrite flag is turned
OFF to avoid data loss.

INPUT: The value expected as input is a logical value. A value
of .F. means turn the flag off while .T. causes the flag to be
turned on.

This parameter is optional with Clipper, and if not specified it
defaults to turn the flag OFF.

RETURN VALUE: The return value of this function has no meaning.

----------------------------------------------------------------

GETOVWR( )

This function gets the current setting of the overwrite flag.
See the discussion for SETOVWR() for information on what the
overwrite flag is.

RETURN VALUE: The value returned is a LOGICAL value. .T.
indicates the overwrite flag is currently ON, while .F. indicates
it's currently OFF.

----------------------------------------------------------------

SETRESTDIR( [flag] )

This function sets the value of the restore directory flag. When
the restore directory flag is ON Switch! will automatically
restore the drive and directory that were active before the child
program was executed. At default this flag is OFF.

INPUT: The value expected as input is a logical value. A value
of .F. causes the restore directory flag to be turned off. A
value of .T. causes the restore directory flag to be turned on.
If you don't specify the flag parameter a default of .F. is
assumed.

RETURN VALUE: The return value of this function has no meaning.

----------------------------------------------------------------

GETRESTDIR( )

This function gets the current setting of the restore directory
flag. See the discussion of SETRESTDIR() for information about
what this flag does.

RETURN VALUE: The value returned by this function is a logical
value. A return value of .F. indicates the flag is off, a return
value of .T. indicates the restore dir flag is currently ON.





Page 14 Switch! - Clipper Version User's Guide








6.2.3 General Information

Currently the Clipper function only works with the Summer 87
version of Clipper. If there's a demand I'll see about getting
it interfaced with the Autumn 86 version of Clipper.

6.2.3.1 Interrupts

Handling of interrupts is something that the new version of
Switch! makes easier for you. Switch! now automatically checks
to see if an interrupt lies in an unsafe area of memory, and if
one is found to be unsafe Switch! will return an error letting
you know. There are a couple of limitations to this feature of
Switch! however. First, Switch! only checks interrupts 0 - 28h.
Second, Switch! can detect if the start of the interrupt handler
lies in an area of memory that would be deallocated, but it
doesn't currently check to see if an interrupt that lies in a
safe area of memory calls any functions that lie in the
deallocated portion of memory (usually the checking Switch! does
is enough, but if you find a case where it isn't you'll need to
turn the problem interrupt off before calling Switch!). Switch!
doesn't bother checking interrupts above 28h because they are
general purpose software interrupts, and aren't usually called by
another application. If you take over interrupts above 28h that
have a possibility of being called by the child program you will
need to turn the interrupt off (restore the previous handler)
BEFORE calling Switch!.

Note that Switch! automatically handles many of the lower
interrupts.

Switch! also AUTOMATICALLY saves ALL interrupt addresses when it
is called and then restores them before returning to your
application. This overcomes problems with any ill-behaved
programs ran by Switch! that change interrupts and never restore
them properly. No interaction is needed on your part. Switch!
is capable of handling the dirty work so you don't have to
.


6.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. The object file for Clipper Summer '87 is called
SWITCH87.OBJ. To link the file in with your application you
simply include the module name on the link line.

An example link for the Clipper version of Switch! might look
like:






Chapter 6, Using Switch! Page 15





plink86 fi SC, SWITCH87 lib \clipper\clipper,\clipper\extend
^ ^
| |
| This is the Switch! OBJ file for Clipper
|
This is the first compiled Clipper module!


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
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.


6.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. The path specification parameter makes it possible to work
with virtually all networks finally! 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
(unless of course you TELL it to!) - 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.






_________________________________________________________________

1. The Turbo Linker ((TM) Borland International) was used with
the demo program for Clipper to come up with the 7-8K value.



Page 16 Switch! - Clipper Version User's Guide








6.5 Should I Switch! to EMS or Disk?


Actually this isn't a question you have to worry about. Switch!
automatically checks 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 attempt to 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.


6.6 Tips on Using Switch!


Switch! can work in most applications, but some will require a
little attention. The new interrupt handling functions added to
Switch! 2.6 make it automatically handle modified interrupts in
most cases. If your program takes over any interrupts that
Switch! isn't able to detect automatically you should either
include the module containing the interrupt handler BEFORE
Switch!, or turn the interrupts off before calling 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
would see that the memory used by the interrupt handler would be
deallocated if it freed all memory possible. Linking Switch! in
this manner will cause it to return an error value indicating
that the interrupt is in an unsafe area of memory if you specify
enough memory to be freed.


















Chapter 6, Using Switch! Page 17














Chapter 7

Switch! Return Values


The value returned by Switch! indicates whether an error
occurred. There are many possible errors that fall into two
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
Warning 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.

Fatal The action suggested for this class is simple - there
isn't any action required by your application. Switch!
has a built in fatal error handler that will print an
error message and drop you to DOS if a fatal error
occurs. In addition the DOS error level is set to the
error number Switch! uses.

Okay, now that I've covered the various classes of errors let's
go over the return values from Switch!.

Return
Value Description
----- -----------
0 No errors occurred. This is what you want!

1 Unable to read file. This means that an error occurred
while reading the temp file back to memory.

2 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).

3 Can't unallocate memory. This means that Switch! can't
deallocate the memory used by your application.

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.


Page 18 Switch! - Clipper Version User's Guide








5 Access Denied. This means that the root directory you
specified for the temp file is full (you really should
consider doing a little file management!). Switch! doesn't
attempt to create the file in the root directory unless you
specify to! This error is also possible if you set the
overwrite flag ON and then specify a name for the temp file
that already exists as a read only file.

6 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).

7 Memory control blocks are damaged. This means it's probably
time to reboot the machine!

8 Not enough memory to reload the original program. This
error could be caused if the user loads a TSR and then exits
back to the first application. .

This error can also mean that there wasn't enough memory to
load a copy of COMMAND.COM to execute the command line. If
control returns to your program it was because COMMAND.COM
couldn't be loaded. The other problem marked as FATAL for
this error causes Switch! to abort the program.

9 Error reading EMS. This error means that an error occurred
while Switch! was restoring the program from EMS.

10 Not enough disk space. This error means the drive to store
the temp file on doesn't have enough free space to save the
file (Switch! checks the disk space before attempting to
create the file).

11 Invalid Drive. This error means the drive specified to
create the temp file on is invalid.

12 Error writing the file. This should never occur since
Switch! checks the drive space before starting, but I check
for this condition just in case.

14 Too many file handles! This means that Switch! can't
properly save the extended file handle table because there
are too many handles in it. Switch! can only handle 255
handles! Out of curiousity how did you get DOS to allow
more?

15 Bad path. This means that the last path specified for the
temporary file has a non-existent directory in it.


16 File exists. This means that the file name you specified
for the temp file already exists. This error is only
returned if the overwrite flag is OFF. When the overwrite



Chapter 7, Switch! Return Values Page 19








flag is ON any file you specify is overwritten without
hesitation .

Any error greater than 255 means that there is an interrupt
that lies in an area that would be deallocated if Switch!
freed the amount of memory requested. To get the number of
the interrupt that is unsafe simply divide the error number
returned by 256. For example:

ret_val = SWITCH87( "", 0 )

IF ret_val > 255
? "Interrupt " + str(INT(ret_val / 256))
? "would be in an unsafe area of memory."




As you can see there are quite a few different return values.
Luckily the odds are against the fatal errors occurring (but they
are possible).





































Page 20 Switch! - Clipper Version User's Guide














Chapter 8

Background


There are several reasons why I developed Switch!. The most
important reason is that a lot of the work I do involves large
data base applications in a network environment. By the time you
add in the memory required by the average Clipper 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.



































Chapter 8, Background Page 21

































































Page 22 Switch! - Clipper Version User's Guide














Appendix A

Example Call to Switch!


This appendix will show an example of calling Switch!.

Clipper Example:

**
** The path specification listed next tells Switch!
** to first try creating the file on the C drive in
** a directory called \SWITCH using a file name of
** SWITCH.$$$. If unable to create the file there
** Switch! will then try the current directory of
** the D drive, and if unable to use the D drive
** Switch! will try the current directory of the
** E drive. If unable to create the file on all
** of the specified paths Switch! will return an
** error (the error specifically says why it couldn't
** create the file on the LAST path specified).

path = "C:\SWITCH\SWITCH.$$$;D:SWITCH.$$$;E:SWITCH.$$$"

memrequired = 64 && insure 64K is free

** Turn off the overwrite flag to insure we don't
** overwrite an existing file.
SETOVWR( .F. )

** Turn on the restore directory flag to cause Switch!
** to restore the current drive and directory when it's
** finished
SETRESTDIR( .T. )

** Now call switch87 to execute TED to edit names.txt
** This is the magical moment we've been waiting for...
switch87( path, memrequired, "TED names.txt" )

** Now you'd have whatever code you wanted to execute after
** the child process is called.










Chapter 1, Example Call to Switch! Page 23








Please see the demo program included with Switch! to see another
example of calling Switch! from a Clipper application























































Page 24 Switch! - Clipper Version User's Guide














Index


C G
calling Switch! getting
examples 23 error level of child
child error level 13 13
Clipper overwrite flag 14
example link line 15 restore directory 14
function name 10 getting child error
version supported 15 level 13
command_line parameter getting options 13
12
configuring Switch! 13 I
considerations interrupts
interrupts 17 special
considerations 17
D
description L
of parameters 10 languages supported 4
directory License agreement 7
restoring 12 link line
drive parameter example for Clipper
meaning 10 15
Linking Switch! to
E applications 15
EMS
support for 9, 17 M
use of 17 memory
error level freeing more 16
getting 13 tips to free more 16
getting childs 13 memrequired parameter
example 11
calls to Switch! 23
link line for N
Clipper 15 name
function for Clipper
F 10
flags name for Clipper 10
overwrite 13 Network use 16
restore directory 14
freeing O
more memory 16 object files
functions linking 15
utility 13 optional
parameters for
Clipper 12




Chapter 1, Index Page 25








options S
getting 13 setting
setting 13 overwrite flag 13
overwrite flag restore directory 14
getting 14 setting options 13
setting 13 Switch!
tips 17
P use on a network 16
parameters Switch! parameters 10
Clipper notes 12 Switch! return value 12
command_line 12 Switch! return values
drive 10 18
memrequired 11 system
parameters for Switch! requirements 3
10
U
R Utility functions 13
requirements
system 3 V
restore directory 12 version
getting 14 Clipper supported 15
setting 14
return value W
for Switch! 12 Warranty 8
return values
meanings 18































Page 26 Switch! - Clipper Version User's Guide














Contents



Chapter 1 Switch! Features 1

Chapter 2 Introduction 3
2.1 What you should read . . . . . . . . . . . . 3
2.2 Ok, Back to the Introduction . . . . . . . . 3
2.3 Program Requirements . . . . . . . . . . . . 3
2.4 Languages Supported . . . . . . . . . . . . . 4

Chapter 3 Registering Switch! 5
3.1 Registration Benefits . . . . . . . . . . . . 5
3.1.1 Registration for Businesses . . . . . . 6

Chapter 4 License 7

Chapter 5 Warranty 8

Chapter 6 Using Switch! 9
6.1 How It Works . . . . . . . . . . . . . . . . 9
6.2 Using Switch! . . . . . . . . . . . . . . . 10
6.2.1 CLIPPER NOTES . . . . . . . . . . . . 12
6.2.2 Utility Functions . . . . . . . . . . 13
6.2.3 General Information . . . . . . . . . 15
6.2.3.1 Interrupts . . . . . . . . . . . 15
6.3 Linking Switch! in Your Applications . . . 15
6.4 Switch! on a Network . . . . . . . . . . . 16
6.5 Should I Switch! to EMS or Disk? . . . . . 17
6.6 Tips on Using Switch! . . . . . . . . . . . 17

Chapter 7 Switch! Return Values 18

Chapter 8 Background 21

Appendix A Example Call to Switch! 23

Index 25












i




  3 Responses to “Category : Miscellaneous Language Source Code
Archive   : SWITCH26.ZIP
Filename : SWITCHCL.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/