Program TALK Documentation and User's Guide J. Yambor and N. Bewtra Computer Sciences Corporation Silver Spring, Maryland Prepared for Goddard Space Flight Center under Technical Direction of Bob Turkelson PAGE 2 1.0 Introduction TALK is a terminal emulation program which enables a PDP-11 user running under the RSX-11M operating system to communicate with a remote host computer. The program usually operates in "terminal" mode which allows the user to talk to the host as if the PDP-11 were invisible. The program also has the capability of bi-directional file transfers. Throughout this document the "host" refers to the computer with which the TALK program is communicating - not the one on which TALK is running. 1.1 System Requirements The PDP-11 must be running under (at least) version 3.2 of RSX-11M with the full duplex terminal driver. Program TALK Documentation PAGE 3 12/2/81 2.0 Operation Details Once TALK has been initiated, the user is prompted to enter the channel number. This is the number of the interface connected to the host computer. A control-Z input at this time will terminate the program. At this point, TALK is in "terminal" mode - that is, any characters typed will be sent directly to the host computer, and all characters from the host computer will be displayed on the terminal. There are a number of control characters which are not transmitted from the keyboard to the host computer. The control-S (^S) and control-Q (^Q) characters are used to suspend and resume (respectively) the processing of characters from the host. The control-B (^B) character instructs the program to transmit a "break" character to the host. During file transfers, a control-O (^O) character alternately suspends and resumes the terminal echoing of characters being transmitted. The control-W (^W) character instructs the program to enter command input mode. In this mode, the user is prompted to enter an alphabetic character specifying one of a number of program commands which are not specified by control characters. These commands are outlined in the next section. 2.1 Command Descriptions Commands entered from "command input mode" are used primarily to control file transfers. There are also commands to display the command menu, send to the host the control characters which are intercepted by TALK in terminal mode, and exit the TALK program. Commands are accepted in both upper and lower case. A carriage return gets the user out of this mode if he does not wish to enter a command at this time. 2.1.1 A - Initiate file transfer to host This command coordinates a number of operations necessary to transfer a text file to the host computer. The user is prompted for the desired host file name as well as the local file name. Redirected input mode is entered and a command is sent to the host to begin the file transfer. When the end-of-file is reached, the character is transmitted to the host to terminate the transfer and redirected input is cancelled. TALK currently Program TALK Documentation PAGE 4 12/2/81 supports file transfers in this manner to one of several host configurations: the Sigma 9 CP-V Operating System, the PDP-11 RSX-11M Operating System, or the VAX/VMS Operating System. The desired host configuration is specified when the program is assembled, by defining the appropriate symbol in the TALK prefix file ( see section 3.1). 2.1.2 B - Initiate file transfer from host This command performs a function similar to the previous command, but is used to transfer files from the host computer. The same general procedure is used, except that the transfer is terminated by the receipt of the host computer's monitor prompt as the first character in any line. Although this may occasionally cause problems, files can always be transfered in a "manual" mode if necessary. During file transfers, , , and characters are not transfered to the output file. 2.1.3 C - Transmit the break command character to the host This command will transmit to the host the control character defined as the TALK break character for entering command mode. 2.1.4 D - Pause This command allows the user to interrupt TALK and communicate with the Monitor Console Routine (MCR). A message is displayed on the terminal indicating how to restart TALK and a "STOP" directive is issued to the task. The program resumes execution when the user issues the "UNSTOP" command to MCR. 2.1.5 E - Change EOR character The user is prompted to enter a new EOR character. The EOR character is used to delimit records in both the redirected input and output modes. If an EOR character is recieved from the host and the input is redirected, the Program TALK Documentation PAGE 5 12/2/81 next record from the input file is sent to the host. Also, in redirected input mode, an EOR character is appended to each record sent to the host. If an EOR character is recieved from the host and the output is redirected, the buffer containing all characters recieved after the previous EOR is written to the output file. The default EOR character is a carriage return. 2.1.6 I - Enter redirected input mode In this mode, the terminal is disconnected as an input device, and data is transmitted to the host from a specified file. The redirected file is transmitted record by record to the host on an EOR prompt basis. Redirected input mode continues until the end of file is reached, a read error occurs (including reading a record longer than INBSIZ, a symbol defined in the TALK source file), or it is cancelled explicitly by breaking to command mode and entering the command to cancel redirect input. The default filename, TLKIN., is used if the user enters no filename when prompted. If the input is already redirected, this command will be ignored. 2.1.7 J - Exit redirected input mode If the input is currently redirected, the input file is closed, and the terminal is reconnected to the host as an input device. This command will be ignored if the input is not redirected. 2.1.8 K - Transmit the "break" control character to the host This command simply transmits the control character which is used as the command to transmit a "break" to the host. Program TALK Documentation PAGE 6 12/2/81 2.1.9 M - Display the command menu This command will display the menu of available commands on the terminal and reissue the prompt for command input. 2.1.10 O - Enter redirected output mode In this mode, everything sent to the terminal from the host computer will also be copied to a specified file. Records are terminated by EOR characters or by exceeding the buffer size, OFBSIZ ( defined in the TALK source file). Redirected output files have the "list" carriage control attribute and can be editted normally. Redirected output mode continues until it is explicitly cancelled by breaking to command mode and entering the command to cancel redirected output. The default filename, TLKOUT., is used if the user enters no filename when prompted. If the output is already redirected, this command will be ignored. 2.1.11 P - Exit redirected output mode If the output is currently redirected, any partial record is written to the output file and the file is closed. This command will be ignored if the output is not redirected. 2.1.12 Q - Transmit a control-Q (^Q) to the host This command simply transmits the ^Q character to the host, since this character would otherwise be intercepted by TALK as a command to restart the processing of host characters. Program TALK Documentation PAGE 7 12/2/81 2.1.13 S - Transmit a control-S (^S) to the host This command simply transmits the ^S character to the host, since this character would otherwise be intercepted by TALK as a command to halt the processing of host characters. 2.1.14 X - Exit redirected input and/or output mode This command exits any redirected mode (input and/or output) currently in effect. 2.1.15 Z or ^Z - Exit from TALK This command will close any redirected input and/or output files and terminate the program. In addition, the port will be disconnected. If desired, TALK may then be rerun, and communication with the host will continue. Exiting from TALK will allow local file preparation without dropping the communications line or logging off the host computer. Program TALK Documentation PAGE 8 12/2/81 3.0 Program Notes 3.1 Parameter and Code Modifications Program command codes and I/O buffer sizes may be easily changed. These parameters are defined in the data definition area of the macro source code and in the TALK prefix and system definition files. The vector and CSR addresses for each port must be defined in the appropriate tables. See the TALK system definition file (TALKSYS.MAC) for instructions on how to do this. The system definition file also contains symbols which define the host computer for which TALK is being used. If a version of TALK is desired to communicate with a PDP-11 RSX-11M system or a VAX/VMS system, comment out the definition of the symbol SIGMA9 and remove the comment indicator (;;;) from the definition of the symbol RSX11 or VAX. The QSIZET or QSIZEP parameters should be increased if the queue overflow message is displayed on the terminal. Currently, the port queue size is 600 characters and the terminal queue size is 200 characters. The INBSIZ and OFBSIZ parameters are the input and output buffers sizes for the redirected files. The current buffer sizes are 133 bytes for input and 133 bytes for output. In addition to the system definition file, there is also a TALK prefix file (TALKPRE.MAC). This file defines some macros and symbols which are also needed by TALK. When assembling TALK, the prefix file and the system definition file should be assembled along with the source modules into the resulting object modules. A command file (TALK.CMD) is provided with TALK to perform the necessary assembly and taskbuild operations. 3.2 General Should TALK be abnormally terminated, the user terminal will have the no-echo, binary input, and full duplex characteristics set. Program TALK Documentation PAGE 9 12/2/81 4.0 Program Design On an abstract level, TALK is a simple program. Separate queues are used for characters from the port and from the terminal. Characters from the terminal are handled by an AST routine, which queues the character and indicates that something is in the queue. Port characters are handled in a similar manner through an "interrupt service routine" (ISR) via hardware interrupts. The "connect to interrupt vector" directive (CINT$) is used. When both of the queues are empty, TALK waits for an event flag to be set by one of the interrupt routines. This prevents the program from competing for the CPU when there are no characters to be processed. Once a character appears in one of the queues, both queues are processed until empty. Most prompted input from the terminal (EOR and file names) are entered when the program is in a special mode. Instead of being sent to the host, characters received from the terminal in this mode are buffered to create an input string. By reading in this fashion, the unsolicited input feature need not be turned off, and host characters may be processed while typing input. The following sections contain the Program Design Language (PDL) code for the TALK program modules. Program TALK Documentation PAGE 10 TALK PDL Source Code 12/2/81 4.1 PDL Source Code TALK initialize file i/o package CALL CNPRT - connect port terminal if connect error then EXIT else CALL ATTDEV( TERMINAL ) - AST attach user terminal - read no echo CALL CONTRL - handle all characters on queue CALL DCNPRT - disconnect the port CALL DETDEV( TERMINAL ) - detach user terminal - read with echo if redirected input then CALL CANINP - cancel redirected input fi if redirected output then CALL CANOUT - cancel redirected output fi fi stop Program TALK Documentation PAGE 11 TALK PDL Source Code 12/2/81 AST -- unsolicited character interrupt handler if queue full then indicate queue overflow else put character on queue if pointer off queue then reset back of queue pointer fi fi return from interrupt Program TALK Documentation PAGE 12 TALK PDL Source Code 12/2/81 PTINTR -- port interrupt routine for character receive disable interrupts if queue has overflowed then set error flag else move character to back of port queue if "back of queue" pointer is at its limit then reset it to the front fi fi set flag to indicate port data if event flag needs to be set then set event flag indicating presence of something in the queue fi enable interrupts return Program TALK Documentation PAGE 13 TALK PDL Source Code 12/2/81 CONTRL while .TRUE. do /* Loop forever */ if port queue processing has not been suspended then wait for a signal that there is something in a queue if the port queue is not empty then if the port queue has overflowed then WRITE 'QUEUE OVERFLOW' message to terminal else CALL PRTIN( CHARACTER ) - process a port character if the port queue is getting full then CALL PSLEEP to put the host to sleep fi fi fi fi while there is something in the terminal queue do if terminal queue has overflowed then WRITE 'QUEUE OVERFLOW' message to terminal else CALL TRMIN( CHARACTER ) - process a user terminal character if wish to exit program then return fi fi od if port queue processing is not suspended then if port queue is empty then if host is asleep then CALL PAWAKE - to wake up the host fi Program TALK Documentation PAGE 14 TALK PDL Source Code 12/2/81 if there is a record to be sent to port then CALL XFERP to transmit it fi fi fi od Program TALK Documentation PAGE 15 TALK PDL Source Code 12/2/81 PRTIN( CHARACTER ) if a command is being sent to the host then echo the character if the character is a then reset the command flag fi else if input is redirected then if character is a prompt for next file read then indicate a record is to be sent to port fi fi echo the character if output is redirected then if character is not , , or then if TALK is helping with file transfer then if the first character in the line is a monitor prompt then CALL CANOUT - to cancel redirected output return fi fi move character to output file buffer else if CHARACTER is EOR then CALL WRTBUF - to write a record to the output file fi fi fi fi return Program TALK Documentation PAGE 16 TALK PDL Source Code 12/2/81 TRMIN( CHARACTER ) case in the process of / building a file name / CALL BUILD( CHARACTER ) - build file name / changing the EOR character CALL ENTEOR( CHARACTER ) - change EOR character / entering a command / CALL CMDIN( CHARACTER ) else case CHARACTER of / enter "command input mode" command / CALL BREAK / transmit break command / CALL SNDBRK / suspend port queue processing command / CALL PSLEEP set "suspend" flag / resume port queue processing command / clear "suspend" flag / suspend/resume terminal echo command / if TALK is helping with file transfer then toggle the echo flag fi else if not redirected input then WRITE CHARACTER to port fi esac esac return Program TALK Documentation PAGE 17 TALK PDL Source Code 12/2/81 CMDIN if character is control-Q or control-S then return fi if character is lower case then convert character to upper case fi if not legal command character then report error to user CALL BREAK - to prompt for new command else case command to / transmit control character / CALL SENDPR( control character ) / initiate file transfer to host / CALL RDIHLP / initiate file transfer from host / CALL RDOHLP / display the command menu / CALL MENU - to display the menu CALL BREAK - to prompt for command / cancel redirected input and/or output / CALL PAWAKE to wake up the host CALL CANINP CALL CANOUT / cancel redirected input / CALL CANINP / cancel redirected output / CALL CANOUT / change EOR character / CALL ASKEOR - to prompt for new EOR character / exit program / set exit flag / redirect input / CALL REDINP / redirect output / CALL REDOUT esac clear command flag CALL PAWAKE - to wake up the host fi RETURN Program TALK Documentation PAGE 18 TALK PDL Source Code 12/2/81 BREAK CALL PSLEEP - to put the host to sleep indicate that port queue processing is suspended indicate command mode is in effect issue the prompt to enter a command RETURN MENU WRITE the command menu to the terminal RETURN Program TALK Documentation PAGE 19 TALK PDL Source Code 12/2/81 RDIHLP prompt for destination file name set flag to indicate that a redirected input command is being built initialize the command length, file name length, and their respective pointers set flag to indicate that TALK is helping with a file transfer RETURN RDOHLP prompt for source file name set flag to indicate that a redirected output command is being built initialize the command length, file name length, and their respective pointers set flag to indicate that TALK is helping with a file transfer return Program TALK Documentation PAGE 20 TALK PDL Source Code 12/2/81 PSLEEP if port output not already suspended then case / host is SIGMA9 / send an H to suspend output / host is RSX11M system / send a ^S to suspend output esac fi return PAWAKE clear flag indicating suspended output case / host is SIGMA9 / send an to resume host output / host is an RSX11M system / send a ^Q to resume host output esac return Program TALK Documentation PAGE 21 TALK PDL Source Code 12/2/81 SNDBRK set the "transmit break" bit in the transmit CSR issue "mark time" directive to wait for one tick (1/60 second) and then execute AST routine CLRBRK if directive status word indicates failure then clear the "transmit break" bit in the CSR fi return CLRBRK clear the "transmit break" bit in the transmit CSR pop the stack return from AST Program TALK Documentation PAGE 22 TALK PDL Source Code 12/2/81 REDINP if not redirected input then indicate that we are building an input file name initialize file name pointer CALL ASKNM - prompt user to enter a file name fi return REDOUT if not redirected output then indicate that we are building an output file name initialize file name pointer CALL ASKNM - prompt user to enter a file name fi return Program TALK Documentation PAGE 23 TALK PDL Source Code 12/2/81 CANINP if redirected input then CALL CLSFLE( type = INPUT ) - close redirected input file turn off redirected input indicator fi if TALK is helping with file transfer then clear terminal echo flag CALL SENDPR( ) fi clear help flag return CANOUT if redirected output then if output file buffer is not empty then CALL WRTBUF - write output buffer to redirected output file fi CALL CLSFLE( type = OUTPUT ) - close redirected output file turn off redirected output indicator clear help flag and terminal echo flag fi return Program TALK Documentation PAGE 24 TALK PDL Source Code 12/2/81 ASKNM WRITE 'Enter file name:' to user terminal initialize file name length to zero return Program TALK Documentation PAGE 25 TALK PDL Source Code 12/2/81 BUILD( CHARACTER ) if CHARACTER is a DEL then erase last character written on the terminal delete last character placed in file name buffer else if CHARACTER is a CR then /* End of file name */ send a to the terminal if building a host file name then append any trailer to the command string if transferring file to host then CALL REDINP else CALL REDOUT fi else /* building a local file name */ CALL OPNFLE - to open file turn off build file name indicator if TALK is helping with file transfer then CALL SNDCMD( command string ) fi fi else echo CHARACTER on user terminal if file name is longer than legal name then /*Error, stop building file name */ WRITE 'File name is too long' to user terminal turn off build file name indicator else place CHARACTER at the end of file name buffer fi fi fi return Program TALK Documentation PAGE 26 TALK PDL Source Code 12/2/81 OPNFLE prepare file name buffer if want to open an input file then open input file if not open error then turn on redirected input indicator WRITE message indicating that input is redirected if TALK is not helping with a file transfer then indicate that there is a record to be transfered fi else WRITE ' File open error' to user terminal clear help flag fi else open output file if not open error then turn on redirected output indicator WRITE message indicating that output is redirected else WRITE 'FILE OPEN ERROR' to user terminal clear help flag fi fi return Program TALK Documentation PAGE 27 TALK PDL Source Code 12/2/81 SNDCMD get address and length of command until all characters are sent do CALL SENDPR( command character ) od return ASKEOR WRITE 'Enter new EOR character' to user terminal turn on change EOR character indicator return ENTEOR( CHARACTER ) echo CHARACTER to user terminal replace EOR by CHARACTER turn off change EOR character indicator return CLSFLE( TYPE ) close file of type = INPUT or OUTPUT return Program TALK Documentation PAGE 28 TALK PDL Source Code 12/2/81 XFERP READ RECORD from redirected input file if not end of file and not read error then append an EOR character to RECORD until end of record do send a character to port if host is RSX11M system then wait for host to echo the character fi od else CALL CANINP - stop redirected input fi return WRTBUF WRITE output buffer to redirected output file return Program TALK Documentation PAGE 29 TALK PDL Source Code 12/2/81 CNPRT set up DPB for terminal read/write until legal channel specified do if channel not specified in the TALK invocation then prompt for and read in channel number if error on read then indicate error return fi fi od connect to interrupt vectors if no errors on connecting then report successful connect else report failure to connect set carry to indicate failure fi return Program TALK Documentation PAGE 30 TALK PDL Source Code 12/2/81 ATTDEV( DEVICE ) save DEVICE characteristics set new DEVICE characteristics attach DEVICE with unsolicited character AST return DETDEV( DEVICE ) detach DEVICE set DEVICE characteristics return Program TALK Documentation PAGE 31 TALK PDL Source Code 12/2/81 5.0 Building TALK A command file (TALK.CMD) is provided with TALK which performs the assembly and/or taskbuild operations necessary to build the program. This command file should be used, rather than performing the operations manually, to insure that the required options are specified.