ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / COMM / MISC / TR3_20.ZIP / TR.DOC < prev next >

Wrap

Text File | 1992-06-10 | 108.0 KB | 1,914 lines

TeleReplica Instruction Manual 0. To Get TeleReplica Up and Running Quickly... If you will be using modems then read the modem setup suggestions at the start of appendix A. Then read whichever of the following sections most closely matches your own application: A1 Consultant/Client via Modem One consultant wishing to connect via modem to many different clients in order to take over the clients' computers. A2 Remote/Shared via Modem One remote access PC to be taken over by many different users via modem. A3 Laptop/Desktop via Direct Cable A simple direct connection with no modems. A4 Remote/Shared via Common Mini-computer Instead of a direct link between the two PCs, each PC will be logged into a common UNIX system. A5 Home/Office via Modem A dedicated office PC to be taken over from a home PC. 1. What TeleReplica Will Do 1.1 TeleReplica will allow you to connect two IBM PC-compatible computers together (via telephone lines and modems, or via a direct cable, or via a common mini- or main-frame computer), and arrange for input to be accepted from either keyboard, and for both displays to appear identical. In this document the computer which is running normal programs is called the host computer, and the other computer is called the replica computer, since its display is a replica of the host computer's display. 1.2 TeleReplica will do a reasonable job of optimizing the screen changes transmitted, so that (for example) moving a highlighted menu bar will appear almost immediately even at 1200 bps (provided the call is relatively local). 1.3 TeleReplica always updates the replica computer's screen to match the current host screen. This means that if several commands are issued without waiting for the display to catch up, then the replica screen will be updated to show the final host screen, without wasting time transmitting the intermediate screens. 1.4 TeleReplica uses a password of up to 39 characters, which means an intruder would (on average) take millions of years at 2400 bps to guess a well chosen password! Since this password is transmitted automatically, there is no need to keep it short and easy to remember - once TeleReplica is installed, you will never need to enter the password manually. 1.5 TeleReplica will allow the host site to call the replica site, or the other way around. For consultants this means you can make your clients pay the 'phone bills! 1.6 TeleReplica will automatically detect the "baud" rate being used by the replica computer, and set the host computer's "baud" rate to match. This means that users with different speed modems can all access a single host. 1.7 TeleReplica uses less than 10K of memory on the host computer, which means there should be enough memory left to run most applications. 1.8 TeleReplica can be installed to "type" a command in response to the 'phone ringing, which allows better control than merely using the modem's auto-answer capability. It can also send a command directly to the modem. 1.9 TeleReplica will trap anything printed to any printer on the host PC, and redirect it to the chosen printer at the replica PC. This redirection takes place only when a session is active, so at other times the host can be used to print normally even if TRHOST is still loaded. 1.10 TeleReplica will allow the host PC to run with screen blanked and keyboard dead for improved privacy. 1.11 TeleReplica will support file transfers using external protocol programs such as DSZ, which provide crash recovery and cope better with poor lines than TeleReplica's built-in protocol. 1.12 TR is "DESQview-Aware". See Appendix D for details. 1.13 Full source code is available at a small cost. See REGISTER.DOC for details. 2. What TeleReplica Will NOT Do 2.1 TeleReplica will not replicate graphics displays. If the user at the replica computer runs a program that displays graphics, then the replica display may show (textual) garbage. Keystrokes will still be transmitted to the host computer, but the user must remember which keys are necessary to get out of graphics mode again! TeleReplica gives a warning that graphics mode has been entered, but by then it is too late to avoid it. However, in an emergency TR can instruct the host computer to reboot, so provided TRHOST is run from AUTOEXEC.BAT this provides a means of recovery. 2.2 TeleReplica will only replicate text page 0, and only as an 80 column by 25 line display. 2.3 TeleReplica will only work with the standard keyboard buffer (starting at the address in segment 0040h specified at offset 0080h, ending at the address specified at offset 0082h, with head pointer stored at offset 001Ah, and tail pointer stored at offset 001Ch). 2.4 Where TeleReplica is being used with a modem, it will work best if the modem and modem cable provide carrier detect, data terminal ready and ring indicator signals in addition to the minimum transmit data, receive data and ground signals. 2.5 TeleReplica will cause bad "snowing" on some older CGA display cards. No attempt has been made to use the retrace intervals for screen memory access. 2.6 TeleReplica will slow down the normal operation of the host computer. On a 4.77MHz PC performance can be halved; on a faster host the difference will not be so noticeable. 2.7 TeleReplica requires DOS 3.0 or later. 2.8 TeleReplica will not work particularly well on a noisy 'phone line. File transfers are error-checked, but normal screen updates are not. Normally this will not be a problem, since a corrupted screen will be obvious to the user and in any case TR will usually detect the problem and automatically request a full refresh. However, if errors happen very frequently then TR can spend all its time continually re-refreshing the display! Printer capture also is not error-checked, so line noise will garble the printout. 3. Why Use TeleReplica? 3.1 Access to Local Area Network from Home TeleReplica will allow you to connect into your office computer from home. This means you do not need to take all your data files home with you, and that you do not need to license additional copies of your software (since your home computer is not running the software, only replicating the screen of your office computer). If your office computer is part of a local area network, then you automatically have access to all the network facilities from home. We regularly use TeleReplica with such programs as WordPerfect, WordPerfect Office (especially mail), WordStar, FoxBASE, Lotus-style spreadsheets, all the Novell NetWare utilities, and our local area network is regularly backed up after hours via TeleReplica! The only programs we have come across that could not be used remotely either: a) used graphics displays (e.g. WordPerfect preview); or b) took over interrupts needed by TRHOST (e.g. comms programs); or c) used text pages other than 0 (e.g. Turbo Debugger?) 3.2 Software Support TeleReplica will allow you to take over your client's computer, so that you can see what is going wrong. In many cases this will avoid the need for an expensive trip to the client's site. For details of these and other applications, see the scenarios in Appendix A. 4. TeleReplica Host Installation To install TeleReplica at the host computer, first copy the files: TRHOSTIN.EXE, TRHOSTC.EXE, TRHOST.EXE, TRPUT.EXE, TRGET.EXE, TRTALK.EXE, TRCHECK.EXE, TRASK.EXE, TRDIAL.EXE, TREXTR.EXE, TREXTS.EXE, TRMODSET.EXE, TRRZ.BAT and TRSZ.BAT into a directory (say \TR) on the host computer. Then enter the command: TRHOSTIN Your display should show a menu similar to: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ A. Select serial port (currently COM1) ║ ║ B. Change password (currently "password") ║ ║ C. Change modem initialization string (currently: ║ ║ "\rat &c1 &d2\r") ║ ║ D. Change modem dialing format string (currently: ║ ║ "atdt %s\r") ║ ║ E. Select maximum "baud" rate (currently 2400) ║ ║ F. Use modem CARRIER DETECT signal (currently YES) ║ ║ G. Flow control (currently NONE) ║ ║ H. Generate INT 9 on each key (currently NO) ║ ║ I. Respond to modem RING signal (currently NO) ║ ║ J. Reboot on loss of carrier (currently NO) ║ ║ K. Synchronize "baud" rate (currently YES) ║ ║ L. Send wakeup every 2 minutes (currently NO) ║ ║ M. Private mode (currently NO) ║ ║ N. Printer redirection (currently HOST) ║ ║ O. Create consistent .TR file ║ ║ Q. Abandon changes ║ ║ S. Save changes and leave installation program ║ ║ ║ ║ Selection: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Consider each of these options in turn: 4.1 Select Serial Port Another menu will appear: ╔══════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program Serial Port Selection ║ ║ ║ ║ 0. Completed, no (further) change ║ ║ => 1. COM1 port (base 0x03F8, interrupt IRQ4) ║ ║ 2. COM2 port (base 0x02F8, interrupt IRQ3) ║ ║ 3. COM3 port (base 0x0000, interrupt IRQ4) ║ ║ 4. COM4 port (base 0x0000, interrupt IRQ3) ║ ║ A. Custom base (currently 0x03F8) ║ ║ B. Custom interrupt (currently IRQ4) ║ ║ ║ ║ Selection: ║ ╚══════════════════════════════════════════════════════════╝ All four "standard" ports are listed, although the port addresses for non-existent ports are unlikely to be meaningful (if you are lucky, they will be flagged with a base of 0x0000). To select one of these ports, just type the port number. If you have a non-standard port/interrupt combination, then use A and B to specify exactly what you want. When you are happy with the settings, select 0 to return to the main menu. Please note that I do not have access to any system which uses the AT IRQ numbers (8-15), so I cannot guarantee the performance of TeleReplica when these 16-bit cards are used. Also, since COM1 and COM3 share the same interrupt, only one or other of these ports can be in use at the same time (the same applies to COM2 and COM4). 4.2 Change Password The string editing menu will appear: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program Password Selection ║ ║ ║ ║ Edit existing string: ║ ║ password ║ ╚═══════════════════════════════════════════════════════════════════════╝ Whenever you see the "Edit existing string:" prompt, you can use the left and right arrow keys to move the cursor through the string, and the backspace and delete keys to delete characters to the left of or under the cursor respectively. Any normal characters you type will be inserted at the cursor position. If the first key you press is a normal printable character then the string will be cleared automatically. You will not be able to enter more than the maximum allowed number of characters for any string. Since you will only need to enter the password once during installation, and never in normal use, it is recommended that you make the password near the maximum length and quite random. The main thing is that no-one should have any chance of guessing the password. 4.3 Change Modem Initialization String The string editing menu will appear again, this time asking for the modem initialization string. This string is transmitted to the modem at the maximum "baud" rate when TRHOST runs for the first time. If you are using an automatic power switch that powers up the host computer when the 'phone starts ringing, then the initialization string may need to answer the 'phone (see scenario A2). There may also be various operating modes that cannot be stored permanently in your modem's non-volatile memory, and which must therefore be established each time TRHOST starts. In many applications, where nothing needs to be changed, this string may be empty. You will probably need to refer to the instruction manual for the host modem to work out what if anything is required. As well as normal characters, you may need to include some special characters such as carriage return. Carriage return can be encoded as \r (see the main menu at the start of section 4). Alternatively, any character can be entered in hexadecimal as \0x followed by two hex digits (for example, the escape key is \0x1B). It may also be necessary to include some kind of delay. For example, some modems go off into a world of their own for a second or so after a reset command. Delays are entered in milliseconds as \D followed by the delay (for example, \D1000. [1 second] or \D500. [half a second]). Delays are only accurate to the nearest 1/18.2th of a second, so the number you enter may be modified slightly to reflect the nearest possible actual delay. 4.4 Change Modem Dialing Format String This string determines what TRDIAL will send to the modem to dial a number. The usual use of TRDIAL will be something like TRDIAL 221166, so normally the dialing format string should contain a %s to insert the number. For example, if the dialing string is "atdt %s\r" and the user enters the previous dialing command, then what will be sent to the modem is "atdt 221166\r". Alternatively, if only one number is required, then the dialing format string may contain the actual number, in which case the user will only need to enter TRDIAL by itself. Note that (when CARRIER DETECT is being used) TRDIAL will only send anything to the modem if there is NO carrier detected - once a carrier had been established the modem would not act on the command in any case, but would send it through to the other end. When TRHOST is installed to ignore CARRIER DETECT, TRDIAL will send data to the modem regardless. 4.5 Select Maximum "Baud" Rate Another window will appear: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program Maximum "Baud" Rate Selection ║ ║ ║ ║ Enter "baud" rate: ║ ╚═══════════════════════════════════════════════════════════════════════╝ You should enter the maximum "baud" rate that the host modem is capable of using. Usually this will be 1200, 2400 or 9600. Note that TRHOST can automatically adjust to half this speed, a quarter of this speed, or one eighth of this speed. Thus if you choose 9600 bps, TRHOST will be able to work at 9600, 4800, 2400 or 1200 bps (provided the host modem can handle these speeds). If you will be using a direct cable between two PCs, then 19200 should work on all systems and 38400 will work on faster computers. If your computers have NS16550AFN UART chips instead of the standard 8250 chips then you may find speeds of 57600 or even 115200 work even on slower PCs (not tested, I only have the 8250!). 4.6 Use modem CARRIER DETECT signal Selecting this option will determine whether or not TRHOST will use the carrier detect signal provided by the modem. If you are using a real modem, then you should set this to YES and make sure the modem is initialized so that it reports the true CD status from the 'phone line. If you are using a direct cable between two PCs, or connecting PCs via a mini-computer, then set this option to NO. 4.7 Flow control Selecting this option will bring up the following menu: ╔══════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program Flow Control Selection ║ ║ ║ ║ 0. Completed, no (further) change ║ ║ => 1. No flow control ║ ║ 2. Hardware (RTS/CTS) flow control ║ ║ 3. Software (XON/XOFF) flow control ║ ║ 4. Both hardware and software flow control ║ ║ 5. Set inter-character gap time (currently 330 ms) ║ ║ ║ ║ Selection: ║ ╚══════════════════════════════════════════════════════════╝ 4.7.1 TeleReplica can use the following flow control systems: NONE No flow control. Use this with a direct cable or with modems that require no speed adjustment. CTS Hardware flow control using RTS (request to send) and CTS (clear to send). Use this in preference to software flow control if it is available. XON Software flow control using XON and XOFF (^S/^Q). Use this if flow control is needed and hardware flow control is not available. BOTH Use both software and hardware flow control. I can't imagine why anyone would want this... 4.7.2 Normally TeleReplica will not need to use any flow control even when it is available. However, some modems communicate with the PC at a different speed than that at which they communicate with other modems, so that it is possible for the PC to "get ahead" of the modem and hence lose data. In these cases it is necessary for the modem to tell the PC when to wait a bit before sending the next byte. 4.7.3 A side effect of software flow control is that TeleReplica will not use ANY control characters: it will not send any, and it will ignore all control characters received apart from XON and XOFF. This may be useful for networks that respond to certain control characters; however, binary file transfers will be slightly slower since 64 characters (control characters with and without the parity bit) are not used. Note that both TR and TRHOST must therefore either use or not use software flow control - if one end uses software flow control and the other does not, then no communication will be possible! 4.7.4 When TRHOST is receiving characters (normally keys that have been pressed at the remote PC - each key is encoded as two or three characters) it waits a certain length of time after receiving the first character before giving up and ignoring the key. This is important, since otherwise a single byte introduced by noise on the line could cause all subsequent keys to be misinterpreted (the second character of one key being treated as the first character in the next key and so on). TR always sends all the characters which constitute one key as close together as the communication speed will allow, so usually a gap of even 0.1 seconds means that something has gone wrong and that TRHOST should start looking for a new key again. However, if the link between TR and TRHOST uses packets, or for any other reason introduces significant gaps between two characters that were sent together, then TRHOST may need to be adjusted to tolerate longer gaps between characters which should be together. Selecting option 5 will bring up the following screen: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program Inter-character Gap Time Selection ║ ║ ║ ║ Longest gap to be tolerated (ms): 330 ║ ╚═══════════════════════════════════════════════════════════════════════╝ Any time up to about 10 seconds (10000 ms) can be entered. Be aware that if this time is set to 10 seconds, and line noise does introduce a stray character, then you will need to wait 10 seconds without typing anything at the remote PC to get TRHOST back into synchronization! 4.8 Generate INT 9 on each key When TRHOST receives a key from TR, it will usually just place it in the keyboard buffer to be found by any program that wants to read a key. However, some applications monitor the keyboard interrupt (INT 9) and only read the keyboard input buffer after there has been a keyboard interrupt! To keep such programs happy, TRHOST can generate an INT 9 after it has placed a key into the buffer. However, this can cause problems for other programs, particularly when the host and remote keyboards may both be in use at the same time (e.g. TRTALK). Leave this option OFF unless it is really necessary. 4.9 Respond to modem RING signal Selecting this option will determine whether or not TRHOST will respond to the RING signal which the modem provides to tell the PC that the 'phone is ringing. If this option is turned on, then the menu will be extended with the following sub-options: G. Respond to modem RING signal (currently YES)───┬─ 1. too short 220 ms ├─ 2. too long 5000 ms ├─ 3. delay 10000 ms ├─ 4. reset 10000 ms ├─ 5. "type" response └─ 6. response ─┐ "\0x1Btrauto\r" 4.9.1 If the 'phone only rings for a very short time, you may wish to ignore the ringing completely - otherwise just knocking the 'phone off the hook can trigger a TRHOST response! 4.9.2 If the 'phone rings for a long time, then this may indicate that the caller is a person who should not be greeted by an ear full of modem! If TRHOST is intended to respond before the 'phone stops ringing, then this time should be set the same as the delay below. 4.9.3 After a certain length of time (measured from when the 'phone starts ringing) TR will check that the amount of ringing was within the specified range, and if so, will "type" the response string (see point 5). 4.9.4 If the 'phone rang for too long, then TR must know when to start looking for another call. If the 'phone has not rung for a certain length of time then TR assumes any ringing must be a new call. 4.9.5 The response string may be either "typed" (that is, inserted into the keyboard buffer as if a user at the host PC had just typed it in), or it can be sent direct to the modem. The advantage of "typing" is that you can run a batch file to check times and do all sorts of other things. The advantage of sending direct to the modem is that the entire operation can take place in the background while an application continues running. 4.9.6 You may specify a response of up to 39 characters. If you expect the host PC to be at the DOS prompt when a call comes in, then it is a good idea to start with an escape key, so that DOS discards anything already typed and treats what follows as a new command. If all this sounds too complicated, but you still think you want to enable ring response, then have a look at the configuration scenario called "Home/Office via Modem" in section A5. 4.10 Reboot on loss of carrier Selecting this option will determine whether or not the computer will reboot when the modem reports that the carrier has been lost (presumably because the other end hung up). See scenario A5 for an example of an application taking advantage of this feature. The PC will not reboot unless there has been a TeleReplica session active since TRHOST was loaded. 4.11 Synchronize "baud" rate Selecting this option will determine whether or not TRHOST will attempt to match the "baud" rate being used by TR at the other end. This is useful if several users will all dial into the same host, but some users have slower modems than others. See scenario A2 for an example of this. 4.12 Send wakeup every 2 minutes Selecting this option will determine whether or not TRHOST will send a NULL character whenever two minutes has passed with no other activity. A single NULL is ignored by TR, but may serve to keep a connection to a mini-computer link. See scenario A4 for an example of this. 4.13 Private mode In private mode, the screen of the host PC will be blank, and the keyboard of the host PC will be inactive (including CTRL-ALT-DEL). This is useful to enhance privacy when the host PC is in a public location. Note that the screen blanking has only been tested on VGA, EGA, CGA and Hercules display cards, and only in text modes. It has worked correctly with all the applications tested, but you should test it with your own applications and display cards before relying on it! 4.14 Printer redirection When a TeleReplica session is active, it is possible to redirect printer output (which would otherwise be printed at the host PC) so that it is printed at the replica PC instead. When no session is active, the host will print normally even though TRHOST is still loaded. 4.15 Create consistent .TR file Once TRHOST has been installed correctly, TRHOSTIN can create a configuration file for TR that is consistent (same "baud" rate, password, use of carrier detect etc). It will normally still be necessary to edit this file to do some fine tuning, but the work required will be less than if you started with the vanilla TR.TR file distributed with TR. 4.16 Abandon Changes If you have made a mistake, or if you only wanted to see what the current settings were, then this option allows you to quit without making any changes. 4.17 Save Changes and Leave Installation Program This is the normal way to exit this program when you have made all the required changes. The relevant files (TRHOST.EXE, TRGET.EXE, TRPUT.EXE TRTALK.EXE, TRDIAL.EXE, TREXTR.EXE, TREXTS.EXE and TRMODSET.EXE) will all be modified appropriately. Note that the executable files are actually modified, so beware of virus protection programs which compute checksums for executable files - they are likely to report possible virus infections after installation! The alternative (loading configuration information from a disk file) was rejected due to the additional memory required for the file processing code... 5. Replica Installation To install TeleReplica at the replica computer, first copy the files: TR.EXE, TR.HLP, and TR.TR (or better still the .TR file that was created during host installation) into a directory (say \TR). Then use a text editor to edit the .TR file. This file should look something like: ═════════════════════════════════════════════════════════════════════════ TeleReplica Configuration File Do NOT change the order of these parameters, or delete any lines! "COM1" Communications port ("COMn" or base/interrupt) 2400 "Baud" rate (typically 300, 1200, 2400, or 9600) "COMSPEC" Pathname for DOS Command Interpreter (or "COMSPEC") 07 Attribute for normal text (such as help screen) 47/70 Attribute for file transfer monitoring 4F/0F Attribute for pop-up windows "trput %s\r" Host command to send (download) files "trget\r" Host command to receive (upload) files 0 Printer (normally 0, 1 or 2) 440 Frequency of "bell" tone (Hz) 100 Duration of "bell" tone (ms) 256 Block size for file upload (1-256) 8 Number of block buffers for upload (1-8) 111 Length of "break" (ms) 3000 Time to wait for first char before timeout (ms) 500 Time to wait for subsequent chars in block (ms) 56 Time to wait between "typing" keys (ms) "password" Password to log in to host computer "MODEM" Type of link (MODEM, DIRECT, or OTHER) "NONE" Flow control (CTS, XON, BOTH or NONE) "YES" Send BREAKs to host computer "YES" Use BIOS for keyboard input "[TR] %s" DOS shell prompt format string "LRCA" Local command shifts (Left, Right, Ctrl, Alt) "" Connect command for modem "" Disconnect command for modem Each of the remaining lines must contain 3 strings and a number. The first string is the trigger string to search for. The second string is the response to be sent after the trigger. The third string is the response to be sent after timeout. The number is the time to wait before timeout (in ms). ═════════════════════════════════════════════════════════════════════════ Most of these parameters will not need to be changed. 5.1 The serial port may be one of the standard ones ("COM1", "COM2", "COM3", or "COM4") or you may specify the base address and interrupt number [e.g. COM1 would be 03F8/IRQ4]. For compatibility with previous versions of TR, you may also use a hex interrupt vector number, so that a third way to specify COM1 is 03F8/0C. 5.2 The "baud" rate should be set appropriately for the modem. 5.3 The DOS command interpreter should normally be taken from the COMSPEC environment variable. However, if this does not work (or does not select the desired command interpreter) the full path name of a command interpreter can be specified (e.g. "C:/DOS/COMMAND.COM" - or "C:\\DOS\\COMMAND.COM" - the \\ is needed since \ introduces an escape sequence). 5.4 Video attributes are two hexadecimal digits: the first is the background color, and the second is the foreground color. Optionally a second attribute may be specified (e.g. 4F/70) - the first attribute is used for color displays and the second is used for monochrome systems (this allows a single control file to work without change with different displays). 5.5 When the user running TR requests a file transfer, TR "types" the necessary command at the host PC. These two lines should not be changed except possibly to fill in a full path name if TRGET.EXE and TRPUT.EXE are not in the path of the host PC. 5.6 When host printing is being redirected to the replica computer's printer, TR needs to know which printer to use. LPT1: is printer 0, LPT2: is printer 1, and LPT3: is printer 2. Serial printers are not directly supported. Note that it is not necessary or possible to specify which host printer is to be redirected; anything sent to LPT1:, LPT2: or LPT3: will be redirected. This was done to save the user the trouble of working out which printer the host was using. 5.7 The frequency (or pitch) and the duration of the "bell" can be modified to suit your personal preferences (and the volume of your PC's speaker!). The "bell" is used to indicate that some corruption of the data being received by TR has occurred. 5.8 The size of file transfer blocks and the number of buffers should not need to be changed, except on a very poor 'phone line (in which case smaller blocks and fewer buffers may improve matters). However, if the line is this bad then TR will probably be unusable anyway... 5.9 The length of "break" required is not likely to need to be changed - unless perhaps a mini-computer requires longer? 5.10 During a file transfer, TR will wait a certain time for the start of each block. If nothing has been received within the time, then TR will request the block be sent again (since presumably it got lost). 5.11 Once the first character in a block has been received, the rest should follow immediately - any gap probably means problems. However, when using an overloaded mini-computer link (or using a packet network that may introduce delays between packets, or using a modem with error correction, compression or bps translation) this parameter could need to be longer. 5.12 Since on many PCs (especially ones with CGA displays) interrupts are disabled for LONG periods when writing to the screen, it is usually necessary to make TR pretend to type quite slowly, especially when sending things like file transfer commands. If you find you are losing characters under these circumstances, then make this delay longer; if you have a smart BIOS and/or version of DOS and/or command interpreter then you may be able to get away with a shorter delay (even 0 ms). On all the systems I have used, the time taken to send two characters at 2400 bps or below is sufficient, so this delay is probably only needed above 2400 bps. 5.13 The password must match the password installed in TRHOST at the host computer. 5.14 There are three kinds of link that may be used between two PCs: MODEM Use this if you are working with a modem that provides CARRIER DETECT (note that you will require an appropriate cable [see Appendix C1] and possibly some initialization of the modem [see the start of Appendix A]). You can also use this if you are using a null modem cable that provides a CD line (see Appendix C3). DIRECT Use this if you are working with a three-wire null modem cable, or if you are using a modem/cable that cannot provide accurate CD information. OTHER Use this if you are working with a mini-computer link (see scenario A4), or for initial modem setup (see the start of Appendix A). 5.15 TR can use the following flow control systems: NONE No flow control. Use this with a direct cable or with modems that require no speed adjustment. CTS Hardware flow control using RTS (request to send) and CTS (clear to send). Use this in preference to software flow control if it is available. XON Software flow control using XON and XOFF (^S/^Q). Use this if flow control is needed and hardware flow control is not available. BOTH Use both software and hardware flow control. See the discussion of flow control under host installation for further details. 5.16 Normally TR should send BREAKs to TRHOST, but see scenario A4 for use with a mini-computer link. 5.17 Normally TR will use the BIOS for keyboard input. However, many BIOSes filter out keys from enhanced keyboards (e.g. <F11>), and if use of these keys is important then it may be necessary to NOT use the BIOS, but rather to use the keyboard input buffer directly. Note however that some keyboard enhancing programs (such as Newkey) will only work with the BIOS setting. This is because they intercept the keyboard interrupt and store keys away in some place other than the standard buffer area, so that TR cannot find them! 5.18 The DOS prompt for when you are in a TR shell can be edited to suit your individual preferences - the %s inserts the original prompt. 5.19 If you don't like the default <Ctrl-Alt-LeftShift-RightShift> key combination to access local commands in TR, then you can change this to any other combination of these four main shift keys ("CAL" would mean <Ctrl-Alt-LeftShift> for example) - see scenario A3 for an application of this). 5.20 The connect command for the modem is sent when TR starts running (this will often be a dial command). The modem command strings here have the same format as those described above for the host computer installation (with the addition of a \B escape sequence that causes TR to transmit a BREAK). Make sure you leave the double quotes (") around each string! 5.21 The disconnect command is sent when TR terminates (using exit option 3 only). 5.22 The automatic response strings at the end of the file can be used to respond to modem status messages. For example, if the replica computer's modem is not set to auto-answer, then TR may need to respond to a "RING" message from the modem by answering the 'phone - see scenario A5 for an application. These strings can also be used to achieve an automatic login to a mini-computer - see scenario A4 for an example. The trigger strings are only active before a TR-TRHOST link is established. They are also disabled once the final trigger string has been detected. Please note that since this file contains the password, anyone who obtains a copy of this file can potentially access the host computer! 6. How to Use TeleReplica The following instructions assume that TeleReplica has been correctly installed (see sections 4 and 5). Only general guidelines are given here; more details are provided in the scenarios in Appendix A. 6.1 Host Computer First run the TRHOST program. If the replica computer is to originate the 'phone call, then this may be all that is necessary. If the host computer is to originate the call, then use the command: TRDIAL or TRDIAL number depending on how the dialing format string was installed. Once TRHOST is resident and the call is established, the host computer can be used normally. The only difference is that everything that appears on the screen is also being replicated on the replica computer's screen. The best way to remove TRHOST from memory is to run TRREMOVE. It is also possible to use utilities such as marknet/relnet. Note that some common mark/release utilities can NOT be used, because they do not restore the interrupt mask register. 6.2 Replica Computer Use the command: TR [use TR.TR configuration file] or TR filename [use filename.TR configuration file] If the replica computer was to originate the call, then the modem initialization string in the configuration file will usually include a dial command to call the host computer. If the host computer was to originate the call, then the initialization string may contain an answer 'phone command. Note that in this case it is important that the TR program not be run until after the 'phone starts ringing! (Alternatively, there may be no initialization string, but instead there may be a trigger string to respond to RING from the modem - see scenario A5.) If the configuration file contains no modem initialization string, then the user at the remote computer can enter modem commands manually. This may be convenient for a consultant wishing to dial many different clients. (Before a carrier is detected, TR will behave much like a normal communications program.) Once both TR and TRHOST are running and connected to each other, they will automatically adjust the host computer's "baud" rate (if this feature is enabled) and the host computer will check the password provided by the replica computer. Provided the password is correct, the replica computer will effectively be able to take over the host computer, or alternatively to observe whatever the host computer is doing. Any key typed on the replica computer will be acted upon by the host computer, and anything that appears on the host computer's screen will also appear on the replica computer's screen. It is sometimes necessary to execute a command on the replica computer, rather than transmitting the keystroke to the host computer. This is achieved by holding down some combination of left shift, right shift, ctrl and alt all at the same time (the exact combination is specified in the .TR file currently in use). When you do this a list of all the possible commands will be displayed, and you can then type the required command key: F2 simulate a carrier signal (useful if the modem does not provide this information) [link type should be OTHER to use this command] Ctrl-F2 simulate NO carrier signal (opposite of F2) F6 send break, restart session [use this if TeleReplica locks up - very rare!] F8 reboot the host computer (useful if host computer "hangs" for any reason, but make sure TRHOST is run from AUTOEXEC.BAT!) F9 shell directly to DOS, return to TR later by typing "exit" F10 exit TeleReplica [optionally shell out and return later] Home refresh display from HOST [use this if a bad 'phone line messes up the screen] PgUp upload file using DMP protocol [transfer file(s) from replica to host] PgDn download file using DMP protocol [transfer file(s) from host to replica] Note that before performing a file transfer, the host computer must be at the DOS prompt, and TRGET.EXE and TRPUT.EXE must be accessible in the current path (or alternatively the .TR file must contain full paths, not just (say) TRGET but rather C:/TR/TRGET - note forward slashes!). If TRGET/TRPUT cannot be found, then the host will display a "command not found" error message, but TR will go on waiting for a response from TRGET/TRPUT! Pressing any key will terminate this waiting and bring up an appropriate error message. If a file transfer needs to access a file in another directory, it may be convenient to shell out of TR, change directories, and then exit from DOS back into TR to start the file transfer. TR will transmit any path that you specify, so if the two PC's have equivalent directory structures it is easy to transfer files to the corresponding directory on the other PC (see Appendix B for a sample file transfer session). 7. TeleReplica Utility Programs 7.1 TRREMOVE This will search for a copy of TRHOST loaded in memory. If one is found, then it is checked to see whether it is currently in use (if so, TRREMOVE will ask for confirmation before removing it). If it is not in use, or if it is to be removed anyway, all interrupts, the interrupt mask register and the serial chip state are restored to their initial state when TRHOST started running, and TRHOST's memory is freed. Please note that as with most TSR programs, this may not work unless TRHOST was the most recent TSR to be loaded. In general TSR programs should be unloaded in the reverse order they were loaded. In this case "not working" means that any TSR loaded after TRHOST may cease to function. If this is not possible then the use of marknet/relnet (or some other mark/release utility that preserves the interrupt mask register as well as the vectors) is recommended. It is sometimes convenient to be able to keep a modem connection even though TRHOST is being unloaded. Normally, TRREMOVE will restore the serial port state to its original state when TRHOST was first run. However, it is possible to force the DTR line to be left active by entering: TRREMOVE ON and DTR can be forced off by entering: TRREMOVE OFF If either ON or OFF is specified, then TRREMOVE assumes you know what you are doing and does not ask for confirmation even if a link is active, allowing TRREMOVE to be used in a batch file on the host PC without pausing for input. 7.2 TRHOSTC This program works much like TRHOSTIN, except that instead of modifying files on disk it modifies the copy of TRHOST currently active in memory. Not all parameters may be altered "on the fly" - for example, the COM port cannot be altered mid-session. The anticipated use for this program is to do things like turning private mode on or off for just part of a session... Note that the copy of TRHOST.EXE on disk is not modified. 7.3 TRTALK TRTALK will allow the users at the host and replica computers to "talk" to each other. Anything that is typed at the host computer is displayed in the top half of the screen, and anything that is typed at the replica computer is displayed in the bottom half of the screen. TRTALK sends a special command to TR to tell TR that talk mode is required, so that TR will send keys in a way that can be distinguished from the host keys. If this command is lost, then what is typed at either end will appear in the top window! If this happens, simply exit TRTALK (Alt-X) and run it again. TRTALK also sends a special command to TR to tell TR to end talk mode. If this command is lost, then TR will behave normally unless a program that uses shift-key status is run, which will cause problems because in talk mode TR does not send shift status information! To correct this problem, use local TR command <F2> (simulate carrier), since a side effect of this command is to end talk mode. 7.4 TREXTS and TREXTR These programs are normally called from TRSZ.BAT and TRRZ.BAT respectively. They allow a clean interface between TeleReplica and external file transfer programs such as DSZ. These programs are an exception to the rule that TRHOSTIN installs only programs used at the host end; TREXTS.EXE and TREXTR.EXE both need to run at both ends, so they must be installed for the correct modem port etc on the replica as well as the host. Once TRHOSTIN has installed these programs correctly on both the host and the replica, and TRRZ.BAT, TRSZ.BAT and the external protocol program (such as DSZ.EXE) are in some directory on the path of both the host and replica, file transfer is quite simple: 7.4.1 To download a file from the host PC to the replica PC, simply enter the following command on the host PC: trsz <filename> ... and TR will automatically run TRRZ on the replica without you doing anything! 7.4.2 To upload a file from the replica PC to the host PC, first ensure that the host PC is at the DOS command prompt. Then shell out of TR (using local F9). Finally enter the following command on the replica PC: trsz <filename> ... and TRHOST will automatically run TRRZ on the host. TRRZ.BAT, TRSZ.BAT, TREXTS.EXE and TREXTR.EXE all pass parameters on to the external protocol program, so parameters other than file names can be used if desired. TREXTS.EXE and TREXTR.EXE recognize one special parameter: #portx# which will substitute in the DSZ portx <base>,<IRQ> command. This allows TRRZ.BAT and TRSZ.BAT to remain unchanged even when TeleReplica is installed for a different port. See the supplied TRRZ.BAT and TRSZ.BAT for examples of this. 7.5 TRMODSET Usage: TRMODSET [-fr] [filename] TRMODSET will send all the commands in TRMODSET.DAT (or in filename.DAT if specified) to the modem, waiting for an "OK" response to each command. This is useful to set up very complicated parameters necessary for some of the more sophisticated modems. It assumes a modem that uses the Hayes AT command set (at least at&f to restore factory defaults and OK in reply to a good command). The -r command line option will cause TRMODSET to start with an "at&f" command to reset the modem to factory defaults, just in case a previous program has left the modem in a peculiar state. The "at&f" is sent before TRMODSET starts monitoring for command echo or "OK" responses. If a carrier is present when TRMODSET runs then it will exit without doing anything unless the "-f" (for "force") command line argument is present. This allows TRMODSET to be run from AUTOEXEC.BAT without disrupting an existing connection if the host PC needs to be rebooted. Note that TRMODSET is installed by TRHOSTIN, so if you want to use TRMODSET on the replica PC you will need to install the host programs on the replica PC (once installed, the other host programs may be deleted, but they must be present for TRHOSTIN to run). Note also that you cannot use TRMODSET to set the modem to "no echo" or "quiet" modes, since TRMODSET monitors that commands are being echoed and that the modem is responding with "OK" to each command. 7.6 TRCHECK TRCHECK checks to see if the current time is within a specified range, and returns the DOS errorlevel set to 0 if within the range and 1 if outside the range. The following code might appear in an AUTOEXEC.BAT file on a host computer: trcheck 9:00:00 17:00:00 if not errorlevel 1 goto done trhost :done The effect of this is to first check to see if the time is between 9AM and 5PM. If so, then errorlevel is set to 0, and nothing further happens. However, if the time is not between 9 and 5, then trhost will be run. This has proved valuable when TRHOST must run on an office computer outside normal working hours, but the computer must be used normally during the day. See also scenario A5 for a further application. 7.7 TRASK Usage: TRASK <timeout> <prompt> <answers> TRASK works much like a normal batch file enhancing ASK program, except that it has a timeout. This is useful when a computer will usually be used as a TeleReplica host, but sometimes must be used locally. Rather than having to boot from a different disk, the following code might appear in an AUTOEXEC.BAT file on a host computer: @echo off path c:\tr trask 5 "Do you want to load TRHOST? (y/n)\a\a: " "yn" if errorlevel 1 goto no trhost :no The effect of this is to run TRHOST if the user presses the 'y' key or if no key has been pressed after 5 seconds. If a user is at the computer and answers 'n' then TRHOST will not be loaded. See scenario A5 for an example of this. TRASK returns an errorlevel that depends on the <answers> string: the first letter in this string (or a timeout) returns error level 0, the second returns error level 1 and so on. Case is not significant unless the <answers> string contains the same letter in both upper and lower case. TRASK is a public domain program and may be distributed separately. APPENDIX A - Configuration Scenarios The following are specific situations in which TeleReplica has been used. The descriptions of the situations, and the resulting configurations of TeleReplica, are presented in detail. It is hoped that seeing the way TeleReplica was installed in some typical applications will help when it comes to installing TR for your own situation. Note that unless otherwise stated, all modems are assumed initially to be in the TeleReplica default state, to be connected to the PC via a 25-way straight-through modem cable, and to be Hayes-AT-command-compatible. To get a Hayes-AT-command-compatible modem into the TeleReplica default state the following commands should be sent to the modem using any normal communications program (or using TR SETUP or using TRMODSET): at &f restore modem to "factory default" at &c1 modem should report true carrier status at &d2 modem should take notice of DTR to hang up 'phone at x4 (optional) give detailed status messages etc at &w save current state for future use (the state is saved in non-volatile RAM, so that this setup only needs to be done once unless some other program interferes) A1. Consultant/Client via Modem A1.1 Here the consultant is running a 2400 bps modem connected to COM1, and the client (whom we will call Fred) is running a similar modem also connected to COM1. Both computers are equipped with EGA color display cards. The consultant will be performing the TRHOST installation for the client, and then sending the client the installed version ready to run. When the client wants help, he will call the consultant (a normal voice call). When both parties are ready TeleReplica must take over the call. A1.2 First the consultant must run TRHOSTIN, and make the changes necessary to achieve the following display: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ A. Select serial port (currently COM1) ║ ║ B. Change password (currently "Fred's password") ║ ║ C. Change modem initialization string (currently: ║ ║ "") ║ ║ D. Change modem dialing format string (currently: ║ ║ "ata\r") ║ ║ E. Select maximum "baud" rate (currently 2400) ║ ║ F. Use modem CARRIER DETECT signal (currently YES) ║ ║ G. Flow control (currently NONE) ║ ║ H. Generate INT 9 on each key (currently NO) ║ ║ I. Respond to modem RING signal (currently NO) ║ ║ J. Reboot on loss of carrier (currently NO) ║ ║ K. Synchronize "baud" rate (currently YES) ║ ║ L. Send wakeup every 2 minutes (currently NO) ║ ║ M. Private mode (currently NO) ║ ║ N. Printer redirection (currently HOST) ║ ║ O. Create consistent .TR file ║ ║ Q. Abandon changes ║ ║ S. Save changes and leave installation program ║ ║ ║ ║ Selection: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Refer to section 4 for the meaning of each option. Since both modems run at the same speed it does not matter whether "baud" rates get synchronized or not. Since Fred will only run TRHOST when he wishes to get help from the consultant, the password is not important. The modem dialing format string simply answers the 'phone - or more accurately, since the 'phone will already be in use for the voice call, it causes the modem to take over the call in "answer" mode. Next the consultant selects option O from the main menu, and enters the name of the configuration file he wishes to use for Fred: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program .TR File Name Selection ║ ║ ║ ║ Edit existing string: ║ ║ fred ║ ╚═══════════════════════════════════════════════════════════════════════╝ Finally the consultant exits TRHOSTIN by selecting option S to save the changes. The consultant can now send Fred a disk with all the installed TeleReplica files on it (note that the consultant should also send Fred an unaltered original copy of the TeleReplica files in case Fred wants to pass them on to anyone - see the LICENCE.DOC file for details). A1.3 Now the consultant needs to edit the file named FRED.TR to make a few alterations (TRHOSTIN only provides a starting point...). In particular, the following line must be changed: "" Connect command for modem to: "at d\r" Connect command for modem This command tells the modem to go "off hook" and take over the call in "originate" mode. This completes the installation stage. A1.4 When Fred wants some help, he will run TRHOST and then 'phone the consultant and explain the problem. When the consultant is ready, he will enter the command: TR FRED and then instruct Fred to enter the command: TRDIAL and hang up the 'phone as soon as he (Fred) hears his modem making a "screaming" noise. After giving these instructions (and thus while Fred is still typing) the consultant will hang up his 'phone. Fred will finish entering the TRDIAL command, and hang up when he hears the screaming noise. TeleReplica will then take over the call, synchronize "baud" rates, exchange passwords, and give the consultant control of Fred's computer. A1.5 When the consultant is finished, he will exit TR using option 3, which will cause the modem to hang up and terminate the 'phone call. Fred can either leave TRHOST running (it will do no harm, and uses less than 10K of memory), or else use TRREMOVE to uninstall TRHOST. A2. Remote/Shared via Modem A2.1 Here a remote user wishes to connect into a local area network, and one node in the LAN is dedicated to this purpose. The main problem is that since the LAN node will be unattended, all it takes is one user to run a program which "hangs" the computer, and then no-one will be able to dial in until someone pushes the reset button on the node PC! However, in this scenario there is a modem-controlled switch box which turns on power to the node PC as soon as the 'phone starts ringing, and leaves the power on until either a minute or so has elapsed with no carrier being established, or until the carrier is lost (which will happen when the remote user hangs up). [These switch boxes are (I believe) commercially available, and indeed the electronics required is trivial to someone who feels at home with circuit diagrams and a soldering iron. We have several home-made ones in use here at MUCG.] This means there is no problem if a user "hangs" the computer; just hang up and then dial in again, and the computer will have been powered down and come up again clean! The node PC has a 2400 bps modem connected to COM2, and the remote user is running a 1200 bps modem connected to COM1. The node PC is equipped with a CGA color display card (with no monitor required). The remote PC is equipped with a Hercules monochrome display. The LAN manager will be performing the TRHOST installation for the node PC, and then providing all the remote users with a disk that is almost ready to go. The 'phone number of the node PC is 123 4567. A2.2 First the LAN manager must run TRHOSTIN, and make the changes necessary to achieve something like the following display: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ A. Select serial port (currently COM2) ║ ║ B. Change password (currently "sdggsdjgxvwept97867km,.mvikjdsdh") ║ ║ C. Change modem initialization string (currently: ║ ║ "\rata\r") ║ ║ D. Change modem dialing format string (currently: ║ ║ "\r%s\r") ║ ║ E. Select maximum "baud" rate (currently 2400) ║ ║ F. Use modem CARRIER DETECT signal (currently YES) ║ ║ G. Flow control (currently NONE) ║ ║ H. Generate INT 9 on each key (currently NO) ║ ║ I. Respond to modem RING signal (currently NO) ║ ║ J. Reboot on loss of carrier (currently NO) ║ ║ K. Synchronize "baud" rate (currently YES) ║ ║ L. Send wakeup every 2 minutes (currently NO) ║ ║ M. Private mode (currently NO) ║ ║ N. Printer redirection (currently HOST) ║ ║ O. Create consistent .TR file ║ ║ Q. Abandon changes ║ ║ S. Save changes and leave installation program ║ ║ ║ ║ Selection: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Refer to section 4 for the meaning of each option. Note that the modem initialization string answers the 'phone - this is nice in the case of timed call charges, since the remote user does not pay for the time it takes the PC to boot. Since some remote users will dial in at 2400 bps, TRHOST must be installed for 2400; but since other remote users will dial in at 1200 bps it is essential that "baud" rates get synchronized. Since anyone could try to get into the LAN via the node PC the password is very important - notice that it is both long and quite random. Next the LAN manager selects option O from the main menu, and enters the name of the configuration file he wishes to use for the node PC: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program .TR File Name Selection ║ ║ ║ ║ Edit existing string: ║ ║ lan1 ║ ╚═══════════════════════════════════════════════════════════════════════╝ Finally the LAN manager exits TRHOSTIN by selecting option S to save the changes. He can now make up a disk with all the installed TeleReplica files on it to give to the remote users, but first he must edit the LAN1.TR file to install the node PC's 'phone number. This means changing the line: "" Connect command for modem to: "at d 123 4567\r" Connect command for modem so that when remote users run TR the number will be dialed automatically. Also, since modems more often use COM1 than COM2, the LAN manager should probably edit the line: "COM2" Communications port (COMn or base/interrupt) to become: "COM1" Communications port (COMn or base/interrupt) A2.3 Now the remote user needs to edit his personal copy of the file named LAN1.TR to work at 1200 bps. The line containing: 2400 "Baud" rate (typically 300, 1200, 2400, or 9600) must be changed to: 1200 "Baud" rate (typically 300, 1200, 2400, or 9600) This completes the installation stage. A2.4 When the remote user wishes to connect into the LAN, he will enter the command: TR LAN1 This will cause the modem to dial the node PC, which will cause the modem switch box to turn on the power to the node PC, which will boot and then run TRHOST, which will make the node PC's modem answer the call. TeleReplica will then synchronize "baud" rates, exchange passwords, and give the remote user control of the node PC. A2.5 When the remote user is finished, he will exit TR using option 3, which will cause the modem to hang up and terminate the 'phone call. The node PC will then be powered down until the next call. A3. Laptop/Desktop via Direct Cable A3.1 Here someone wishes to connect a laptop computer to a desktop computer via a three-wire null modem cable. The reason for this is that the desktop only has a 5.25" disk, and the laptop only has a 3.5" disk, and it is necessary to transfer files between the two systems. The desktop computer is a 20MHz 80386, and the laptop is a 12MHz 80286. The cable is connected from COM1 on the desktop to COM1 on the laptop. The desktop has a VGA color display; the laptop has a gas plasma display that emulates EGA. It does not matter which PC is the host, but for the sake of this example we will assume the desk PC will be the host. The laptop computer has its <Del> key right next to <RightShift>, so the user does not wish to be using <Ctrl-Alt-LeftShift-RightShift> for fear of accidentally rebooting the computer. <Ctrl-Alt-LeftShift> seems a safer combination. A3.2 First the user must run TRHOSTIN, and make the changes necessary to achieve something like the following display: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ A. Select serial port (currently COM1) ║ ║ B. Change password (currently "password") ║ ║ C. Change modem initialization string (currently: ║ ║ "") ║ ║ D. Change modem dialing format string (currently: ║ ║ "") ║ ║ E. Select maximum "baud" rate (currently 38400) ║ ║ F. Use modem CARRIER DETECT signal (currently NO) ║ ║ G. Flow control (currently NONE) ║ ║ H. Generate INT 9 on each key (currently NO) ║ ║ I. Respond to modem RING signal (currently NO) ║ ║ J. Reboot on loss of carrier (currently NO) ║ ║ K. Synchronize "baud" rate (currently NO) ║ ║ L. Send wakeup every 2 minutes (currently NO) ║ ║ M. Private mode (currently NO) ║ ║ N. Printer redirection (currently HOST) ║ ║ O. Create consistent .TR file ║ ║ Q. Abandon changes ║ ║ S. Save changes and leave installation program ║ ║ ║ ║ Selection: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Refer to section 4 for the meaning of each option. Notice that the "baud" rate is set to 38400 for fast file transfers (this works well on my test system, but slower speeds may be needed on other systems - experiment!). Obviously here the password is not important. Since the three-wire cable will not provide any carrier information, it is essential that carrier be ignored. Next the user selects option O from the main menu, and enters the name of the configuration file he wishes to use for the desktop: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program .TR File Name Selection ║ ║ ║ ║ Edit existing string: ║ ║ desk ║ ╚═══════════════════════════════════════════════════════════════════════╝ Finally the user exits TRHOSTIN by selecting option S to save the changes. A3.3 Next the user needs to edit the file named DESK.TR to use the shift key combination required for the laptop. The line containing: "LRCA" Local command shifts (Left, Right, Ctrl, Alt) must be changed to: "LCA" Local command shifts (Left, not Right, Ctrl, Alt) The user can now copy the installed files onto a 5.25" floppy disk, take the disk to a computer that has both 5.25" and 3.5" inch drives, and copy the file onto a 3.5" disk for the laptop. This completes the installation stage. A3.4 When the user wishes to connect the two computers, he will enter the command: TRHOST on the desktop, and the command: TR DESK on the laptop. This will cause TeleReplica to synchronize "baud" rates, exchange passwords, and give the user control of the desktop computer from the laptop. Files can now be transferred at almost 3.8K per second! A3.5 When the user is finished, he will exit TR using option 3, which will take the laptop back to normal, but leave TRHOST in the desktop's memory (see A1.5 for further discussion of this). A4. Remote/Shared via Common Mini-computer A4.1 Here a remote user wishes to connect into a local area network, and one node in the LAN is dedicated to this purpose. There is no direct link between the PCs; instead, both the node PC and the remote user must log into the same mini-computer and run a link program (such as trfifo) to establish a connection via the mini-computer. One problem is that since the LAN node will be unattended, all it takes is one user to run a program which "hangs" the computer, and then no more remote users will be able to connect to the LAN until someone pushes the reset button on the node PC! (Note that TeleReplica does support rebooting the host PC, but this can only work if interrupts are not disabled and if the relevant code has not been overwritten. As a rule, TeleReplica can get out of any situation that <Ctrl-Alt-Del> could get out of, but if the hardware reset button was needed TR would be helpless.) Another potential problem is that if one user exits TR while still logged in to the LAN, then the next user could pick up the session! This is avoided by having the link program send a "reboot" command to the node PC when the link is broken. Trfifo cannot pass BREAKs from one end to the other; instead, BREAK is used to terminate the execution of trfifo. This means that TR must not send a BREAK unless it wants to kill the link. To make life complicated, the mini-computer will automatically disconnect any terminal that does no input or output for 5 minutes. However, the node PC must remain connected to the mini-computer all day waiting for remote users to connect in. The mini-computer links are set at 9600 bps, and cannot be changed. Both computers are connected to the mini-computer via COM1, and both computers are running color displays (however, the dedicated node PC requires no monitor). The LAN manager will be performing the TRHOST installation for the node PC, and then providing all the remote users with a disk that is almost ready to go. A4.2 First the LAN manager must run TRHOSTIN, and make the changes necessary to achieve something like the following display: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ A. Select serial port (currently COM1) ║ ║ B. Change password (currently "sdfddffgjkiou774htgjhgsduh875sdh") ║ ║ C. Change modem initialization string (currently: ║ ║ "") ║ ║ D. Change modem dialing format string (currently: ║ ║ "") ║ ║ E. Select maximum "baud" rate (currently 9600) ║ ║ F. Use modem CARRIER DETECT signal (currently NO) ║ ║ G. Flow control (currently NONE) ║ ║ H. Generate INT 9 on each key (currently NO) ║ ║ I. Respond to modem RING signal (currently NO) ║ ║ J. Reboot on loss of carrier (currently NO) ║ ║ K. Synchronize "baud" rate (currently NO) ║ ║ L. Send wakeup every 2 minutes (currently YES) ║ ║ M. Private mode (currently NO) ║ ║ N. Printer redirection (currently HOST) ║ ║ O. Create consistent .TR file ║ ║ Q. Abandon changes ║ ║ S. Save changes and leave installation program ║ ║ ║ ║ Selection: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Refer to section 4 for the meaning of each option. The password is not so critical here, since a user must be able to log into the mini-computer before getting through to the node PC. The mini-computer line will not provide any carrier information, so this must be ignored. "Baud" rates must NOT be synchronized, since a NULL character transmitted at 2400 bps would be received as a BREAK by the mini-computer at 9600 bps! To avoid the node PC getting logged out, TRHOST must send a NULL character to "wake up" the mini-computer every few minutes. This will be ignored by TR. Next the LAN manager selects option O from the main menu, and enters the name of the configuration file he wishes to use for the node PC: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program .TR File Name Selection ║ ║ ║ ║ Edit existing string: ║ ║ lan2 ║ ╚═══════════════════════════════════════════════════════════════════════╝ Finally the LAN manager exits TRHOSTIN by selecting option S to save the changes. He can now make up a disk with all the installed TeleReplica files on it to give to the remote users. A4.3 Due to the way trfifo buffers input (or possibly some other peculiarity of our mini-computer?) the delay between sending keys needs to be 165 ms to avoid losing characters! Therefore, the line containing: 56 Time to wait between "typing" keys (ms) must be changed to: 165 Time to wait between "typing" keys (ms) Also, since we are using a mini-computer link, the line containing: "DIRECT" Type of link (MODEM, DIRECT, or OTHER) must be changed to: "OTHER" Type of link (MODEM, DIRECT, or OTHER) Finally, TR is capable of automating the mini-computer login process. If this is desired, then something like the following lines must be added at the end of the file: "DISCONNECTED" "\D250\r" "\r" 5000 "Enter RESOURCE ? " "\D100G9000\r" "\r" 5000 "CONNECTED TO" "" "" 5000 "login: " "\D100doug\r" "\B\r" 500 "Password:" "\D100password\r" "\r" 10000 "Selection: " "\D100d\r" "" 40000 "/users/doug>" "\D100trfifo lan2\r" "" 40000 "and run TR" "\D1000" "" 40000 The exact strings will depend on the mini-computer. This example (apart from the password) works for the author. This completes the installation stage. A4.4 When the remote user wishes to connect into the LAN, he will run TR: TR LAN2 which will automatically log into the mini-computer and run trfifo to connect to the node PC (in this case lan2). TeleReplica will then synchronize "baud" rates, exchange passwords, and give the remote user control of the node PC. A4.5 When the remote user is finished, he will exit TR using option 3, which will send a BREAK to the mini-computer. This will terminate the trfifo program which the remote user was running. The trfifo program that the node PC was running will detect that this has happened, and send a TeleReplica reboot command to the node PC to ensure that the next user cannot pick up anything the previous user left running. The node PC's trfifo program will then prepare for the next remote user. The node PC will complete rebooting, and run TRHOST from AUTOEXEC.BAT ready for the next remote login. [All this sounds complicated, but we use this system daily here at MUCG for some staff who have mini-computer lines but are too far away for LAN connections.] A5. Home/Office via Modem A5.1 Here a user wishes to dial in from home and take over the PC on his desk at work. The office PC has a 2400 bps modem connected to COM2, and the home PC has a 2400 bps modem connected to COM1. The office PC is equipped with an EGA color display, and the home PC is equipped with a Hercules monochrome display. One problem is that since the office PC will be unattended, all it takes is for the user to run a program which "hangs" the computer, and that will be the end of the office PC until the user goes back to work and presses the reset button! (Note that TeleReplica does support rebooting the host PC, but this can only work if interrupts are not disabled and if the relevant code has not been overwritten. As a rule, TeleReplica can get out of any situation that <Ctrl-Alt-Del> could get out of, but if the hardware reset button was needed TR would be helpless.) Since the user is putting in overtime working at night without getting paid for it, it seems reasonable that the office 'phone should at least pay for the call. However, how can the office computer know when to call the user at home? One possibility would be to set up a batch file to run TRDIAL at a predetermined time. However, it would be better if the user could choose any convenient time. TeleReplica can achieve this by monitoring the RING signal from the modem, and responding appropriately. The basic idea is that the user will dial the office number, and then hang up as soon as the 'phone starts ringing. TeleReplica will detect the 'phone ringing, and respond by calling the user at home. Since the user does not want to be bothered by nuisance calls from the office computer, TeleReplica needs to be quite selective about the ring patterns it will respond to. Too short a ring may mean a telephone company routine line test. Too long a ring will mean a person trying to ring the office. Even if the ring is the correct length, the user may still wish to guarantee no interruptions between 11PM and 7AM! The 'phone number of the office PC is 123 4567. The 'phone number of the home PC is 765 4321. A5.2 First the user must run TRHOSTIN, and make the changes necessary to achieve something like the following display: │═══════════════════════════════════════════════════════════════════════╗ │plica Host 3.20 Installation Copyright (c) 1992 Douglas Thomson ║ │ ║ │Select serial port (currently COM2) ║ │Change password (currently "fhkjeuyibn4593874sefeh8631wjds874dffd") ║ │Change modem initialization string (currently: ║ │"") ║ │Change modem dialing format string (currently: ║ │"\r%s\r") ║ │Select maximum "baud" rate (currently 2400) ║ │Use modem CARRIER DETECT signal (currently YES) ║ │Flow control (currently NONE) ║ │Generate INT 9 on each key (currently NO) ║ │Respond to modem RING signal (currently YES)───┬─ 1. too short 220 ms ║ │Reboot on loss of carrier (currently YES) ├─ 2. too long 5000 ms ║ │Synchronize "baud" rate (currently YES) ├─ 3. delay 10000 ms ║ │Send wakeup every 2 minutes (currently NO) ├─ 4. reset 10000 ms ║ │Private mode (currently NO) ├─ 5. "type" response ║ │Printer redirection (currently HOST) └─ 6. response ─┐ ║ │Create consistent .TR file "\0x1Btrauto\r" ║ │Abandon changes ║ │Save changes and leave installation program ║ │ ║ │ion: ║ │═══════════════════════════════════════════════════════════════════════╝ Refer to section 4 for the meaning of each option. Since anyone could try to get into the office PC the password is important - notice that it is both long and quite random. The modem dialing format string permits ANY modem command to be sent direct to the modem. It is essential that TRHOST takes notice of the CD signal, since the host computer will be automatically rebooted if the carrier is lost (see below). The host computer is to monitor the 'phone ringing and respond accordingly (again, see below). "Baud" rate synchronization is not important here. Next the user selects option O from the main menu, and enters the name of the configuration file he wishes to use for the office: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Host Program .TR File Name Selection ║ ║ ║ ║ Edit existing string: ║ ║ office ║ ╚═══════════════════════════════════════════════════════════════════════╝ Finally the user exits TRHOSTIN by selecting option S to save the changes. He can now make up a disk with all the installed TeleReplica files on it to take home. However, still on the office PC the user needs to create a batch file called TRAUTO.BAT, containing something like: trcheck 7:00:00 23:00:00 if errorlevel 1 goto done trdial atd7654321 :done which will check that the time is between 7AM and 11PM, and if so dial the user's home number. Note that the "atd7654321" contains no spaces! The user must also ensure that AUTOEXEC.BAT has the directory containing all the TeleReplica files on the path, and that TRHOST is run whenever the system boots. However, when the user is at the office he will not want TRHOST loaded, so AUTOEXEC.BAT should contain something like: @echo off prompt $p$g path c:\tr trask 5 "Do you want to load TRHOST? (y/n): " "yn" if errorlevel 1 goto no trhost :no This will ask the user at the host PC whether or not to load TRHOST, and if the user does not say no within 5 seconds TRHOST will be loaded anyway. If the user is at the office, then typing 'n' will prevent TRHOST from loading. A5.3 At home the user needs to edit the file named OFFICE.TR to install the office PC's 'phone number. This means changing the line: "" Connect command for modem to: "at d 123 4567\r" Connect command for modem so that when the user runs TR the number will be dialed automatically. Next, since the home modem is on COM1 the line: "COM2" Communications port (COMn or base/interrupt) must become: "COM1" Communications port (COMn or base/interrupt) Finally, TR should respond to the modem ringing by answering the 'phone. This means adding an extra line at the end of the file containing: "RING" "\D250ata\r" "" 40000 (Note the \D250 to wait a little bit for the modem to finish sending the carriage return and line feed after RING before sending the answer command. With some modems this may not be necessary; with others, a different delay may work better. If the answer command is ignored, then try a different delay.) This completes the installation stage. A5.4 Before leaving the office, the user must remember to reboot the PC (thus loading TRHOST) and leave it turned on! However, it would be a good idea to switch the monitor off. When the user is ready to dial into the office PC from home, he will enter the command: TR OFFICE This will cause the modem to dial the office PC. The user must then listen to the modem and wait until he hears the 'phone ring once. As soon as he hears this, he must press any key (say the space bar) to terminate the call. TRHOST will start a timer going when the 'phone rings, and then wait 10 seconds, keeping track of the total time the 'phone has spent ringing. If, during the 10 seconds, the 'phone was ringing for more than 0.2 seconds but less than .9 seconds, then TRHOST will pretend to "type" the keys: <Esc>trauto<enter> The <Esc> will ensure that anything currently on the command line is ignored, and the trauto will run the TRAUTO.BAT script. The batch file will check that the time of day is reasonable, and then call the user back. When the user's 'phone rings, the modem will send the message: RING to the home PC, and TR will trigger on this to respond to the modem with: ata which will answer the 'phone. TeleReplica will then synchronize "baud" rates, exchange passwords, and give the user control of the office PC. A5.5 When the user is finished, he will exit TR using option 3, which will cause the modem to hang up and terminate the 'phone call. The office PC will then automatically reboot, ready for the user to call in again. [This is probably the most complicated set up of all, but it is the one the author has found most useful, and is in daily use by a number of staff at MUCG.] APPENDIX B - Sample File Transfer Session B1 In this example, we will assume that a good link has been established as described in scenario A2. The user has logged into the LAN from home, and wishes to transfer all the C source files from the LAN directories: F:\USERDATA\FRED\TEST F:\USERDATA\FRED\UTILS F:\USERDATA\FRED\PROBLEM to the corresponding directories on his home PC: C:\PROGRAMS\TEST C:\PROGRAMS\UTILS C:\PROGRAMS\PROBLEM The current working directory on the LAN PC is F:\USERDATA\FRED. The current working directory on the home PC is C:\TR. First, the user needs to make C:\PROGRAMS the current working directory on his home PC. To do this, he must hold down Ctrl, Alt, LeftShift and RightShift all at the same time! This will bring up a screen similar to: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Copyright (c) 1992 Douglas Thomson ║ ║ ║ ║ Key Effect ║ ║ === ====== ║ ║ <F2> - simulate carrier - not used with MODEM link ║ ║ <Ctrl-F2> - simulate NO carrier - not used with MODEM link ║ ║ <F6> - send break, restart session ║ ║ <F8> - perform warm boot on host ║ ║ <F9> - shell to DOS ║ ║ <F10> - exit TeleReplica ║ ║ <Alt-X> - exit TeleReplica ║ ║ <Home> - refresh display from HOST ║ ║ <PgUp> - upload file using DMP protocol ║ ║ <PgDn> - download file using DMP protocol ║ ║ ║ ║ <ESC> - do nothing ║ ║ Press key: ║ ╚═══════════════════════════════════════════════════════════════════════╝ Then he should press <F9> to shell to DOS, and enter the command: CD \PROGRAMS to make C:\PROGRAMS the current working directory. Then he can enter the command: EXIT to return to TR. Next he needs to start the download. To do this he must again hold down Ctrl, Alt, LeftShift and RightShift, and then press <PgDn>. Another box will appear: ╔═══════════════════════════════════════════════════════════════════════╗ ║ Name(s) of file(s) to be downloaded (use DOS wildcards): ║ ║ WARNING: Files with the same names on this PC will be overwritten! ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════╝ and he must enter the relative paths and wildcards: ╔═══════════════════════════════════════════════════════════════════════╗ ║ Name(s) of file(s) to be downloaded (use DOS wildcards): ║ ║ WARNING: Files with the same names on this PC will be overwritten! ║ ║ TEST\*.C TEST\*.H UTILS\*.C UTILS\*.H PROBLEM\*.C PROBLEM\*.H ║ ╚═══════════════════════════════════════════════════════════════════════╝ If there were some problem (for example, if TRPUT.EXE were not on the path of the LAN PC), then the following could be displayed: ╔═══════════════════════════════════════════════════════════════════════╗ ║ TeleReplica Error: ║ ║ no ready marker from host ║ ║ Type <ESC> to continue: ║ ╚═══════════════════════════════════════════════════════════════════════╝ However, normally the download will then commence, leaving the following display: ╔═════════════════════════════════════════════╗ ║ File Transfer in Progress... ║ ║ ║ ║ File: test\xyz.c ║ ║ ║ ║ Error: ║ ║ ║ ║ Efficiency: 96.6% ║ ║ ║ ║ You may: ║ ║ 1. Abort the file transfer ║ ║ 2. Shell to DOS ║ ║ ║ ║ Selection: ║ ╚═════════════════════════════════════════════╝ The number of bytes remaining to be transferred is displayed in the top right corner of the screen. The most recent error will be reported in the appropriate line of the box, and the efficiency of the transfer (relative to a perfect 10 bits per byte) may help to relieve the boredom while waiting for the transfer to complete! The box also indicates which file is currently being transferred. At this stage, the user can either wait for the transfer to finish, or else select option 2 from the menu and shell to DOS. In this case, he can use his home PC for other jobs while the transfer takes place in the background. TR will continue to display the number of bytes remaining in the top right corner until the transfer is completed, at which time the number in the top right corner will become the string "Completed" (or, possibly, "Doubtful" if one or more files could not be created on the home PC). However, the user must be careful not to do things like delete the file that is being downloaded! While shelled out to DOS in this way, the user may exit back into TR at any time. If the file transfer is still in progress, then the file transfer window will still be there; otherwise, the exit will leave TR displaying the normal replica of the host PC's display. APPENDIX C - Modem Cables C1. Minimum Standard Modem Cable Although a full 25-wire straight-through male-to-female RS232 cable is recommended for TeleReplica (since there is less room for error in the cable construction/selection), in fact the following signals are the only ones ever required or used: MALE (modem) FEMALE (PC) ============= ======== 25D RS232 pin signal signal 25D 9D (as in AT) ============= ====== ====== === == 2 TD <------- TD 2 3 3 RD -------> RD 3 2 4 RTS <------- RTS 4 7 5 CTS -------> CTS 5 8 7 GND <------> GND 7 5 8 CD -------> CD 8 1 20 DTR <------- DTR 20 4 22 RI -------> RI 22 9 The following sections describe the kind of null modem cables that can be used with TeleReplica. C2. Simplest Possible 3-wire Null Modem Cable This is the most common kind of null modem cable, but TR and TRHOST must be set to ignore carrier detect, since the cable does not provide this information. MALE FEMALE ============= ======== 25D RS232 pin signal signal 25D 9D (as in AT) ============= ====== ====== === == 7 GND <------> GND 7 5 3 RD <------- TD 2 3 2 TD -------> RD 3 2 C3. Full TeleReplica Null Modem Cable If you can build or get hold of one of these, then TeleReplica can use carrier detect correctly. Note that CTS is not provided, and that TeleReplica must therefore be installed not to use it (there would be no point is using flow control with a direct cable in any case)! MALE FEMALE ============= ======== 25D RS232 pin signal signal 25D 9D (as in AT) ============= ====== ====== === == 7 GND <------> GND 7 5 3 RD <------- TD 2 3 2 TD -------> RD 3 2 20 DTR -------> CD 8 1 8 CD <------- DTR 20 4 C4. Complete Null Modem Cable If you really want a complete null modem cable, which should work with ANY communications program, then I would suggest: MALE FEMALE ============= ======== 25D RS232 pin signal signal 25D 9D (as in AT) ============= ====== ====== === == 7 GND <------> GND 7 5 3 RD <------- TD 2 3 2 TD -------> RD 3 2 5 CTS <------- RTS 4 7 4 RTS -------> CTS 5 8 20 DTR ----+--> CD 8 1 | +--> DSR 6 6 8 CD <--+---- DTR 20 4 | 6 DSR <--+ APPENDIX D - DESQview Compatibility D1. TR is "DESQview-Aware" and runs nicely in a small DESQview window. TRHOST needs to put keys into the BIOS keyboard buffer, and this means that what is typed at the remote end cannot be distinguished by DESQview from what is typed at the real keyboard at the host end. The net effect is that there is no point in trying to run TRHOST in a DESQview window, and so TRHOST makes no attempt to be "DESQview-Aware". Also, DESQview is activated by "tapping" the ALT key, but TRHOST has no way to make this appear to happen, hence DESQview cannot be activated remotely. TRHOST and DESQview really don't mix! D2. For anyone wishing to set up DESQview for TR, these are the settings that I am currently using successfully: ╔1══Change═a═Program════════════════════════════════════════════════════╗ ║ Change a Program ║ ║ ║ ║ Program Name............: TR ║ ║ ║ ║ Keys to Use on Open Menu: TR Memory Size (in K): 70 ║ ║───────────────────────────────────────────────────────────────────────║ ║ Program...: C:\TR\TR ║ ║ ║ ║ Parameters: REMOTE ║ ║ ║ ║ Directory.: \TR ║ ║───────────────────────────────────────────────────────────────────────║ ║ Options: ║ ║ Writes text directly to screen.......: [N] ║ ║ Displays graphics information........: [N] ║ ║ Virtualize text/graphics (Y,N,T).....: [N] ║ ║ Uses serial ports (Y,N,1,2)..........: [1] ║ ║ Requires floppy diskette.............: [N] ║ ║ ║ ║ Press F1 for advanced options Press <─┘ when you are DONE ║ ╚═══════════════════════════════════════════════════════════════════════╝ and advanced options: ╔1══Change═a═Program════════════════════════════════════════════════════╗ ║ Change a Program Advanced Options ║ ║ ║ ║ System Memory (in K): 0 Maximum Program Memory Size (in K)..: 70 ║ ║ ║ ║ Script Buffer Size: 100 Maximum Expanded Memory Size (in K): 0 ║ ║ ║ ║ Text Pages: 1 Graphics Pages: 0 Initial Mode: Interrupts: 00 to 2F ║ ║───────────────────────────────────────────────────────────────────────║ ║ Window Position: ║ ║ Maximum Height: 25 Starting Height: 25 Starting Row...: 1 ║ ║ Maximum Width.: 80 Starting Width.: 80 Starting Column: 1 ║ ║───────────────────────────────────────────────────────────────────────║ ║ Shared Program ║ ║ Pathname..: ║ ║ Data......: ║ ║───────────────────────────────────────────────────────────────────────║ ║ Close on exit (Y,N,blank)..: [Y] Uses its own colors...........: [Y] ║ ║ Allow Close Window command.: [N] Runs in background (Y,N,blank): [Y] ║ ║ Uses math coprocessor......: [N] Keyboard conflict (0-4).......: [0] ║ ║ Share CPU when foreground..: [Y] Share EGA when foreground/....: [Y] ║ ║ Can be swapped out (Y,N, ).: [N] Protection level (0-3)........: [0] ║ ║ ║ ║ Press F1 for standard options Press <─┘ when you are DONE ║ ╚═══════════════════════════════════════════════════════════════════════╝ D3. When running under DESQview, the "shell to DOS" option during a file transfer is disabled, since DESQview does not permit interrupt handlers to call DOS and BIOS functions (necessary for reading and writing files). However, this is not a serious limitation under DESQview, since DESQview will allow you to run multiple simultaneous programs. D4. The normal "shell to DOS" option may be used under DESQview, but in this case more than 70K of memory will need to be allocated - with 4dos, it has been reported that at least 150K is required! APPENDIX E - Acknowledgements I would like to thank all the users of TeleReplica who have helped me to improve the package by suggesting new features and reporting difficulties. The following individuals in particular have had a significant impact on the current version: Mr Lindsay Smith, Monash University College, Gippsland, Australia Prof. Timo Salmi, University of Vaasa, Finland ============================================================================== ============================================================================== ============================================================================== ============================================================================== ============================================================================== ============================================================================== ============================================================================== ============================================================================== ============================================================================== ========================================================