HP 3000 KERMIT Version 1.0 1.0 Introduction ---------------- This version of KERMIT was written in SPL specifically for the HP 3000. Its most notable feature is that it allows great flexibility in the way that received files are stored on the 3000. Virtually all development work on this version was done on an HP 3000 Series III. Since the Series III is not capable of 8 bit character transmission, true "binary" file transfers must be done with 8 bit quoting. The newer (HPIB) models in the HP 3000 Series are supposed to handle 8 bit characters, so a subsequent release will address this and other issues. It does work on the newer processors, but does not attempt to use 8 bit characters. 2.0 HP 3000 File System ----------------------- On the 3000, a disc file is divided into records. They may be fixed or variable length, ASCII or binary. If a less than a "full" record is written to a file with fixed length records, it will be padded with blanks (if ASCII) or binary zeros (if binary). 2.1 Text Files -------------- Each record of a text file corresponds to a "line" of printed output. If a file contains variable length records, the file system "knows" how long each record is. Carriage return and/or linefeed are NOT generally stored in text files. When transferring a text file to the 3000 via KERMIT, carriage returns are ignored and linefeed is assumed to be the record terminator. If a linefeed is not encountered before the maximum record size is reached, the remainder of the record is continued on the next line. This can be of use when sending "word processor generated" documents to the HP (the CR/LF sequence may be omitted, except at the end of a paragraph). A CR/LF sequence is appended to each record of a text file when it is transmitted from the 3000. 2.2 Binary Files ---------------- Binary files are usually stored in 256 byte, fixed-length records. The concept of a "record" may not be meaningful, this is just the most efficient way (disc storage wise) to store the file. This KERMIT regards binary files as a stream of 8 bit bytes. When receiving a binary file, all records are "filled" except (possibly) the last one. Remember that the HP file system will pad this record with binary zeros unless the file is defined as having variable length records. Another "feature" of the file system is that it assumes all binary files are made up of 16 bit words. An odd number of bytes for the record length of a file will be rounded up. Likewise, an odd number of bytes written as a record will have a binary zero appended REGARDLESS of variable length record structure. 3.0 Program Operation --------------------- HP 3000 KERMIT, like other HP programs, is invoked via the RUN command. If an INFO parameter is specified, this is interpreted as the initial command. For example, to start KERMIT in SERVER mode: RUN KERMIT;INFO="SERVE" Subsequent KERMIT commands are read from the job or session input stream. KERMIT may be initiated from a batch job, but the communications line must be specified explicitly via the SET command. 4.0 Commands ------------ 4.1 TAKE Command -------------------- Syntax: TAKE filespec The TAKE command causes subsequent commands to be taken from the specified file until EOF is reached. If a subsequent TAKE is encountered within the original TAKE file, the first file is closed and execution continues with the second. This means that if a TAKE appears within a TAKE file, commands that follow it (in the original take file) will be ignored. 4.2 SERVER Command ----------------- Syntax: SERVER The SERVER command causes HP 3000 KERMIT to go into server mode. Once in server mode, the only way back to command mode is the Control-Y trap. In addition to the standard KERMIT transactions for file transfer, the following server functions are supported: Function Probable Syntax (if available on local KERMIT) ------------- ---------------------------------------------- Finish Processing FINISH Type a file REMOTE TYPE filespec Directory Listing REMOTE DIRECTORY [filespec] File Space Listing REMOTE SPACE [filespec] Delete a file REMOTE DELETE filespec Wildcard file specification may be used only for the DIRECTORY and SPACE transactions. Wildcard specifications are in the native HP 3000 format. To produce a DIRECTORY listing of all files starting with "FOO" use: REMOTE DIRECTORY FOO@ 4.3 SEND Command ---------------- Syntax: SEND filespec1 [filespec2] This command causes a file (indicated by filespec1) to be sent from the HP to the local KERMIT. Wildcard characters are not permitted. If filespec2 is specified, the file will be sent with that name. 4.4 RECEIVE Command ------------------- Syntax: RECEIVE [filespec] The RECEIVE command causes HP KERMIT to enter receive mode and wait for the local kermit to start sending a file. If filespec is specified, the file will be stored under that name. 4.5 CONNECT Command ------------------- Syntax: CONNECT The CONNECT command causes HP KERMIT to enter a very primitive connect mode. The HP is a half duplex machine. Consequently, the kermit must read the console, echo the console, read the line, and write the console in 80 byte blocks. One must use the 'delay' parameter to force a timeout at the appropriate time of the console read. The escape character is checked after the console write of the line read. The escape characters are ^ (control) ] (back bracket) C (capital C). 4.6 SET Command --------------- Syntax: SET parameter-1 [parameter-2] ... [parameter-n] This command is used to alter the many default parameters for HP KERMIT operation. 4.6.1 DEBUG Parameter --------------------- Syntax: SET DEBUG number This sets the debug level to the indicated number. Currently, only one level exists. This level is enabled by setting the number to any non-negative, non-zero number. If DEBUG is enabled, packets sent and received are written to the LOG file. The LOG file defaults to the job/session output file. LOG output to the job/session output file is disabled when communications are taking place unless the communications line has been re-designated via the SET LINE command. 4.6.2 LOG Parameter ------------------- Syntax: SET LOG filespec This command sets the LOG file to the indicated filespec. Error and DEBUG messages (if enabled) are written to the LOG file (see SET DEBUG). 4.6.3 HANDSHAKE Parameter ------------------------- Syntax: SET HANDSHAKE option This specifies any handshaking that is to be done on the communications line. Options are: XON Generate an XON character prior to each read. This is the default mode and is needed in most cases since the HP will "lose" any characters that are transmitted when no read is active. The local KERMIT must be capable of waiting for an XON character before issuing a write to the communications line. NONE Generate no special characters prior to a read. XON2 Same as XON except in both directions. This sets the read termination character to XON in an attempt to synchronize with another KERMIT having similar limitations. 4.6.4 LINE Parameter -------------------- Syntax: SET LINE ldev This causes the indicated ldev (logical device number) to be used for communications purposes. 4.6.5 SPEED Parameter --------------------- Syntax: SET SPEED speed Sets the communications speed to the indicated number of characters per second. Supported speeds are: 30, 60, 120, 240, 480, 960. 4.6.6 DELAY Parameter --------------------- Syntax: SET DELAY number Causes a pause for the indicated number of seconds prior to starting a SEND command. This is to allow the user to escape back to the local KERMIT and enter a RECEIVE command. 4.6.7 SEND Parameter -------------------- This parameter is used to alter the default conditions relating to how files are sent. 4.6.7.1 PAUSE Parameter ----------------------- Syntax: SET SEND PAUSE number This causes a pause of number/10 seconds prior to packet transmission. A pause of this nature is needed when communicating with a KERMIT that has trouble "turning the line around". 4.6.7.2 BINARY Parameter ------------------------ Syntax: SET SEND BINARY option Defines the mode (ASCII or binary) in which to transmit files. Options are: ON Send all files as binary. OFF Send all files as ASCII. AUTO Look at how the file is defined on the HP and transmit it accordingly. This is the default mode. 4.6.8 RECEIVE Parameter ----------------------- This parameter is used to alter the default conditions regarding file reception. 4.6.8.1 BINARY Parameter ------------------------ Syntax: SET RECEIVE BINARY option Tells how to store received files on the 3000. Options are: ON Store files as binary. OFF Store files as ASCII. 4.6.8.2 DEVICE Parameter ------------------------ Syntax: SET RECEIVE DEVICE [dev] Specifies the device class for received files. Default is DISC. This command can be used to send files directly to the system line printer: SET RECEIVE DEVICE LP 4.6.8.3 FCODE Parameter ---------------------- Syntax: SET RECEIVE FCODE n Specifies the file code for received files. 4.6.8.4 RECLEN Parameter ------------------------ Syntax: SET RECEIVE RECLEN [-]n Specifies the maximum record length (n) for a received file. As with other HP file system commands, n is assumed to be words if positive and bytes if negative. 4.6.8.5 BLOCKF Parameter ------------------------ Syntax: SET RECEIVE BLOCKF n Specifies the blocking factor for received files. If n is 0, the file system will calculate a blocking factor automatically. 4.6.8.6 FIXREC Parameter ------------------------ Syntax: SET RECEIVE FIXREC option This parameter is used to identify fixed or variable length records. Options are: ON Use fixed length records. OFF Use variable length records. 4.6.8.8 MAXREC Parameter ------------------------ Syntax: SET RECEIVE MAXREC n Specifies the maximum number of records that can be stored in a received file. 4.6.8.9 MAXEXT Parameter ------------------------ Syntax: SET RECEIVE MAXEXT n Specifies the maximum number of extents for a received file. This number (n) must be in the range 1 ... 32. 4.6.8.10 SAVESP Parameter ------------------------- Syntax: SET RECEIVE SAVESP option This parameter specifies if unused file space at the end of the file is to be returned to the operating system. Options are: ON Return unused space. OFF Do not return unused space. 4.6.8.11 PROG Parameter ----------------------- Syntax: SET RECEIVE PROG This parameter can be specified to set all of the other parameters needed to receive an HP 3000 program (executable) file. It is equivalent to: SET RECEIVE BINARY ON SET RECEIVE FIXREC ON SET RECEIVE FCODE 1029 SET RECEIVE RECLEN 128 SET RECEIVE BLOCKF 1 4.6.8.12 BIN128 Parameter ------------------------- Syntax: SET RECEIVE BIN128 This sets up the needed parameters for receiving a binary file in the "normal" HP representation. It is equivalent to: SET RECEIVE BINARY ON SET RECEIVE FIXREC OFF SET RECEIVE FCODE 0 SET RECEIVE RECLEN 128 SET RECEIVE BLOCKF 0 4.6.8.13 TEXT Parameter ----------------------- Syntax: SET RECEIVE TEXT This sets up the needed parameters for receiving "generic" text files. It is equivalent to: SET RECEIVE BINARY OFF SET RECEIVE FIXREC OFF SET RECEIVE FCODE 0 SET RECEIVE RECLEN -254 SET RECEIVE BLOCKF 0 4.6.8.14 TXT80 Parameter ------------------------ Syntax: SET RECEIVE TXT80 This sets up the needed parameters for receiving 80 character text files in the manner that is most convenient for the typical text editor on the HP. It is equivalent to: SET RECEIVE BINARY OFF SET RECEIVE FIXREC ON SET RECEIVE FCODE 0 SET RECEIVE RECLEN -80 SET RECEIVE BLOCKF 16 4.7 EXIT Command ---------------- Syntax: EXIT This command causes the HP KERMIT process to terminate in an orderly manner. 4.8 HELP Command ________________ This gives a list of commands available to the command mode. 4.9 SHOW Command --------------- Syntax: SHOW parameter This command is used to show the many default parameters for HP KERMIT operation. A SHOW ALL will show all parameters. 4.9.1 DEBUG Parameter --------------------- Syntax: SHOW DEBUG number This shows the debug number. Currently, only one level exists. This level is enabled by setting the number to any non-negative, non-zero number. If DEBUG is enabled, packets sent and received are written to the LOG file. The LOG file defaults to the job/session output file. LOG output to the job/session output file is disabled when communications are taking place unless the communications line has been re-designated via the SET LINE command. 4.9.2 LOG Parameter ------------------- Syntax: SHOW LOG filespec This command shows the LOG file to the indicated filespec. Error and DEBUG messages (if enabled) are written to the LOG file (see SHOW DEBUG). 4.9.3 HANDSHAKE Parameter ------------------------- Syntax: SHOW HANDSHAKE option This shows any handshaking that is to be done on the communications line. Options are: XON Generate an XON character prior to each read. This is the default mode and is needed in most cases since the HP will "lose" any characters that are transmitted when no read is active. The local KERMIT must be capable of waiting for an XON character before issuing a write to the communications line. NONE Generate no special characters prior to a read. XON2 Same as XON except in both directions. This sets the read termination character to XON in an attempt to synchronize with another KERMIT having similar limitations. 4.9.4 LINE Parameter -------------------- Syntax: SHOW LINE ldev This shows the ldev (logical device number) to be used for communications purposes. 4.9.5 SPEED Parameter --------------------- Syntax: SHOW SPEED speed Shows the communications speed to the indicated number of characters per second. Supported speeds are: 30, 60, 120, 240, 480, 960. 4.9.6 DELAY Parameter --------------------- Syntax: SHOW DELAY number Causes a pause for the shown number of seconds prior to starting a SEND command. This is to allow the user to escape back to the local KERMIT and enter a RECEIVE command. 4.9.7 SEND Parameter -------------------- This parameter is used to alter the default conditions relating to how files are sent. 4.9.7.1 PAUSE Parameter ----------------------- Syntax: SHOW SEND PAUSE number This shows a pause of number/10 seconds prior to packet transmission. A pause of this nature is needed when communicating with a KERMIT that has trouble "turning the line around". 4.9.7.2 BINARY Parameter ------------------------ Syntax: SHOW SEND BINARY option Shows the mode (ASCII or binary) in which to transmit files. Options are: ON Send all files as binary. OFF Send all files as ASCII. AUTO Look at how the file is defined on the HP and transmit it accordingly. This is the default mode. 4.9.8 RECEIVE Parameter ----------------------- This parameter is used to alter the default conditions regarding file reception. 4.9.8.1 BINARY Parameter ------------------------ Syntax: SHOW RECEIVE BINARY option Shows how to store received files on the 3000. Options are: ON Store files as binary. OFF Store files as ASCII. 4.9.8.2 DEVICE Parameter ------------------------ Syntax: SHOW RECEIVE DEVICE [dev] Shows the device class for received files. Default is DISC. This command can be used to send files directly to the system line printer: SHOW RECEIVE DEVICE LP 4.9.8.3 FCODE Parameter ---------------------- Syntax: SHOW RECEIVE FCODE n Shows the file code for received files. 4.9.8.4 RECLEN Parameter ------------------------ Syntax: SHOW RECEIVE RECLEN [-]n Shows the maximum record length (n) for a received file. As with other HP file system commands, n is assumed to be words if positive and bytes if negative. 4.9.8.5 BLOCKF Parameter ------------------------ Syntax: SHOW RECEIVE BLOCKF n Shows the blocking factor for received files. If n is 0, the file system will calculate a blocking factor automatically. 4.9.8.6 FIXREC Parameter ------------------------ Syntax: SHOW RECEIVE FIXREC option This parameter is shown to identify fixed or variable length records. Options are: ON Use fixed length records. OFF Use variable length records. 4.9.8.8 MAXREC Parameter ------------------------ Syntax: SHOW RECEIVE MAXREC n Shows the maximum number of records that can be stored in a received file. 4.9.8.9 MAXEXT Parameter ------------------------ Syntax: SHOW RECEIVE MAXEXT n Shows the maximum number of extents for a received file. This number (n) must be in the range 1 ... 32. 4.9.8.10 SAVESP Parameter ------------------------- Syntax: SHOW RECEIVE SAVESP option This parameter shows if unused file space at the end of the file is to be returned to the operating system. Options are: ON Return unused space. OFF Do not return unused space. 5.0 SHOW ALL ____________ Syntax: SHOW ALL Shows all the parameters. 5.1 FINISH __________ Syntax: FINISH Used in a TAKE file or CONNECT mode to finish a server on the remote machine. 6.0 Initial State of Parameters ------------------------------- When HP KERMIT is started, parameters are set as follows: Debug: 0 (No DEBUG Messages) Log: None Handshake: XON Line: Session output device Speed: Current Speed of Session Device Delay: 10 Seconds Send Pause: None Send Binary: Auto Receive Binary: Off Receive Device: DISC Receive Fcode: 0 Receive Reclen: -80 Receive Blockf: 0 Receive Fixrec: On Receive Maxrec: 5000 Receive Maxext: 32 Receive Savesp: On