home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / cis / ozrle94h.arc / OZRLE.DOC next >
Text File  |  1989-10-09  |  51KB  |  975 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                                      OZRLE
  21.                                   Version 9.4h
  22.     An external protocol module for the CompuServe "B" and "BPlus" protocols
  23.           and supporting the CompuServe GIF and RLE graphics images
  24.  
  25.                            Copyright(c)1987,1988,1989
  26.                                   Steve Sneed
  27.                                 CIS ID 71520,77
  28.  
  29.  
  30. Welcome to OZRLE!
  31. -----------------
  32.  
  33. OZRLE is an "external protocol module", a program that allows you to add
  34. the CompuServe "B" and "BPlus" file transfer protocols into other communi-
  35. cations programs.  While not designed primarily as such, the program can
  36. also be used as a (limited) stand-alone communications package for accessing
  37. the CompuServe Information Service (CIS).
  38.  
  39. Popular file transfer protocols such as XMODEM do not function well under
  40. CompuServe's complex packet-switching network.  The KERMIT protocol, while
  41. operational, is very slow on CIS.  CompuServe developed the B/B+ protocols
  42. to provide optimum performance on the network - it is the recomended method
  43. of file transfer when using CIS.
  44.  
  45. Also (and for many users, more importantly), OZRLE supports the CIS graphics
  46. standards RLE (Run Length Encoded) and GIF (Graphics Interchange Format) for
  47. both offline and realtime-online image display.  Additionally, OZRLE captures
  48. received images to disk - this means you can "preview" an image while
  49. downloading so you can verify you really want the image, and save connect time
  50. charges.
  51.  
  52. In addition, OZRLE supports both the ANSI/VT100 and VT52/Vidtex terminal
  53. emulations used by CIS for attractive screen handling.  A wide range of
  54. options, both on the command line and within the program, allow you to
  55. configure the program to match your needs.  The program automatically
  56. matches itself to your existing communications port configuration, meaning
  57. you do not have to worry about setting things like baud rate and parity
  58. when calling the program.
  59.  
  60. OZRLE works with most all major commercial and shareware/freeware comm
  61. programs, and can be used with any comm program that can shell out to DOS
  62. without dropping the connection.  On those programs that provide the capa-
  63. bility, OZRLE works best when set up as an external protocol callable from
  64. within the program (examples are ProComm Plus, QModem, Boyan and GT-PowerComm.)
  65. At this writing the only known major commercial comm program known not to
  66. work with this program is Hayes' SmartCom II, because it provides no way
  67. to shell out to DOS.
  68.  
  69.  
  70. Before we start...
  71. ------------------
  72.  
  73. Please read this documentation completely.  I know you want to get using the
  74. program right away, but taking a few minutes now may well save you time and
  75. money (in connect-time charges) later.  The program is very simple to use,
  76. and for most users' configurations is fully automatic, but an ounce of pre-
  77. vention is worth a pound of cure.  Thanks!
  78.  
  79. It is assumed throughout this document that you have a good basic under-
  80. standing of DOS commands, batch files and batch file commands, what
  81. "environment variables" are and how to set them.  If this is not the case,
  82. please have a good MS-DOS tutorial book handy in case I use unfamiliar
  83. terminology.
  84.  
  85. Help for this program is available online in the IBMNew forum on CompuServe.
  86. Many program-specific help files written by SysOp Connie Kageyama are
  87. available in LIBrary 2 of that forum.  Do a "DIR *.HLP" at the "!" prompt
  88. in that library for a list of those files, or do a "BRO/KEY:HELP" at the
  89. same prompt. Another place to get help on the program with GIF- and graphics-
  90. related questions is in the GRAPHSUPPORT Forum.  The sysops in both forums
  91. are familiar with the program and can answer questions, and of course I
  92. frequent the forums to help users.
  93.  
  94.  
  95.  
  96. The Legalese...
  97. ---------------
  98.  
  99. This program is the copyrighted work of its author, Steve Sneed.  All rights
  100. under US copyright law are reserved.  The author hereby grants to private,
  101. noncommercial users of this program a limited license to use, copy and
  102. distribute the program free of charge, as long as:
  103.  
  104. a) the program and its accompanying files are not modified in any way other
  105.    than changing the "archive format" used to store and transmit the program;
  106.  
  107. b) no charge is made for any distribution beyond a nominal disk/duplication
  108.    fee; and
  109.  
  110. c) the distribution of the program is not done by a business, company or
  111.    private entity whose primary business purpose is the distribution of
  112.    public domain and/or "shareware" software, by any means magnetic or
  113.    electronic, for profit.  Specific exclusion of this clause is hereby
  114.    granted by the author to The First Osborne Group (FOG), The Public
  115.    (Software) Library, CompuServe Inc. and PCMagNet.
  116.  
  117. If the program is used for commercial purposes, a license from the author
  118. is required along with payment of a $15 license fee per copy.  Multi-copy
  119. and site licenses are available; contact the author at the address listed
  120. at the end of this document for more information.  "Commercial purposes"
  121. as used above is defined as use by a company or government service or
  122. organization in an official capacity, or use by a company or individual
  123. whereby financial profit is made from such use - for example, a stock broker
  124. who uses the program to aquire ticker information for clients.  Specific
  125. exclusion of this clause is hereby granted by the author to CompuServe Inc.,
  126. Borland International, TurboPower Software, and PCMagNet.  No other rights
  127. are in any way relinqushed by the author, and the author reserves sole right
  128. to grant and administer licensing and distribution.
  129.  
  130. This software is provided "as-is", without warranty of any kind, including but
  131. not limited to any warranty of mercantibility or suitability for a specific
  132. purpose.  At no time will the author be held liable for any loss or damage,
  133. including loss of data or time, due to any operation or use of this program,
  134. even if the author has been informed of such loss or potential for loss.
  135.  
  136. "GIF", "GIF Format" and "Graphic Interchange Format" are Service Marks of
  137. CompuServe Inc., an H&R Block Company.
  138.  
  139.  
  140. Installing OZRLE
  141. ----------------
  142.  
  143. OZRLE generally should be installed in the same location as your comm program.
  144. If you use a hard disk, this means in the same subdirectory.  If you use more
  145. than one comm program with OZRLE and have different programs in different
  146. subdirectories, be sure to place OZRLE in a subdirectory that is on your DOS
  147. path.
  148.  
  149. OZRLE is delivered to the CompuServe forums in "archived" format, using the
  150. standard ARC format utility ARCA.COM by Vern Buerg and Wayne Chin.  Some
  151. forums (and BBS systems, if that is where you aquired this program) may re-
  152. compile the program files into a different archive format such as the .ZIP
  153. format, or may use a utility like LHARC to create a self-extracting program
  154. archive.  Once you have copied the archive file or self-extractor onto your
  155. disk, you will need to use the appropriate un-arc utility (if not a self-
  156. extractor) to un-arc the program files back to their original runable state.
  157. Utilities for this purpose are available in most forums on CompuServe, and on
  158. nearly every BBS in America.
  159.  
  160. OZRLE comes with a special installation program called SETSVGA.EXE.  You only
  161. need to use this installation utility if you will be using the program on an
  162. Super VGA card.  SETSVGA tells OZRLE what SVGA chipset to support and what
  163. maximum resolution your card/monitor combination can support.  If these terms
  164. are unfamiliar to you, especially if you do not know what chipset your brand
  165. of video card uses, stop by the PICS Forum on CompuServe - we'll be glad to
  166. help you.  Please consult the chart at the bottom of this document for a list
  167. that covers approx. 90% of the cards currently on the market and their max
  168. resolutions.
  169.  
  170. A second installation utility is also available separately to change the text
  171. colors the program uses.  It is called OZPATCOL.ARC and is available in the
  172. PICS and IBMNEW Forums.  See the readme file with OZPATCOL for instructions
  173. on its use.
  174.  
  175.  
  176. Configuring OZRLE
  177. -----------------
  178.  
  179. Configuration of OZRLE is very simple.  The program uses a "standard"
  180. internal configuration that will be correct for 90% or better of users.
  181. The program is quite flexible, however; almost any type of special con-
  182. figuration used on CIS is supported by the program, as well as several
  183. options governing the way the program functions or performs.
  184.  
  185. The following list contains OZRLE's nominal configuration.  Only if
  186. your particular configuration differs from this list should you worry
  187. about the various settings available.
  188.  
  189. * Uses the COM1: serial port/modem.
  190. * Uses the chosen port's existing baud rate, parity and data/stopbits settings.
  191. * Uses full-duplex communications.
  192. * Provides an audible alarm at the end of a protocol transfer.
  193. * Returns to its own internal terminal mode at the end of a transfer.
  194. * Uses the DOS current working directory for storage of downloaded files,
  195.   and looks in the same directory for files to upload.  Ditto for graphics
  196.   image files.
  197. * On exit, leaves the modem CarrierDetect line high and restores the port to
  198.   the same configuration in which it was found.
  199.  
  200.  
  201.  
  202. Setting Options
  203. ---------------
  204.  
  205. If one or more of the above settings does not match your configuration, there
  206. are two possible ways to change things.  The first, and recommended, way is
  207. thru setting variables in the DOS environment.  The second is to use command
  208. line parameters when executing the program.  If you are calling OZRLE from
  209. a program such as QModem that wants to see a batch file rather than a free-
  210. standing program to execute, it is simpler to use the command line parameters
  211. within the batch file (saving the DOS environment space for other programs.)
  212. Parameters set via environment variables can be overridden via command line
  213. options.
  214.  
  215. Below is a list of OZRLE's environment variable names and the associated
  216. options:
  217.  
  218. OZPORT=?         Replace ? with your commport number (1 thru 4)
  219. OZBASE=?         Replace ? with the Base Address of your port hardware
  220. OZIRQ=?          Replace ? with the Int Request # of your port hardware
  221.    (NOTE: the above two variables are used *only* if your comm port resides
  222.     at a non-standard base address and/or int request line (for example,
  223.     PS/2 systems on COM3 or 4.)  If one is used, the other *must* be used
  224.     as well.)
  225. OZPATH=?         Replace ? with the full path to use for up/downloaded files
  226. OZMAC=?          Replace ? with the full path/filename of your macros file
  227. OZGIF=?          Replace ? with the full path to your GIF/RLE files
  228. OZOPT=?...       Replace ? with one or more of the option letters in the
  229.                  parameters list below.
  230.  
  231.  
  232. When using command line parameters, all parameters must begin with either
  233. a dash (-) or a forward slash (/) character.  Parameters that require qual-
  234. ifying information (such as the port selection parameter) must have the
  235. information immediately after the option letter with no space.  At least
  236. one space must separate each parameter.  Below is the list of available
  237. parameter option letters:
  238.  
  239. C{portnumber}   Select the comport.  If you use COM2, this would be "/C2".
  240.                 The default is COM1.  Ports 1 thru 4 are available.
  241.  
  242. A{baseaddress}  Specifies the non-standard base address for the chosen
  243.                 port.
  244.  
  245. I{irqnumber}    Specifies the non-standard Int Request line # for the chosen
  246.                 port.  If either the A or I parameters are used, both must
  247.                 be used.
  248.  
  249.  
  250. If you are using the program as a stand-alone comm program rather than from
  251. within another comm program (and, generally, _only_ when you use it as such),
  252. 4 other parameters are available to configure the port.  They are:
  253.  
  254. B{baudrate}     Specifies the baud rate setting at which to open the port.
  255.                 Available baud rates are 300, 1200, 2400, 4800, 9600 and
  256.                 19200.  The default is to use whatever setting the port
  257.                 currently holds.
  258.  
  259. P{parity}       Specifies the parity setting to use.  Normally either None
  260.                 or Even, but Odd, Mark and Space settings are available as
  261.                 well.  You only have to provide the first letter of the
  262.                 parity type word (so setting None parity would be "/PN".)
  263.  
  264. W{dataword}     Specifies the data word length; 5, 6, 7 or 8 databits.
  265.  
  266. S{stopbits}     Specifies the number of stop bits (almost always 1.)
  267.  
  268.  
  269. The other available parameters are used to configure the way OZRLE works.
  270. These are the "options" settable with the OZOPT= environment variable.
  271. They are:
  272.  
  273. X               Exit OZRLE immediately on completion of a protocol transfer.
  274.                 The default is to return to OZRLE's internal terminal mode
  275.                 so you can download more files or navigate to another area
  276.                 of CIS.  This option is normally only used when the program
  277.                 is being called from within another comm program's script
  278.                 file for automatic execution.
  279.  
  280. D               Drop carrier on exit.  The default is to leave CarrierDetect
  281.                 high.  Using this parameter will mean that OZRLE will break
  282.                 any existing connection on the modem when exiting - not a good
  283.                 idea when you are loading the program from within another
  284.                 comm package.
  285.  
  286. N               Turn off the audible alarm normally provided at the end of a
  287.                 protocol transfer.  The default is to provide a beeper at
  288.                 the end of a proto transfer and wait for a keypress before
  289.                 continuing.  When this switch is used, no alarm sounds and
  290.                 the program does not wait for the keypress.
  291.  
  292. Q               Automatically send an XON character on startup.  This param
  293.                 is normally only used with the CIS-specific "auto-navigator"
  294.                 programs AUTOSIG and TAPCIS, both of which send an XOFF flow
  295.                 control command to CIS when shelling out to DOS.  Some versions
  296.                 of the TELIX comm program seem to need this switch as well.
  297.  
  298. U               Automatically send a Ctrl-U character on startup.  Using this
  299.                 parameter means that, on startup of OZRLE, the CIS system
  300.                 will automatically interrogate OZRLE for its terminal-type
  301.                 and protocol-support capabilities.  This option should be
  302.                 used with caution; in a few places that you might call OZRLE
  303.                 the sending of the Ctrl-U may confuse the CIS system or may
  304.                 abort the imput prompt that was waiting when you called OZRLE.
  305.  
  306.  
  307.  
  308.  
  309. Z               Forces use of program's monochrome screen colors set.  Some
  310.                 monochrome video hardware tries to "emulate" color; on these
  311.                 video systems the normal colors used for the prompt line and
  312.                 protocol status window may be unreadable.  If you find this
  313.                 to be the case (common on some Leading Edge machines), use
  314.                 this option.  Also see my OZPATCOL program for setting colors.
  315.  
  316. L{filespec}     Tells OZRLE to look for and load a macros file named
  317.                 {filespec}.  OZRLE does _not_ search the DOS path for this
  318.                 file, so you must explicitly provide any path information
  319.                 if the file is not in the DOS current working directory.
  320.  
  321. F{path}         Tells OZRLE to put all downloaded files in the {path}
  322.                 drive and/or subdirectory, and to take all uploaded files
  323.                 from that same location.  OZRLE verifies that the specified
  324.                 path does exist and if it does not notifies you of the error
  325.                 and reverts to the current DOS working directory.  Note that
  326.                 you can override this path by including any desired path with
  327.                 the filename when answering the "Filename for your computer:"
  328.                 prompt from CIS right before beginning the transfer.
  329.  
  330. T{size}         Set the size in lines of the scrollback buffer.  The default
  331.                 size is 48 lines (two screenfulls) to keep memory usage to
  332.                 a reasonable size.  You can increase this value up to 400
  333.                 lines (about 16 screenfulls.)  If you increase the value beyond
  334.                 the size of available memory, the buffer will not be turned on;
  335.                 keep this in mind when setting the buffer size.
  336.  
  337. EGA480          Tells OZRLE to support the 640x480x16 mode many EGA cards
  338.                 provide.  Default is to not support this mode for several
  339.                 reasons; see "Video Stuff" below for more information.
  340.  
  341.  
  342.  
  343. Running OZRLE
  344. -------------
  345.  
  346. OZRLE is simple to use.  Depending on what general communications software
  347. you use, it can be made almost automatic.  Due to the wide range of different
  348. communications programs available, no one setup will always be right for
  349. your particular configuration.  However, following these guidelines will make
  350. using the program simple and straightforward.
  351.  
  352. A)  If your comm program supports it, always install OZRLE as an external
  353.     protocol module.  Some programs or versions of programs do not support
  354.     defined external protocol modules but do allow the definition of external
  355.     programs (like editors.)  If this is true for your software, use that
  356.     type of setup.  Only use OZRLE from a "general" DOS shell if your soft-
  357.     ware provides no other support for external programs.  Installing OZRLE
  358.     as an external protocol module means calling OZRLE will be done in the
  359.     same manner as all other protocols, giving you a consistant interface.
  360.  
  361. B)  If your program requires batch files for external protocol modules (ala
  362.     QModem and a few others), do all parameters options on the batch file
  363.     command line.  Here is an example batch file for QModem:
  364.  
  365.     ECHO OFF
  366.     CLS
  367.     OZRLE /c2 /fA:\DNLD\TODAY /lC:\QMODEM\VT100.KEY %1 %2 %3 %4 %5 %6 %7
  368.     CLS
  369.  
  370.     There are several things to notice here.  First, we establish the port to
  371.     use as COM2: (/c2), then the path for downloaded files to be stored under
  372.     (/f...), and finally the macros file to use (/l...), then we provide for
  373.     passing other command line settings as we may need from time to time.
  374.     Note that the files path can be on any drive.  Also note that QModem's
  375.     VT100.KEY file redefining the keyboard to more closely emulate a true
  376.     DEC VT100 terminal will work nicely in OZRLE.  Finally, you can set the
  377.     standard settings you use most of the time as environment variables, and
  378.     then remove the /c, /f and /l parameters from the command line above but
  379.     leave the batch variable identifiers; this way allows you to easily
  380.     override your envirnment variable settings with command line parameters
  381.     if a special case warrants.
  382.  
  383.     This type of setup is also recommended if you use the program from a
  384.     "plain" DOS shell or from within AutoSIG or TAPCIS, or if you run the
  385.     program standalone.
  386.  
  387. C)  If your communications program is like Boyan (where you can call the
  388.     program directly), it is better to use environment variables to set
  389.     any needed options.  This is best done in your AUTOEXEC.BAT file so
  390.     that the variables are always set.  Programs like Boyan make it easy
  391.     to set a single configuration but make it difficult to modify that
  392.     configuration for special cases; make your setup flexible.
  393.  
  394. D)  In all the above cases, note that unlike most other protocol modules
  395.     OZRLE does not distingush between upload and download on the command
  396.     line.  This is handled at the start of a protocol transfer by the protocol
  397.     itself.  Therefore, you generally only need one configuration for both
  398.     the upload and download entries in your comm program.  However, a tip here
  399.     is that if you use different subdirectories for storing downloads and
  400.     finding uploads, you can set up separate configurations with different
  401.     paths on the /F option on the command line (either batch file or direct
  402.     command methods), or set an environment variable for the files path for
  403.     downloads and override it with a command line setting in the upload setup.
  404.  
  405.  
  406.  
  407. Using OZRLE
  408. ------------
  409.  
  410. Most protocol modules, when executed, immediately enter the protocol itself.
  411. The B protocols do not work this way.  CIS sends a special interrogation
  412. sequence to the remote system (you) to make sure the remote can in fact do
  413. B and/or B+ before initiating the protocol itself.  OZRLE _must_ be loaded
  414. and running to reply to this interrogation properly, or you may well not be
  415. able to do the transfer.  (This is not a deficiency, it is a safety mechanism
  416. for both CIS and you.)  Many places on CIS where you can transfer files, this
  417. interrogation may not be done immediately prior to the protocol initiation;
  418. often it is done when you first request a transfer but before CIS has asked
  419. you for the filename to process and the file type (binary or ASCII.)  Because
  420. of this you should call OZRLE _before_ you request the transfer.  OZRLE
  421. comes up in terminal mode so that you can answer any pending prompts, etc.
  422.  
  423. Usually, when you shell out to OZRLE from another comm program, there is
  424. a prompt from CIS pending input.  There is no way OZRLE can know what this
  425. prompt was and therefore redisplay it (or anything else that was on the screen
  426. when you called it) so you must remember what the prompt was and reply to
  427. it after OZRLE is operational.  This is no problem; just type in what you
  428. would have had you been sitting at the prompt.  CIS never sees OZRLE load
  429. so it never knows you were not able to see the prompt.  (If you use the
  430. /U or /Q options, CIS will know but won't care.)
  431.  
  432. Some users have noted that they "forget I'm in OZRLE rather than my main
  433. program."  OZRLE provides a status line at the bottom of the screen at all
  434. times to remind you.  I have tried to make sure it does not resemble too
  435. closely the status lines provided by many other comm programs, to make this
  436. recognition easier.   Since OZRLE only has 1 set of colors for color video
  437. systems and another for mono, you may want to make sure your main comm program
  438. uses a different set of colors on its status line as a further reminder.  You
  439. can change the colors the program uses; get my OZPATCOL program to do so.
  440.  
  441. Many CIS users (most?) log in at 7 bits/Even parity.  OZRLE has no problem
  442. with this; it knows how to switch to 8 bits/No parity for the actual transfer
  443. and back at the correct times.  HOWEVER... some serial ports and/or modems
  444. do not handle the "flying switch" properly and will cause grief.  For this
  445. reason I recommend you use 8 bits/No parity at all times on CIS.  To do so
  446. you must change some of your "user profile" parameters that CIS maintains
  447. on you.  Enter GO TERMINAL at any ! prompt, amd follow the menus to set your
  448. parity to None/Zero.
  449.  
  450. OZRLE provides both a clock and an online timer on its status line.  The
  451. online timer displays and "ticks" only when a connection is established.
  452. If you use the program standalone this timer will be accurate, but if you
  453. call OZRLE from another program it will only display the amount of time you
  454. have been in OZRLE.
  455.  
  456.  
  457.  
  458. Video Stuff
  459. -----------
  460.  
  461. OZRLE supports most common IBM video types, including Hercules Monochrome,
  462. CGA, MCGA, EGA and VGA.  It also supports many "Super" VGA types, at reso-
  463. lutions (depending on the card) up to 1024x768.  A chart (below) lists the
  464. resolutions supported as well as video hardware types and what mode is used
  465. for that hardware.  Some important notes concerning graphics modes and this
  466. program:
  467.  
  468. All video types: TEST FIRST!!!  Save yourself some possible grief and connect
  469. time - test the program's video handling in offline mode first, to make sure
  470. your hardware and OZRLE get along and that you have used the SETSVGA utility
  471. correctly.  Download a few GIF images using a normal protocol file transfer,
  472. making sure the image sizes match up to your video modes, and check OZRLE out
  473. before trying to view online.  If by some rare occurance the program and your
  474. hardware don't see eye to eye, you'll know about it before you try to view
  475. online and waste time.
  476.  
  477. All video types:  Where the program has multiple video modes to choose from
  478. (all color systems), the mode will be as closely matched to the image reso-
  479. lution as possible.  Most images created on IBM hardware will exactly match
  480. one of these modes, but images created on other hardware (Macs, Amigas, etc.)
  481. may well be "odd" resolution dimensions.  Since the vast majority of these
  482. odd-sized images will be tall-and-narrow rather than short-and-fat, the pro-
  483. gram concentrates on the image height as the determining factor in selecting
  484. a mode.  Some odd-sized images can "fool" the program though, so be aware
  485. of image resolutions before viewing or downloading a specific image.  The
  486. same goes for colors; trying to view a 256-color image on 4-color CGA hard-
  487. ware is usually a disapointment.  CGA users take note: I recommend Tom
  488. Potoki's exellent TWOBIT program for offline viewing high-color images on
  489. CGA hardware.  The offline decoders have two advantages over the online
  490. decoders: they have the luxury of time (I have to concentrate on the serial
  491. port) and they have the complete file already at hand to simplify the process
  492. of dithering multiple colors down to 4 or 2 (I only have what has already
  493. come in the port so I can't "look ahead" to balance tonal qualities, and due
  494. to the nature of this program I can't make it much larger by adding the
  495. code nessessary to do the dithering.)
  496.  
  497. Another one for all video types:  If you have used offline decoders you may
  498. try the first online view and wonder why it is so s-l-o-w and why it displays
  499. in spurts.  Keep in mind that image data arriving to the program via the
  500. serial port is comming in at one/one-thousandth or less the speed a program
  501. can read data from a hard disk; it _has_ to be far slower.  The reason the
  502. program displays in spurts is because of the transfer protocol protection
  503. being used.  The actual image data is in compressed binary format as it is
  504. received and must be uncompressed by the program before it is displayed;
  505. because one byte corrupted by line noise can cause the decompression code
  506. to enter hyperspace at Warp IX, a transfer protocol must be used to insure
  507. the data's integrity before it ever is handed to the decoder.  Because proto-
  508. cols send data in blocks, a block must be received and verified before it is
  509. handed to the decoder; the decoder processes the data to the screen before
  510. turning control back over to the protocol section... thus the "display/wait"
  511. spurts.  This is also a limitation of the operating system, as environments
  512. that can process multiple "threads" of programming can easily be receiving
  513. one block while they process the previous block.  Good ol' DOS...
  514.  
  515.  
  516.  
  517. Hercules Mono and InColor(tm) cards: This code has been designed on and
  518. tested on a true-blue Hercules(tm) brand card and 3 "clone" herc cards of
  519. various heritage; I cannot guarantee it will work correctly on all clone
  520. cards.  Most herc clone cards on the market today are quite compatible, but
  521. many earlier cards have problems with graphics modes.  Caveat emptor.  If
  522. you have two video systems (one herc mono and a color system of some type),
  523. the program should always detect and use the color system.  If for some reason
  524. it wants to detect and use the herc card, I'm sorry... you typically will
  525. have all kinds of grief and will not be able to use the program; try removing
  526. one card or the other.  Finally, while I have gone to some lengths to provide
  527. decent display of >2 color images on Herc hardware, it will always be somewhat
  528. of a disapointment.  I do recommend that, if you have Herc mono and want to
  529. view the weather maps, do so in the BWMAPS section using RLE instead of the
  530. GIF format in the COLMAPS section.  Note that Hercules InColor cards are
  531. treated as monochrome and not color.
  532.  
  533. EGA (true): Like VGA, there are a multitude of EGA cards on the market.  Many
  534. are "Super"EGA cards and support modes above the normal EGA level (640x350x16).
  535. OZRLE supports only one of these enhanced modes, the 640x480x16 mode 0x12
  536. that is the same as VGA 640x480x16.  Many users will have a system made up of
  537. one of these "SEGA" cards and a generic vanilla EGA monitor. (A sad but common
  538. occurance in the cheap clone marketeering game is to advertise a super-gee-
  539. wowie EGA card... and deliver the system with a standard EGA monitor that
  540. can't take advantage of the card's capabilities.  The unknowing, hapless
  541. purchaser almost always gets stuck.  End of editorial.)  Because of this,
  542. OZRLE defaults to only supporting up to 640x350x16.  If you can handle the
  543. 640x480x16 mode, use the /EGA480 command line switch to enable support for
  544. mode 0x12.  If you use this switch and nothing displays, or you get a few
  545. garbage pixels, or (rare) the system locks up, your card can't support the
  546. 640x480 resolution as a BIOS-directed mode.  (A few cards support it but not
  547. via the video BIOS, only thru direct hardware programming.)  If you get what
  548. seems to be an image but it wavers or jitters rapidly, or has a bad vertical
  549. roll, your monitor cannot handle the higher sync rate used on the 0x12 mode.
  550. Try this offline to verify before you use it online.
  551.  
  552. EGA (true):  The EGA low-resolution mode (320x200x16) is an oddball.  IBM in
  553. their infinite wisdom made the handling of this mode a little different on
  554. the card than the other EGA modes, and then compensated in their EGA monitor.
  555. Some aftermarket EGA cards follow right along with this different handling,
  556. but very few monitors do the resultant nessessary compensation; some EGA
  557. cards just don't support the full 16-of-64 palette in 320x200x16 mode.  As
  558. a result, this mode will usually provide very poor color resolution on a
  559. given image compared to a higher resolution mode on the same image.  As a
  560. result, the EGA 320x200x16 mode is not normally supported and 320x200 images
  561. on EGA use the 640x350 mode to maintain aspect ratio.  CIS weather maps and
  562. TREND charts, however, will use this mode as the colors are good for these
  563. images and give a close-to-full-screen display.
  564.  
  565.  
  566.  
  567. VGA ("standard"):  You do *not* need to use the SETSVGA utility.  In fact, it's
  568. important that you do not; if you use it and tell OZRLE that you have a super
  569. VGA system when in fact you do not you're sure to see all kinds of problems.
  570.  
  571. SVGA ("SuperVGA"):  OZRLE now supports the 7 major SVGA chipsets internally in
  572. assembler (no linked-in drivers, etc.)  Support is provided for Tseng Labs,
  573. Paradise, Video7, ATI, Everex, Trident and Chips&Tech.  OZRLE needs to know
  574. two things about your video system: which chipset it should support, and what
  575. the highest 256-color image size is that your combination of card and monitor
  576. can support.  The SETSVGA program gets this information from you and patches
  577. the appropriate information directly into the executable file.  Before you use
  578. OZRLE the first time you need to run SETSVGA and answer its two questions.
  579. Note that the question on max resolution is for the highest *256-color* mode
  580. your hardware can handle, not nessessarily the max mode the card can do.  If
  581. for instance you have a Paradise PRO with only 256K of video memory, you
  582. should use the 640x400 setting as a max mode because you can only do 16 colors
  583. at higher modes.  Another example would be if you have an STB VGA/em with 512K
  584. but only have a "standard" (non-MultiSync) analog monitor, you need to set the
  585. max mode to the 640x480 setting.  OZRLE will always do at least to 640x480
  586. even when it has to use 16 colors.  Also note that the Everex SVGA support is
  587. limited to 640x400 (this is all most Everex cards will do at 256 colors.)
  588. The Video7 type does not support the 720x540 mode.  The 360x480x256 mode
  589. 0x13 "special" is not supported in this version; I hope to get it working in
  590. a future release.  I also hope to get IBM8514/A support added in a future
  591. release.
  592.  
  593.  
  594.  
  595. Commands Within OZRLE
  596. ----------------------
  597.  
  598. OZRLE provides several commands while operational.  These all are used to
  599. modify the same functions you set with command line options or environment
  600. variables.  Generally, the letter used for a particular option setting will
  601. be the key used with the [Alt] key to modify that option while in OZRLE.
  602. To see a menu of available Alt-Key commands in the program, press the [Home]
  603. key.  Most all of the commands are self-explanitory.
  604.  
  605. The "Offline View" part of OZRLE is a program within itself.  This section
  606. allows you to view offline those GIF images you have captured.  Press Alt-G
  607. to enter offline view mode.  Offline view gives many features only found
  608. in the powerful offline-only decoders such as a "tag-and-shoot" interface,
  609. "slides" mode (display multiple files automatically), large image scroll
  610. and "banded" interlacing.  Note that while OZRLE has these and other capa-
  611. bilities and is a fairly fast offline decoder, it should not be considered
  612. a replacement for a good offline-only decoder such as VPIC or FASTGIF.
  613. These programs provide faster display speed and many special features that
  614. there simply isn't room for in a program such as OZRLE.
  615.  
  616. The available commands in offline view mode are these:
  617.  
  618.    while in filepick mode:
  619.  
  620.      cursor keys,
  621.      pgup/pgdn,
  622.      home/end    - move around in the files list
  623.      enter       - display the highlighed file
  624.      spacebar    - "tag" the highlighted file for slides mode display
  625.      Alt-S or F2 - display tagged files (slides mode)
  626.      Alt-N       - toggle alarm sound on/off
  627.      Alt-B       - toggle banded interlace on/off
  628.      Alt-A       - toggle autosize on/off (Herc, CGA and EGA only)
  629.  
  630.    while a single image is displayed (only the esc command works in slides
  631.    mode):
  632.  
  633.      cursor up/dn,
  634.      pgup/pgdn  - scroll large image into view  (EGA, VGA only)
  635.      "1"        - force standard image sizing \
  636.      "2"        - force autosizing            / (Herc, CGA, EGA only)
  637.      enter      - exit display
  638.      esc        - abort slides display
  639.  
  640.  
  641. Another new command is available in OZRLE - the Alt-V (View Scrollback buffer)
  642. command.  This allows you to see what has scrolled off the top of the screen.
  643. Currently this is only one screen in size; I will be expanding it (up to 400
  644. lines user-settable) in a future version.
  645.  
  646.  
  647.  
  648. Macro "QuickKeys"
  649. -----------------
  650.  
  651. OZRLE allows you to define up to 40 "QuickKeys" to simplify its use.  These
  652. keys are the function keys, and the function keys used in conjunction with
  653. [Ctrl], [Shift] and [Alt].   Each may have a string of up to 127 characters
  654. assigned to it (a "macro".)  Macros 1 thru 10 are assigned to function keys
  655. [F1] to [F10], macros 11 thru 20 are assigned to [Shift][F1] thru [Shift][F10],
  656. macros 21 thru 30 go with [Ctrl][F1] thru [Ctrl][F10], and 31 thru 40 are
  657. assigned to [Alt][F1] thru [Alt][F10].  Pressing a QuickKey causes the program
  658. to send the macro assigned to that key out the serial port.
  659.  
  660. The definition for macro keys are stored in a flat ASCII text file.  Do not
  661. use a word processor that inserts special control codes or other non-standard
  662. characters to create this file, or be sure to save the file in ASCII or
  663. "non-Document" mode.  The file is read by the program sequentially a line
  664. at a time, each line being assigned to the next macro (line 1 goes to macro
  665. 1, line 2 to macro 2, and so forth.)  The file does not have to be 40 lines
  666. long.  To skip a macro, insert a blank line in the file.  The default name
  667. for this file is OZRLE.FKS, but you can name the file anything you like as
  668. long as you set that name to the OZMAC environment variable or set the /L
  669. command line option to that filename.  Previous versions of OZRLE gave a
  670. warning if it could not find the OZRLE.FKS file on startup and no new file
  671. name was provided; many users found this confusing so the warning has been
  672. removed unless OZRLE.FKS (or the filename you specify) is found but corrupt
  673. in some way, or if you provide an overriding filename and _that_ file is not
  674. found.
  675.  
  676.  
  677. Macro Subcommands
  678. -----------------
  679.  
  680. OZRLE provides further flexibility by allowing several embedded subcommands
  681. within macros.  These subcommands allow you to insert the current port, baud
  682. rate and parity setting, have a macro request input and then place that input
  683. in the macro before sending, wait until a character is received, and to use a
  684. macro to shell to DOS and execute the macro as a DOS command line.  Addition-
  685. ally, subcommands are available to insert a carrage return in a macro and to
  686. delay macro processing 1/2 second.  Finally, standard "carat notation" is
  687. allowed to insert control characters in a macro.  Where found in a macro, the
  688. subcommand is replaced with the data it specifies.
  689.  
  690.  
  691.  
  692. All embedded subcommands (except the CR and delay characters and the control
  693. character notation) begin with the "at" symbol (@).  The following list
  694. defines the available subcommand letters:
  695.  
  696. O       Force a DOS shell, and use the macro as a DOS command line.  This
  697.         only works when the first 2 characters of a macro are "@O", otherwise
  698.         they are ignored.  The macro is processed for insertion of all other
  699.         subcommands before executing.  The macro is not sent to the port.
  700.  
  701. M       The "M" subcommand takes a second qualifying letter defining the
  702.         specific modem parameter to be inserted in the macro.  these
  703.         qualifiers are:
  704.  
  705.             C - insert the current port number.
  706.             B - insert the current baud rate.
  707.             P - insert the current parity setting.
  708.  
  709.         For example, placing "@MC" in the macro when the current port is
  710.         COM1 would cause the subcommand to be replaced with "1".
  711.  
  712. W       The "W" subcommand takes a second qualifying character or string and
  713.         waits until received.  This gives a very limited but useful "script"
  714.         capability.  Example: "@W!" would wait until the "!" char was received
  715.         (or the <esc> key is pressed) before continuing execution of the
  716.         macro.  When waiting for more than one character (a string) you need
  717.         to enclose the specified string in double-quote marks.  Example: to
  718.         wait for the string "User ID:" you would use `@W"User ID:"' in the
  719.         macro.  You can place up to 10 "Wait" commands in a macro and each
  720.         can wait for a different character or string.
  721.  
  722. I       The "I" subcommand forces the macro to prompt you for input, and
  723.         then insert that input in place of the subcommand.
  724.  
  725. An example macro to call the DSZ external ZModem protocol module from within
  726. OZRLE to upload a file to a BBS would probably contain this:
  727.  
  728. @O DSZ port @MC speed @MB sz @I
  729.  
  730. When you press the QuickKey assigned to this macro, you would first be
  731. prompted for input.  Assuming you input "FOO.BAR", and you were using COM1
  732. at 2400 baud, the following command line would be executed by DOS:
  733.  
  734. DSZ port 1 speed 2400 sz FOO.BAR
  735.  
  736. ---
  737.  
  738. The pipe character (|) is used as a carrage-return in a macro.  The tilde
  739. character (~) forces a one-half second delay where it is found in the
  740. macro.  These two special characters are provided to simplify using macros
  741. as modem command strings.  As an example, let's say you want the F1 key
  742. to send a command to your "Hayes-compatible" modem to reset and then dial
  743. the number of your CIS node.  Assuming the number of the node I use and the
  744. way I normally set my modem, the following macro would be used:
  745.  
  746. ATZ|~~~~ATM3V1X4DT922-3308|
  747.  
  748.  
  749.  
  750. This sends the "ATZ" command to the modem with a carrage-return, waits two
  751. seconds (so the "OK" reply from the modem can display), then sends the setup/
  752. dial command string and a carrage-return.  Another example is the macro I
  753. use to log on thru Tymnet:
  754.  
  755. |~~~~~~~~A@W:CIS02|@W"User ID:"70000,000|@W"Password:"my-password|
  756.  
  757. Once I get the "CONNECT 2400" from the modem, I press F2 for this macro.  It
  758. sends a carrage-return, waits four seconds for Tymnet to give its "Please enter
  759. your terminal identifier:" prompt and replies with the "A" nessessary, waits
  760. for the "Please log in:" Tymnet prompt, sends the "CIS02" and carrage-return
  761. to tell Tymnet to connect me to CIS, then waits to allow CIS to issue the "User
  762. ID:" prompt and sends a userid and carrage-return, and finally waits for the
  763. "Password:" prompt and sends a password.
  764.  
  765.  
  766.  
  767. The Protocol Window
  768. -------------------
  769.  
  770. During a protocol transfer a window appears on screen detailing the transfer
  771. activity.  Most things about the window are pretty self-explanitory, but one
  772. area deserves clarification - the "Port" and "Data" percentages on the "Ef/Tm"
  773. (Efficiency/Time) line.  The percentage displayed in the "Port" column is the
  774. comparison of current protocol "raw" port rate to the current port baud rate
  775. setting of the UART.  In other words, at 2400baud this figure would optimally
  776. be 100% if we were seeing 240 bytes per second comming in the port during a
  777. transfer.  Since CIS uses its packet-switching network and network delays of
  778. some magnitude are inevitable, this figure will almost always be less than
  779. 100%.  Normally you can expect greater than 230 cps "raw" rates on downloads,
  780. but uploads often fall below 200.  Connections established thru suplimental
  781. carriers such as Tymnet may well be less.  The percentage under the "Data"
  782. column, on the other hand, is the ratio of total data bytes received to the
  783. protocol's average "raw" port rate.  In other words, the efficiency of the
  784. actual data comming in the port.  This figure normally runs around 92 - 96%
  785. for binary files and 97 - 99% for ASCII text files.  However, bad packet
  786. resends when an error occurs and is corrected cause this figure to drop,
  787. sometimes dramatically.  Providing both figures makes it easier for you to
  788. decide when to abort a transfer.  If the "Port" figure is dramatically low
  789. (usually due to a high network traffic load but can also be due to delays
  790. caused by suplimental carrier networks), you may want to abort the transfer
  791. and wait until network traffic had dropped so good port rates are possible.
  792. If the "Data" figure is low (usually due to a high error-packet count), you
  793. may want to abort and call back on another node.  The time display under the
  794. "File" column is the time the transfer has taken so far, while the time under
  795. the "Remaining" column is an estimate of the time it will take the rest of the
  796. transfer to complete.  The "Remaining" time figure will vary based on the cur-
  797. rent port rate as it is recalculated at the end of each packet.
  798.  
  799. On GIF image views that are protected by protocol (right now only the TREND
  800. area of CIS does not use B+ protocol protection), a small window is displayed
  801. after the image view is complete, and notes the important protocol performance
  802. results.  Because the actual image data display process between blocks takes
  803. a little time, it is very rare that you will get the same performance figures
  804. on an image view that you get on a file download, but they should be pretty
  805. close.  Remember, the TREND area does not provide protocol protection on the
  806. image stream, and if that unprotected image data gets corrupted it will usually
  807. cause the system to lock up.
  808.  
  809. While on the subject of the TREND area of CIS, another note:  TREND works
  810. funny.  When you enter the TREND area you are prompted for a stock (either
  811. name or ticker symbol) and then for "number of periods".  After this last
  812. prompt, you get nothing - for as long as 2 to 3 minutes.  No "Please wait"
  813. message, nada.  What is happening is that the CIS computers are analyzing
  814. your request and "building" the graphic image in real time, and that _takes_
  815. time.  The problem is that the host appears to have "died" or disconnected;
  816. hitting [enter] a few times does nothing, nor does the usual Ctrl-P or Ctrl-C
  817. abort commands.  Just be aware of the delays and don't think CIS has dropped
  818. you.  I've hit FEEDBACK about this problem, and since FEEDBACK is free I
  819. hope all of you who use TREND will also stop by there and leave a complaint
  820. message (not nasty of course, just a polite reminder) that there needs to
  821. be some sort of "Please hang on - this can take a few minutes" message after
  822. that last prompt.  Thanks.
  823.  
  824.  
  825.  
  826. Video Modes Capabilities Charts
  827. -------------------------------
  828.  
  829. The following chart lists the video modes OZRLE uses for graphics images.
  830. RLE images always use the lowest size mode available on a given video system,
  831. usually 320x200; since Herc mono has only one size mode, RLE and small GIF
  832. images will show only in the upper lefthand corner of the screen.
  833.  
  834. Mode numbers are Decimal.
  835.  
  836. Adapter           Mode #         Description (WDTH x HT x NUMCOLORS)
  837. -------           ------         --------------------------------------------
  838. Herc Mono          xxx           720x348x2
  839.  
  840. CGA                04            320x200x4 (grayscale)
  841.                    06            640x200x2
  842.  
  843. EGA                13            320x200x16 (normally used only on CIS images)
  844.                    14            640x200x16
  845.                    16            640x350x16
  846.                    18            640x480x16 (requires /EGA480 switch)
  847.  
  848. MCGA               17            640x480x2
  849.                    19            320x200x256
  850.  
  851. VGA                14            640x200x16
  852. (and "std" VGA     16            640x350x16
  853.  modes on most     18            640x480x16
  854.  SVGA cards)       19            320x200x256
  855.  
  856. SVGA             varies          640x350/400x256
  857.               (see below)        640x480x256
  858.                                  800x600x256
  859.                                  1024x768x16
  860.  
  861.  
  862.  
  863. Here is a list of VGA/SVGA chipsets, popular cards that use them and the
  864. max 256-color image size (these are currently supported in OZRLE):
  865.  
  866.   Chipset/card               Max 256-color mode
  867.   ------------
  868. Tseng Labs:
  869.    Orchid Designer              800x600  640x480
  870.    STB VGA/em                   800x600  640x480
  871.    Genoa 5200                   800x600  640x480
  872.  
  873. Paradise:
  874.    AST                          640x400
  875.    AST VGA Plus                 640x480
  876.    Compaq                       640x480
  877.    Dell                         640x480
  878.    Paradise VGA Pro             640x480
  879.  
  880. Trident:
  881.    Maxxon                       800x600  640x480
  882.    Logix                        800x600  640x480
  883.    ATI Prism Elite              640x480
  884.  
  885. Everex:
  886.    EV-673                       640x400
  887.  
  888. ATI:
  889.    VGA Wonder                   800x600  640x480
  890.  
  891. Video 7:
  892.    VRAM                         640x480
  893.    V7 VRAM                      800x600
  894.    FastWrite                    640x400
  895.    FastWrite AD                 640x480
  896.  
  897. Popular cards that currently support only 320x200x256 in OZRLE:
  898.    Rennasance GRX I & II                (CIRRUS chipset)
  899.    Zenith VGA, Tecmar VGA & VGA-AD      (early Tseng Labs)
  900.    Sigma VGA/H                          (another early Tseng Labs)
  901.      most other VGA cards
  902.    IBM 8514/A                           (VGA emulation mode)
  903.    IBM MCGA and VGA
  904.  
  905. Where two sizes are listed, the first is for that make/model card with 512k
  906. video RAM memory installed and the second is for the same card with 256k.
  907. OZRLE supports almost all VGA cards at 320x200x256 and 640x480x16.  Some
  908. cards are still on the market with older chipsets by one of these mfgrs that
  909. do not match up modes properly (example: the Zenith, Sigma VGA/H and Tecmar
  910. "std" and VGA-AD cards use chipsets made by Tseng Labs but with grossly dif-
  911. ferent setups; these can only do 320x200x256) so be aware that older cards may
  912. not work properly.  I hope to have these "oddball" chipsets supported in a
  913. future release (especially the IBM 8514/A.)  Many of these cards have other
  914. resolution modes as well, but these are the only ones that are both common
  915. across most chipsets and also generally used for GIF images.
  916.  
  917.  
  918.  
  919. Kudos, Credits, Karma Enhancements
  920. ----------------------------------
  921.  
  922. The sysops of the IBMNet forums on CIS: Don Watkins, Connie Kageyama, Chris
  923. Dunford and Vern Buerg.  My primary beta testers, and the greatest group
  924. of folks around.  Ditto for Valerie Zen and Tom Potoki, sysops of the Graphics
  925. Trilogy forums on CIS, who also help test.  Really have to include the whole
  926. of the Developer's Group in the PICS forum as many have tested, provided
  927. suggestions, etc.
  928.  
  929. Kim, Brian and Rich of TurboPower Software, for writing and maintaining the
  930. best library of Turbo Pascal utility routines in the free world.
  931.  
  932. Chris Young, HSX-200 SysOp and GIF wizard, for the asm LZW decompress and GIF
  933. header decoding, and the EGA video routines.  *BIG* help!
  934.  
  935. John Bridges (of GRASP fame) for his SVGA bankswitch and modesetting code.
  936.  
  937. Russ Ranshaw ("Wiz10") and others at CIS, for providing exellent documentation
  938. on the B+ protocols, and understandable source code for same.  Ditto to Brion
  939. Jones of CIS for informative literature on interrogation/response sequences
  940. and terminal reply codes.
  941.  
  942. Most importantly... you, the users.  Your questions, criticisms and sugges-
  943. tions have helped make the program what it is.  If you like it thank yourself,
  944. not me.
  945.  
  946.  
  947. Point of Contact
  948. ----------------
  949.  
  950. I can most easily be reached via CompuServe; my ID# is 71520,77.  Please leave
  951. questions in either IBMNEW or IBMCOM rather than EasyPlex; other users or the
  952. sysops may well be able to give you a faster answer.  If you need to contact
  953. me concerning registration, please do so by EasyPlex or US mail:
  954.  
  955. Steve Sneed  71520,77
  956. 409 San Juanico
  957. Santa Maria, CA.  93455
  958.  
  959. This program is not shareware in the traditional sense; I do not require
  960. private non-commercial users to register or pay a license fee (see the section
  961. on license requirements at the top of this document.)  If you have a burning
  962. urge to send me money anyway... I won't turn it down. <grin>  Please make
  963. checks payable to Steve Sneed.  Updates are only done thru CIS; I do not
  964. notify users of updates (except for fully-licensed commercial users.)  If
  965. you are registering for full license, please plainly state so in your
  966. corospondence along with how you are using the program.  Site licenses and
  967. multi-license discounts are available; please contact me for specific info.
  968. Finally, please do not call me voice, and I cannot accept any collect calls.
  969. I don't mind helping folks, but 7am and 11pm calls do not help my baby
  970. daughter sleep.  Thanks.
  971.  
  972. I hope you enjoy the program!
  973.  
  974. <eof>
  975.