HOW TO USE THE UPLOAD PROGRAM (A utility to port Series-80 files to HP-UX Technical BASIC) (c) copyright 1985 Hewlett-Packard Co. last revised 10/29/1985 1. Summary UPLOAD is a softkey-driven program that lets you transfer Series-80 BASIC programs, as well as data and graphics files, to IPC HP-UX Technical BASIC. No special preparation is necessary for transfer - EXCEPT that Series-80 BASIC programs MUST be "SAVE"d in files whose names start with an underscore ("_") before they can be ported to Tech BASIC. 2. Types of Series-80 Files Series-80 BASIC file types that can be tranferred to Tech BASIC, and the resulting file types are as follows: 1. Programs. A Series-80 BASIC program must be "SAVE"d in ASCII form in a DATA file whose name starts with an underscore. This file is transferred as an HP-UX text file. The Tech BASIC "GET" command can load this file so it can be run. Once the file is loaded into the computer's memory by the "GET" command, the program can be "STORE"d as a tokenized Tech BASIC program. 2. DATA file. A Series-80 DATA file is transferred as a Tech BASIC DATA file, which can be accessed by the Tech BASIC "ASSIGN#" and "READ#" statements. Alternatively, if you "RENAME" a Series-80 DATA file to start with an underscore, or if you invoke UPLOAD with the "-s" option, UPLOAD will transfer all data items, including numeric data, in ASCII form to an HP-UX text file. 3. Graphics file. A Series-80 GRAF file is transferred as a Tech BASIC GRAF file, which can be retrieved by the Tech BASIC "GLOAD" command. In order to transfer an HP-85 graphics file, UPLOAD must be invoked with the "-g" option. 4. LIF file. A LIF (Logical Interchange Format) ASCII file is transferred as an HP-UX text file. This format is used, for example, by Series-200 (Rocky Mountain) BASIC. 3. Preparation for Transfer With UPLOAD 3.1. General It is recommended that Series-80 file names be restricted to upper and lower case alphabet characters, digits 0 through 9, and the underscore character. UPLOAD can transfer the contents of the entire disc without your having to specify the individual file names. You can hide from UPLOAD the files you do not want to transfer by "RENAME"ing the unwanted Series-80 files to start with an asterisk ("*"). 3.2. Series-80 Programs The Series-80 PROG files with tokenized programs CANNOT be transferred with UPLOAD. The Series-80 BASIC programs must be converted into ASCII data files by the AP ROM or EDISC ROM command "SAVE", or by the same command available in the GETSAV binary. The "SAVE"d program file name must start with an underscore character ("_"). The purpose of this convention is to tell UPLOAD that the file being transferred is a "SAVE"d program file - and NOT a regular data file. Note that a "SAVE"d program file and an ordinary data file are both of the Series-80 DATA file type. If the SAVEd program files are not named with an underscore, UPLOAD will transfer those files as Tech BASIC data files. The Tech BASIC "GET" command CANNOT use a Tech BASIC DATA file as a source of a program. 3.3. Series-80 DATA, GRAF, and LIF ASCII Files Nothing needs to be done when transferring an ordinary Series-80 DATA (not a "SAVE"d program file), or GRAF, or LIF ASCII files. LIF ASCII files are transferred to HP-UX text files. The DATA file name must NOT start with the underscore character. If the name of an ordinary DATA file starts with the underscore character, UPLOAD will create an HP-UX text file and copy the contents to the data file as series of ASCII strings, terminated with the line-feed character (ASCII 10). Such files are useful under certain circumstances. For example, WORD/80 PUT files can be transferred to HP-UX text files this way. Keep in mind that HP-UX text files thus created can not be accessed with Tech BASIC mass storage statements such as "ASSIGN#" and "READ#", since the file format is not the same as the Tech BASIC DATA file format. However, HP-UX text files can be read with the Tech BASIC "ASSIGN" and "ENTER" statements. 3.4. Hardware Requirements and Set-Up UPLOAD will work with the basic IPC without an additional disc drive, but 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 run the "scan_discs" program (found in the "/rom" directory) to make the appropriate entries in the "/dev" directory. 4. UPLOAD, Step-by-Step UPLOAD is softkey-driven and its operation should be self-explantory. Here is a brief description of the operating procedure. 4.1. Basic IPC system 1. Insert the disc containing UPLOAD into the internal drive and invoke UPLOAD by pressing the [Start] softkey when "upload" is in inverse video, or simply by typing "upload", and pressing the RETURN key. The program name can be followed by a list of options. 2. Remove the disc from the internal drive and insert the Series-80 disc you want to transfer. 3. UPLOAD will prompt you to input the name of the device which contains the Series-80 disc. Type "internal". 4. UPLOAD will prompt you to input the destination directory/device name. Type the name of a directory in RAMdisc, say "/tmp". 5. If you want to transfer the ENTIRE Series-80 disc, then press softkey [Disc]; otherwise press [Files] to transfer individual files. If you choose file-by-file transfer, you can go through the list of files by pressing softkeys until the desired file name appears in the window. You press the [Pick] softkey to choose the file to transfer. If file-by-file transfer is chosen, and a regular Series-80 DATA file is to be transferred, the program will ask you if the resulting Tech BASIC data file should have a [Larger] logical record size or the [Same] size as the source (Series-80) data file. You make this choice by pressing one of the two softkeys. WARNING: if the destination directory already contains a file with the same name as the file to be transferred, the existing file will be overwritten. The program will NOT warn you that an existing IPC file of the same name is being overwritten by the transferred file. 6. If the destination directory (in this case in RAMdisc) becomes full, and there are more Series-80 files to be transferred, the program will ask you to specify another destination directory name. At this point, you must remove the Series-80 disc, insert another IPC HP-UX disc into the internal drive, copy the contents of the RAMdisc to this disc, and delete the files from the RAMdisc. You can now replace the HP-UX disc with the original Series-80 disc. You can give the name of the original destination directory, and continue with the operation. 4.2. IPC with External Drives If there is at least one external drive, Series-80 files can be transferred directly to a disc, without intermediate transfer to the RAMdisc. It is strongly recommended that you unmount the discs in the external drives with the "unmount_disc" program (on the system utility disc) before you insert the destination HP-UX and source Series-80 discs, and unmount the destination disc after uploading. 1. If the disc containing UPLOAD is in the internal drive, then UPLOAD can be invoked by either typing UPLOAD's pathname, or pressing the softkey [Start] when the cursor block is on "upload" in its resident directory. However, if UPLOAD has been copied to the RAMdisc, or to the destination disc, or if the UPLOAD disc is in a third drive (other than drives holding the HP-UX destination disc and the Series-80 source disc), UPLOAD can be invoked with a list of parameters and options. In this case, UPLOAD can be invoked by typing: upload [option list] [src device name] [dest directory/device name] Examples: command line comment ------------ ------- upload program asks for parameters upload -n ditto upload -nf ditto upload -n -f same as above upload D000 program asks for the remaining param. upload -s D000 ditto upload D000 /mydisc entire source disc uploaded upload -n D000 /mydisc ditto where: the option list must be "-" (a minus sign), followed immediately (i.e., no blanks must separate '-' and what follows) by a list of available options, or a blank followed by another option list. The available options are discussed later. [source device name] is the name of the disc drive in which the Series-80 disc resides. [destination directry/device name] is the destination HP-UX directory name, or the device name where a destination HP-UX disc resides. If the device name is given, UPLOAD will place transferred files to the TOP LEVEL directory of that disc. If you want to create files in a subdirectory in a disc, you MUST specify the full subdirectory pathname. If UPLOAD is invoked with a complete list of parameters, in order for UPLOAD to proceed normally, BOTH the source device and the destination directory MUST be immediately available. If not, UPLOAD will go into the interactive mode and ask you to correct the situation or type the correct device/directory names. Once options are set at invocation time, they remain effective throughout the session, and cannot be changed. 2. When the destination disc becomes full, and there are more files to be transferred, UPLOAD will ask you to type the name of another destination device/directory name; you can either specify another disc drive that contains an HP-UX disc, or replace the full disc with an empty HP-UX disc. This step can be repeated until all Series-80 files have been transferred to HP-UX discs. 5. Softkeys and their functions Following are the softkeys in the main menue. [Catalog] Displays the statistics (name, type and size) of DATA, GRAF and LIF file types on the Series-80 source disc. [First] Sets the current file to the first directory entry (not in alphabetical order but first in the source disc's list of file names). [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 one in the source disc's list of file names. [Pick] Chooses the current file as the file to be uploaded. [Exit] Terminates the session. 6. Options f: File by file transfer. If this option is set, UPLOAD will ask for the name of each file to be transferred. If UPLOAD is invoked with a complete list of parameters (i.e., source device and destination device/directory), in the absence of this option the entire contents of the source disc will be transferred automatically. n: Suppress expansion of the logical record in the Tech BASIC DATA file. In the absence of this option, the program will create Tech BASIC DATA files with 12.5% larger logical record size. s: ALL Series-80 DATA files, regardless of the starting character in their names, will be transferred to IPC as HP-UX text files. This option is effective in BOTH file-by-file and disc transfer. The use of this option eliminates the need for renaming "SAVE"d files. This option can be set ONLY AT THE TIME OF PROGRAM INVOCATION. After the program starts, you are not given an opportunity to change the setting. g: This option enables the transfer of HP-85 GSTORED files to Tech BASIC GRAF files. e: This option disables the conversion of undisplayable characters to escape sequences starting with "~". This option is available only at the time of program invocation. This option may be used if you want to map normally undisplayable characters to your own character set. 1: These are language options. The user of an HP-86B with a local 2: language character ROM can map control characters (0 to 31) to IPC 3: Roman 8 and special graphics characters. This option can only be enabled at invocation time IN CONJUNCTION WITH the 'e' option described above (the order of options on the command line does not matter), and applies to all HP-UX text files created. In order to see special graphics characters, the user must set the window to display mode. The options 1,2 and 3 are respectively French, Spanish, and English character sets. If more than 1 language option is given in the command line, the LAST option specified will be enabled. Since the IPC Roman 8 character set does not have many of the characters of the English character ROM, missing characters are mapped to the corresponding FRENCH character set. 7. APPENDIX 7.1. Data Types and Their Storage Requirements In the Tech BASIC data file, character strings occupy the same amount of space as in the Series-80 data file. However, real numbers occupy more (9 bytes) and integers less (5 bytes) space than in Series-80 (where all numbers occupy 8 bytes). Because of these differences, an equivalent data file in Tech BASIC may take up a different amount of space from the Series-80 counterpart. UPLOAD, by default, creates a Tech BASIC DATA file with a logical record size approximately 12.5% greater than the Series-80 source. This is so that, even in the worst case, the random accessibility of the transferred file will be maintained at the expense of extra space. However, you can suppress this default setting and force the program to create a Tech BASIC data file with the same logical record size as the source file. This can be accomplished either by invoking UPLOAD with the "-n" option, or, in case of file-by-file transfer, choosing the [Same] record size softkey. Under the following circumstances you can safely transfer a Series-80 DATA file to a Tech BASIC DATA file with the same logical record size: 1. The source file contains string data only. 2. The source file was always accessed sequentially and the transferred file will be used exclusively sequentially. 3. The source file contains numeric data and was accessed randomly but each logical record has ample unused space. 7.2. Limitations UPLOAD holds in memory up to 100 Series-80 directory entries (the first 100 in a Series-80 disc directory). If a disc contains more than 100 files, UPLOAD warns that the directory contains more than 100 potential transfer candidates. If you need to transfer more files after transferring the first 100 files, you must "hide" from UPLOAD some of those files already transferred. You can do this by RENAMEing the files to start with an asterisk ("*"). As explained earlier, UPLOAD ignores Series-80 files whose names start with an asterisk. 7.3. Error Handling There are two types of errors: recoverable and unrecoverable. UPLOAD can continue after a recoverable error, but not after an unrecoverable error. Recoverable errors include: 1. Encountering corrupt Series-80 files. 2. Nonstandard data file format, or other conditions that make it impossible for UPLOAD to interpret data items. 3. The destination disc becomes full. UPLOAD terminates if it can not read from or write to mass storage, or if it cannot obtain temporary memory. 7.4. Reading Program Files Transferred to Tech BASIC DATA files If you do not follow the convention to prepend a "SAVE"d program file with the underscore character on a Series-80 disc, the file is transferred to IPC as a Tech BASIC data file, rather than as an HP-UX text file. This is not a good way of transferring a "SAVE"d program file, since the Tech BASIC "GET" command cannot retrieve the program from a Tech BASIC DATA file. If this is done, the contents of the Tech BASIC DATA file still can be examined. In order to do so, you simply open the file with the BASIC "ASSIGN#" statement, and read each line of program serially with "READ#" into a string variable. Since a line of a "SAVE"d Series-80 program is terminated with a carriage return, the Tech BASIC "DISP" command will not display the contents of the string variable properly on the IPC text screen - because the carriage return moves the cursor to move to the beginning of the line just displayed. The string can be "DISP"layed properly with: DISP a$[1,len(a$)-1] - that is, omitting the last character from the string. 7.5. Differences in Graphics Screen Size Between the IPC and the HP85/86/87 HP86/87 BASIC has two graphics modes: normal GRAPH, and GRAPHALL - with the screen resolutions of 400 x 240 dots and 544 x 240 dots, respectively. The HP-85 has graphics resolution of 256 x 192 pixels. IPC Tech BASIC has one graphics mode, whose resolution is 512 by 255 dots. These differences are handled by UPLOAD as follows: 1. An image stored in an HP86/87 normal GRAF file, or in an HP85 "GSTORE"d file, occupies the left upper portion of the Tech BASIC graphics window. The extra space is filled with "0" (off) bits. 2. The rightmost 32 columns of pixels of the HP86/97 GRAPHALL graphics file are truncated, and 15 rows of pixels (all "0" bits) are added at the bottom, on the Tech BASIC graphics window. 7.6. 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 decimal digits. In binary representation, the decimal fractions that can be represented precisely in BCD may NOT be represented precisely, since a decimal fraction is approximated by a binary fraction. This difference raises two problems when data files are transferred. The first is that of numeric overflow or underflow. This problem is handled by UPLOAD by substituting ALL Series-80 overflow or underflow values with the maximum or minimum values representable in Tech BASIC. These values are as follows: infinity: 2.2250738585072e+308 epsilon : 1.79769313486232e-308 The second problem is that of precision. When a Series-80 BCD REAL number is transferred to a Tech BASIC data file and read back into a REAL variable in Tech BASIC, its value may not be exactly the same as the original value. One must be careful in comparing values thus retrieved for equality in Tech BASIC. It should be mentioned here that there is no problem in transferring integer values to Tech BASIC, since Tech BASIC has a greater range of integer values (-2^31 to 2^31-1) than Series-80 BASIC. 7.7. Series-80 BASIC Programs Containing Binary Programs If a Series-80 program contains binary program keywords, it still may be transferred to an IPC HP-UX text file, but the parser comments out lines that contain the keywords. The parser may parse some lines containing binary keywords WITHOUT flagging syntax errors. This could happen if the parser parses unrecognizable keywords as variables, or if the binary keywords are the same as keywords available in Tech BASIC. A discussion of how to modify Series-80 programs containing binary keywords is beyond the scope of this document. Some suggestions are made here without going into details. 1. Replace binary keywords with functionally equivalent keywords - if such are available. 2. Replace binary keywords with user-defined functions or subprograms. 3. Replace binary keywords with Tech BASIC "C" binary programs. 7.8. Line Expansion with Unprintable Characters On Series-80, all ASCII codes 0 through 255 can be displayed on the screen. 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. Some of the non-displayable characters, when sent to an IPC window have special (sometimes undesirable) effects on the behavior of the window. For this reason, when a "SAVE"d program is transferred to a IPC HP-UX text file, any non-displayable characters are escaped with a "~", followed by 3 decimal digits. The "~" character itself is represented as "~~". A line of Series-80 BASIC containing non-printable characters may look like this after transfer to IPC: 20 A$ = "THIS ~002~034~023 line expands ~132~150~~ as you can see" The obvious side effect of this is that the original line gets longer when transferred to an HP-UX text file. In the worst case, a line expands by a factor of 4, and the Tech BASIC GET command may complain that some input lines are too long. If this happens, you must edit the file and split each long line into two or more lines. Note that once the parser parses a line containing non-printing character sequences, each 4-character sequence is stored as 1-byte ASCII character in the tokenized program.