___/Documentation for XUSER.COM  by John Evancie\___

    FOG contribution, July, 1985

_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .

  What is XUSER.COM?

It is a program to emulate and extend CPM's built-in
USER function, allowing access to areas 0 thru 31, 
inclusive. CPM version 2.0 or higher is required.

_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .


  Why is it needed?


If you work with user areas, you may be interested
in this program for two reasons:

	- it extends the range of areas open to you

	- it emulates the built-in USER function,
	  so you can reach it from within an 
          application that restricts you to external 
          commands (e.g., WordStar's "R" option)


_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .


   How is it used?


Simple! Just type:


 XUSER nn<cr>

   This will switch you into User Area nn, for
   nn between 0 and 31, inclusive; if nn is 
   omitted, you are returned to User Area 0.
   (that <cr> means press RETURN)

You can execute this command at the A> prompt, or 
from within WordStar (via the "R" option)

_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .

   How does it work?


The program makes use of BDOS function call 32 to
set and then get CPM's current User Area. First the
command line is checked, and the target user area is
extracted and stashed in the E register. BDOS # 32
is called to set the new area. Then, as a check on
our work, and to illustrate both uses of #32, it is
called again to ask CPM what area we are in. The 
result is stored in the A register, where the pro-
gram converts and displays it (with thanks to B. D.
DePaola and R. S. Burkey, PORTABLE COMPANION, Dec.
82/Jan 83, pgs 50-53).


_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .


N O T E S:

	- Before implementing this program, you must 
          use STAT to declare XUSER.COM to be a 
 	  system file (i.e., STAT XUSER.COM $SYS),
	  so that CPM can still find it when you 
	  wander off into some exotic area...

	- also, any application that invokes XUSER
	  must have an image in the target area, or
	  CPM will not find its way back to your
	  application. I use my WestWind(tm) utility
	  DISKMGR to establish multiple directory
	  entries referring to the same data blocks
	  on the disk; one could also use DU or SID
	  to set up such entries...

_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .

I hope that you find this as useful as I have. It is
a small trade for all the truly spectacular public
domain gems that FOG members have shared, and cont-
inue to share. 

My next submittal is going to be in a similar vein;
once I started using User Area, I had to get to them
from within MBASIC and dBASE... coming soon!


                     PAX,

                     John Evancie
                         07-22-85