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. _S_u_m_m_a_r_y Upload is a softkey-driven program that lets you transfer Series 80 Basic Program, Data and Graphics files to IPC HP- UX Technical BASIC (Tech BASIC for short) easily. If you follow the simple steps described in this document, tranfer of files between the two machines should be quick and pain- less. No special preparation is necessary for transfer EXCEPT that Series 80 programs MUST be SAVE'd in files whose names start with an UNDERSCORE character '_' before they can be ported to Tech BASIC. _2. _T_y_p_e_s _o_f _S_e_r_i_e_s _8_0 _f_i_l_e_s Series 80 BASIC files types that can be tranferred to Tech BASIC and resulting files types are as follows: 1. Program file. A BASIC program must be SAVE'd as ascii strings in a DATA file whose name start with an underscore character. This file is transferred as an HP-UX text file which can be edited by HP-UX editors such as vi or examined by the PAM View command. The Tech BASIC GET command can use this file as a source for a Basic program. 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 data file to start with an underscore character or if you invoke UPLOAD with the -s option, UPLOAD will transfer all data items including numeric data as ascii strings to an HP-UX text file. 3. Graphics file. A Series 80 GRAF file is transferred as a October 29, 1985 - 2 - 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. An 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. The data from the resulting file can be retrieved by the Tech BASIC GET command, if the source file was ascii form of a Basic program. Otherwise ASSIGN and ENTER statements can be used to retrieve the data. _3. _P_r_e_p_a_r_a_t_i_o_n _f_o_r _t_r_a_n_s_f_e_r _w_i_t_h _U_P_L_O_A_D _3._1. _G_e_n_e_r_a_l 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. When creating an HP-UX file, UPLOAD will substitute special characters with the underscore character and append a number to the file name. UPLOAD can transfer the contents of the entire disc without your having to specify the individual file names. You can mask and hide from the program the files you do not want to transfer to IPC by RENAME'ing the unwanted Series 80 files to start with an asterisk '*'. _3._2. _S_e_r_i_e_s _8_0 _p_r_o_g_r_a_m_s The Series 80 PROG files with tokenized programs can NOT be DIRECTLY transferred with this program. The Series 80 BASIC programs must be converted into ascii data files by the APROM or EDisc ROM command SAVE or by the same command available in the GETSAV binary. Note that the SAVE command stores Series 80 strings to DATA, not LIF files. 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 SAVE'd program files are not named according to this convention, UPLOAD will transfer those files as Tech BASIC data files. The Tech BASIC GET command can NOT use a Tech BASIC DATA file as a source of a program. This naming con- vention can be circumvented by the use of a program option which will be described later. _3._3. _S_e_r_i_e_s _8_0 _D_A_T_A, _G_R_A_F _a_n_d _L_I_F _a_s_c_i_i _f_i_l_e_s Nothing need 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. October 29, 1985 - 3 - The DATA file name must not start with the underscore char- acter. If the name of an ordinary DATA file starts with the underscore character, UPLOAD will create an HP-UX text file and copies the contents to the data file as series of ascii strings terminated with the LF 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 and can later be edited with an HP-UX text editor or can be read by the PAM View command. 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 that of the Tech Basic data file. However, HP-UX text files can be read with the Tech BASIC IO Rom ASSIGN and ENTER statements. _3._4. _H_a_r_d_w_a_r_e _r_e_q_u_i_r_e_m_e_n_t_s _a_n_d _s_e_t-_u_p UPLOAD 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 run the scan_discs program found in the /rom directory. This guarantees the Operating System to find the external drives and make appropriate entries in the /dev directory. _4. _U_p_l_o_a_d _s_t_e_p _b_y _s_t_e_p The program is softkey-driven and its operation should be self-explantory. Here is a brief description of the operat- ing procedure. _4._1. _B_a_s_i_c _I_P_C _s_y_s_t_e_m 1. Insert the program disc to the internal drive and invoke the program by pressing the softkey [Start] when the program name is in inverse video or simply typing the program name and pressing the Return key. The program name can be fol- lowed by a list of options. 2. Remove the program disc from the internal drive and insert the Series 80 disc you want to tranfer. 3. The program will prompt you to input the name of the dev- ice which contains the Series 80 disc. Type internal. 4. The program will prompt you to input the destination directory/device name. Type the name of a directory in the root directory which is in the ramdisc. The /tmp directory should be in the root directory. If there is no directory to which you can write to, go to PAM and execute a command "makefolder dir_name", where dir_name might be /hp86. October 29, 1985 - 4 - 5. If you want to transfer the entire Series 80 disc then press softkey [Disc], otherwise press [Files] to transfer the individual files you choose. 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 tranfer. 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 exising file will be overwritten. The program will NOT warn you that an exising 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 and inserts another IPC HP-UX disc into the internal drive and copies the contents of the ramdisc to this disc and deletes the files from the ramdisc. Now the ramdisc has free space available. You can now replace the HP-UX disc with the original Series 80 disc. You can give the name of the destination directory, say /tmp, and con- tinue with the operation. This step can be repeated until all Series 80 files have been transferred to HP-UX discs. _4._2. _I_P_C _w_i_t_h _e_x_t_e_r_n_a_l _d_r_i_v_e_s If there is at least one external drive, Series 80 files can be transferred directory to a disc without doing intermedi- ate 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. There is no need to mount the destination disc or the source disc since the program mounts the destination disc and the source disc is not mountable. 1. If the program disc is in the internal drive, then pro- gram can be invoked by either typing the path name of the program file or pressing the softkey [Start] when the cursor block is on the program file name. However, if the program has been copied to the ramdisc or to the destination disc, or if the program disc is in a third drive other than drives holding the HP-UX destination disc and the Series 80 source disc, the program can be invoked with a list of parameters and options. In this latter case the program can be invoked October 29, 1985 - 5 - by typing: upload [option list] [source device name [destination 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 fol- lows) by concatenation of available options or a blank fol- lowed by another option list. The available options are listed in the following section. [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 the program will place transferred files to the TOP LEVEL directory of that disc. If you desire to create files in a subdirectory in a disc, you MUST specify a directory name. If the program is invoked with a complete list of parame- ters, in order for the program to proceed normally BOTH the source device and the destination directory MUST be immedi- ately available. If not, the program will go into the interactive mode and asks you to correct the situation and/or type the correct device/directory names. Once options are set at the program invocation time, they remain effective throughout the session. There is NO manual over- ride of options in effect. 2. When the destination disc becomes full and there are more files to be transferred, the program will ask you to type the name of another destination device/ directory name. Here you can either specify another disc drive on line that contains an HP-UX disc or replace the full disc with an empty HP-UX disc in the same device. This step can be repeated until all Series 80 files have been transferred to HP-UX discs. The transfer of a hard disc may require a number of floppy discs. October 29, 1985 - 6 - _5. _S_o_f_t_k_e_y_s _a_n_d _t_h_e_i_r _f_u_n_c_t_i_o_n_s 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 program's list of file names). [Next] Sets the current file to the one next to 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 program's list of file names. [Pick] Chooses the current file as the file to be uploaded. [Exit] Terminates the session with the upload program. _6. _O_p_t_i_o_n_s f: file by file transfer. If this option is set the pro- gram will ask for the name of each file to be transferred. If the program 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: suppression of 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 INVOCA- TION. 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. October 29, 1985 - 7 - e: This option disables the conversion of undisplayable characters to escape sequence starting with '~'. This option is available only at the time of program invoca- tion. Thus it can not be set and unset for each file being transferred. This option is used only for HP-UX text file creation and applied for all appropriate files. This option may be used if you want to map nor- mally undisplayable characters to your own character set. 1,2 These are language options. The user of an HP-86B with a local language character ROM can map control charac- ters (0 ~ 31) to IPC Roman 8 and special graphics char- acters. 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 applied to all HP-UX text files created. In order to see special graphics characters the user must set the terminal 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. _A_P_P_E_N_D_I_X _7._1. _D_a_t_a _t_y_p_e_s _a_n_d _t_h_e_i_r _s_t_o_r_a_g_e _r_e_q_u_i_r_e_m_e_n_t_s In the Tech BASIC data file, character strings occupy the same amount of space as in the Series 80 data file. How- ever, real numbers occupy more (9 bytes) and integers less (5 bytes) space than in Series 80 (all numbers occupy 8 bytes). Because of these differences an equivalent data file in Tech BASIC may take up more or less, or identical amount of space as 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 accessi- bility 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 identical 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 without affecting data accessibility: October 29, 1985 - 8 - 1. The source file contains string data only. 2. The source file was always accessed sequentially and the transferred file will be used exclusively sequen- tially. 3. The source file contains numeric data and was accessed randomly but each logical record has ample unused space. _7._2. _L_i_m_i_t_a_t_i_o_n_s This program holds in memory up to 100 Series 80 directory entries (FIRST 100 in a Series 80 disc directory). If a disc contains more than 100 files to be TRANSFERRED, the program issues warning that the directory contains more than 100 POTENTIAL transfer candidates. If you need to tranfer more files after transferring the first batch of 100 files or part thereof, you must "hide" from the program some or all of those files already transferred. You can do this by RENAME'ing the files to start with the asterisk '*'. As explained earlier the program ignores Series 80 files whose names start with an asterisk. _7._3. _E_r_r_o_r _h_a_n_d_l_i_n_g There are two types of errors: recoverable and unrecover- able. The program execution can continue after a recoverable error but not after an unrecoverable error. Recoverable errors include: encountering corrupt Series 80 files, non- standard data file format or other conditions that make it impossible for the program to interpret data items; the des- tination disc becoming full. The destination file may con- tain valid data up to the time of the occurrence of a recov- erable error. The program terminates if it can not read from or write to a mass storage medium, or it can not get enough memory while trying to dynamically obtain temporary memory. _7._4. _R_e_a_d_i_n_g _p_r_o_g_r_a_m _f_i_l_e_s _t_r_a_n_s_f_e_r_r_e_d _t_o _T_e_c_h _D_A_T_A _f_i_l_e_s If you do not follow the convention to prepend a SAVE'd pro- gram 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 desirable way of transferring a SAVE'd program file, since the Tech BASIC GET command can not retrieve the program from a Tech BASIC DATA file. If this is done, still the contents of the Tech BASIC DATA file can be examined. In order to do so you simply opens 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 chr$(13), the Tech BASIC DISP command will October 29, 1985 - 9 - not display the contents of the string variable properly on the IPC text screen (because chr$(13) = CR causes the cursor to move to the beginning of the line just displayed). The string can be DISPlayed properly by doing: DISP a$[1,len(a$)-1], i.e., omitting the last character from the string. _7._5. _D_i_f_f_e_r_e_n_c_e_s _i_n _g_r_a_p_h_i_c_s _s_c_r_e_e_n _s_i_z_e _b_e_t_w_e_e_n _I_P_C _a_n_d _H_P_8_5/_8_6/_8_7 HP86/87 BASIC has two graphics modes, normal GRAPH and GRA- PHALL with the screen resolution of 400 x 240 dots and 544 x 240 dots, respectively. IPC Tech BASIC has one graphics mode whose screen size is 512 by 255 dots. The HP85 has the graphics resolution of 256 x 192 pixels. These differences in the graphics screen are handled by UPLOAD as follows: 1. An image stored in an HP86/87 normal GRAF file or in HP85 GSTORE'd file after transfer occupies left upper portion of the Tech BASIC graphics screen. The extra space on the graphics screen is filled with 0 (off) bits. 2. 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 when a corresponding Tech BASIC graphics file is created. This means some of the picture area is lost when an HP86/87 GRAPHALL file is transferred to Tech BASIC. _7._6. _D_i_f_f_e_r_e_n_c_e_s _i_n _d_a_t_a _p_r_e_c_i_s_i_o_n _a_n_d _v_a_l_u_e _r_a_n_g_e 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. In Tech BASIC 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, instead they may be approximated with a long series of binary fractional digits. These differences raise two problems when data files are transferred. The first is that of numeric overflow or underflow. This problem is handled by the upload utility 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 October 29, 1985 - 10 - Tech BASIC. It should be mentioned here that there is no problem in transferring integer values to Tech BASIC. Tech BASIC has a greater range of integer values, i.e., -2^31 ~ 2^31-1, than Series 80 BASIC. _7._7. _S_e_r_i_e_s _8_0 _B_A_S_I_C _p_r_o_g_r_a_m_s _c_o_n_t_a_i_n_i_n_g _b_i_n_a_r_y _p_r_o_g_r_a_m_s Any Series 80 program that contain binary program keywords may be transferred to an IPC HP-UX text file. Of course you must do LOADBIN to SAVE such a program to a Series 80 file before running UPLOAD. You can use the Tech BASIC GET com- mand on the program that contains binary keywords to obtain a runnable Tech BASIC version of the program. However, chances are that you will have lines containing binary key- words displayed with syntax errors. This is because the Tech BASIC parser does not recognize binary keywords and flags syntax errors. The parser comments out the lines that contain syntax errors. The parser may parse some lines con- taining binary keywords without flagging syntax errors. This could happen if the parser parses unrecognizable key- words as variables or the binary keywords are the same as keywords available as part of ROM keywords contained 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 ROM keywords if such are available. [2] Replace binary keywords with user-defined functions or subprograms. [3] Replace binary keywords with Tech BASIC binary programs (e.g., compiled C functions or subroutines). If a program requires extensive editing, it is more con- venient to edit the program using an HP-UX editor such as vi than to use the Tech BASIC line editor. An HP-UX text edi- tor can only be used on HP-UX text files and NOT on token- ized BASIC program files. _7._8. _L_i_n_e _e_x_p_a_n_s_i_o_n _w_i_t_h _u_n_p_r_i_n_t_a_b_l_e _c_h_a_r_a_c_t_e_r_s On the Series 80 machine all ascii code 0 through 255 can be displayed on the screen. The default character set on the IPC is Roman extension with ascii code in the ranges of 0-31 and 128-159 decimal being non-displayable characters. Some of the non-displayable characters when sent to (i.e., displayed on) the IPC screen have special (sometimes undesirable) effects on the behavior of the IPC screen which October 29, 1985 - 11 - is emulating a terminal. For this reason when a SAVE'd pro- gram 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 "~~". This situation may occur, for example, in-line literal strings containing high-lighted characters or bit patterns for a graphics shape. 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, since a single character in the original Series 80 program is expanded to 4 characters. The Tech BASIC GET command may complain that some input lines are too long. If this happens you must edit the file and split a 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. October 29, 1985