This chapter describes the utilities provided with HP BASIC/UX.
BASIC/UX utilities are found in the following directories:
/opt/rmb/utils
/opt/rmb/rmb8_0/utils
Some utilities are complete BASIC programs, such as LIF_UTIL. To use these programs, LOAD them into BASIC/UX and execute:
RUN
Other utilities are CSUBs (Compiled SUBprograms), and must be called from within a BASIC program. For information on the use of CSUBs, see the book Developing CSUBs for HP BASIC/UX or the keyword descriptions for CALL and LOADSUB in the HP BASIC Language Reference.
Utilities are for experienced BASIC programmers. You should be able to:
It is helpful to have performed the tasks described in Using HP BASIC/UX, and the HP BASIC Programming Guide.
The table in this section provides a brief description of the utilities. A complete description of each utility can be found in the "Utilities Reference" section next in this chapter.
Utility | Short Description |
---|---|
BITMAP_S | Replaces BASIC/WS GDUMP_C utility: dump a raster image to a file in proper format for Starbase (so you can use Starbase utility pcltrans). |
BPLOT | Store and load rectangular blocks of raster data from graphics frame buffers. |
GDUMP_R | CSUB utility to dump graphics raster images to a printer and rotate them 90 degrees. |
LEX_AID | Create your own lexical order tables. |
LIF_UTIL | A combination of utilities to:
|
PHYREC | A CSUB to perform bit-by-bit copies of an integer array in memory to a physical record on a LIF mass storage media (and vice versa). |
This section contains detailed descriptions of each of the BASIC/UX utilities.
BITMAP_S (found in the /opt/rmb/rmb8_0/utils directory) is a CSUB utility that dumps a screen to a file in the Starbase bitmap format (see the Starbase Reference). Use this utility to print dumps of the screen.
There is no correlation between:
Syntax for BITMAP_S:
Bitmap_store( |from_ds|,"<var |to_file|") </CODE>
Where: | Represents: |
from_ds | The device (screen) whose frame buffer you want to dump. You must supply a value (for example in X Windows: the window number). It does not have to be the current PLOTTER IS device. |
to_file | is the name of a file or a pathname where the bitmap data is to be stored. It may also be a string beginning with a pipe, for example: "| pcltrans -C | lp -oraw" |
To load the CSUB and run it, follow these steps:
COPY "/opt/rmb/rmb8_0/utils/BITMAP_S" TO "BITMAP_S"
COPY "/opt/rmb/rmb8_0/utils/bmap_store.sl" TO "bmap_store.sl"
400 LOADSUB ALL FROM "BITMAP_S"
420 Bitmap_store(600,"save.bits")
After dumping to a file, use the HP-UX pcltrans command to dump to a printer from a BASIC/UX process (save.bits is the example file name):
EXECUTE "pcltrans -C save.bits | lp -oraw"
Refer to the HP-UX man page for pcltrans for options to control things such as background color and image size.
See the PCL Formatter section of Starbase Device Drivers Library for a complete list of supported printers (all that support pcltrans, for example, the HP 3630A PaintJet).
Outside of a program, load the CSUB with LOADSUB, and call it by executing:
CALL Bitmap_store(CRT,"/tmp/mypicture")
where /tmp/mypicture stores the bitmap data.
To delete the CSUB, execute:
DELSUB Bitmap_store
For tips on how to use the pcltrans command, see the Starbase Reference manual or the Starbase Device Drivers Library manual.
BPLOT is a CSUB utility to store (Bstore) and load (Bload) rectangular "blocks" of raster data (using numeric arrays; not supported on terminals). Bstore and Bload are similar to GSTORE and GLOAD, except:
COPY "/opt/rmb/rmb8_0/utils/BPLOT" TO "BPLOT"
COPY "/opt/rmb/rmb8_0/utils/bload_bstore.sl" TO "bload_bstore.sl"
400 LOADSUB ALL FROM "BPLOT"
410 !
420 Bstore(Int_array(*),X_pixels,Y_pixels)
430 !
Bstore stores a rectangular area of the frame buffer in an INTEGER array. For example:
Bstore(Int_array(*),X_pixels,Y_pixels,Rplcmt_rule,X_start,Y_start)
where:
X_pixels | is an INTEGER for width of the rectangular raster area (in pixels). |
Y_pixels | is an INTEGER for height of the rectangular raster area (in pixels). |
Rplcmt_rule | is an optional INTEGER parameter that specifies how the pixels are placed into the array. Default value is 3 (source). |
X_start | is an optional REAL parameter that specifies the X coordinate of the upper left corner of the area to be stored: in current graphics unit of measure (not pixels). Default is the current graphics pen position. |
Y_start | is an optional REAL parameter that specifies the Y coordinate of the upper left corner of the area to be stored: in current graphics unit of measure (not pixels). Default is the current graphics pen position. |
X_pixels and Y_pixels values are placed in the INTEGER array Int_array as one byte per pixel for all frame buffers.
If part of the area is outside the current clip limits, then only the portion of the frame buffer within these limits is stored in the array--the remainder of the array remains unchanged.
The optional parameter Rplcmt_rule specifies the replacement rule to use in combining (these rules correspond to the rules provided by CRT CONTROL register 14 for bit-mapped displays):
The following table shows the rule values you can use.
Parameter\Value | Effect on\Destination Bits |
---|---|
0 | All bits set to 0 |
1 | Source AND Destination |
2 | Source AND NOT Destination |
3 | Source (Default) |
4 | NOT Source AND Destination |
5 | Destination |
6 | Source EXOR Destination |
7 | Source OR Destination |
8 | Source NOR Destination |
9 | Source EXNOR Destination |
10 | NOT Destination |
11 | Source OR NOT Destination |
12 | NOT Source |
13 | NOT Source OR Destination |
14 | Source NAND Destination |
15 | All bits set to 1 |
If you want the source bits to be placed into the destination without modification, then specify a value of 3 for the replacement rule parameter.
Subroutine Bload loads a rectangular area of the frame buffer from an INTEGER array. For example: Bload(Int_array(*),X_pixels,Y_pixels,Rplcmt_rule,X_start,Y_start)
The parameters are the same as Bstore, except that the statement loads a rectangular area on the frame buffer with the current contents of the INTEGER array Int_array.
The array variables for Bstore (X_pixels, Y_pixels) must be of sufficient size to store the specified pixels, or an error is reported (ERROR 16 Improper or inconsistent dimensions).
This CSUB utility dumps graphics raster images to a printer. It provides the same function as the DUMP GRAPHICS statement, except that it "rotates" the image 90 degrees before sending it to the printer.
COPY "/opt/rmb/rmb8_0/utils/GDUMP_R" TO "GDUMP_R"
COPY "/opt/rmb/rmb8_0/utils/dg_rotate.sl" TO "dg_rotate.sl"
400 LOADSUB ALL FROM "GDUMP_R" ! Load the CSUB into memory.
410 !
420 Gdump_rotate(CRT,701) ! Dump raster (select code 1) to
430 ! HP-IB printer (select code 7,
440 ! address 1).
If you specify 0 as the printer select code, the current DUMP DEVICE IS device is used. This allows you to dump to a pipe or file. For example, dump the CRT to the lp spooler:
DUMP DEVICE IS "|lp -oraw"
...
...
Gdump_rotate(CRT,0)
To delete the CSUB, execute:
DELSUB "Gdump_rotate"
The LEX_AID program (found in the /opt/rmb/utils directory) simplifies the creation of user-defined lexical tables. You may wish to make modifications to the program to suit your particular needs.
The remainder of this section further expands steps 3 and 4.
LEX_AID uses the softkeys to provide menu selections. One of the following main menus appears on the screen when the program is run:
Key Labels for ITF Keyboards
Seq Mode Show Show Show Fill Get Quit Save List
Num Index Seq Mode Table Block Table Table Table
The options work as follows:
Seq Num | Allows a sequence number to be assigned to a character. The program prompts for the character, and then for the sequence number to be assigned. Whenever the program is prompting for a character, either the character may be typed from the keyboard or its decimal value may be entered. |
ModeIndex | Displays a sub-menu (shown later) from which the special mode entries can be selected. |
Show Seq | Prompts for a character then displays the character, its value and its current sequence number. |
ShowMode | Displays all of the currently defined mode table entries. |
ShowTable | Displays the current assignments on the CRT. The mode type and mode index are displayed as a single value to save space. |
FillBlock | Prompts for the beginning sequence number and the first and last characters of the block to be filled. Thus a group of characters can be assigned consecutive sequence numbers quickly. |
GetTable | Loads a previously defined lexical order table from the disk. |
Quit | Returns you to normal keyboard mode and terminates the program. |
SaveTable | Saves the currently defined lexical order table to the disk. |
ListTable | Prints the currently defined lexical order table to the current PRINTER IS device. |
Requesting ModeIndex displays one of the following menus:
Key Labels for ITF Keyboards
Don't 1for2 2for1 Accent Normal
Care
Note that the keys shown without labels may have previously defined "typing-aid" definitions and labels.
If you are not familiar with these mode types, you may wish to review the aforementioned "User-defined LEXICAL ORDER" section. With either keyboard, the options work as follows:
Don'tCare | Requests the character to be ignored for collating purposes. |
1for2 | Asks if a suitable entry already exists. If the current character can use a previously defined "1 for 2" entry, the same mode table entry can be used. Answering "Yes" to the question prompts for the new character and then prompts for the character which already has the proper entry. Answering "No" to the question prompts for the character and then asks for the number of secondary characters. Each character and its sequence number is then entered. |
2for1 | Asks if a suitable entry already exists. If several characters use the same secondary character (as in the GERMAN lexical order), the same mode table entry can be used for more than one character. Answering "Yes" to the question prompts for the new character and then prompts for the character which already has the proper entry. Answering "No" to the question prompts for the sequence number of the second character (both upper and lower case). |
Accent | Requests the priority (0 through 63) and then the character to be assigned the accent priority. |
Normal | Allows you to cancel a special mode entry that was mistakenly assigned to a character. No provision is implemented in the LEX_AID program to actually delete the mode table entry. |
With practice, you can create your own lexical order tables with LEX_AID. Be sure to save the table when you are finished.
Having created a table and stored it on disk, you can install it with the following BASIC program.
10 INTEGER Table(0:320)
20 ASSIGN @File TO "MYTABLE" ! Open file
30 ENTER @File;Table(*) ! Read file
40 ASSIGN @File TO * ! Close file
50 LEXICAL ORDER IS Table(*)
60 !
70 END
You may need to replace the name "MYTABLE" with the name of the file in which you have stored the table you have created with LEX_AID.
The lexical order remains in effect until a SCRATCH A or another LEXICAL ORDER IS statement is executed, or BASIC/UX is restarted.
This example uses LEX_AID to create a case-independent lexical order. Both upper- and lower-case characters collate together.
10 INTEGER Table (320)
20 ASSIGN @File to "NOCASE"
30 ENTER @File;Table(*)
40 LEXICAL ORDER IS Table(*)
50 IF "Hello" = "hElLO" THEN
60 PRINT "NO DIFFERENCE"
70 ELSE
80 PRINT "LEX DOESN'T WORK"
90 END IF
100 END
The message NO DIFFERENCE is printed. Similar results could have been achieved by using the UPC$ and LWC$ functions.
Applications needing specialized collating sequences can be simplified by the use of the LEXICAL ORDER IS statement.
It is often easier to separate lexical tables into two arrays, one for the sequence number and a second for the mode entry. This simplifies the calculations of the mode entry. The two arrays are then merged into a single INTEGER array. You can list the LEX_AID program to see the operation.
LIF_UTIL is a utility that contains elements of previous BASIC Workstation utilities:
DUMP | Dump mass storage records in a variety of formats. |
INITIALIZE | Create non-standard sized LIF directories. |
REPACK | Repack a LIF disk for contiguous available space at the end of the disk. |
UNPURGE | Restore files previously purged from a LIF directory. |
VERIFY_LIF | Verify if the current MSI device is a LIF disk. |
ZAP | Clear (destroy files and data) the directory of a LIF disk. |
LOAD "/opt/rmb/utils/LIF_UTIL"
RUN
or press the {{RUN}} key ([f3] in the System menu).
You can also use the {{Next}} or {{Previous}} softkeys to move the cursor, followed by the {{Select}} softkey to choose an option.
This part of LIF_UTIL dumps mass storage records in a variety of formats. To understand this section you may need to have a knowledge of LIF (Logical Interchange Format) disks.
Several alternatives for dumping a record are selected via softkeys. On an ITF keyboard, toggle between softkey menus to see all options. The default dump is hexadecimal.
RECORD# | This lets you select the record you wish to dump. |
Hex | Dumps a record in hexadecimal format. |
Hex/ascii | Dumps a record in hexadecimal/ASCII format, where control characters are masked out and replaced by periods. |
LIF sys | Dumps the LIF volume label in the correct format. |
LIF dir | Causes subsequent dumps to have a LIF directory format. |
CAT | Displays a catalog of the disk. |
N=1, N-1 | Allows you to increment or decrement the current record number and dumps a record according to the current format. |
Integer | Dumps a record in an integer format. |
Oct/ascii | Dumps a record in an octal/ASCII format. Control characters are masked out and replaced by periods. |
Main Menu | Returns you to the main menu. |
If the program pauses after the fourth entry, type CONT or press the {{Continue}} softkey on the System menu to print the rest of the record.
When you select Initialize a LIF disk, you should only be creating non-standard-sized LIF volumes. Standard LIF directories should be created using the INITIALIZE keyword (see the HP BASIC Language Reference).
The program selects the optimum interleave factor for the given msvs.
When you select Repack a LIF disk from the main menu, the currently MSI'd disk is repacked to give you contiguous available space at the end of the disk.
Pay attention to available softkey options.
When you select Restore purged files from the main menu, an extended CAT is displayed.
Clear the directory of a disk by placing a -1 in the file type field of the first directory entry to denote the logical end of the directory (similar to INITIALIZE).
PHYREC copies a bit-by-bit memory integer array to a sector on a LIF mass storage media, and vice versa. PHYREC contains two CSUBs:
Phyread | Copies data from the current msvs into an integer array. |
Phywrite | Copies data from the integer array to the specified msvs. |
Caution | |
---|---|
Indiscriminate use of Phywrite can cause loss of valuable data. Considerable programming and computer experience are required to effectively use PHYREC. |
COPY "/opt/rmb/rmb8_0/utils/PHYREC" TO "PHYREC"
COPY "/opt/rmb/rmb8_0/utils/phyrec.sl" TO "phyrec.sl"
400 LOADSUB ALL FROM "PHYREC"
410 !
420 Phyread(Sector,INTEGER Int_array(*))
430 !
Phyread copies data from the current msvs into an integer array of one to six dimensions. For the example,
Phyread(Sector,INTEGER Int_array(*))
Sector | Replace Sector with a numeric expression. It is evaluated to a real, and rounded to specify the sector (address) on the disk where the copy begins. See "How LIF Disk is Sructured" for more information on sectors. A sector is assumed to contain 256 bytes. For example, a disk with 1024-byte physical sectors is accessed by four 256-byte logical sectors for each 1024-byte physical sector. |
Int_array(*) | The disk is read, beginning with the starting sector, and data is copied into an integer array (Int_array) in a row-major order. Data is copied until each array element is occupied or until an attempt is made to read beyond the end of data on the media (in this case, an error is reported). |
When using arrays, be sure to use 0 or 1 OPTION BASE as required by the nature of your data. See HP BASIC Programming Guide.
The Phywrite CSUB works similar to Phyread, except data is copied from the array to the media (an error is reported on an attempt to write beyond the end of the media).
Phywrite(Sector,Int_array(*))
The following tables contain information about the contents of LIF disks. Use them to conceptualize how information is stored.
Sector\Number | Description |
---|---|
0 | Volume label |
1 | Empty (set to 0) |
2-15 | Directory. 14 sectors is the default, with 112 file entries (each sector is 256 bytes, 128 words, long). |
16-xx | Actual space for files. |
In sector number 0, the volume label contains the following words:
Word Number\(2 bytes) | Contents |
---|---|
0 | LIF disk identifier (100000 Octal) |
1, 2, 3 | Volume label: 6 characters long |
4, 5 | Directory start address (default is 2) |
6 | Reserved (10000 Octal) |
7 | 0 |
8, 9 | Length of directory (default is 14 sectors) |
10 | Reserved |
11 | 0 |
12-20 | Information on disk hardware (level 1 extensions) |
21-126 | Reserved (0) |
127 | Reserved |
The following table shows how sectors relate to file entries on a LIF directory (each sector is 128 words and each file entry is 16 words):
Sector\Number | Contents |
---|---|
2 | File entries 1-8 |
3 | File entries 9-16 |
4 | File entries 17-24 |
... | ... |
15 | File entries 105-112 |
The following table shows the structure of an individual entry in a LIF directory.
Word\Number | Contents | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0-4 | File name. Each byte is one character; 10 characters are allowed. | ||||||||||||||||||
5 | File type. Codes for each file type are found here. Those supported by
BASIC include (type follows code):
File type codes are also used to indicate end of directory and an empty file entry. |
||||||||||||||||||
6-7 | File address. Numeric entry (two words) specifies the file's contents and start on the disk. | ||||||||||||||||||
8-9 | File length. Numeric entry (two words) specifies the file's size. | ||||||||||||||||||
10-12 | Creation time. Used to store the time when the file was made (three words: 12 BCD digits in the form YYMMDDHHMMSS). | ||||||||||||||||||
13 | Volume number. Used for operating systems that support multiple volumes mapped logically (not used by BASIC). | ||||||||||||||||||
14 | Protect code. A two-character password used for the file (0 for ASCII; default is 2 blanks for other file types). | ||||||||||||||||||
15 | Defined record size:
|
The following table shows how LIF directory entries compare to those done in a CAT list.
Field Value | File Type | Directory\Value | CAT |
---|---|---|---|
file type | ASCII
Empty entry Logical end of directory BDAT BIN PROG PROG21 SYSTEM HP-UX |
1
0 -1
-5791 -5775 -5808 -12976 -5822 -5813 |
ASCII
BDAT BIN PROG PROG2 SYSTEM HP-UX |
file address | BDAT
All others |
n
n |
n + 1
n |
file length | BDAT | Number of sectors | Number of sectors users sets at creation. Read words 4 and 5 of system sector. Stores as first sector of file. |
protect code | ASCII
SYSTEM
HP-UX Others |
0
Upperword start address Upper word eof byte 2 character code |
|
defined record size | ASCII
BIN PROG PROG2 HP-UX BDAT
SYSTM |
0
128 128 128 Lower word eof byte If n=0 If n>0 (length in words) Lower word start address |
256
256 256 256
1 2n (length in bytes) 256 |
1 Only on HP BASIC/UX 700.
The following table lists some of the BASIC/WS utilities that are not supported on BASIC/UX. In many cases, the functionality of the utility is covered by BASIC/UX in another capacity.
BASIC/WS \Utility | Description
|
---|---|
BACKUP/RESTORE | Use HP-UX back-up. See "Backing Up the System" in Chapter 4. |
CAT | Use CAT TO statement. See HP BASIC Language Reference. |
CBACKUP | Not supported. |
CONFIGUR | Not supported. |
CPR | Supported on BASIC/UX 300/400. Not supported on BASIC/UX 700. |
CREATE | See HP BASIC Language Reference for statement usage. |
DISK_UTIL | Not supported. See separate entries for MKHFS, HFSCK, and BACKUP/RESTORE. |
FBACKUP | Not supported. |
FONT_ED | Not supported. |
GPIO_STAT | Supported on BASIC/UX 300/400. Not supported on BASIC/UX 700. |
HFSCK | Use fsck. See the section Checking File System Consistency Running the fsck Command in the chapter Managing the File System in the HP-UX System Administration Tasks manual. |
HPIB_STAT | Supported on BASIC/UX 300/400. Not supported on BASIC/UX 700. |
INFO | Not supported. |
INITIALIZE | See LIF_UTIL and HP BASIC Language Reference entry for INITIALIZE. |
LISTER | Functionality supported by:
|
Loader Utility | Not supported. |
MASS_STOR | FILE SIZER, PURGE, Change MSVS, Extended CAT, Change Volume Label are not supported. UNPURGE, REPACK and ZAP are a part of LIF_UTIL. |
MEM_UTILS | Not supported. |
MKHFS | See the section Creating a File System in the chapter Managing the File System in the HP-UX System Administration Tasks manual. |
RS232_STAT | Supported on BASIC/UX 300/400. Not supported on BASIC/UX 700. |
TAPEBACKUP | Not supported. |
82905DUMP | Not supported. |
VERIFY | Supported on BASIC/UX 300/400. Not supported on BASIC/UX 700. |
VME Driver | Not supported. |