___/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.  (The requested user
number is now stored - in ASCII! - in the print string
displayed on exit. I removed the silly, buggy,
"educational" routines for converting and displaying
the user number - this is supposed to be a utility,
isn't it? - b/m, v1.1)


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


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...
	  (unfortunately, this tip only works for
	  CP/M Plus, CP/M 2.2 users will have to
	  use the Plu*Perfect Systems PUBlic patch
	  on their BDOSs and declare XUSER.COM as
	  a PUBlic file - b/m, v1.1)
	- 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...
	  (PUBlic is a much better solution for 2.2
	  users, DUPUSER by Bruce Ratoff can also be
	  do the job in the less elegant manner of
	  the WestWind utility,  Mike Rubenstein's
	  SETDRU is another worthy method - b/m, v1.1)
_  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .  _  .

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 Areas, I had to get to them
from within MBASIC and dBASE... coming soon!


                     PAX,

                     John Evancie
                         07-22-85

Notes for version 1.1 added by Bruce Morgen, 9/25/85.