.PS64,80.lm0.rm80.HEADER MIXED.nhy # .b10 .C;HPX -- HP2648A FILE TRANSFER UTILITY .b2 .c;USER'S GUIDE .b15.lm20.nf Author:#####Chris Doran, .lm32 Sira Ltd., South Hill, Chislehurst, Kent, BR7 5EH, England. .lm20.B1 Telephone:##01-467 2636 Telex:######896649 Fax:########01-467 6515 .b5 Version:####V1.08 .b2 Date:#######6th October 1987 .f.LM0.page .t HPX -- HP2648A File Transfer Utility .ST User's Guide .hl1 INTRODUCTION The Hewlett-Packard 2648A is an alphanumeric/graphics terminal which may be fitted with two tape drives for 110kbyte DC100A cartridges, and/or a slave printer. By use of local or computer-generated commands, data may be transferred bidirectionally between the various terminal devices (including the alphanumeric display), and between the devices and a computer connected through the EIA interface. .p0 Although physically identical, the HP tape cartridges are &n&o&t interchangeable with DECtape II cartridges used in TU58 tape drives. The latter are factory-formatted, twin-track, and can be used for random-access disk-like operations, whilst the former are unformatted, single-track, and written sequentially like magtapes. Unfortunately, DEC do not provide a way to format DC100A blank cartridges, and trying to use one in a TU58 drive will simply unwind the tape off one of the spools! .p0 HPX is a utility to transfer ASCII or binary data files between a PDP-11 running RSX-11M/M-PLUS, or a VAX running VMS, and a Hewlett-Packard 2648A terminal display, tape cartridges, or printer. .hl1 INVOKING HPX Under RSX-11M/M-PLUS, HPX may be started in any of the usual ways:- .list 1 .le;For single line execution with a command line: .p5 >HPX .le;For multiple execution with several command lines: .lm+5;.b1;.nf >HPX HPX> HPX> HPX> ... HPX>ctrl/Z .lm-5;.f .le;By install-run-and-remove-on-exit: .p5 >RUN $HPX .b1 in which case it prompts for command lines as in method 2. .le;By install-run-and-remove-on-exit with a command line (RSX V4.0 and later only): .p5 MCR>RUN $HPX/CMD="HPX " .br or###DCL>R $HPX/COMMAND="HPX " .els Methods 1 and 2 may also be used to run HPX under the VAX-11 RSX Applications Migration Executive on VAX/VMS systems, once HPX is installed as a foreign command, using: .p5 $ HPX :== $HPX .p0 For any of the above, the command line(s) may be contained in an indirect command file, and the command to invoke HPX takes the form: .p5 >HPX @ .p0 Command cannot be nested i.e_. one command file cannot contain a call to another. .p0 Command lines take several forms, as described in the following sections. .hl2 COMMAND LINE SYNTAX SUMMARY .nf.ts5,12,40 Copy disk file(s) to terminal device(s): >HPX ={/AS}{/BI} .b1 Copy from terminal device to disk file: >HPX {/SP}{/AP}={/AS}{/BI} .b1 Compare device with disk file: >HPX {/SP}={/AS}{/BI}/CMP .b1 Position tape only: >HPX {/RT:n}{/LT:n} .tp5 where s are: /LT:n File n on left tape (default n = next file). Unsigned n is absolute, signed is relative to current position. /LT:A Append to end of last file on tape. /LT:C Condition tape, leaving it rewound. /LT:E Start a new file after last file on tape. /LT:R Rewind tape. /RT:x As above, for right tape. /DI Screen display. /PR Printer. .b1 Other switches are: /AS ASCII data to be transferred = /-BI [default]. /BI Binary transfer mode required = /-AS. /FO Create output file with FORTRAN carriage-control. /SP Spool output file to computer printer. /AP Append output to existing file. /LA Latch current switch settings for next command line. /WBR Use write-backspace-read mode [default = /-WBR = don't]. /CMP This is a compare operation [default = /-CMP = copy]. /LI List files during multi-input copy/compare [default]. /-LI Don't list files during multi-file copy/compare. /EL Reset character set and emphasis at end of line [default /-EL]. .f .hl2 TERMINAL DEVICE SPECIFICATIONS The same utility is used to transfer both to and from the terminal. Terminal devices and files are specified by command line switches only, whereas computer devices and disk files are named in the usual way. This enables HPX to determine the transfer direction since the terminal side of the command line will contain only switches, whereas the computer side must give at least some part of a filename. Operations between one terminal device and another (e.g_. copy left tape to terminal printer) are not supported by HPX since they can be done entirely by local keyboard commands. However, a tape rewind facility is provided to enable tapes to be rewound automatically before removal. .p0 Four possible terminal devices may be specified as source or destination for transfer operations: /DI for the display, /LT for the left tape, /RT for the right tape, and /PR for the printer (destination device only). HPX will report an error if an attempt is made to access a device which is not actually fitted. .p0 The tape drive switches may have ASCII or numeric switch values, separated from the switch letters by a colon, to specify tape positioning by file number. There are several cases: .lm10;.p-10,1,5;.ts10 /LT:n where n is an unsigned decimal number between 1 and 255., gives an absolute file number on the left tape (/RT:nnn for right tape). "Terminal device error F" occurs if an attempt is made to position to a file beyond the end of the tape. .p-10,1,5 /LT:+n where +n is a signed positive decimal number between +1 and +255, spaces forward by nnn files. E.g_. if the tape is currently positioned at file number 3, then /LT:+2 specifies absolute file number 5. "Terminal device error F" occurs if an attempt is made to space beyond the end of the tape. Note that after file n has been read or written, the current file is number n+1, so /LT:+1 will skip one file, and NOT just advance to the next, as might be supposed. .p-10,1,4 /LT:-n spaces back n files from the current file. If an attempt is made to space back before file 1, then file 1 will be read or written, without warning. .p-10 /LT Specifies the left tape at the current position. .p-10,1,6 /LT:0 is the same as /LT again selecting the current file. .p-10 /LT:R rewinds the tape, so that the next file accessed will be file 1. .p-10,1,4 /LT:E positions the tape just after the final file, and writes a file mark, so that the next file written will be a new file at the end of the tape. .p-10,1,3 /LT:A positions the tape at the end of the final file, but does not write a file mark, so the data next written will be appended to it. .p-10,1,5 /LT:C "conditions" the cartridge by winding the tape all the way forward and back again to repack it, leaving the tape rewound. Brand new cartridges, or ones which have been unused for some time may need to be conditioned to enable the tape to run freely. .lm0.p0 When the display is given as a source device, the following prompt appears in blinking reverse video: .p5 Edit display, position cursor, press a key .p0 You may then use the terminal's editing keys to remove any unwanted text (including the prompt) or make additions. Set the terminal to LOCAL to type extra text. When editing is complete position the cursor to the first character to be transmitted, set the terminal to REMOTE, and press any key (which is not echoed). All text from the cursor position down to the last character in the display memory (including any initially off the bottom of the screen) is then copied to the computer output file. .p0 Any number of destination devices may be specified for copying &t&o the terminal, but only one for copying from (or comparing). Thus it is possible to write two identical tapes in one command, or to echo the output to the display for verification. .hl2 COMPUTER FILE SPECIFICATIONS Any valid file specification, in the usual format, may be used: .p5 device:[directory]filename.type;version .p0 As explained above, there must be at least ^&some\& portion of a filename, so that HPX can determine the required transfer direction. The default filename is SY:HPX.TXT, in the current directory. Filetypes and device/directory are defaulted along the line (and filetypes also from line to line if the /LAtch switch is in use). .p0 There may be more than one input file on the right-hand side of the command line when copying ^&to\& the terminal; each such file is written to a separate file on the tape(s). Wildcards may appear as any part of the directory or filename but wild characters and part-wildcard fields (AB%CD, XY*Z etc.) are not supported. Only one output/comparison file is allowed. .p0 The /APpend switch may be used on an output file to append data to an existing file. .p0 The /SPool switch may be used on any file to cause it to be spooled to the computer lineprinter when it is closed. Files with names matching certain specifications may be deleted after printing. .p0 When a new file is being created for output, its record attribute is set according to the following rules: .list 1 .le;If a binary transfer is specified (/BI switch -- see below), then no carriage-control (assumed embedded if required). .le;If an ASCII transfer is specified and the /FORTRAN switch is off (default or /-FO), then standard carriage control (FD.CR) is selected, and each record of the file will be preceded by a line feed and followed by a carriage return when it is output to a terminal or printer. .le;For ASCII transfers when the /FORTRAN switch is on, the file is opened with FORTRAN carriage-control, in which the first byte of the record specifies the vertical format to be used on printing. No modifications are made to the records transferred by HPX -- the control character is assumed to be actually present on, or will be copied to, the tape file or display. .els When an existing file is opened for append or read, the carriage-control information is taken from the file header, and the /FO switch is ignored. .hl2 TRANSFER MODES Data may be transferred or compared in ASCII or binary modes, as selected by the /ASCII and /BInary switches, which are logical complements. For details of the exact transfer mechanism the reader is referred to Chapter IV of the HP2648A Graphics Terminal reference manual. .p0 The important difference is that binary transfers pass all eight bits of the data and may include codes which are ASCII control characters, whereas ASCII transfers involve only seven bits (the parity bit is cleared), and certain control characters (e.g_. linefeed, DC1, control/U) have special significance and cannot be transferred properly. Escape sequences, such as those used to give special screen highlighting effects, will, however, be transferred correctly. ASCII transfers involve less handshaking between terminal and HPX and are therefore preferable where possible. An additional advantage of using ASCII mode to write files to the computer is that normal carriage-control is used, and the file copied can therefore be read and edited without difficulty. .p0 Binary mode must be used, however, when all eight bits are required (e.g_. for object files), and when special control characters are included. .p0 Note that when ASCII text is copied to a file in binary mode, a carriage-return and line feed are appended to the end of each record written, thus giving a file with embedded carriage control which will print correctly, but gives problems when attempting to read it with some DEC utilities and user-written programs. .p0 The maximum record size for both ASCII and binary files is 256_. bytes. Files with records larger than this (e.g_. task images) cannot be handled by HPX. .p0 One further difficulty occurs with binary transfers: There seems to be no way to write a zero-length record to the terminal in binary mode. Such records are therefore written as a single null byte. This ensures that the correct number of records is transferred, but since the inverse translation is &n&o&t made when a tape is copied back to the computer, problems may arise when saving and restoring such binary files. Similarly, no allowance is made for these records when a tape is compared with a file, so a number of differences will be reported. .hl2 FILES CONTAINING HIGHLIGHTING AND ALTERNATIVE CHARACTER SETS On the HP2648A terminal, special character sets and emphasis automatically go off at the end of a line. This does not apply, however, to some other HP devices, such as the 2686 LaserJet printer, which carries them forward from line-to-line. So that files (especially forms) can be created on the screen and printed on the LaserJet, the /EL switch is provided to explicitly turn them off by appending to each record: .ts13.p5 ctrl/N if there was a ctrl/O not followed by ctrl/N .br and##esc_&d@ if there was any of esc_&dA to esc_&dO not followed by esc_&d@, .b1 the first cancelling character set selection, and the second emphasis. In principle, equivalent reset commands should be appended to cancel protected and alphabetic/numeric field selections, but since no other device is known to be affected by them, this has not yet been done. .p0 The /EL switch operates only for ASCII transfers, since escape sequences are not generated in binary mode: .p0 The behaviour of the terminal when transferring screen displays containing enhancements, such as inverse video, blinking, or protected fields, is not described in the manual. Apparently, feature control is stored internally in single bytes, with sign bit 7 set, so octal byte 202 means "put following characters in inverse video" and 200 means "end enhancement". They are interpreted as display actions when the internal memory or a tape is copied to the screen, and expanded to escape sequences when the display or a tape is sent to the computer in ASCII mode. They are not expanded during binary transfers, however, so ASCII mode must be used to copy an enhanced or protected display to a file which is to be displayed later by another program or system utility. If an enhanced display is stored in binary mode then the 2xx codes go into the file, and the enhancements only reappear when that file is copied back to the screen by a binary transfer. .hl2 VERIFICATION FACILITIES When writing to tape cartridges, the terminal has a built-in check facility which may be enabled by the /WBR switch. With this switch on (by default it is off), the terminal automatically re-reads each record as it is written, and will report an error, aborting the operation, if any recording faults are detected. .p0 HPX also has a facility to compare a file on a tape or the display with a disk file on the computer. A command line giving a single file on the left-hand side of the = sign, and a single device file on the right-hand side, together with the /CMP switch, changes its operation from "copy terminal device to file" to "compare computer file with terminal file". The /BI or (default) /AS switches must be the same as they were when the original copy was made. HPX then reads the entire file on the terminal (thus leaving tapes positioned at the next logical file) and reports: .p5 HPX -- *DIAG*-nnnn. differing records .BR or###HPX -- *DIAG*-No differing records .p0 When the files fail to match, only the number of lines (or binary records) which differ is given. For a more informative check, the terminal file must be examined visually, or copied to a second disk file and compared with the first using DEC's CMP utility (DIFFERENCES under DCL). .hl2 THE LATCH SWITCH Default switch settings and filetypes are usually reset at the end of each command line. The latch switch may be used to carry them forward from one line to another. Latching continues until the end of the line on which the switch is negated (/-LA). .p0 Terminal device specification switches cannot be latched. .hl2 POSITIONING THE TAPE As a special case, a tape positioning command may be given alone on a line which does not contain a filename or equals sign. In this case the tape is simply positioned without writing or reading any data. The most usual use of this is to rewind a cartridge before removing it, although it could be used to position a tape for the next operation. .tp8 .hl2 MULTIPLE- AND WILDCARD FILE COPIES When an input file specification for a copy operation contains several files, or wildcards, HPX will display the filename as it starts each copy operation. This is particularly useful when wildcards appear, as the files are not found in any particular order, and without this list there may be no way to know the order of files on the tape, or to determine which file any error messages are associated with. If a hard-copy of the list is required as a tape directory, a subsequent "copy display to file" command can be used. The list of files can be suppressed by the /-LI switch if, for example, it would interfere with a screen display. .tp8 .hl2 EXAMPLE COMMAND LINES .lm8;.i-8 >HPX OUTPUT=/LT:3 .br Copies the third file on the left tape to file OUTPUT.TXT (default filetype) in ASCII mode. .p-8,1,5 >HPX OUTPUT=/LT:-1/CMP/LA .br Verifies the above copy by comparing OUTPUT.TXT with the tape file from which it was just written, by backspacing 1 file. Use of the /LA switch means that all subsequent operations will be compares until /-CMP or /-LA is given. .p-8,1,4 >HPX DISPLAY.DAT=/DI .br Writes a selected portion of the screen display to ASCII file DISPLAY.DAT. .p-8,1,5 >HPX /RT:E=PROGRAM.OBJ/BI/WBR .br Writes file PROGRAM.OBJ in binary mode as the next file on the end of the right tape. Write-backspace-read mode is turned on for write checking. .p-8,1,4 >HPX /RT:1/PR/LT:3=FILE1.FTN,FILE2 .br Copies FILE1.FTN to right tape file 1, and left tape file 3, and also the terminal printer. FILE2.FTN is then copied to right tape file 2, left tape file 4, and the printer. Note that the file positioning commands specify only the positions of the first files to be written, and any subsequent ones follow sequentially. .p-8,1,5 >HPX LP.LST/FO/SP=/RT .br Copies the current file on the right tape to LP.LST, created with FORTRAN carriage-control. LP.LST is spooled to the computer printer and will be deleted automatically. .p-8,1,3 >HPX /RT:R/LT:R .br Rewinds both tapes. .p-8,1,3 >HPX /LT:R=*.FTN .I-8 >HPX LP.LST/SP=/DI .BR Copies all FORTRAN source files in the user's directory to the left tape (starting at the beginning) and re-invokes HPX to make a list of the files on the tape in file LP.LST, which will be spooled to the lineprinter. .lm0;.tp9 .hl1 ERROR MESSAGES .lm5;.i-5 HPX -- *FATAL*-Aborted by CLI .br This message indicates that HPX was terminated by the user, or another privileged terminal issuing a CLI ABORT command. .p-5,1,4 HPX -- *FATAL*-Command line error .br This covers a number of possible cases e.g.: .list 0 .le;A command line fetch may have failed (e.g_. an indirect command file did not exist), .le;There is a syntax error in a file name, .le;An invalid switch or wildcard has been used, .le;A switch other than /LI, /LA, /BI, or /AS has been given on a second or subsequent input file in a multi-file copy, .le;More than one output file, or wildcard output, has been specified, .le;A device to device or file to file operation has been specified. .els Processing of the current command line is abandoned, and HPX either prompts for a new command line or exits. .p-5,1,5 HPX -- *FATAL*-Directive error nn. .BR A device or file I/O operation failed. The code given in nn is the decimal value of directive status word error code, described in the Executive Reference Manual. .p-5,1,4 HPX -- *DIAG*-nnnn_. differing records .br In a compare operation the tape and computer files did not match in all records and in number of records. nnnn is the number of records which differ. .p-5,1,3 HPX -- *DIAG*-No differing records .BR A compare operation found no differences between tape and computer files. .p-5,1,6 HPX -- *FATAL*-File I/O error nn. .br An error occurred while reading or writing a file. The reason is given in the FCS error code shown in decimal, and listed in the I/O Operations Reference Manual. Common error codes are -24_. = "Device full", and -40_. = "Illegal record size" (>256_. bytes). .p-5,1,5 HPX -- *FATAL*-File open error nn. .br HPX failed to open an input or output file for the reason given by the FCS error code shown. Common errors are -26_. = "file not found", -38_. = "File was not closed properly", and -16_. = "privilege violation". .p-5,1,5 HPX -- *FATAL*-Illegal tape position .br A switch value given to /LT or /RT is not one of the letters: A, E, or R, or a signed decimal number. .p-5,1,5 HPX -- *FATAL*-Invalid terminal device(s) .br The command line had too many input devices (only one is allowed), or none at all, or an attempt was made to read from the printer only. The command line is ignored. .p-5,1,5 HPX -- *FATAL*-No printer .br An attempt has been made to output to a non-existant printer. If the printer &i&s present, make sure that it is correctly plugged into the terminal, and re-issue the command. .p-5,1,5 HPX -- *FATAL*-No tape in xH drive .br There is no tape in the specified drive. Insert a cartridge, and/or make sure it is correctly seated, and re-issue the command. .p-5,1,5 HPX -- *FATAL*-Timed out after nnn_. sec .BR HPX failed to receive acknowledgement of completion of an operation after the specified time had elapsed. Check that the terminal is still on-line and retry the operation. HPX's timeout periods are varied according to the operation being performed. If you find a case which persistently times out, it may be that the standard wait period should be increased. Please report such situations to the author. Tape operations can sometimes fail due to a cartridge being wound overtight, which sometimes happens during manufacture or storage. It may help to "condition" a failing cartridge using /xT:C (q.v.). .p-5,1,5 HPX -- *FATAL*-Terminal device error F .BR The terminal reported failure on a read or write operation. This may be due to a faulty tape cartridge or drive, or an attempt to position past the last file. .p-5,1,5 HPX -- *FATAL*-Terminal device error .BR The terminal failed to reply as expected to a command from HPX. This may be due to the user pressing a terminal key while an operation was in progress, or to a transmission failure. Retry the operation. Further information on the problem may be given by the character (if any appears). This is first character of the reply HPX received to a status request. .p-5,1,6 HPX -- *FATAL*-QIO error nn. .br An I/O error occurred in transferring data to/from the terminal. nn is an error number as given in the I/O Operations Reference Manual. Positive values indicate that the operation succeeded, but for the wrong reason. One common situation is where a previous operation failed, leaving unprocessed terminal output which is incorrectly received by the next command. If this problem persists, it can usually be cured by pressing the terminal reset key once or twice. Another common cause is an attempt to make an ASCII transfer of a file which contains certain control codes or escape sequences which are intercepted by the terminal or operating system. Such files must ^&always\& be copied in binary mode. .p-5,1,6 HPX -- *FATAL*-TI:# not a 2648A .BR On startup, HPX checks that the user terminal is actually an HP2648A, by sending out the "identify" escape sequence. If it is not, or for some reason does not reply correctly or in time, no HPX operations can be performed, so it exits immediately with the above message. .p-5,1,5 HPX -- *FATAL*-xH tape is write-protected .br A request has been made to write to a tape which is write-protected. Make sure that you specified the correct cartridge and that the RECORD tab is slid fully to the left, then re-issue the command. .lm0 .hl2 EXIT STATUS If the host system supports exit with status (a Sysgen option), HPX will return exit status of success (EX$SUC = 1) if no errors are detected in any operation. Any errors detected return other exit status values of varying degrees of severity. If several errors occur, the worst case is reported. .p0 'Severe error' status (EX$SEV = 4) is returned if HPX is aborted or terminates on startup because the terminal is not a 2648A. "Command line error" and "Invalid terminal device(s)" return 'error' exit status (EX$ERR = 2) to indicate that the command line was not fully processed. All others, including file comparisons where differences were found, set 'warning' status (EX$WAR = 0). Success status is returned if a file comparison succeeds and no more serious errors are detected. .p0 During normal operation, HPX sets the terminal to upper/lower case, no auto LF, and not block mode, regardless of the setting of the latching keys on the terminal itself. On exit, it attempts to reset these functions as they were when it started. This will not necessarily work if it terminates abnormally, however, and in such cases it may be necessary to press the terminal reset key.