HOW TO USE THE DOWNLOAD PROGRAM (A utility for tranferring IPC HP-UX BASIC files to Series-80) (c) Copyright 1985 Hewlett-Packard Co. last revised 10/29/1985 1. Summary DOWNLOAD is a softkey-driven program that lets you transfer IPC HP-UX Technical BASIC files to Series-80 computers. Its interface is very much like that of its companion program, UPLOAD. Series-80 files with the same names as the source files are created on the Series-80 destination disc at the end of the transfer. No special preparation is necessary prior to transfer. The following types of transfer are provided: 1. "SAVE"d files (i.e., HP-UX text files) to Series-80 DATA files or LIF files compatible with Series-200 BASIC. 2. Tech BASIC DATA files to Series-80 DATA files or LIF files. 3. Tech BASIC GRAF files to Series-80 GRAF files. 2. Types of HP-UX Technical BASIC Files The HP-UX Technical BASIC file types that can be transferred to Series-80 are as follows: 1. HP-UX (ASCII) text files. This type of file can be created in Tech BASIC by: (a) "SAVE"ing a program; (b) redirecting output (using the "ASSIGN" statement) to a file. Outside Tech BASIC, a text file can be created by any HP-UX editor. When a file of this type is downloaded to Series-80, the result is a DATA file containing string data with a logical record size of 256. On the Series-80 computer, the data can be retrieved by the "GET" command (if the source was a "SAVE"d Tech BASIC program), or by the mass storage commands "ASSIGN#" and "READ#". This is the default transfer mode for HP-UX text files. However, if you specify the "-l" option at the time of program invocation, the resulting file is an LIF ASCII file. This option was included to help transfers of IPC Tech BASIC programs to Series-200 BASIC. 2. HP-UX Tech BASIC DATA files. This type of file can be created by the Tech BASIC "CREATE" command, and written by the "PRINT#" command. The result of downloading this type of file is a Series-80 DATA file with the identical logical record size as the source file. In the default mode, Tech BASIC numeric data is transferred as Series-80 BCD REAL numbers, and strings as strings. The contents of the resulting file can be accessed by the commands "ASSIGN#" and "READ#". If you specify the "-a" option at invocation, however, all Tech BASIC numeric data items are transferred as ASCII digit strings. Therefore, the resulting file contains ALL strings. In this case, the logical record size of the file is 256. 3. HP-UX Tech BASIC GRAF files. A Tech BASIC GRAF file is transferred as a Series-80 GRAF file. The resulting file can be retrieved by the "GLOAD" command. When you "GLOAD" the downloaded Tech BASIC GRAF file, Series-80 BASIC will be in GRAPHALL mode. The Tech BASIC graphics screen is 255 by 512 pixels, and the Series-80 GRAPHALL screen is 240 by 544 pixels, so the downloaded graphics file's rightmost 32 pixel columns are truncated and bottom 15 pixel rows are filled with "0" bits. 3. Hardware Requirements and Set-Up This utility will work with the basic IPC without an additional disc drive. The operation will run faster and will be more convenient if at least one external HP-IB disc drive is available. If an external HP-IB drive is available, it should be connected and turned on BEFORE the IPC is booted. Otherwise, you must excecute the "scan_discs" program (located in the "/rom" directory) to make sure the external drives are entered in the "/dev" directory. 4. DOWNLOAD Step-by-Step The program is softkey-driven and its operation should be self-explanatory. Here is the brief description of the operating procedure. 4.1. Basic IPC System (RAMdisc to Internal Disc Drive) 1. Copy HP-UX Tech BASIC files you want to download to a directory in RAMdisc, say "/tmp". 2. Insert the disc containing DOWNLOAD in the internal drive, and invoke DOWNLOAD by pressing the softkey [Start] when "download" is in inverse video, or by simply typing "upload" and pressing the RETURN key. The program name can be followed by a list of options starting with a dash (see the section on program options). 3. Remove the disc from the internal drive and insert a Series-80 destination disc (single sided Sony disc). It is best to start with an empty disc, or a disc with a lot of space left beyond the end of the last file. 4. DOWNLOAD will prompt you to input the name of the device which contains the Series-80 disc. Type "A" or "internal". 5. DOWNLOAD will prompt you to input the source HP-UX directory/device name. Type the name of the directory in the RAMdisc to which you have copied files in step 1. 6. If you want to transfer the entire contents of the HP-UX source directory, then press the [Direct] softkey. If you want to transfer only specified files, press the [Files] softkey. In case of file-by-file transfer, you can go through the list of files by pressing softkeys until the desired file name appears. You press the [Pick] softkey to choose the file to transfer. If the destination disc becomes full, the program will prompt you to replace the disc with another. 4.2. IPC With External Drive(s) If there is at least one external drive, files can be transferred directly to a disc without doing the intermediate transfer to the RAMdisc. There are different ways of doing the transfer. One example is given here. It is strongly recommended that you unmount the discs in the external disc drives with the "unmount_disc" program on the system utility disc before inserting the HP-UX source, or Series-80 destination, disc and that you unmount the source HP-UX disc after downloading. If the disc that contains DOWLOAD is in the internal drive, then DOWNLOAD can be invoked by either typing the DOWLOAD's pathname, or pressing the [Start] softkey when the cursor is on "download". However, if DOWNLOAD has been copied to the RAMdisc or to the source disc, or if the program disc is in a third drive (other than drives holding the HP-UX source disc or the Series-80 destination disc), DOWNLOAD can be invoked with a list of parameters and options. In this case the program can be invoked by typing: download [opt. list] [dest dev.name] [source directory/device name] Examples: command line comment ------------ --------------------------- download program asks for parameters download -l ditto download D000 program asks for the remaining param. download -l D000 ditto download D000 /tmp entire source diretory downloaded download -a D000 internal ditto where: - The option list must be "-" (a minus sign) followed immeditely (i.e., no blanks must separate "-" and what follows) by concatenation of available options, or a blank followed by another option list. (Options are discussed later.) - [destination device name] is the name of the disc drive in which the Series-80 disc resides. - [source directry/device name] is the source HP-UX directory name, or the name of the disc drive, where a source HP-UX disc resides. If the drive name is given, DOWNLOAD will download files that are in the TOP LEVEL directory of that disc. If you want to transfer files to a subdirectory, you MUST specify the full subdirectory name. If DOWNLOAD is invoked with a complete list of parameters, BOTH the destination device and the source directory MUST be available. If not, DOWNLOAD will go into the interactive mode and ask you to correct the situation. Once options are set at the program invocation time, they remain effective throughout the session. There is NO manual override of options once the program starts. The remaining steps are the same as in the single drive configuration. 5. Softkeys and Their Functions Following are the softkeys in the main menu. [Catalog] Displays the statistics (name, type and size) of the files in the source directory. This function will display HP-UX text file, Tech BASIC DATA and GRAF (optionally PROG and SUBP) file types. [First] Sets the current file to the first directory entry. [Next] Sets the current file to the one following the one that is currently on the screen. [Previous] Sets the current file to the one previous to the one that is currently on the screen. [Last] Sets the current file to the last directory entry. [Pick] Chooses the current file as the file to be downloaded. This key will not appear if the current file has already been downloaded. [Exit] Ends the session with the DOWNLOAD program. 6. Options f: File by file transfer. If this option is set, DOWNLOAD will ask for the name of each file to be transferred. If DOWNLOAD is invoked with a complete list of parameters (i.e., destination device and source device/directory), in the absence of this option, the entire contents of the source directory will be transferred automatically. t: Blank substitution for TAB. A "t", followed by 1- or 2-digit number specifies the number of blanks to replace a TAB character in an HP-UX text file. A "t" followed by 0 or no number suppresses blank substitution. For example: "download -t12" - tells the program to substitute each TAB character with 12 blanks. a: All numeric data in HP-UX Tech BASIC DATA files is downloaded as ASCII strings, and NOT as Series-80 BCD numeric data in a Series-80 DATA file. l: HP-UX text files are downloaded as ASCII strings to LIF files compatible with Series-200 BASIC. If both "a" and "l" options are set, HP-UX text and Tech BASIC DATA files are downloaded as ASCII strings to LIF files. p: Makes the program keep file statistics on Tech BASIC program and subprogram files so that [Catalog] can display them, even though these files cannot be downloaded. 7. NOTE When DOWNLOAD creates Series-80 files on a Series-80 disc, it scans the directory to the end and creates files beyond the current end of the directory. It will NOT use NULL holes. It is recommended that you start with an empty disc or a disc with a lot of space beyond the last file on the disc. When DOWNLOAD creates an entry in a Series-80 directory, it does not check for duplicate file names, e.g., if a Series-80 disc contains a file named "A" and you download a like-named file to it, you end up with 2 files named "A". Since HP-UX file names can be up to 14 characters long, and Series-80 file names are maximum of 10 characters, long file names are truncated to 10 characters. This means that HP-UX file names that are the same in the first 10 characters end up identical on Series-80. If an HP-UX source file name contains characters that have special meanings in Series-80, such as the colon or period, they are converted into an underscore character. When a Tech BASIC DATA file is downloaded to Series-80, the program attempts to maintain random accessiblity by moving the same number of data items in the corresponding logical records. However, under certain circumstances, this may not be possible. For example, if a Tech BASIC data file containing INTEGER or SHORT numbers (which occupy 5 bytes each) is transferred to Series-80, the resulting data file may not hold the same number of data items per logical record. On the display of a Series-80 computer, the TAB character is a single displayable character. DOWNLOAD replaces a TAB character in the source HP-UX text file with 8 blank characters. You can override this default setting by specifying the desired substitution as a DOWNLOAD option. If the source directory does not contain HP-UX text file or Tech BASIC files, DOWNLOAD will declare the directory empty and quit. DOWNLOAD will also ignore file names starting with a period. 8. APPENDIX 8.1. Limitations DOWNLOAD holds in memory up to 100 HP-UX directory entries (the first 100 in a directory). If a directory contains more than 100 files to be transferred, DOWNLOAD warns that the directory contains more than 100 potential transfer candidates. If you need to transfer more files after transferring the first batch of 100 files, you must "hide" from DOWNLOAD some of the files already transferred. You can do this by "RENAME"ing the files to start with a period ("."_). 8.2. Error handling There are two types of errors: recoverable and unrecoverable. DOWNLOAD continue after a recoverable error, but not after an unrecoverable error. Recoverable errors include: 1. Encountering corrupt HP-UX files. 2. Nonstandard data file formats, or other conditions that make it impossible for DOWNLOAD to interpret data items. 3. The destination disc becoming full. DOWNLOAD terminates if it can not read from or write to mass storage, or if it cannot obtain temporary memory. 8.3. Differences in Data Precision and Value Range In Series 80 BASIC, the range of REAL numbers is +/-9.99999999999E+/-499, and the numbers are represented in BCD with accuracy of 12 digits. In Tech Basic, the range of REAL numbers is +/-8.98846567431E+/-307, and the numbers are stored as binary numbers accurate to 16 digits. In binary representation, the decimal fractions that can be represented precisely in BCD representation may not be represented precisely, since they are approximated with a binary fraction. The first 12 significant digits of Tech BASIC numeric data are transferred to Series-80. All three Tech BASIC numeric types (REAL, INTEGER and SHORT) are converted into the Series-80 REAL type. 8.4. HP-UX Tech BASIC Programs Containing Escaped Characters The default character set on the IPC is Roman extension, with ASCII codes in the ranges of 0-31 and 128-159 decimal being non-displayable characters. In Tech BASIC programs, in-line string literals with non-displayable characters are escaped with a "~", followed by 3 decimal digits. The "~" character itself is represented as "~~". In Tech BASIC, such a program line may look like: 20 A$ = "THIS ~002~020~023" On Series-80, you must replace these escaped sequences with single displayable characters; in the example above, CHR$(2), CHR$(20), and CHR$(23), respectively.