Documentation for The XyWWWeb Jumbo Almost-All-Inclusive U2 File, by Robert J. Holmgren and Carl L. Distefano XYWWWEB.U2 (part of XYWEB###.ZIP)


Important: We probably shouldn't make it so easy, nor obscure the interesting details of how each file operates, nor deprive you of documentation — HOWEVER! — we've packaged up all the most important external EXEcutables and DLLs used by U2 in a single 1.3Mb U2UTILS.EXE file, which you can download. See External Files, below, for details. Download this single file, extract it in Editor's directory (command at a DOS prompt: “U2UTILS.EXE<cr>”), and then move SOME of the constituent files carefully to the indicated directory, as described below in External Files. Do it! Use these UPDATED VERSIONS of important files! Don't omit this! It's N-E-C-E-S-S-A-R-Y!

Reminder: Use XyperLinks! They are extremely handy, and extremely fast. They work just like browser hyperlinks, except that they do much more: fetch files from the Internet, jump to a REGistry variable so you can fill in data, open a Web browser on a particular page at a remote website, run XPL and Windows programs, etc. etc. Put your cursor on the XyperLink, and hit <Helpkey>. In most cases, you MUST clear the command line first, otherwise <Helpkey> may try to interpret CMline data as part of the XyperLink, or as superseding the XyperLink.

Reminder: Install freeware cURL (or cURL for OS/2), which is used for file transfers of all types (HTTP, FTP, FILE). cURL is a multi-platform program (runs on almost everything: Windows, Mac OS X, DOS, OS/2, Linux, etc). cURL executables for Windows were included with XYWEB115.ZIP only, for your convenience, but are NOT included in later XYWEB###.ZIPs. Install cURL by placing CURL.EXE in any convenient location, and setting (or adding to XYWWWEB.REG) the new REGistry variable cURL_EXE. See further HELP GetHTTP<Helpkey>.


XYWWWEB.U2 collects most of the enhancements to XyWrite 4, XyWrite for Windows, and NotaBene for Windows available at «XyWWWeb» (http://users.datarealm.com/xywwweb) in a single, easy-to-install User Command Set (U2) file. XYWWWEB.U2 provides the latest versions of code (source Holmgren and/or Distefano) described at the «XyWWWeb» site. A few XyWWWeb programs are not included because they require machine-specific installation, or because they do not operate from U2.

XYWWWEB.U2 is updated from time to time.

Note that, although the current size of XYWWWEB.U2 exceeds 800Kb, the actual consumption of XyWrite available memory is merely 12Kb, due to the incomparable economy of Helpfile indexing. Moreover, by merging into U2 your own personal programming (formerly loaded verbatim by most users), you may release significant memory, for a net reduction of EDITOR.EXE memory overhead. XYWWWEB.U2 is extremely parsimonious about Save/Get and memory usage; although we reserve a large range of two hundred Save/Gets (600-799), at any moment very few of these are in use, and they are emptied (cleared) before routines terminate (see further HELP ClearSgt<Helpkey> in XyWWWeb.INF).

The present documentation provides quick-start directions for installation and use. For a detailed discussion of the why's and wherefore's of our usage scheme, please read PARSEFRM.DOC and REORGaNIZ.DOC. These are old and deprecated documents, so caveat emptor — but familiarity with them may enhance your enjoyment and use of the XyWWWeb routines.

Before You Start
Make sure that Error Help and Command Override are both turned OFF. Since these features are inactive by default, many users will not need to make any change. You can verify your current values by commanding, respectively, VA/NV $EH<cr|XC> and VA/NV $OO<cr|XC>; in each case, the PRompt line should display “0”. If either query returns “1”, the default value has been changed, probably at startup. An XPL program may have toggled either EH or OO. SETTINGS.DFL (also XWSET.DFL, NB.DFL) and printer (*.PRN) files can also manipulate Error Help; SEarch your DFL file for “df eh=1” and change the value to “0”, or deactivate the line with a leading semi-colon: “;df eh=1”. Scan your STARTUP.INT or equivalent file for statements such as “BX d eh=1Q2 ” and/or “BX ooQ2 ”, and remove them (or proactively enter this line:

BX d eh=0Q2 BX oxQ2 ;*;

at the end of STARTUP.INT).

SETTINGS.DFL (XWSET.DFL | NB.DFL)
Additional suggestions for permanent values in SETTINGS.DFL (replace current values, if they exist — don't just add what follows as a block!):
;1A=0 honors EOF marker 1Ah (Ascii-26); 1A=1 ignores it
df 1a=0
;
;BI sets Beep [Barf] Inhibit (1 turns off error beeps)
df bi=1
;
;D1 is the Delete Stack (Clipboard) size (# of entries,min # of chars)
;df d1=30,4 <==default
df d1=200,1
;
;EH Error Help is an absolute no-no! (0=Off, 1=Enabled)
df eh=0
;
;FZ is Date in DIR listings, etc
df fz=MM-DD-YYYY
;
;If you use Windows:
;KS must be COMMENTED OUT because WinNT balks at it
;KS is KeyboardSpeed: repeat rate, delay
;df ks=0,1
;
;LA sets the LAnguage (i.e. CodePage, or character set)
;In XyWrite|XyWin ONLY (NBWin uses the LAnguage DeFault differently, e.g. «LAEnglish»):
df la=850
;
;OD=1 - left and right OffsetDisplayed on screen; 0=not displayed
df od=0
;
;WA is WAit time for error messages (wa=18: ±1 second)
df wa=4
; or even
df wa=0
;
;WF=1 Wraps text to Fit window borders in draft and expanded views
;Doesn't wrap in Page-Line mode, only in WG mode
df wf=1
;
;XD=1 sets directory to read-only (& hilites current line)
;XD=0 makes directories editable/definable
df xd=0
;
;Preserve upper and lower case in spelling commands, e.g. Auto-Expand
; (‘Zero Capitalization’)
df zc=1
;
PRiNter Files
Ensure that fontname STANDARD is associated in your PRiNter file(s) (*.PRN) with a monospace display and printer font (e.g. COURIER10), in both the FA: and FP: tables (SEarch for "FA:N" and "FP:N"). The lines should say something like this:
FA:3
COURIER10=COURIER,1,66,154,201,211,240,250,260,280,290,LINEPRINTER,STANDARD
...
FP:3
COURIER10=STANDARD,1,66,154,201,211,240,250,260,280,290
...
NotaBene for Windows Users please note well: Compatibility with NBWin is not quite 100%, due largely to incomplete testing — but we are approaching fast. As of U2 v119 and NBWin v8.0, we have found a very high degree of compatibility with Xy4-DOS, and with XyWWWeb.U2 routines. Most run as designed. However, we still encounter occasional bugs in NBWin, and moreover there are new NBWin “features” that need to be reckoned and harmonized.

One such feature is “simple sequential windows”, which (by default) automatically changes high window numbers to lower numbers as low windows are closed and become available for use. This confuses XyWWWeb routines that open and close some windows but expect other windows to retain fixed window numbers. Candidly, we do not understand what useful purpose sequential windows serve. Sequential windows can, and must, be disabled in NB.DFL, by means of a new NB.DFL VAriable:

;WN=1 turns off simple sequential windows
df wn=1
NBWin (and also XyWin) users must ensure that Message Boxes are not permitted to pop up when errors occur in the midst of a U2 routine. U2 routines do their own error handling, whereas Message Boxes require manual “OK” confirmation before processing can continue. You MUST compel error messages to be displayed on the PRompt line, and not in pop-up boxes:
;MB=0 turns off Message Boxes (forces display on PRompt line)
df mb=0
The Help facility (XyWWWeb.INF) will work more smoothly if NBWin users add the following line to NB.DFL:
MD SO=216
Do you want the spell checker to beep as you type? I don't. Put func AC toward the end of NBSTART.INT (command “pfun AC<cr>”), to turn off Auto-Correction.

Very Important:
If you CAll XYWWWEB.U2 into a window for any reason, you MUST use the following syntax:

	CA/100 [d:\path\]XYWWWEB.U2
If you do not use CA/100, certain characters [159, 222, 223] contained in the U2 file will be changed automatically and without your knowledge by Nota Bene, with catastrophic consequences to the correct functioning of many programs. Do not ignore this requirement! N.B.: It is not sufficient (it should be, but isn't) to set your default DisplayType to zero (“D[F] DT=0”) — you must use the explicit command syntax “CA/100” (i.e. CAll file in eXPanded view). An alternate approach is to replace file CHARUPDT.TBL in the %root% directory of NB (the same directory that contains NOTABENE.EXE) with file CHARUPXY.TBL (archive the original CHARUPDT.TBL, then REName CHARUPXY.TBL as CHARUPDT.TBL) and then restart Nota Bene — you can now CAll files using any “view” with no changes to any characters in files.

The necessity for other “tweaks” to the NB setup may become apparent as NBWin “settles in” and as we gain experience with it. Over time, we are building NBWin fixes into XyWWWeb.U2, to relieve you of the need for action; but for now, the above fixes are required. Repeat: they apply only to NBWin users.


Installation
To use XYWWWEB.U2, you need four things: 1) the U2 file itself, LOADed in memory (usually via STARTUP.INT); 2) the REGistry file, XYWWWEB.REG; 3) a dedicated <Helpkey>, which you must configure in your KeyBoarD file; and 4) the INFormation (a.k.a. Help) file, XYWWWEB.INF, which contains usage instructions.

A. First-time U2 users:

1) Copy XYWWWEB.U2 and XYWWWEB.INF to your XyWrite subdirectory
   (the directory occupied by EDITOR.EXE, XW.EXE, or NOTABENE.EXE).

2) Add a line like the following to STARTUP.INT (Xy4), XWSTART.INT
   (XyWin), and/or NBSTART.INT (NBWin); change the drive and
   path as necessary:
BX load d:\xy4\xywwweb.u2Q2 ;*;

3) Create a "Helpkey" to launch programs from the command line: CAll
   your .KBD file and assign the following to the key (nn) of your choice:
nn=NOXHJM2,.,P,r,s,C,M,l,i,n,e,Q2
   Stack Users only (you know who you are!) should use this assignment:
nn=NOXH$SNOJM2,.,P,r,s,C,M,l,i,n,e,Q2
   Stack Users should additionally make sure that they install an updated
   XY4.DLG file, replacing any old copy.  After U2 is installed, consult
   HELP STACK<Helpkey> for further info about Stack configuration.

4) STore these changes to disk.

5) QUIT and restart XyWrite.

6) To verify that XYWWWEB.U2 is properly installed, command
VA/NV $U2<cr>.
   XyWrite should report the full path and filename for the U2 file
   on the status (PRompt) line. If that works, command:
HELP<Helpkey> and/or TEST-INSTALL<Helpkey>
   Note that you are using your newly-configured <Helpkey> to
   launch a routine instead of the carriage return ("<cr>") or
   Enter key. XyWrite should call XYWWWEB.INF and report the
   installed XYWWWEB.U2 version and release date.

7) XYWWWEB.REG Configuration:
   A number of routines employ “User Variables” which solicit user
   information or preferences that must be supplied for the routine to
   work properly.  If required User Variable information has not been
   entered the first time you try to run such a routine, you will be
   prompted to do so.

   You should establish all or most of your User Variables in
   one gulp, so that all routines in XYWWWEB.U2 run without further
   intervention.  This requires setting up and editing file
   XYWWWEB.REG, the User Variable REGistry.  An adequate, working REG
   file can be configured automatically, by running XyWrite program
   REGCFG.PM (in U2UTILS.EXE) after you download U2UTILS.EXE,
   unpack it in Editor's directory, and run U2UTLNT.BAT or U2UTL9x.BAT
   from DOS – see External Files, below, for full details.

   Alternatively, you can make the necessary edits to the REG file manually.
   See REG-READ.ME, in this XYWEB###.ZIP, and follow all the ReadMe
   instructions carefully.

B. Users with pre-existing (non-XYWWWEB) U2 file:

1) Un-ZIP XYWEB###.ZIP in a temporary directory.

2) Copy XYWWWEB.INF to your XyWrite subdirectory.

3) Copy XYWWWEB.REG to your XyWrite subdirectory.

4) CAll your U2 file and MErge XYWWWEB.U2 at the *top* of the file.

5) SAve and re-LOAD the U2 file.

6) If necessary, follow Step A.3 above to create a Helpkey.

7) Verify that your U2 file is active by commanding VA/NV $U2.

8) Follow Step A.7, above (set up the REGistry).
How to Replace an Old Version of XYWWWEB.U2 with the Latest Version
Essentially, just overwrite the old XYWWWEB.U2 with the new one. Append your own U2-formatted programming, if any, at the end. REG-READ.ME contains further information.

External Files

Several external files are widely used in U2.  Install them all at once.
  Download the following file — save it in Editor's directory!:
U2UTILS.EXE

  Go to a DOS prompt.  Locate in the same directory as Editor.
  Extract the contents of U2UTILS.EXE — command:
U2UTILS.EXE<cr>
  If it asks for overwrite permission, respond “A” (capital A).
  You will then need to MOVE some of the files to one different
  directory. A BATch file in U2UTILS.EXE does this for you hands-off.
  Depending on your operating system, run (in the same directory
  as Editor), either U2UTL9x.BAT (if you have Windows 95, 98, or ME)
  or U2UTLNT.BAT (if you have Windows NT4, 2000, XP, or Server).
  
  Behind the scenes, these BATch files unpack U2UTILS.EXE and then
  move files that need to be in the DOS Path into the same directory
  as your system command processor: CURL.EXE, CWSDPMI.EXE, FSW.EXE,
  GoNB.EXE, GoXy.EXE, KMD.EXE, LIST.COM, PKUNZIP.EXE, PKZIP.EXE,
  UNZIP32.EXE, VIEW.EXE, WCD.EXE, ZIP.EXE.

  The following files *stay* in Editor's directory.  Don't MOVE them:
  AUTOITX3.DLL, BASE64.EXE, CAPSLOCK.EXE, CLIP.EXE, CLIP.VBS,
  DArchBit.BAT or DArchBit.CMD, HD.EXE, MTR.EXE, RAWPRINT.EXE,
  TOUCH.COM, UNDERLN.EXE.

  The U2UTL*.BATch file also strips the Archive bit off of all
  directories (NOT files) on Editor's drive and on the BootDrive
  (if these are identical, it does it twice).  Otherwise Editor can't
  see those directories, or CAll/Run files in them.  Manually execute
  DArchBit.BAT (in 9x) or DArchBit.CMD (in NT+) against other drives,
  if you intend to CAll/Run files in them.

  The U2UTL*.BATch file removes the Read-only attribute from directory
  "{BootDrive}:\Program Files"; otherwise you can't launch Internet Explorer or
  any other file in a subdirectory of "Program Files".

  If you run Windows 9x, you need the Unicode Layer to be able to Copy and
  Paste.  The U2UTL9x.BATch file automatically installs UNICOWS.dll.

One more step is required.  Return to XyWrite, and locate in Editor's
  directory.  Make sure that a copy of XYWWWEB.REG exists in this directory!
  Then command:
	LOAD XYWWWEB.U2<cr>
  and lastly command:
	RUN REGCFG.PM<cr>
  Hands-off, REGCFG.PM will search for the following Variable names and
  assign to each the fully qualified d:\path\filename of the utility it
  references.  Note that REGCFG.PM will display a black screen and issue a
  lot of “File Not Found” and “Device not ready” errors – these are
  normal – ignore them.

  If you wish, you may configure REG manually (and more thoroughly).  The
  following include EXAMPLE path specs!  CHANGE them to reflect *your*
  “%COMSPEC% directory's d:\path\” — for example (WinXP on BootDrive C:):
cURL_EXE=C:\WINDOWS\SYSTEM32\cURL.EXE
List=C:\WINDOWS\SYSTEM32\LIST.COM
PKUnZip=C:\WINDOWS\SYSTEM32\PKUNZIP.EXE
PKZip=C:\WINDOWS\SYSTEM32\PKZIP.EXE
UnZip=C:\WINDOWS\SYSTEM32\UNZIP32.EXE
VieW_DOS=C:\WINDOWS\SYSTEM32\LIST.COM
VieW_Win32=C:\WINDOWS\SYSTEM32\LIST.COM
WCD_Win32=C:\WINDOWS\SYSTEM32\wcd.exe
WPerf=C:\WINDOWS\SYSTEM32\VIEW.EXE
Zip=C:\WINDOWS\SYSTEM32\ZIP.EXE
  The next Variable does not take a Path spec.  Recommended: set to “E”
EXE_or_VBS=E

  Finally, SAve XyWWWeb.REG when you are done.

U2 General Usage To launch a routine (a “frame”), type its name on the CMline and hit your Helpkey: FRAMENAME<Helpkey>
Supplementary instructions are passed to a frame with command-line arguments. Some frames require one or more arguments; in others, arguments are optional (or nonexistent). Arguments are set apart from the framename by a space; multiple arguments normally are separated from each other by commas: FRAMENAME argument1,argument2,...<Helpkey> An important example of a routine that accepts an argument is HELP, which provides on-line usage advice for most XyWWWeb routines. This Help INFormation is contained in a freestanding text file named XYWWWEB.INF, which is automatically accessed by routine HELP, but also can be opened and freely searched or browsed. Indicate the information you desire by passing a framename to HELP as an argument: HELP framename<Helpkey> e.g.: HELP ViewURL<Helpkey> HELP Help<Helpkey>

Keyboard-File Usage A U2 routine called PrsKbdArg is used to assign a U2 routine and any associated arguments to a key number (“nn”). Case is sensitive! The basic usage (no arguments) is: nn=JM,(,2,.,P,r,s,K,b,d,A,r,g,),f,r,a,m,e,n,a,m,e,NO Example: 19=JM,(,2,.,P,r,s,K,b,d,A,r,g,),R,u,n,c,o,d,e,NO The concluding function NO (NoOperation) is mandatory. A single argument is coded thus: nn=JM,(,2,.,P,r,s,K,b,d,A,r,g,),f,r,a,m,e,n,a,m,e, ,a,r,g,NO Example: 25=JM,(,2,.,P,r,s,K,b,d,A,r,g,),d,i,a,l, ,C,O,M,2,NO Multiple arguments to a single frame are separated from each other by func CO: nn=JM,(,2,.,P,r,s,K,b,d,A,r,g,),f,r,a,m,e, ,a,r,g,1,CO,a,r,g,2,CO,a,r,g,3,NO Multiple frames may be assigned to a single key: nn=JM,(,2,.,f,r,a,m,e,1,),JM,(,2,.,f,r,a,m,e,2,) which may also be written as: nn=JM2,.,f,r,a,m,e,1,Q2JM,2,.,f,r,a,m,e,2,Q2 Getting Started The following commands will help you become acquainted with the array of powerful features in XyWWWeb: INDEX<Helpkey> displays a categorical list, with brief descriptions, of all routines in the XyWWWeb Jumbo U2 file. You can search the Index for specific Help topics using one or more arguments, for example: INDEX ansi INDEX defined text INDEX search The Index also can be summoned with commands HELP CONTENTS<Helpkey> HELP IDX<Helpkey> HELP INFO[RMATION]<Helpkey> TABLE INDEX<Helpkey> HLIST<Helpkey> produces at any time a sorted listing, with brief descriptions, of all routines in the U2 file, including all routines added by users CITE New<Helpkey> (issued against HLIST output) quickly compiles a list of all routines added or updated recently CITE UserVar<Helpkey> (issued against HLIST output) produces a list of all routines that include User Variables HELP [framename]<Helpkey> summons on-line usage information for any routine

Save/Get Usage
The use of extended (memory-resident) Save/Gets in XYWWWEB.U2 is confined to the range 600-799. In the interest of keeping initial installation and future upgrades hassle-free, we ask that users reserve this range for U2's exclusive use and RENUMBER third-party programs if they intrude on this range, to avoid conflicts with XyWWWeb routines.

Feedback
Your comments and suggestions are welcome and often encourage further development. We are always delighted to hear from users.


Enjoy!

---------------
C.L.Distefano <CLDistefano@worldnet.att.net>
R.J.Holmgren <xywwweb@mail.datarealm.com>

LastRev.8/7/06