What To Do When Programs Don't Work Out-of-the-Box
A Few Things to Check...
(XyWWWeb CLD+RJH Last 11/6/2005)
Q: What if a Help file won't load?
A: Possibly it isn't a real Help file! Help files, by definition, require a file identifier in column zero of the first line of the file. This identifier, e.g. “;DG;” or “;U2;”, indicates to the system which Help file is being loaded.
Q: What diagnostic process should I follow if some Help routines that used to work properly suddenly won't run, or if it appears that the whole Help file isn't loading successfully?
A: Note the name of the last programming frame in the Help file. Then examine the crashing Help file with a file viewer (e.g. LIST.COM) at the operating system (DOS) level, and locate this last programming frame. Immediately after it, two back-to-back instances of character 26d|1Ah should appear (looks something like “-› -›”), followed by an Index of all frames in the Help file, listed in order of occurrence. This Index does not display within XyWrite! The last name in this Index should be identical with the last framename in the Help file. When some but not all routines in a Help file start to bomb, an error is usually reflected in this Index. For example, the Index may be incomplete; the last frame which is listed in the Index (or the next-following frame) probably has a fatal error in it which causes Indexing to halt. If frames aren't Indexed, they won't run.
Q: What causes frames to fail, or Indexing to halt?
A: Several potential problems. The inadvertent insertion or deletion of a character in a Help file is the most common cause. The Index analysis described above will generally help you to pinpoint the culprit frame.
Unbalanced pairs of 02d|02h, the Ascii-2 smiling white face that surrounds most frames, can cause frames to act crazily. Occasionally an Ascii-2 becomes embedded as the 2nd or 3rd character within a 3-byte character, causing XyWrite to think that a frame has ended abruptly. Likewise, character 26d|1Ah (the EndOfFile character) can become embedded, causing XyWrite to think that the whole file ends at that spot. These errors can be difficult to locate within XyWrite, because 3-byte characters do not display their internal byte-content or composition, but rather a mnemonic that occupies (usually) one screen column only extremely misleading! You need to use a good OS-level viewer that can search for any character, including low- and high-Ascii characters such as 26d or 255d.
Authors of programs are expected to check them for this type of error before releasing them to the public.
Q: What if I get an Error#332 [“Error saving file )DUM(MY.HLP...”] while attempting (with frame LOADHELP) to SAve and reLOAD a newly-altered Help file?
A: This usually happens because two iterations of XyWrite IV (or one each of Xy4 and XyWin) are open and mutually accessing the same Help resource (the same file); an attempt to alter a file which is also being used by another executable triggers a sharing violation. To recover immediately, manually reload the Help file, e.g. issue “LOAD XYWWWEB.U2<cr>”. This should reactivate the original, unmodified Help. Note that this file has not been successfully SAved and reLOADed in its new, modified form! So close the other instance(s) of XyWrite, add then delete a space or other character, and execute “LOADHELP<Helpkey>” again.
N.B.: To determine the current value of a DeFault VAriable, and thus to find out whether you need to change it, use this command syntax:
va/nv $VAwhere VA=the [usually two-letter] mnemonic of a VAriablename. In response, XyWrite will report the requested value on the PRompt line. To get an accurate report of value, in some cases and therefore as a good general rule you need to put the cursor in the text window (not on the CMline) when you poll VAriables.
For example, to determine the current value of ErrorHelp EH, command:
Possible reported values, in the case of $EH, are 0 (EH is Off) or 1 (EH is On).
Difference between VA and $VA:
VA=the original value of the VAriable when XyWrite was initialized, reflecting values built-in to EDITOR or established by SETTINGS.DFL or STARTUP.INT or another initialization file
$VA=the current value of the VAriable, which may differ from the original value if you, or a program you've run, have modified it.
Not all VAriables report both the VA and $VA form (some report just one or the other, according to the sense of the situation).
In the discussion below, we indicate our suggested setting.
1) Turn off VAriable EH ErrorHelp permanently. EH is a huge impediment to XPL:
in SETTINGS.DFL [XWSET.DFL in XyWin], issue:
or, in STARTUP.INT [XWSTART.INT], after the command to “BX load settings.dflQ2 ”, issue:
2) If there are long pauses after every error (and many conditions fully anticipated by both the program designer and the user represent nominal errors), set the [error message] WAit time VAriable WA to zero:
df wa=0 (in SETTINGS.DFL); d wa=0 (in STARTUP.INT)As a compromise, to enable you to briefly view PRompt messages, set WA=4. (A WAit value of 18=1 second.)
3) Many Bitstream Speedo fonts expect to function in a Code Page 850 environment. The American default, however, is Code Page 437. The LAnguage DeFault LA controls the Code Page in XyWrite, regardless of your Operating System setting:
df la=850 (in SETTINGS.DFL); d la=850 (in STARTUP.INT)
4) Never set default 1A to ignore the end-of-file character! You'll trash all your help files if you SAve them when 1A=1, and you could easily cause configuration files to fail to load. Worst of all, you probably won't know what hit you when XyWrite starts crashing.
df 1a=0 (in SETTINGS.DFL); d 1a=0 (in STARTUP.INT) that's “One-A”, not “LA”
5) Do you really need Document Information? Turn it off. Waste of bandwidth, and confusing to some external programs because DocInfo writes a lot of information at EOF which you never see unless you examine your files at the Operating System level (i.e. outside XyWrite).
df io=0 (in SETTINGS.DFL); d io=0 (in STARTUP.INT)
6) Having trouble reading PRompts and instructions generated by PrograMs, because your cursor generates messages every time it lands on an embedded delta? For example, if XT=1 and your cursor is on an IP command, the PRompt line will say “Indent paragraph (IP)”. Turn off eXTended description:
df xt=0 (in SETTINGS.DFL); d xt=0 (in STARTUP.INT)
Return to XyWWWeb