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. _S_u_m_m_a_r_y Download is a softkey-driven program that lets you transfer IPC HP-UX Technical BASIC (Tech BASIC for short) files to Series 80 computers quickly and painlessly. 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 directory. No special preparation is necessary prior to transfer. 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. _T_y_p_e_s _o_f _H_P-_U_X _T_e_c_h_n_i_c_a_l _B_A_S_I_C _f_i_l_e_s 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 files 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 of HP- UX editors or redirection of output. When a file of this type is downloaded to Series 80, the resulting file is a DATA file containing string data with 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 pro- gram, and/or by the mass storage commands, e.g., 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 facilitate transfer of IPC Tech BASIC programs to Series 200 BASIC. October 29, 1985 - 2 - 2. HP-UX Tech BASIC DATA files. This type of file can be created by the Tech BASIC mass storage CREATE command and written by the PRINT# command. The result of downloading of this type of file is a Series 80 DATA file with the identi- cal logical record size as the source file. In the default mode Tech BASIC numeric data items are transferred as Series 80 BCD real numbers and strings as strings. The contents of the resulting file can be accessed by the mass storage com- mands, ASSIGN# and READ#. If you specify the -a option at the program invocation time, however, all Tech BASIC numeric data items are transferred as ascii digit strings. There- fore 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 GRAPH ALL mode. The Tech BASIC graphics screen is 255 by 512 and the Series 80 GRAPH ALL screen is 240 by 544. The downloaded graphics file's rightmost 32 pixel columns are truncated and bottom 15 pixel rows are filled with 0 bits. _3. _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 This utility will work with the basic IPC without an addi- tional 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. This guarantees the Operating System to find the external drives and make appropriate entries in the /dev directory. _4. _D_o_w_n_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-explanatory. Here is the brief description of the operating procedure. _4._1. _B_a_s_i_c _I_P_C _s_y_s_t_e_m (_r_a_m_d_i_s_c _t_o _i_n_t_e_r_n_a_l _d_i_s_c _d_r_i_v_e) 1. Copy HP-UX Tech BASIC files you want to download to a directory in ramdisc, say /tmp. 2. 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 starting with a dash (see the section on program options). 3. Remove the program disc from the internal drive and October 29, 1985 - 3 - 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. 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 source HP-UX directory/device name. Type the name of the directory in the ramdisc to which you have copied files in step 1. 5. 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 in the window. You press the [Pick] softkey to choose the file to tranfer. If the desti- nation disc becomes full the program will prompt you to replace the disc with another. _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, files can be transferred directly to a disc without doing the intermedi- ate transfer to the ramdisc. There are different way 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. You do not have to mount the source or destination discs since the program mounts the source disc and the destination (Series 80) disc is not unmountable. If the program disc is in the internal drive, then program 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 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, the program can be invoked with a list of parameters and options. In this latter case the program can be invoked by typing: download [opt. list] [destinat'n dev.name [source dir./dev. name]] October 29, 1985 - 4 - 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 The option list must be '-' (a minus sign) followed immedi- ately (i.e., no blanks must separate '-' and what follows) by concatenation of available options or a blank followed by another option list (see the section on Options). [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 driver where a source HP-UX disc resides. If the drive name is given the program will download files that are in the TOP LEVEL directory of that disc. If you desire to transfer files in a subdirectory on 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 destination device and the source 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 once the program starts. The remaining steps are the same as in the single drive con- figuration. _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 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 (not in alphabetical order but first in the program's list of file names). October 29, 1985 - 5 - [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 down- loaded. This key will not appear if the current file has already been downloaded. [Exit] Terminates the session with the download 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., 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 sets 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 exam- ple: "download -t12" tells the program to substitute each occurrence of a TAB character with 12 blanks. a: All numeric data in HP-UX Tech BASIC DATA files are downloaded as ascii strings and NOT as Series 80 BCD numeric data to 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 to keep file statistics on Tech BASIC Program and Subprogram files so that [Catalog] can display them, even though these files can not be down- loaded. _7. _N_O_T_E When the download program creates Series 80 files on a Series 80 disc, it scan 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. October 29, 1985 - 6 - When the program 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 con- taining 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. HP-UX editors such as vi do not replace a TAB charactor with a number of blanks. On the CRT screen of a Series 80 com- puter the TAB character is a single displayable character. The program 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 on the command line as a program option. If the source directory does not contain HP-UX text file or Tech BASIC files, the program will declare the directory empty and quit. The program will also ignore file names starting with a period and will not download these files. _8. _A_P_P_E_N_D_I_X _8._1. _L_i_m_i_t_a_t_i_o_n_s This program holds in memory up to 100 HP-UX directory entries (FIRST 100 in a directory). If a directory 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 period '.'. _8._2. _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 October 29, 1985 - 7 - errors include: encountering corrupt HP-UX 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. _8._3. _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. The first 12 significant digits of Tech BASIC numeric data are transferred to Series 80. All three numeric types, i.e., REAL, INTEGER and SHORT, of Tech BASIC are converted into the Series 80 REAL type. _8._4. _H_P-_U_X _T_e_c_h _B_A_S_I_C _p_r_o_g_r_a_m_s _c_o_n_t_a_i_n_i_n_g _e_s_c_a_p_e_d _c_h_a_r_a_c_- _t_e_r_s The default character set on the Pisces is Roman extension with ascii code 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. October 29, 1985