Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / COMMUNIC / K9X88D_4.ZIP / OZBEXTB.ZIP / OZBEXT.DOC next >

Wrap

Text File | 1989-03-13 | 33.0 KB | 677 lines

OZBEXT 10.1f 14-Mar-89 Copyright(c)1988,1989 Steve Sneed ---------------------------------- NOTE TO USERS OF PREVIOUS VERSIONS: *Please* read this document before using! Several things have changed from earlier versions, most notibly the exact syntax for command line parameters and the meaning of a couple of parameters themselves. See the section "For Users of Earlier Versions" at the end of this document! DISCLAMER/COPYRIGHT NOTICE -------------------------- This program is copyrighted (c)1988,1989 by Steve Sneed. The program may be freely copied and used under the following restrictions: 1. The program file and its associated documentation file are distributed together in an "archive" format, and neither is modified in any way. 2. The program is free of charge or request for renumeration for use or distribution for any private, non-commercial use. Commercial use of any kind, including (but not limited to) use in a business, or distribution by any commercial enterprize, requires a license and payment of a $10 fee. Specific license without nessessary fee payment is hereby granted to CompuServe, Inc. (an H&R Block Co.), the First Osborne Group (FOG), The Public (Software) Library, TurboPower Software and PCMagNet. Multi- copy and site licenses are available at reduced rates; contact the author at the address below for more information. While every care has been taken to assure this program works as intended, no warranty or guarantee of any kind is made with respect to the program or its documentation, including any guarantee of fitness for a particular purpose. IN NO CASE WILL THE AUTHOR BE HELD LIABLE OR RESPONSIBLE FOR ANY LOSS, INCLUDING LOSS OF DATA OR EQUIPMENT DAMAGE OR MALFUNCTION. This program was written using Turbo Pascal 5.0 and Turbo Assembler 1.0, and debugged using Turbo Debugger 1.0, all from Borland International. Some parts are from source libraries by TurboPower Software. B+ protocol source routines taken in part from some by Russ Ranshaw, CompuServe Inc. All used with permission. WHAT IS IT? ----------- OZBEXT is an "external protocol module"; a program used to provide one or more file transfer protocols to communications programs that do not internally support those protocols. OZBEXT supports the CompuServe Information Service- specific protocols, known as "B" and "B-Plus" (sometimes incorrectly called "Quick-B".) The B protocol is an older protocol using a "send-and-wait- for-reply" design (and is slow), while B-Plus uses modern "windowing" protocol technology for very fast performance and provides extensions such as Aborted Transfer Resume and File Information Passing. Why use the B-series protocols? The XMODEM-derivitive protocols (with the exception of ZModem, which is not supported on CIS) were designed to be used strictly on a direct connection - that is, where one PC is connected directly to another (as when you call a local Bulletin Board System) and both machines can devote their full attention to processing the protocol. CompuServe's mainframes are handling many callers at once, and the network used to connect those callers can introduce delays that can (and usually do) kill the XMODEM-type protocols. Even XMODEM protocols that have "relaxed" timing parameters can have problems. KERMIT, a protocol designed to work well in hostile environments such as the CIS network, is very slow, and many of the available PC implementations do not fully match the KERMIT standard and therefore do not always work with CIS. The B protocols were designed by CIS to work on CIS. Some existing communications programs provide older versions of the B protocol internally or as specific add-on overlays, but to my knowledge none currently provide support for the full, current B-Plus specification (although I believe TAPCIS has a version in BETA testing as this is written.) B+ provides the best and safest protocol performance available on CIS, period - it should always be the protocol of choice on CompuServe. FEATURES -------- OZBEXT provides everything you need to effectively transfer files on CIS. In addition, the program provides some extra features that make it easier to use, more configurable to suit the needs of most users and other pro- grams, and more exactly matched to the way the CompuServe network does things. Some of the features include: * All program state options settable both from the command line and within the program. * Full, latest-version B-Plus protocol for fast, reliable file transfers on CompuServe and other networks and BBS systems that support B-Plus. * 40 "Macros" keys definable by you. Macros can contain metacommands for requesting and providing special information, and can force a "Shell to DOS" while providing a complete command line to execute (for calling other external protocol modules, editors, etc.) * Full support for both the CIS VT100 and VT52/VidTex terminal emulations, and true DOS ANSI emulation, for screen colors and cursor control. * The ability to define a default path for files to be up/downloaded other than the current path. * Provides an EOA ("Emergency Override Abort") functionality. The B+ protocol can be very slow when an abort is requested mid-transfer, especially when the abort is wanted because carrier has been dropped. EOA aborts within a very few seconds. * A direct interface to my OZRLE program for viewing RLE and GIF format graphics images while online. CONFIGURING OZBEXT ------------------ OZBEXT takes all of its configuration information from the command line you enter when you execute the program. There is no "config" program to run or definition file you must create. OZBEXT defaults to a certain group of settings that are by far the most commonly used on CIS; only if you need to change one or more of these do you need to enter anything on the command line. OZBEXT uses a standard notation for command line parameters: the program's name is followed by one or more option "switches" and any nessessary qualifying information, separated by spaces. Each switch is a forward slash (/) or dash (-) and a letter. The switch letters are not case- sensitive. Any switch requiring a qualifier has the qualifier immediately following the switch with no space in between. OZBEXT's available configuration options fall into two groups: port-related options and internal program states. Port-related options are those that effect the comm port to which your modem is attached, such as port number, baud rate, parity, etc. Internal state controls effect the way OZBEXT deals with characters received/transmitted and certain other functions such as how the program behaves at the end of a transfer. The port-related options are usually not needed; they are provided as an adjunct to using the program as a stand-alone communications program or terminal emulation facility. On startup, OZBEXT examines the selected comm port for its existing settings and then uses them unless told otherwise on the command line. Issuing specific port-related options that may not match the port's existing settings can cause the port to be confused, causing a system lock-up and requiring a reboot. The following list contains the available port-related switches: /C[port] Selects the comm port to use. The program assumes COM1 to be the desired port. Before looking for this switch, the program also checks the DOS environment to see if an environment variable called OZPORT has been defined, and if so uses the port number so defined. If no OZPORT env. var. exists, the program looks for one called DSZPORT (normally used by the DSZ.COM external protocol module by Omen Technology Inc.) and if defined uses it. Rather than using this switch, it is recommended that you define one of these two variables by adding a line to your AUTOEXEC.BAT file that says: SET OZPORT=? or SET DSZPORT=? where the question mark is replaced with your working comm port number. Allowable port numbers are 1 thru 4. /A[baseaddr] /I[irq] Select a non-standard base address and interrupt request line for the chosen port. These options are provided for those folks using IBM PS/2 systems on COM 3 or 4 that have non-standard base addresses, and other systems using special serial port cards - they are NOT required for any system using a standard COM 1 or 2 card, or COM 3 or 4 on most XT/AT-buss cards. Note that if either option is provided, the other must be provided as well. You can also set these options from the environment; the OZBASE env. variable sets the base address and the OZIRQ env. variable sets the IRQ line. The IRQ value can be any number between 1 and 15. The base address value must be a 4-digit hexidecimal number preceeded by a dollar sign ($). /B[rate] Selects baud rate. OZBEXT examines the selected port on startup and uses its current baud rate unless overridden with this switch. Any standard baud rate number from 300 to 38400 is allowed (300, 1200, 2400, 4800, 9600, 19200, 38400.) The default baud rate is 2400. /P[parity] Selects parity setting. OZBEXT examines the port on startup and uses its current parity unless overridden with this switch. Available parity settings are None, Even, Odd, Mark and Space. Only the first letter of the parity word is required, but you may provide the full word if you like. If parity is set to None, the dataword size is auto- matically set to 8 unless overridden with the /W switch. Likewise, the dataword is automatically set to 7 if parity is set to Even or Odd (if Mark or Space parity is chosen, you must provide a /W switch as well.) /W[dataword] Selects the data word size. Existing port setting is used unless overridden with this switch. Available settings are 5 thru 8. /S[stopbits] Selects the number of stop bits. Existing port setting (almost always 1) is used unless overridden by this switch. Available options are 1 and 2. If 5 dataword bits is selected using /W, the stop bits setting is automatically set to 1-1/2 by the UART chip and is not overridable. The program state options are used to modify the standard configuration. OZBEXT normally starts in this configuration: Full Duplex communications. Returns to its own terminal mode at the end of a transfer. Provides an audible alert at the end of a transfer and waits for you to press a key. Uses the special VT100/VT52 terminal emulations used by CIS. Leaves the modem DTR signal high on exit so an existing connection is not dropped. Uses the current drive/path for transfer files. Looks for and loads a file named OZBEXT.FKS for function-key macros. All of the states can be changed with command line option switches. All but two are "toggles", meaning that the startup state is "on", and providing the option switch turns it "off". The other two options are for transfer file path and macros file, and require qualifying information to be pro- vided. Note that all of the above options can be changed within the program as well as on the command line. All state options can be established from environment variables: OZOPT=??????? (where the question marks are replaced by one or more of the switch letters D, H, X, N, V, O or Q); OZPATH=path (where "path" is replaced with a valid path); and OZMAC=file (where "file" is replaced with a valid path/filename for the macros file.) The switches for the state options are as follows: /D Forces the modem DTR signal to be dropped on exit, hanging up any call in progress. The default state is to leave DTR high so the existing connection is not broken when returning from OZBEXT to some other comm program. Note that some cheap and/or oddball modems do not obey the DTR signal very well and may not break an existing connection (the SMT and Zoom internal modems are notorious for this.) /H Forces OZBEXT to use half-duplex communications mode. Default is the far more common full-duplex. CIS always starts a call in full-duplex mode. /X Forces OZBEXT to exit immediately on completion of a transfer and return to the calling program. Default is to return to its own internal terminal mode so you can transfer another file or navigate to another area. If the comm program you are currently using gives good support for the other functions of CIS and you are using OZBEXT strictly for its fast file xfer, you may well want to use this switch. Using this switch overrides the state of the /N "Noise alarm" switch (see below.) /N Forces OZBEXT to be quiet (not give any audible alarms except for gross error conditions.) Default is to provide an audible alarm at the end of a transfer and under a few other conditions. Note that this switch actually serves two functions: in its default state (noise ON), on transfer completion you are both notified audibly and the transfer information window is left on the screen until you press a key; when the switch is OFF you are not barraged with the beeper and the transfer info window immediately disappears without waiting for the keypress. Also, using the /X switch overrides this switch - if /X is used, Noise is forced OFF. Nice for busy offices where a beeping computer is a real annoyance. /O OZBEXT continually monitors the carrier signal during a transfer. If carrier is dropped, an EOA is automatically performed. While this is an exellent safety feature, some CIS users are connected to the network directly thru a standard serial 3-wire connection rather than thru a modem. For those users, the CD signal is not provided so the auto-EOA kicks in immediately when a transfer is initiated - not pretty. The /O switch turns off this CD checking so an EOA is only performed if one is actually requested from the keyboard. Use of this switch is not recommended unless you have one of these direct network connections. /Q Forces an XON character to be sent immediately on startup. While not many programs send an XOFF when calling an external module, a few (notably AutoSIG and TAPCIS) do. Using this switch forces an XON to be sent once OZBEXT is initialized so communications can continue. If you use ATO or TAP, you should use this switch. /V Forces OZBEXT to use "true" DOS ANSI terminal emulation rather than the default VT100/VT52/VidTex emulation. DOS ANSI and the Digital Equipment Corp. VT100 emulations are close but unequal (and improper) subsets of the American National Standards Institute's X3.64 standard for terminals. Exact DOS ANSI emulation used on CompuServe can cause the screen to be cleared at some very bad times - like right after a menu has been displayed but before the input prompt. However, using VT100 on some BBS's can cause the ANSI graphics screens to not display properly. This switch should not be used if you are calling CIS, only if you are calling a BBS or other non-CIS system. /F[path] Allows a path other than the current DOS working path to be specified for files during transfer. The provided path is checked to be sure it does in fact exist. /L[file] Allows a macros file name other than the default (OZBEXT.FKS) to be specified. When started, OZBEXT looks for the file in the current (or specified) path and, if found, loads it for the macro key's definitions. See the section on macros below. Here are some example command lines that might be used for the program: OZBEXT /q -forces an XON to be sent on startup. Recommended for users of the CIS- specific comm programs AUTOSIG and TAPCIS. OZBEXT -X -forces OZBEXT to exit immediately after a transfer. Good if you use an automated navigation program (like ATO or TAP) or a program with good VT100 emulation (like ProComm+ or QModem.) OZBEXT /d /c2 /b2400 /pNone /v -forces OZBEXT to use COM 2, set the port to 2400 baud at None parity, drop carrier when exiting and use true ANSI emulation. A possible command line if you are running OZBEXT "stand-alone" to call a BBS. OZBEXT /fA: -force all downloads to be placed on the A: drive, and all uploads to come from that drive. OZBEXT /Lvt100.key -force OZBEXT to look for and load a file called VT100.KEY for the macros definitions. Note that the VT100.KEY file provided with QModem 3.0 and later works perfectly with OZBEXT so you can have a more complete VT100 emulation. SETTING UP TO RUN OZBEXT ------------------------ OZBEXT can be used stand-alone (as a general-use comm program), but it is best used as an adjunct to your favorite general communications package. When used in this manner, there are two primary ways to set up OZBEXT: if your comm program provides a method to "install" an external protocol module, you should by all means take advantage of the capability; or you can create a batch file that passes to OZBEXT all command line options nessessary for your particular setup and then run the batch file from a DOS shell. A few programs (such as QModem) use both together. It is beyond the scope of this document to cover exact installation methods for every comm program out there that supports external modules. However, the general guidelines below may prove to be of help: 1. Most programs allow you to enter a complete command line to call the external program, and allow some way of imbedding port-related info in the loaded command line. Many people feel that the port-related info is required - it is NOT for OZBEXT. When establishing a command line for OZBEXT as installed in another program, the only command line parameters you will want to use are those that set internal program states, such as duplex mode, exit-when-transfer-done, etc. Possibly you may need to provide the comm port number; this is better done by setting the OZPORT or DSZPORT environment variable in your autoexec.bat file. See the section above on configuration for more information. 2. Almost all programs that support externals provide for a separate loader for uploading and downloading. Because OZBEXT starts in terminal mode rather than immediately entering a protocol transfer, the exact same loader line should be used for each of the upload and download commands. 3. If your program only provides a single "external program" loader (an example is the older ProComm 2.4.2 version), or simply provides a "Shell to DOS" feature, it is best to create a batch file to execute OZBEXT rather than trying to remember and type in all the option switches you might use. Here is an example batch file content that executes OZBEXT on a command-line port in half-duplex and quiet modes: ECHO OFF CLS IF %1X==X GOTO ERROR OZBEXT /C%1 /H /N GOTO DONE :ERROR ECHO No port information provided! :DONE Use your favorite ASCII text editor (or the DOS "COPY CON" command) to create this file, calling it CISB.BAT. Then you would enter: CISB 1 to run OZBEXT on COM1, or CISB 2 to run on COM2. 4. If your DOS environment has the room to spare, set all of your common switches using environment variables rather than switches on the command line. For example, if you always use OZBEXT from within AUTOSIG in half-duplex mode, add a line to your AUTOEXEC.BAT file that says SET OZOPT=HQ and you will never need to worry about those switches when running OZBEXT. If you have a specific subdirectory in which you always want downloaded files to be stored (say, C:\COMM\DNLDS), you can use SET OZPATH=C:\COMM\DNLDS and never have to enter it again. If you use many programs that use environment variables, you may not have the room available, but do use them whenever possible. Note that providing /F or /L info on the command line overrides existing environment variable settings. 5. For program-specific help in using OZBEXT, the sysops of the IBMNet on CompuServe have written a series of help files. These files are kept in LIBRARY 2 of the IBMNEW Forum, and cover most of the more popular commercial and Shareware/PD programs. You do not have to download these files; you can use the CIS "READ" command to read them while online. The files all have a name extension of .HLP, and have the desired program's initials and "-QB" as the name (example: the help file for the BitCom program given away with many internal modems is called BC-QB.HLP.) I recommend that, when you do read the file specific to your main comm program, you use that program's "capture to disk" capability to save the file for later review. USING OZBEXT ------------ OZBEXT is very simple to use, thanks to the way the B/B+ protocols work. Both are "host-driven", which means the CIS computers control most all aspects of the transfer. You can call OZBEXT from your main comm program at any time after you log on to the CIS network, or even use the program to make the call. However, you need to be sure to have OZBEXT loaded and active *before* you request a transfer to/from CIS. CIS interrogates the remote program (you) with a special code when a transfer is requested, and very few programs know how to deal with this interrogation - most just ignore it, and the few that do understand and know how to reply to it do not provide the information nessessary to exactly match OZBEXT's capabilities and functions. This is especially important when your main program supports the older B protocol but you want to use this program for BPlus; if OZBEXT is not loaded before you request the transfer and the main program replies to the interrogation with its own setup information, CIS may not offer you the option of using BPlus. Also, since CIS "remembers" your protocol capabilities after the first transfer in a forum during any one online session, you will want to get the first one right. The most common pattern of use for OZBEXT is as follows: 1. You navigate thru the CIS system to the forum library (or FILTRN or your PER area) and browse thru the available files. 2. Once you locate the file you want, run OZBEXT. This makes sure OZBEXT is active when you request the transfer. 3. Now request the transfer, using the DOW command. If this is your first transfer this session, CIS will ask you for the transfer protocol type you want - select "QB". CIS will then ask you for the "File name for your computer:" - enter the name you want the file stored under on your system. If you have not specified a files path to OZBEXT and want the file placed somewhere besides your current working path, you can include whatever specific path information you need as part of this prompt response. 4. The transfer will begin. If you need to abort the transfer for some reason, just press [ESC]. Because of the "send ahead" nature of the B+ protocol, it can take several seconds for the abort to be processed. If carrier is dropped or the protocol seems to "lock up" for some reason, perform an Emergency Override Abort (EOA) by pressing the [ESC] key 3 or more times in rapid succession - the EOA will cleanly abort the transfer within a very few seconds. 5. When the protocol transfer is complete, the program will either notify you and wait for a key to be pressed, or just return to its own terminal mode or exit to the calling program, based on the settings of the /X and /N toggles. FUNCTION KEY MACROS ------------------- OZBEXT allows you to assign strings of characters to one or more function keys, so that pressing a specific key sends a complete command rather than just a single character. These strings are commonly known as "macros". 40 macros are available, one for each of the normal, shifted, CTRL-ed and ALT-ed function keys. Macros 1 thru 10 are assigned to F1 thru F10, macros 11 thru 20 are assigned to Shift-F1 thru Shift-F10, 21 to 30 go with Ctrl-F1 thru Ctrl-F10, and 31 thru 40 go with Alt-F1 thru Alt-F10. Each macro can be up to 127 characters long. Macros are stored in a text file you create with any editor or word processor that creates flat ASCII files. Each line of the file contains one macro. OZBEXT reads the file and assigns each line to a function key, in order as they are read from the file. To skip a key, just have a blank line in the file for that key. The file does not have to be 40 lines long. The program provides several "metacommands" for use within macros. These metacommands allow program information to be embedded in a macro string dynamically, allow a macro to request input from you, and force a Shell to DOS. All macro metacommands begin with a forward slash (/) followed by one or two characters. When you press a macro key, the macro string is examined for metacommands before it is sent and any found are processed. Here is a list of the available metacommands: /O -when found at the start of a macro string, assumes the following string data is a DOS command line, shells to DOS and executes the string. If found elsewhere in a macro, it is ignored. /M -modem data insertion. The /M must be followed by another letter specifying what modem data to insert. The qualifying letters are: C -inserts port #. B -inserts current baud rate. P -inserts current parity. /I -requests input from the keyboard and inserts it into the macro. An good example macro is one that would run the DSZ.COM ZModem protocol module (by Omen Technology Inc.) to upload a file using the ZModem protocol. Such a macro could be: /O DSZ port /MC speed /MB sz /I You would be prompted for input - a filename in this case. Let's say you entered "DUMMY.FIL". If you were running at 2400 baud on COM 1, the following line would be sent to DOS: DSZ port 1 speed 2400 sz DUMMY.FIL A couple of other metacommands are available that do not require the leading slash. These are primarily used when a macro is being used as a modem command. The metacommands are: | -inserts a carrage return. ~ -causes macro execution to delay 1/2 second. An example macro string using these metacommands would be one that resets and configures a Hayes-or-compatable modem. ATZ|~~~~ATM1V1X4|~~~~ The macro string above would send the "ATZ" and a carrage return, pause 2 seconds to allow the modem's "OK" response to be received and displayed, send the "ATM1V1X4" and a carrage return, and pause 2 more seconds for the next "OK" modem response. Finally, you can embed control characters in a macro. To do so, use the common "carat notation" for control characters - to enter a ctrl character in a macro, put a carat (the ^ character) and the character in the macro. Example: to put a control-C in a macro, use "^C" in the macro. FOR USERS OF EARLIER VERSIONS ----------------------------- The biggest change between this version and earlier versions is the syntax for command-line parameters - older versions required a space between a command line option switch and its qualifier, while this version requires that *no* space be placed between the switch and its qualifier. I know this means many of you will have to change batch files or module definitions in other programs; I'm sorry for the inconvenience. However, the change was requested by many users, and was needed to gain room on the command line to provide for a transfer files path which was requested be even more users. One command line switch has been added (the /F option to provide the xfer path), and a couple have been changed. Please see the section on options above. Oh, yes... the added support for specifying switches as environment variables is new. The program no longer requires that ANSI.SYS be loaded to do the ANSI/VT100 emulation - all emulation support is now internal. All of you VGA users that have had grief with some of the pseudo-ANSI drivers provided with your cards, and DesqView users who had problems with DVANSI, can now breathe easier. While I do not use DesqView, the program's video routines are "multitasker- aware" and should not "bleed thru" from a background window. They work fine under ConcurrentDOS/XM and 386, and VPix. This version is about 11K larger in actual executable file size than previous versions, but takes only 1K more total memory to execute thanks to paring down memory requirements in several areas - I had been severely pessimistic about locking out enough memory for several processes and suffecient stack space, but thanks to Turbo Debugger I was able to watch the program's stack and memory allocation usage much closer and "trim the fat" from the program. Some of the code size increase came from the added code to internally handle the ANSI/VT100 parsing and adding full support for assigned file paths. Drastically improving the way the program shells to DOS and adding the new environment variable support added the rest. A "ticker" clock display has been added. Of course, it is accurate only for the time you are in OZBEXT; it cannot know online times before or after using the program. I have completely rewritten this documentation file in hopes that it will be clearer and easier to understand, especially for the novice communications software user. No one ever accused me of being able to write anything other than program code; I make no promises as to its clarity, but I do hope you find it easier to understand than earlier versions. Finally, this new version was compiled using the new Turbo Pascal 5.0 compiler, and a few sections of the program were redone using Turbo Assembler 1.0 for improved speed (the port ISR and the ANSI/VT100 command parser.) Also, the latest version 5.0 of the Turbo Professional library from TurboPower Software provided many routines. KUDOS, CONGRATS, KARMA ENHANCEMENTS ----------------------------------- Connie Kageyama, Don Watkins, Chris Dunford and Vern Buerg - the SysOps of the IBMNet Forums on CIS - for their tireless help and testing of this and all previous versions of the program. The greatest group of folks I know. Kim Kokkonen, Brian Foley and the gang at TurboPower Software, for writing and continuing to update and support the finest add-on libraries for Turbo Pascal in the free world. Russ Ranshaw and Steve Wilhite, CIS, for clean B-Plus protocol source code and understandable documentation on same. Most importantly, you - the users, whose exellent suggestions and constructive criticisms have made this program what it is. If you find fault, it's mine; if you like what you see, thank them. Especially, thanks to the many private non-commercial users who have registered the software and paid the license where it was not required - it is *you* who are keeping the spirit of shareware alive! POINT OF CONTACT, ETC. ---------------------- I can always be reached via CIS - my User ID is 71520,77. If you like slow, my mailing address is: Steve Sneed Ozarks West Software 409 San Juanico Santa Maria, CA. 93455 If you contact me via CIS, *please* do so in the IBMNEW or IBMCOM Forums, or in the GRAPHSUPPORT Forum, rather than by EasyPlex - there is no local CIS node where I live so all my access to CIS is long-distance and _expensive_; I have free flags in those areas while EasyPlex time costs me CIS charges so every little bit helps! The C2G BBS is offline (but will ressurrect like the phoenix soon at a different phone number), so CIS and the mail are for now my only available contact points. <eof>