CompuServe CSEXEC(TM) 3.0 Intelligent Terminal Emulator for CP/M Systems Copyright (c) 1983 CompuServe Incorporated Page 1 1.0 INTRODUCTION CSEXEC(TM) for CP/M is an easy-to-use, powerful communications program written for CompuServe by Susan Cavanaugh. This program allows your CP/M system to communicate with the CompuServe Information Service as well as any other host computer system with telephone answering capabilities utilizing the same communications standards. This manual explains how to use the CSEXEC software with examples illustrating its use on CompuServe. For information on accessing and using a particular host computer, refer to the User's Guide for that system. 1.1 Hardware Required CSEXEC requires a CP/M computer system with at least 32K of RAM, one disk drive, a serial communications interface, and an RS-232 modem. 2.0 CUSTOMIZING THE EXECUTIVE TO YOUR SYSTEM Due to the variety of I/O configurations possible among computer systems running under CP/M, you will need to customize the Executive's I/O routines for your particular system configuration. This requires a basic knowledge of programming in 8080 assembler language. 2.1 The Input/Output Overlay Your CSEXEC diskette contains a file called OVERLAY.ASM which contains assembler source code of the serial I/O routines which service the modem. It is to be used for customizing the executive to different serial I/O configurations. OVERLAY.ASM contains three subroutines: SIOINI - initializes the UART. SIOGET - checks modem receiver and returns with: Z = 1 if no data ready. Z = 0 if data was read, data is in the accumulator. SIOPUT - stores the contents of the accumulator in the UART's transmitter. It waits until the transmitter accepts data before returning. Page 2 Modify OVERLAY.ASM according to your own communications UART specifications. For instance, it may be necessary to modify the initialization routine to specify the baud rate and you may need to change the sense of the receive and transmit flags in the get and put routines. Timing considerations require that the console and listing devices be capable of handling data at a speed which is at least TWICE the baud setting of the modem serial port. If this is not the case for your computer, it is probable that incoming data will be lost. The necessary specifications are: 8 data bits no parity 1 stop bit Included in OVERLAY.ASM are the program stack and the compressed ascii dictionary. These don't need to be changed for your system. They are included in the overlay because they must follow the I/O routines in memory. 2.2 Creating CSEXEC For Your System After you have made all the necessary changes to OVERLAY.ASM, assemble it. Then, type the following at the CP/M prompt: DDT EXECOR.COM IOVERLAY.HEX R This will overlay your I/O routines with the generic CP/M Executive, EXECOR.COM, in your computer's RAM. Now type CTRL-C to exit DDT and return to CP/M. To save the completed CSEXEC for your system on your diskette, type: SAVE 24 CSEXEC.COM Note that if you have supplied more than two pages of code in OVERLAY.ASM, you will need to save more than 24 pages. Page 3 3.0 USING A PRINTER WITH CSEXEC If you have a printer connected to your computer, you can use it to obtain hardcopy with CSEXEC. 3.1 Copying Data To The Printer If you type a CTRL-R on the keyboard, a copy of all subsequent characters received will be sent to the printer. A CTRL-T stops the copying. When a CTRL-R (ASCII character DC2) is received from the host, the copying to the printer will start. When a CTRL-T (ASCII character DC4) is received, the copying is stopped. If the printer is not ready, an error message will be displayed. 4.0 RUNNING CSEXEC To load and execute CSEXEC, type "CSEXEC" at the CP/M prompt. 5.0 EXITING CSEXEC CTRL-X will display the menu, at which time, typing an "X" (for eXit) will exit CSEXEC and return control to CP/M. To continue the terminal session, reload and execute CSEXEC. Page 4 6.0 AUTO LOGON Auto logon allows you to keep logon information for many different systems. It also has the capacity to act in place of the user for a number of applications. 6.1 Auto Logon Control The auto logon menu allows you to control all available auto logon operations. To display the menu, type CTRL-X. While looking at the menu, press the letter that corresponds to the operation you want. The figure below shows the menu. Auto Logon Functions C Create Auto Logon File E Execute Auto Logon File A Abort Auto Logon T Transmit CTRL-X X Exit program Press your choice or for terminal mode. To return to terminal mode, press . Type "X" to exit the program and return to CP/M. 6.2 Creating A New Auto Logon File In order to create a new auto logon file on your diskette, follow these steps: 1. Type CTRL-X to display the auto logon menu. Press "C" (for Create) and you will then be prompted for the auto logon file name you wish to use. If you press with no file name, the program will assign a default file name of CSEXEC.ATO. To abort auto logon file creation, type a CTRL-C at any time during the creation process and the file will be erased from your diskette and the menu redisplayed. 2. You will then be asked for a prompt to wait for from the host. If you do not want to wait for a prompt, just press the or key. Otherwise enter the host's prompt. The prompt sequence is translated to upper case before it is stored on disk. All received characters are translated to upper case for matching with the prompt. The maximum length of a prompt from the host is 20 characters. A prompt length of four to five characters or less is recommended due to the possibility of noise occurring over the phone lines and garbling the incoming prompt. You may press the or key Page 5 to terminate the prompt. Neither terminator will be included in the prompt to be searched for. 3. You will then be asked for a response to transmit. Enter your response terminated by or . The carriage return will be transmitted with the response. The will transmit no terminator when the response is sent. If you enter just an for a response, a null response is indicated. The maximum length for a response is 64 characters. A response of more than 64 characters can be transmitted by entering the response in two or more parts, each less than 64 characters, while entering a null prompt between each part of the response. 4. Repeat the prompt/response input sequence as many times as is necessary to complete your logon sequence. When you are done, type an at the next prompt and response request. The auto logon menu will reappear and allow you to specify which action to take next. 6.3 Executing An Auto Logon To execute an auto logon file, press CTRL-X to display the menu, then "E" (for Execute). You will then be prompted for the auto logon file name to read from disk. The default file name CSEXEC.ATO will be used if you press at the file name prompt. If the file exists on your diskette, CSEXEC will enter auto logon mode. To abort execution of an auto logon sequence, press CTRL-X to return to the menu, then type "A" (for Abort). When using auto logon for logging on to a system, you should wait until the remote system answers the phone to begin the auto logon sequence. CSEXEC will automatically exit auto logon mode when all prompts have been found and all responses sent. The keyboard remains active during an auto logon execution. This allows you to type during auto logon without affecting the execution of the auto logon file. 6.4 Additional Auto Logon Features Auto logon can do more than simply log on to a host system. The prompt-seeking function allows CSEXEC to act in your place on the keyboard to provide a response to a host program. A prompt should always be specified after a response that will cause the host to display text. Prompts can be any text that the host displays. Typical prompts are: "!", ":", and "OK". The response from auto logon can be any text or control characters. To enter a control character into the response, type a carat (^) then type the letter of the control key. Page 6 To obtain a delay of one-half second, enter ^& (carat-ampersand) into the response. For a delay of two seconds, enter ^% (carat-percent) into the response. A single carat mark is entered into a response by entering two consecutive carats. 6.5 Auto Logon File Chaining The execution of a new auto logon file may be started from an already-executing auto logon file. This feature allows you to create an auto logon sequence in multiple files. To change a part of the sequence, re-create the file containing that part. The other files do not need to be re-created. When the CTRL-X is executed from an auto logon file, the current file is closed and the file specified is then executed. The contents of the auto logon file after the "CTRL-XEfilename" is ignored. 6.6 Auto Logon Examples A sample auto logon creation sequence to log on to CompuServe is shown below. Creating New Auto Logon Enter file name: cpusrv.ato Select the file Prompt: Don't wait for prompt, transmit immediately Response: ^C () Transmit a CTRL-C with no carriage return Prompt: ID: Wait for 'USER ID:' Response: 70000,1 Then send '70000,1' Prompt: word: Wait for 'PASSWORD:' Response: SECRET Then send 'SECRET' Prompt: ! Wait until DISPLA prompts for input Response: GO HOM-1 Transmit 'GO HOM-1' Prompt: Terminate the input Response: sequence by entering null prompt and null response Page 7 A sample auto logon creation sequence to log on to CompuServe through TYMNET is shown below. Creating New Auto Logon Enter file name: tymnet.ato Select the file Prompt: FIER Wait for 'PLEASE TYPE YOUR TERMINAL IDENTIFIER' from TYMNET Response: A Transmit an 'A' without a carriage return Prompt: IN: Wait for TYMNET login message Response: CIS02 Request connection to CompuServe Prompt: ID: Wait for 'USER ID:' Response: 70000,1 Then send '70000,1' Prompt: word: Wait for 'PASSWORD:' Response: SECRET Then send 'SECRET' Prompt: ! Wait until DISPLA prompts for input Response: GO HOM-1 Transmit 'GO HOM-1' Prompt: Terminate the input Response: sequence by entering null prompt and null response Page 8 The following example shows how the autolog feature could be used to automatically dial and login with the D. C. Hayes Smartmodem. This example programs the Smartmodem to dial '555-1234' using tone dialing. Refer to the Smartmodem manual for instructions on creating a programming string. Creating New Auto Logon Enter file name: smart.ato Select the file Prompt: Don't wait for prompt, transmit immediately Response: AT DT555-1234 Program the Smartmodem to dial 555-1234 using tone dialing Prompt: CONNECT Wait for connection Response: ^%^C Delay for two seconds and transmit a CTRL-C with no carriage return Prompt: ID: Wait for 'USER ID:' Response: 70000,1 Then send '70000,1' Prompt: word: Wait for 'PASSWORD:' Response: SECRET Then send 'SECRET' Prompt: ! Wait until DISPLA prompts for input Response: GO HOM-1 Transmit 'GO HOM-1' Prompt: Terminate the input Response: sequence by entering null prompt and null response Page 9 The following auto logon could be used to get to the CB simulator program from most any other menu on CompuServe. HOM-21 is used for illustration only and may not be the actual page number of CB on the system. Creating New Auto Logon Enter file name: cb.ato Select the file Prompt: Don't wait for prompt Response: T Send T for TOP Prompt: ! Wait until top menu is displayed Response: GO HOM-21 Transmit 'GO HOM-21' Prompt: ? Wait until CB prompts for handle Response: (Your handle) Transmit handle Prompt: Terminate the input Response: sequence by entering null prompt and null response The following shows how the auto logon might execute. It is initiated by typing a CTRL-X and responding with 'E' (for Execute) at the menu, then typing 'cb.ato' at the file name prompt. T CompuServe Page CIS-1 CompuServe Information Service 1 Home Services 2 Business & Financial 3 Personal Computing 4 Services for Professionals 5 User Information 6 Index Enter your selection number, or H for more information. !GO HOM-21 CompuServe Page HOM-21 Request Recorded, One Moment, Please Thank You for Waiting CB Simulator Ver 3(45) What's your handle? (Your handle) (Channel) users tuned in Which channel: 1 (1,Susana) Hi, CB'er Page 10 7.0 FILE TRANSFER USING CSEXEC Most of CompuServe's CSEXEC programs contain the ability to transfer a file from the microcomputer's disk to CompuServe. While this is a feature found in many other terminal programs, most of them merely transmit the contents of the file or write exactly what is received. CSEXEC uses an error-free communications protocol to perform file transfer. This means that if noise occurs on the communications line, the error will be detected and the data block will be retransmitted. The procedure for performing a file transfer on CompuServe is relatively simple and is described below. A few terms must first be defined in order to explain file transfers. The process of transferring a file from CompuServe to a microcomputer is called DOWNLOADing. The process of transferring a file from a microcomputer to CompuServe is called UPLOADing. The CompuServe mainframe computer is referred to as the HOST computer system and your microcomputer is referred to as the REMOTE computer. There are three types of file transfers: text, binary, and machine specific. A text transfer is used to transfer ASCII text files such as untokenized BASIC programs and text files produced by word processing programs. A binary transfer is used to transfer eight-bit files such as tokenized BASIC programs and machine language programs. This can also be used to transfer most microcomputer's BASIC data files. CSEXEC does not alter any data during a binary file transfer. A machine-specific transfer is used to transfer machine-dependent files. CSEXEC inserts all the information it needs to recreate the file exactly as it originally existed. If an attempt is made to download a machine-specific file to a microcomputer which is of a different type than the microcomputer from which the file was uploaded, CSEXEC will issue a warning message. Machine-specific transfers can be used to transfer files that have information kept outside of the file (usually in the disk directory) that is essential to the file (such as file type, record length). For both an upload and a download, the CompuServe file extension determines the type of transfer that will be performed. The valid extensions and the transfer types are: BIN Binary transfer CMP Reserved for CompuServe IMG Machine-specific (image) transfer TXT Text transfer Page 11 If any other extension or no extension at all is used, a text transfer will be performed. To initiate a file transfer, at the 'OK' prompt, enter: R FILTRN CompuServe will respond with: CompuServe File Transfer Program Your machine will then be interrogated to see if you are running a version of CSEXEC which supports file transfers. If you are not running a CSEXEC program or if your version of CSEXEC does not support file transfers, an error message will be printed and you will be returned to the 'OK' prompt. If you are running a version of CSEXEC which supports file transfer, you will be asked for the direction of the transfer: Select direction- D if to your computer U if to CompuServe : Enter a 'U' to transfer a file from your microcomputer to CompuServe (upload) or a 'D' to transfer a file from CompuServe to your microcomputer (download) at the ':' prompt. You will then be prompted with: Enter the CompuServe file name: Enter an appropriate file name and extension. Remember that the file extension determines the type of transfer performed. For a download this is the name of the existing file to be transferred to your microcomputer. For an upload this is the name of the file which will be created in your Programming Area. You will then be prompted with: Enter a file name for your computer: You may specify any file following the naming rules of CP/M. This might include a drive designation, a file name extension, or punctuation. The remote file name does not affect the type of transfer performed. For an upload, enter the name of the file to be transferred to CompuServe. For a download, enter the name of the new file to be created on your diskette. If the file already exists on your diskette, you will be asked if you would like it to be replaced. If so, CSEXEC will erase the existing file and download the new contents. If not, the file transfer will be aborted and you will be returned to the 'OK' prompt. The original file will not be erased from the diskette. As a transfer proceeds, a series of digits will be displayed on your screen, one for Page 12 each block of data. For each 32 bytes of data transferred within each block, a plus sign (+) will be displayed between these digits. When the transfer is completed, the message: *** File Transfer Completed! *** will appear and you will be returned to the 'OK' prompt. To signal CSEXEC to abort a file transfer, hold CTRL-X until the next digit appears on the screen. 8.0 TECHNICAL INFORMATION The following information is provided for determining compatibility with hosts other than the CompuServe network. 8.1 Flow Control CSEXEC recognizes the standard ASCII flow control characters, (CTRL-S or DC3) and (CTRL-Q or DC1). If CSEXEC receives an from the host, it will halt transmission. If an is not received in approximately five seconds, transmission will be resumed. CSEXEC expects the host to observe the same rules. An is sent to stop transmission from the host while the menu is being used. An is sent when transmission can be resumed. If the host does not respond to flow control, characters may be dropped. 8.2 ESCAPE Sequences CSEXEC responds to certain ESCAPE sequences when received from the host computer. These sequences cannot be performed locally; they must be received from the host. 8.2.1 Keyboard Lock And Unlock When an sequence is received, CSEXEC will lock the keyboard and not transmit any more characters typed. This condition is reset when CSEXEC receives an sequence. These sequences can be used by a host program which does not want to be interrupted during critical processing. Page 13 8.2.2 Video Enable And Disable When an sequence is received, the video is disabled and subsequent characters are not displayed. The video is enabled again when an sequence is received. 8.3 The Protocol CSEXEC contains a data communications protocol which allows error-free data transfer between CompuServe and your computer. The details of this protocol are copyrighted by CompuServe, Inc. and can only be disclosed under a special license (not included with this software). 8.4 CompuServe Control Characters This section is provided to demonstrate how control characters are used on a host computer. In the following table, "^x" means to hold the the CTRL key and press the letter "x". Transmitted Control Characters ^A Suspends output being displayed by CompuServe at the end of the current line. Repeated issuance of ^A causes successive lines of output to be displayed, one line at a time. Running output is turned back on with a ^Q. ^A is not typed out. ^S Suspends output immediately. ^Q Restores the running display of output at the point where it had been interrupted by a ^A or ^S. ^C Interrupts display or a program's execution so that you can enter another menu selection or command. ^B Used as a type ahead ^C, forcing an interrupt when CompuServe requests input. Page 14 ^P Interrupt display or a program's execution so that you can enter another command to the program. ^H Backspaces, deleting the character that was there. Same as BACKSPACE key. ^U Deletes the line currently being typed. ^V View current line; redisplays the line you are currently typing. ^O Tells host to turn off output currently being displayed. 8.5 The ASCII Character Set 0 1 2 3 4 5 6 7 0 NUL DLE SPC 0 @ P ` p 1 SOH DC1 ! 1 A Q a q 2 STX DC2 " 2 B R b r 3 ETX DC3 # 3 C S c s 4 EOT DC4 $ 4 D T d t 5 ENQ NAK % 5 E U e u 6 ACK SYN & 6 F V f v 7 BEL ETB ' 7 G W g w 8 BS CAN ( 8 H X h x 9 HT EM ) 9 I Y i y A LF SUB * : J Z j z B VT ESC + ; K [ k { C FF FS , < L \ l | D CR GS - = M ] m } E SO RS . > N ^ n ~ F SI US / ? O _ o 9.0 CSEXEC ERROR MESSAGES Typical Errors: % VTXFAE - That file already exists on your disk. Do you wish to replace it (Y or N)? The file you specified for your system to download to is already on your diskette. If you want to overwrite it, reply "Y"; if not, reply "N" and the file transfer will be aborted. Page 15 % VTXPNR - Printer not ready! The printer is not ready. Make sure the power switch is on and the printer is online. ? VTXDKF - Diskette is full! The diskette has run out of storage space during file transfer. CSEXEC erases the partially downloaded file from the diskette and aborts the file transfer. ? VTXNEF - That file is not on your diskette! The file you specified for upload to the host doesn't exist on your diskette. The file transfer is aborted. % VTXFNC - This file may not be compatible with your computer. Do you still want to receive it? (Y or N) This message signifies that you are attempting to download an image file which was uploaded from a different microcomputer than yours. A "Y" response will cause the host to download the file anyway, and an "N" response will abort the transfer. Page 16 10.0 GLOSSARY This glossary defines some of the more frequently used terms associated with the CompuServe Information Service. database is a collection of information which is stored on the computer. defaults are settings telling your terminal specific ways to respond. For example, how many lines on a screen you want to have displayed while scrolling, the first page to see after logon, the number of characters to delay after issuing a command, etc. These default setting can be made permanent or can be in effect for the current session only. disk storage refers to the storing or saving of data in the Programming Area on a device called disk. The data can then be retrieved for use. Each Standard and Prime Service customer is allocated 128,000 characters of disk space at no extra charge. Additional storage can be requested through Feedback for an extra charge. DISPLAY is the program which accesses the Videotex Area from the Programming Area. download is the process of transferring a file of data from your on-line disk storage to your own personal computer system. EMAIL is the CompuServe Information Service Electronic Mail program. ENTER is the specific key on the keyboard which enters the current line into the computer; acts like a carriage return on a typewriter. Executive See CSEXEC. Page 17 FEEDBK is the program which enables you to provide your comments, ask questions or get help with a problem from Customer Service. You may also order documentation and CompuServe Information Service products while in the Feedback program. file is a collection of data, uniquely identified by a name up to 6 characters long and optionally an extension of up to 3 characters (for example, TEST.DAT). Filge is CompuServe's File Generator and Editor which is used for creating and modifying files, for use in EMAIL, the Bulletin Board, and the Programming area files. hardcopy is a printout or a paper copy of computer data. host is the CompuServe computer to which you are connected. initial page is the first page of information which is displayed after logon. job is a user's individual session while logged onto the CompuServe computer. logoff is the sequence of events which disconnects you from the CompuServe computer. logon is the sequence of events which connects you with the CompuServe computer. menu refers to the item choices from which you may select a page to be displayed in the Videotex Area. Page 18 network is the communications link equipment that enables you to connect to CompuServe's computers in Columbus, Ohio. CompuServe operates its own network in most major cities in the 48 contiguous United States. Access from other cities in the U.S. and Canada is available through a supplemental network (such as TYMNET or DataPac) at an additional communications surcharge. node is a specialized communications computer which allows many terminals to communicate through the same line to CompuServe's large computer complex in Columbus, Ohio. OK is the prompt which is used in the Programming Area to indicate readiness to accept a command. page is any one of the 16-line displays which appear on your terminal. password is a unique set of characters that secures entry into the service for a unique User ID. Your password is your key to safeguarding your data and usage charges. You are responsible for all usage of your User ID. The CompuServe Information Service strongly recommends that you keep your password in a secure place separate from your User ID and never give it to anyone, verbally or through the service. The most secure password consists of two non-related words connected with a symbol. program is a set of machine instructions which the computer uses to perform a defined function. References to particular programs used on the CompuServe Information Service are made by program name, such as EMAIL, FEEDBK, DISPLAY. When a program is requested, the computer loads and executes (runs) the specified set of instructions (program). prompt is the message which is displayed to alert you that the computer is waiting for input. For example, Key M for menu! in the Videotex Area, or OK in the Programming Area. Screen refers to one page of information. SIGS is the program which accesses the Special Interest Groups area. The SIGS offering contains many groups with mutual special interests which have been given a unique area to allow members to communicate with each Page 19 other. SOFTEX is the name for the Software Exchange program which allows a user who is equipped with the proper version of the Executive to purchase programs on-line that can be run on his/her personal computer. These programs can be downloaded to the personal computer system upon purchase. terminal is a keyboard and printing or display mechanism used to enter data into a computer and to display output from a computer. A microcomputer which is running terminal emulation software is considered to be a terminal. upload is the process of transferring a file from your personal computer system to your CompuServe disk storage area. User ID is a unique number assigned to your account that, when used with the correct password, allows access to CompuServe Information Service. For example, 77777,777. Videotex is an easy to use interactive menu formatted system for accessing remote databases or programs. On CompuServe, the Videotex format is in pages of text. CSEXEC(TM) is a terminal emulator program which is specifically designed for use with the CompuServe Information Service and which is in the CompuServe Videotex format. CSEXEC(TM) software is sold through computer dealers and through the CompuServe Information Service on-line product ordering area found in Feedback. Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . 1 Hardware Required . . . . . . . . . . . . . . . . . . . 1 Customizing the Executive to Your System . . . . . . . . . 1 The Input/Output Overlay . . . . . . . . . . . . . . . . 1 Creating CSEXEC for Your System . . . . . . . . . . . . 2 Future Versions of the Executive . . . . . . . . . . . . 3 Using A Printer With CSEXEC . . . . . . . . . . . . . . . . 3 Copying Data to the Printer . . . . . . . . . . . . . . 3 Running CSEXEC . . . . . . . . . . . . . . . . . . . . . . 3 Exiting CSEXEC . . . . . . . . . . . . . . . . . . . . . . 3 Auto Logon . . . . . . . . . . . . . . . . . . . . . . . . 4 Auto Logon Control . . . . . . . . . . . . . . . . . . . 4 Creating Auto Logon File . . . . . . . . . . . . . . . . 4 Executing An Auto Logon . . . . . . . . . . . . . . . . 5 Additional Auto Logon Features . . . . . . . . . . . . . 5 Auto Logon File Chaining . . . . . . . . . . . . . . . . 6 Auto Logon Examples . . . . . . . . . . . . . . . . . . 6 File Transfer Using CSEXEC . . . . . . . . . . . . . . . . 10 Technical Information . . . . . . . . . . . . . . . . . . 12 Flow Control . . . . . . . . . . . . . . . . . . . . . 12 ESCAPE Sequences . . . . . . . . . . . . . . . . . . . 12 Keyboard Lock and Unlock . . . . . . . . . . . . . . 12 Video Enable and Disable . . . . . . . . . . . . . . 13 The Protocol . . . . . . . . . . . . . . . . . . . . . 13 CompuServe Control Characters . . . . . . . . . . . . . 13 The ASCII Character Set . . . . . . . . . . . . . . . . 14 CSEXEC Error Messages . . . . . . . . . . . . . . . . . . 14 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . 16