SAVE - SYSTEM$

SAVE

Supported On UX WS DOS IN
Option Required EDIT
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SAVE creates a text file and copies all or part of the program to the file in a human-readable format.

Example Statements

SAVE "WHALES"
SAVE File$,First_line,Last_line
SAVE "TEMP",1,Sort
SAVE "Dir<SRM_RW_pass>/File"
SAVE "Ascii_file:REMOTE"

Syntax

Item Description Range
file specifier string expression (see drawing)
beginning line number integer constant identifying a program line;

Default = first program line

1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
beginning line label name of a program line any valid name
ending line number integer constant identifying a program line;

Default = last program line

1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
ending line label name of a program line any valid name
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

An entire program can be saved, or any portion delimited by the beginning and (if needed) ending line numbers or labels. Use SAVE to create new files. Using SAVE with a file name that already exists causes error 54. If you need to replace an old file, see RE-SAVE.

If a specified line label does not exist, error 3 results. If a specified line number does not exist, the program lines with numbers inside the range specified are saved. If the ending line number is less than the beginning line number, error 41 occurs. If no program lines are in the specified range, error 46 occurs.

Lines longer than 256 characters will not be saved correctly. When a GET is performed on a program with such a line, an error will occur. However, a program containing lines exceeding this length can be successfully STOREd and LOADed.

HFS Permissions

In order to SAVE a file on an HFS volume, you need to have W (write) and X (search) permission of the immediately superior directory, as well as X permission on all other superior directories.

When a file is saved on an HFS volume, access permission bits are set to RW-RW-RW-. You can modify the access permission bits with PERMIT if desired. For HP BASIC/UX, these permissions are subject to alteration by the user's umask value, if set. See the HP-UX Reference, umask(1).

DFS and HFS File Headers

All ASCII type files on DFS or HFS volumes contain a 512-byte header (at the beginning of the file's contents). This header allows the HP BASIC system to recognize the file as being an ASCII file. (The header is handled automatically by the HP BASIC system, so you do not have to take any special actions.) HP-UX type files do not have a header.

SRM Passwords and Exclusive Mode  

In order to SAVE an SRM file, you need to have R (read) and W (write) capabilities on the immediately superior directory, and R capabilities on all other superior directories.

Including an SRM password with the file name does not protect the file. You must use PROTECT to assign passwords. You will not receive an error message for including a password, but a password in the file name portion of the SAVE statement will be ignored.

SAVE opens an SRM file in exclusive mode (denoted as LOCK in a CAT listing) and enforces that status on the file until the SAVE is complete. While in exclusive mode, the file is inaccessible to all SRM workstations other than the one executing the SAVE.

SBYTE

Supported On UX WS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SBYTE returns 1 when the first byte of a string expression is a valid second byte of the HP-15 character set. The HP-15 character set is used by versions of HP BASIC that support certain two-byte languages, such as Japanese.

Example Statement

IF FBYTE(A$) AND SBYTE(A$[2])THEN Valid_Kanji

Syntax

Semantics

Certain localized versions of HP BASIC, such as Japanese localized HP BASIC, use two-byte characters. Together, FBYTE and SBYTE allow you to programmatically determine a whether character is one or two bytes long. Note that FBYTE only checks the first byte of the string expression. If FBYTE returns 1 (true), you must also test the second byte of the string using SBYTE to determine if the second byte is in the valid range for HP-15 characters.

For a general discussion of globalization and localization including two-byte characters, refer to the HP BASIC Porting and Globalization manual. To determine the values returned by SBYTE for specific characters, refer to Using LanguageX with HP BASIC, where LanguageX is your local language.

SC

Supported On UX* WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SC returns the interface select code associated with an I/O path name.

Example Statements

Interface=SC(@Device)
Drive_isc=SC(@File)

Syntax

Item Description Range
I/O path name name of a currently assigned I/O path any valid name

Semantics

If the I/O path name is assigned to a device selector (or selectors) with primary and/or secondary addressing, only the interface select code is returned. If the specified I/O path name is assigned to a mass storage file, the interface select code of the drive is returned. If the specified I/O path name is assigned to a buffer, a zero is returned.

If the I/O path name is not currently assigned to a resource, an error is reported.

HP BASIC/UX Specifics

The I/O path name cannot refer to a file on an HFS disk, or error 810 results (unsupported feature).

SCRATCH

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

SCRATCH erases all or selected portions of memory.

Example Statements

SCRATCH
SCRATCH A
SCRATCH ALL     !HP BASIC/UX and HP BASIC/WS only
SCRATCH COM
SCRATCH KEY
SCRATCH KEY 21
SCRATCH WINDOW  !HP BASIC/UX under X Windows only

Item Description Range
key number integer constant 0 through 23

Semantics

The HP BASIC/WS and HP BASIC/DOS do not support the following secondary keywords with the keyword SCRATCH:

W

WINDOW

Both full names and single character abbreviations for actions are accepted.

SCRATCH clears the HP BASIC program and all variables not in COM. Key definitions are left intact.

SCRATCH C clears all variables, including those in COM. The program and keys are left intact.

SCRATCH R clears the [RECALL] key buffer.

To scratch a key, type SCRATCH KEY, followed by the key number, and press [EXECUTE], [ENTER], or [Return]. Also, pressing a softkey after typing SCRATCH will cause SCRATCH KEY, followed by the key number, to be displayed. When a key is specified, the definition for that key only is cleared. When an individual key is not specified, all key definitions are cleared. In either case, the program and all variables are left intact.

SCRATCH A clears the HP BASIC program memory, all the key definitions, and all variables (including those in COM). Most internal parameters in the computer are reset by this command. The clock is not reset and the recall buffer is not cleared. See the Master Reset Table in the "Useful Tables" section in the back of this manual for details.

SCRATCH BIN

SCRATCH BIN causes an extended SCRATCH A. It resets the computer to its power up state. All programs, variables, and BINs are deleted from memory. The BIN which contains the CRT driver for the current CRT is not deleted. Note that SCRATCH BIN will not remove any binaries that reside in ROM.

SCRATCH BIN and SCRATCH B are not supported on HP BASIC/UX.

If you execute SCRATCH BIN for the measurement coprocessor, all binaries except the CRTB and DFS binaries will be removed. Thus, LOAD BIN can subsequently load binaries from the DFS disk files.

SCRATCH A Effects on SRM and HFS Volumes

With SRM volumes, SCRATCH A releases the system resources allocated to the workstation executing the SCRATCH A, making those resources available to other SRM workstations. More specifically, SCRATCH A closes all files and directories, and resets the workstation's working directory to the root directory of the default volume (the mass storage volume from which the workstation booted). SCRATCH A also closes files and directories with HFS volumes.

If the workstation has Boot ROM version 3.0 or A or later, and booted from the SRM, SCRATCH A resets the working directory to the root of the default system volume. If the workstation has an earlier version Boot ROM, SCRATCH A resets the working directory to the device from which the workstation booted (for example, :INTERNAL if the workstation booted from a built-in drive).

SCRATCH W or SCRATCH WINDOW (HP BASIC/UX only)

In a windowing environment, this command causes all created windows to be destroyed. Note that this does not destroy the root HP BASIC window.

This command is only valid when running within a window system. When not in a window system, this command causes an error.

SEC

See SEND.

SECURE

Supported On UX WS DOS IN
Option Required PDEV
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

SECURE protects programs lines so they cannot be listed. There is no way to remove this security, once executed.

Example Statements

SECURE
SECURE Check_password
SECURE Routine1,Routine2

Syntax

Item Description Range
beginning line number integer constant; Default = first line in program --
beginning line label name of a program line any valid name
ending line number integer constant; Default = beginning line number if specified, or last line in program --
ending line label name of a program line any valid name

Semantics

If no lines are specified, the entire program is secured. If one line number is specified, only that line is secured. If two lines are specified, all lines between and including those lines are secured.

Program lines which are secure are listed as an *. Only the line number is listed.

CAUTION
Do not SECURE the only copy of your program. Make a copy of your program, SECURE the copy, and save the original "source code" version of your program in a safe place. There is no way to "unsecure" a program once you have protected it with the SECURE statement. This prevents unauthorized users from listing your program.

SELECT...CASE

Supported On UX WS DOS IN
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... No

SELECT...CASE provides conditional execution of one program segment chosen from several.

Example Statements


600  SELECT String$
610    CASE "0" TO "9"
620      GOSUB Digits
630    CASE ";"
640      GOSUB Delimiter
650    CASE <CHR$(32),>CHR$(126)
660      GOSUB Control_chr
670    CASE ELSE
680      GOSUB Ignore
690  END SELECT

Item Description Range
expression a numeric or string expression --
match item a numeric or string expression; must be same type as the SELECT expression --
program segment any number of contiguous program lines not containing the beginning or end of a main program or subprogram, but which may contain properly nested construct(s). --

Semantics

SELECT...END SELECT is similar to the IF...THEN...ELSE...END IF construct, but allows several conditional program segments to be defined; however, only one segment will be executed each time the construct is entered. Each segment starts after a CASE or CASE ELSE statement and ends when the next program line is a CASE, CASE ELSE, or END SELECT statement.

The SELECT statement specifies an expression, whose value is compared to the list of values found in each CASE statement. When a match is found, the corresponding program segment is executed. The remaining segments are skipped and execution continues with the first program line following the END SELECT statement.

All CASE expressions must be of the same type, (either string or numeric) and must agree in type with the corresponding SELECT statement expression.

The optional CASE ELSE statement defines a program segment to be executed when the selected expression's value fails to match any CASE statement's list.

Branching into a SELECT...END SELECT construct (via GOTO) results in normal execution until a CASE or CASE ELSE statement is encountered. Execution then branches to the first program line following the END SELECT statement.

Errors encountered in evaluating CASE statements will be reported as having occurred in the corresponding SELECT statement.

Nesting Constructs Properly

SELECT...END SELECT constructs may be nested, provided inner construct begins and ends before the outer construct can end.

SEND

Supported On UX WS DOS
Option Required IO
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SEND sends low-level messages to an HP-IB interface.

Example Statements

SEND 7;UNL MTA LISTEN 1 DATA "HELLO" END
SEND @Hpib;UNL MLA TALK Prime CMD 24+128

Item Description Range
interface select code numeric expression, rounded to an integer 7 through 31
I/O path name name assigned to an interface select code any valid name (see ASSIGN)
primary address numeric expression, rounded to an integer 0 through 31
secondary address numeric expression, rounded to an integer 0 through 31

Semantics

CMD

The expressions following a CMD are sent with ATN true. The ASCII characters representing the evaluated string expression are sent to the HP-IB. Numeric expressions are rounded to an integer MOD 256. The resulting byte is sent to the HP-IB. CMD with no items sets ATN true.

DATA

The expressions following DATA are sent with ATN false. The ASCII characters representing the evaluated string expression are sent. Numeric expressions are rounded to an integer MOD 256. The resulting byte is sent to the HP-IB. If END is added to the data list, EOI is set true before sending the last byte. DATA with no items sets ATN false without waiting to be addressed as a talker.

If the computer is active controller, and addressed as a talker, the data is sent immediately. If the computer is not active controller, it waits until it is addressed to talk before sending the data.

TALK

TALK sets ATN true and sends the specified talk address. Only one primary address is allowed for a single talker. An extended talker may be addressed by using SEC secondary address after TALK. A TALK address of 31 is equivalent to UNT (untalk).

UNT

UNT sets ATN true and sends the untalk command. (There is no automatic untalk.) A TALK address of 31 is equivalent to UNT.

LISTEN

LISTEN sets ATN true, sends one or more primary addresses, and addresses those devices to listen. A LISTEN address of 31 is equivalent to UNL (unlisten).

UNL

UNL set ATN true and sends the unlisten command. (There is no automatic unlisten.) A LISTEN address of 31 is equivalent to UNL.

SEC

SEC sets ATN true and sends one or more secondary addresses (commands).

MTA

MTA sets ATN true and sends the interface's talk address. It is equivalent to performing a status sequence on the interface and then using the returned talk address with a SEND..TALK sequence.

MLA

MLA sets ATN true and sends the interface's listen address. It is equivalent to performing a status sequence on the interface and then using the returned listen address with a SEND..LISTEN sequence.

Summary

The computer must be the active controller to execute SEND with CMD, TALK, UNT, LISTEN, UNL, SEC, MTA and MLA.

The computer does not have to be the active controller to send DATA. DATA is sent when the computer is addressed to talk.

The following table lists the HP-IB message mnemonics, descriptions of the messages, and the secondary keywords required to send the messages. Any numeric values are decimal.

HP-IB Messages Used With SEND
Mnemonic Description Secondary Keyword and Value

DAB Data Byte DATA 0 through DATA 255
DCL Device Clear CMD 20 or CMD 148
EOI End or Identify DATA (data) END (sends EOI with ATN false, which is the END message; EOI with ATN true is the Identify message, sent automatically with the PPOLL function)
GET Group Execute Trigger CMD 8 or CMD 136
GTL Go To Local CMD 1 or CMD 129
IFC Interface Clear Not possible with SEND. An ABORT statement must be used.
LAG Listen Address Group LISTEN 0 through LISTEN 31; or CMD 32 through CMD 63
LLO Local Lockout CMD 17
MLA My Listen Address MLA
MTA My Talk Address MTA
PPC Parallel Poll Configure CMD 5 or CMD 133
PPD Parallel Poll Disable PPC (CMD 5 or CMD 133), followed by CMD 112; or CMD 240; or SEC 16.
PPE Parallel Poll Enable PPC (CMD 5 or CMD 133), followed by CMD 96 through CMD 111; or CMD 224 through CMD 239; or SEC 0 through SEC 15 (SEC 0 allows a mask to be specified by a numeric value)
PPU Parallel Poll Unconfigure CMD 21 or CMD 149
PPOLL Parallel Poll Not possible with SEND. PPOLL function must be used.
REN Remote Enable Not possible with SEND. REMOTE statement must be used.
SDC Selected Device Clear CMD 4 or CMD 132
SPD Serial Poll Disable CMD 25 or CMD 153
SPE Serial Poll Enable CMD 24 or CMD 152
TAD Talk Address TALK 0 through TALK 31, or CMD 64 through CMD 95, or CMD 192 through CMD 223.
TCT Take Control CMD 9 or CMD 137
UNL Unlisten UNL, or LISTEN 31, or CMD 63, or CMD 191.
UNT Untalk UNT, or TALK 31, or CMD 95, or CMD 223.

SEPARATE ALPHA FROM GRAPHICS

Supported On UX* WS  DOS*
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SEPARATE ALPHA FROM GRAPHICS is used to simulate the separate alpha and graphics rasters of Series 200 displays (not supported in HP BASIC/UX window environment).

Example Statements

SEPARATE ALPHA
IF (s_300 AND Multi_plane) THEN SEPARATE ALPHA FROM GRAPHICS

Syntax

Semantics

This statement is used to set up the planes on multi-plane bit-mapped alpha displays for independent use as separate alpha and graphics rasters. (This is the way that Series 200 displays work.) If the display is a monochrome, bit-mapped alpha display, an error will be reported. An error will also be reported if HP BASIC is running in a windowing environment.

The statement performs the following actions:

Display-Specific Parameters

Here are the values of parameters for the different types of Series 300 bit-mapped alpha displays:

Number of\Planes Alpha Mask Color Map Graphics Mask
4 Plane 4(1000 base 2) Alpha pen is 8. Pens 0 through 7 have normal default values; pens 8 through 15 are green. Planes 1 through 3(0111 base 2) Graphics pens are 0 through 7.
6 Planes 5 & 6(110000 base 2) Alpha pens are 16, 32, and 48. Pens 0 through 15 have normal default values; pens 16 through 31 are green; pens 32 through 47 are brown; pens 48 through 63 are cyan. Planes 1 through 4(001111 base 2) Graphics pens are 0 through 15.
8 Planes 7 & 8(11000000 base 2) Alpha pens are 64, 128, and 192. Pens 0 through 63 have normal default values; pens 64 through 127 are green; pens 128 through 191 are brown; pens 192 through 255 are cyan. Planes 1 through 6(00111111 base 2) Graphics pens are 0 through 63.
8 gray Planes 7 & 8 (11000000 base 2) Alpha pens are 64, 128, and 192. Pens 0 through 63 have normal default values; pens 64 through 127 have lum=.30; pens 128 through 191 have lum=.53; pens 192 through 255 have lum=.41. Planes 1 through 6(00111111 base 2) Graphics pens are 0 through 63.

If you are using a gray scale display, refer to the chapter "More About Color Graphics" in the HP BASIC Advanced Programming Techniques manual for more information.

Color map entries below the lowest alpha pen value have their default colors set by PLOTTER IS CRT,"INTERNAL". Using a value in this range as an alpha pen will produce transparent text (i.e., is equivalent to using pen 0). Setting up the color or gray map as given in the table causes the alpha text to be dominant over graphics images. If the COLOR MAP option is used with PLOTTER IS, the SET PEN statement can still be used to set all color or gray map entries, not just those dedicated to graphics pens.

Here is a HP BASIC program that performs similar configuration of the planes of a 4-plane display:


100 PLOTTER IS CRT, "INTERNAL";COLOR MAP!Series 300 display
110 FOR I=8 TO 15
120 SET PEN I INTENSITY 0,1,0 ! Set alpha colors (green).
130 NEXT I
140 ALPHA PEN 0 ! Set alpha pen to black (temp).
150 ALPHA MASK 15 ! Enable all planes (temp).
160 CLEAR SCREEN
170 ALPHA MASK 8 ! Enable plane 4 for alpha.
180 ALPHA PEN 8 ! Set alpha pen.
190 INTEGER Gm(0) ! Declare array for GESCAPE.
200 Gm(0)=7 ! Set bits 2,1,0, which select
210 GESCAPE CRT,7,Gm(*) ! graphics planes 3,2,1.
220 ALPHA ON ! Display alpha plane.
230 GRAPHICS ON ! Display graphics planes.
240 PLOTTER IS CRT,"INTERNAL" ! Return to non-color-map
250 END ! mode.

Note that when using this operation with AREA COLOR and AREA INTENSITY, there may be unexpected results. The algorithm that AREA COLOR and AREA INTENSITY use to select graphics pens does not account for the graphics write-enable or display-enable masks. If the pens selected by these statements have bits outside of the write-enable mask, then the planes corresponding to these bits will not be affected. The result is that the area fill colors will not be what is expected.

HP BASIC/UX Specifics

Does not work in a windowed environment.

HP BASIC/DOS Specifics

Supported only for VGA (color or monochrome) and EGA displays.

SET ALPHA MASK

Supported On UX WS DOS
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET ALPHA MASK is used to specify which plane(s) can be modified by alpha display operations.

Example Statements

SET ALPHA MASK Frame_mask
SET ALPHA MASK 3
SET ALPHA MASK IVAL("1100",2)
IF Total_frames = 5 THEN SET ALPHA MASK 8

Syntax

Item Description/Default Range Restrictions
frame buffer mask numeric expression, rounded to an integer 1 through 2^n - 1, where n equals the number of display planes

Semantics

This statement does not affect the operation of monochrome displays or the display of the Model 236C. An error is reported if HP BASIC is running in a windowing environment.

Setting bit 0 of the frame buffer mask (i.e. SET ALPHA MASK 1) enables alpha write permission to plane 1; setting bits 2 and 3 of the frame buffer mask (i.e. SET ALPHA MASK 12) enables write permission to planes 3 and 4. The masks you can use to enable write permissions range from 1 through 2^n - 1 where n is the number of display planes (e.g. the range of frame buffer masks for 4-planes would be 1 through 15).

This statement affects any alpha display operation using the CRT (e.g. PRINT, DISP, CAT, error messages, etc.).

The difference between this statement and SET DISPLAY MASK is SET ALPHA MASK specifies which plane(s) can be modified by alpha operations (regardless of whether or not it/they are displayed). SET DISPLAY MASK specifies the plane(s) that are to be displayed (regardless of whether or not anything has been or can be written to it/them).

For further information on the alpha write-enable mask, see the HP BASIC Programming Guide.

Note that the functionality of this statement can be achieved through CRT CONTROL register 18.

For more information related to this statement, see SEPARATE ALPHA and MERGE ALPHA which are found in this reference.

SET CHR

Supported On UX WS DOS*
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET CHR redefines the bit pattern used for characters in the current font on bit-mapped alpha/graphics displays only.

Example Statements

ALLOCATE INTEGER Char_cell(1:CHRY,1:CHRX)
SET CHR Char_code,Char_cell(*)

ALLOCATE INTEGER Entire_font(1:Num_chars;1:CHRY,1:CHRX)
SET CHR 0,Entire_font(*)

Syntax

Item Description Range
first character numeric expression, rounded to an integer, which specifies the numeric code of the first character to be re-defined 0 through 258
bit-pattern array name of an INTEGER array any valid name

Semantics

If the alpha display is not bit-mapped (that is, if the alpha is separate from the graphics raster, and is generated by character-generator-ROM hardware), then attempting to execute this statement results in error 880.

The "first character" parameter specifies the code of the first character whose bit-pattern is to be re-defined.

The "bit-pattern array" contains the actual pixels that are to comprise the new character. If the display is monochrome (single-plane), then only the low-order bit of each INTEGER element is used. If the display is color (multi-plane), then as many bits are used as there are planes in the display.

If the bit-pattern array parameter has only two dimensions, then only one character is re-defined. The first dimension must have a range of exactly the value of CHRY for this display; the second must have a range of CHRX. (Character cells are 20 rows by 10 columns for 1280 × 1024 resolution bit-mapped alpha displays, 16 rows by 8 columns for 1024 × 768 resolution bit-mapped alpha displays, and 15 rows by 12 columns for medium-resolution bit-mapped alpha displays.)

If the bit-pattern array parameter has three dimensions, then multiple characters are re-defined beginning at the character specified by the "first character" parameter, and continuing until the array is exhausted. Redefinition can stop without exhausting the array if character code 256 (for one-byte characters) or 258 (for two-byte characters) is reached. The first dimension of this array corresponds to the character's code, the second to the character-cell row, and the third to the character-cell column.

Underline Character Definition

Note that character code 256 is the pattern which is exclusive OR'd with a one-byte character to produce underlined characters on the display.

For two-byte characters, HP BASIC uses the character codes 257 and 258 to exclusive OR with the first and second bytes, respectively.

For information regarding enabling underlining on the CRT, see the section, "Display-Enhancement Characters", in the "Useful Tables" section of this manual.

Restoring the Power-Up Default Font

If you want to return to using the default font, then execute this statement:

       CONTROL CRT,21;1

HP BASIC/DOS Specifics

All bits on the bit pattern for a character must be the same color. Restoring the power-up default font is not supported.

SET DISPLAY MASK

Supported On UX WS DOS
Option Required CRTX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

This statement is used to specify which plane(s) can be seen on the alpha display.

Example Statements

SET DISPLAY MASK Frame_mask
SET DISPLAY MASK 3
SET DISPLAY MASK IVAL("1100",2)
IF Disp_frames = 5 THEN SET DISPLAY MASK 8

Syntax

Item Description/Default Range Restrictions
frame buffer mask numeric expression, rounded to an integer 0 through 2^n - 1, where n equals the number of display planes

Semantics

This statement does not affect the operation of monochrome displays or the display of the Model 236C. An error is reported if HP BASIC is running in a windowing environment.

Setting bit 0 of the frame buffer mask (i.e. SET DISPLAY MASK 1) enables the displaying of alpha plane 1; setting bits 2 and 3 of the frame buffer mask (i.e. SET DISPLAY MASK 12) enables displaying of alpha planes 3 and 4. The masks you can use to enable display range from 0 through 2^n - 1 where n is the number of display planes (e.g. the range of frame buffer masks for 4-planes would be 0 through 15).

This statement affects any display operation using the CRT (e.g. PRINT, DISP, CAT, error messages, graphics, etc.).

The difference between this statement and SET ALPHA MASK is SET DISPLAY MASK specifies the plane(s) that are to be displayed (regardless of whether or not anything has been or can be written to it/them). SET ALPHA MASK specifies which plane(s) can be modified by alpha operations (regardless of whether or not it/they are displayed).

For further information on the display-enable mask, see the HP BASIC Programming Guide.

Note that the functionality of this statement can be achieved through CRT CONTROL register 20.

For more information related to this statement, see ALPHA ON/OFF, GRAPHICS ON/OFF, and GESCAPE found in this reference.

SET ECHO

Supported On UX WS DOS
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET ECHO sets an echo to the specified location on the current PLOTTER IS device.

Example Statements

SET ECHO X_location,Y_location
SET ECHO 1000,2200

Syntax

Item Description Range
x coordinate numeric expression in current units --
y coordinate numeric expression in current units --

Semantics

If the current PLOTTER IS device is a CRT, a 9-by-9-dot cross-hair is displayed at the specified coordinates if they are within the hard clip limits; the soft clip limits are ignored. No echo is displayed if the coordinates are outside the hard clip limits.

If the current PLOTTER IS device is an HPGL plotter, the pen is raised and moved to the specified coordinates if they are within the current clip limits. If the pen is inside the clip limits and the new echo position is not, it moves towards the new echo position but stops at the clip boundary. If the pen is outside the clip limits and the new echo position is outside the clip limits, the pen moves along the nearest clip boundary.

SET ECHO is frequently used with the READ LOCATOR statement.

SET HIL MASK

Supported On UX WS*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET HIL MASK enables the specified HIL devices for use by HP BASIC. In HP BASIC/WS, the editor accepts this command, but it has no effect.

Example Statements

SET HIL MASK 16
SET HIL MASK 2^Mouse+2^Knobbox1+2^Buttonbox2

Syntax

Item Description Range
address mask the sum of 2 raised to the power of each of the addresses of the desired devices any even number from 0 to 254

Semantics

The address mask provides the capability of specifying the HIL devices to be used by the HP BASIC system. The most recent SET HIL MASK statement specifies the HIL devices which are used in subsequent ON KNOB, ON CDIAL, and GRAPHICS INPUT IS statements. In addition, it specifies the devices which generate arrow keystrokes during live keyboard and editing when the devices are not being used by any of the above statements.

The value of the mask is obtained by raising 2 to the power of each of the addresses of the desired device, and adding these values. Suppose you want to create a mask which would only allow interrupts from HP-HIL devices at addresses 1 and 3. You would take 2 and raise if to the first power and add this result to 2 raised to the third power; the final result is a mask value of 10.

At start-up time, the HP BASIC system attempts to use all available devices on the HP-HIL link. You may then use this statement to select only those devices which you require and relinquish the other devices for use by different HP-UX processes (e.g. other HP BASIC/UX processes). You should never specify the address of the HIL keyboard with this statement since this interferes with the operation of HP BASIC and block all keyboard input.

Any HIL device which has been specified with this statement or which is not owned by other processes can be identified using the HIL SEND statement as in:

HIL SEND 4; IDD

You should note that the X Windows environment monopolizes all HIL devices unless explicitly specified not to do so. When a device is thus owned by X Windows, it is not available for use by any HP BASIC processes running under the environment. These devices must also be connected to the local system since they cannot be accessed on a remote system. See the section "Opening Input Devices" in the chapter "System-Level Customization" found in the Using the X Window System, Version 11 manual, for details on how to prevent the X Window server from opening specified HIL devices.

Each invocation of rmb in the X Windows environment should relinquish the HP HIL devices that it does not need with SET HIL MASK to allow other invocations of rmb to access those devices; otherwise, the first invocation of rmb will monopolize all HP HIL devices on the link.

SET KEY

Supported On UX WS DOS
Option Required KBD
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET KEY programmatically redefines typing-aid softkey(s).

Example Statements

SET KEY 1,OneKey$
SET KEY First_key,Several_keys$(*)

Syntax

Item Description Range
key number numeric expression, rounded to an integer 0 through 23
string containing 1 softkey definition string expression any valid string expression
string array of softkey definition(s) name of a string array any valid name

Semantics

Typing-aid softkeys are used when typing text at the keyboard. They are active whenever there is not a running program that has defined interrupt service routines for the keys (with ON KEY).

The "first key" parameter indicates the first key to be re-defined.

The second parameter (the string expression or array) determines the number of keys to be re-defined:

                      For instance, if this parameter has a value of 5, and the string array has 3 elements, then softkeys [f5], [f6],                       and [f7] are redefined, respectively.

In order to minimize the chances of typing-aid memory overflows, keys in the range to be re-defined are first cleared and then the corresponding string values are placed into typing-aid memory. For instance, if the "first key" parameter is 3 and the array contains 4 elements, then softkeys 3 through 6 are cleared, after which the string array elements are placed into the corresponding softkeys. If typing-aid memory does overflow, the remaining keys in the range remain undefined. For instance, in this example if a memory overflow occurred while defining key 5, then keys 3 and 4 would have new definitions while keys 5 and 6 would remain undefined.

If the string, or string array element, contains a null (0 length) string, the corresponding typing-aid becomes undefined. Use EDIT KEY or LOAD KEY to define null string typing-aids.

SET LOCATOR

Supported On UX WS DOS
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET LOCATOR specifies a new position for the locator on the current graphics input device.

Example Statements

SET LOCATOR 12,95
SET LOCATOR Old_x,Old_y

Syntax

Item Description Range
x coordinate numeric expression specifying the x coordinate of the locator's new position in current units range of REAL
y coordinate numeric expression specifying the y coordinate of the locator's new position in current units range of REAL

Semantics

If any of the coordinates are outside the device's limits, they are truncated to the nearest boundary.

In order to change the X and Y coordinates of the locator, the graphics input device must have a programmable locator position, (e.g. graphics input is from the keyboard and other relative locators).

The HP 9111A tablet does not support this capability.

SET PEN

Supported On UX* WS DOS*
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET PEN assigns a color or gray value to one or more graphics pens.

Example Statements

SET PEN P_num COLOR Hue,Saturate,Luminous
SET PEN Selector INTENSITY Red,Blue,Green
SET PEN Start_pen COLOR Hsl_array(*)
SET PEN 2 INTENSITY 4/15,1/15,9/15

Syntax

&nocaption;
Item Description Range
pen selector numeric expression, rounded to an integer 0 through 32 767
hue numeric expression 0 through 1
saturation numeric expression 0 through 1
luminosity numeric expression 0 through 1
HSL array name name of a two-dimensional, three-column REAL array any valid name
red numeric expression 0 through 1
green numeric expression 0 through 1
blue numeric expression 0 through 1
RGB array name name of a two-dimensional, three-column REAL array any valid name

NOTE
SET PEN cannot change the color definitions unless a PLOTTER IS...COLOR MAP statement has been executed previously, such as:
         PLOTTER IS CRT, "INTERNAL"; COLOR MAP

Semantics

SET PEN defines the color or gray value for one or more entries in the color map. Either the HSL (hue/saturation/luminosity) color model or the RGB (red/green/blue) color model may be used. SET PEN is ignored for non-color-mapped devices and color or gray-mapped devices in non-color-map mode.

For both SET PEN COLOR and SET PEN INTENSITY, the pen selector specifies the first color or gray map entry to be defined. If individual RGB or HSL values are given, that entry in the color or gray map is the only one defined. If an array is specified, the color or gray map is redefined, starting at the specified pen, and continuing until either the highest-numbered entry in the map is redefined or the source array is exhausted.

Specifying color or gray with the SET PEN and AREA PEN statements (resulting in non-dithered color) results in a much more accurate representation of the desired color than specifying the color with an AREA COLOR or AREA INTENSITY statement.

SET PEN COLOR

The hue value specifies the color. The hue ranges from zero to one, in a circular manner, with a value of zero resulting in the same hue as a value of one. The hue, as it goes from zero to one, proceeds through red, orange, yellow, green, cyan, blue, magenta, and back to red.

The saturation value, classically defined, is the inverse of the amount of white added to a hue. What this means is that saturation specifies the amount of hue to be mixed with white. As saturation goes from zero to one, there is 0% to 100% of pure hue added to white. Thus, a saturation of zero results in a gray, dependent only upon the luminosity; hue makes no difference.

The luminosity value specifies the brightness per unit area of the color. A luminosity of zero results in black, regardless of hue or saturation; if there is no color, it makes no difference which color it is that is not there.

If you are using a gray scale display, hue and saturation are not used, and the brightness per unit area of gray is specified by the luminosity value. A luminosity of zero results in black.

The example program COLORS, found on the MANUAL EXAMPLES disk, demonstrates many of the effects of HSL color model.

COLORS shows the changes brought about by varying one HSL parameter at a time. The button bar shows that when saturation (the amount of color) is zero, hue makes no difference, and varying luminosity results in a gray scale.

It also displays the fully saturated, fully luminous colors selected as the hue value goes from 0 through 1. Any value between zero and one, inclusive, can be chosen to select color, but the resolution (the amount the value can change before the color on the screen changes) depends on the value of hue, as well as the other two parameters.

COLORS illustrates the effect that varying saturation and luminosity has on hue with several small color wheels.

SET PEN INTENSITY

For a color display, the red, green, and blue values specify the intensities of the red, green, and blue displayed on the screen.

For a gray scale display, the intensity of gray displayed on the screen is specified by the following expression:

0.30 * red  + 0.59 * green  + 0.11 * blue.

The example program COLORS, found on the MANUAL EXAMPLES disk, demonstrates the effect of varying the intensity of one color component while the other two remain constant.

It also shows combinations of red, green and blue. The values are represented in fifteenths: 0 fifteenths, 5 fifteenths, 10 fifteenths, and 15 fifteenths--every fifth value. Fifteenths are the units. Thus, zero fifteenths through fifteen fifteenths made a total of sixteen levels. The values for each color component are represented in that color.

HP BASIC/UX Specifics

Dithering on the HP 2397 terminal assumes that the hardware color map contains power-on color assignments. However, these do not correspond to the standard HP BASIC color map. To make dithering results accurate on the HP 2397, the color map must be set to the following with SET PEN:

Pen R G B
0 0.0     0.0    0.0  
1 1.0 0.0 0.0
2 0.0 1.0 0.0
3 1.0 1.0 0.0
4 0.0 0.0 1.0
5 1.0 0.0 1.0
6 0.0 1.0 1.0
7 1.0 1.0 1.0

HP BASIC/DOS Specifics

SET PEN color selections are fully supported for a VGA color display. However, for an EGA display, the color selections are limited.

SET TIME

Supported On UX* WS DOS*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET TIME resets the time-of-day given by the real-time clock.

Example Statements

SET TIME 0
SET TIME Hours*3600+Minutes*60
SET TIME ! HP BASIC/UX only 

Syntax

Item Description Range
seconds numeric expression, rounded to the nearest hundredth 0 through 86 399.99

Semantics

SET TIME changes only the time within the current day, not the date. The new clock setting is equivalent to (TIMEDATE DIV 86 400)×86 400 plus the specified setting.

HP BASIC/UX Specifics

This statement does not reset the HP-UX clock, even if the user is super-user. Instead it resets the clock which HP BASIC/UX keeps for itself.

SET TIME without a parameter resynchronizes the time with the HP-UX clock. This does not affect the date nor the timezone. If the timezone is subsequently resynchronized with HP-UX (via TIMEZONE IS), then the time will change accordingly. The proper way to resynchronize both the time and timezone is to do the timezone first as in:

TIMEZONE IS

SET TIME

HP BASIC/DOS Specifics

With MS-DOS 3.1 and 3.2, SET TIME affects only the "local" HP BASIC time and MS-DOS time. With MS-DOS 3.3 and above, SET TIME also sets the CMOS battery-backed clock (the real-time clock on the PC).

SET TIMEDATE

Supported On UX* WS DOS*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SET TIMEDATE resets the absolute seconds (time and day) given by the real-time clock.

Example Statements

SET TIMEDATE TIMEDATE+86400
SET TIMEDATE Strange_number
SET TIMEDATE DATE("5 Dec 1986")+TIME("08:00:00")
SET TIMEDATE ! HP BASIC/UX only 

Syntax

Item Description Range
seconds numeric expression, rounded to the nearest hundredth 2.086 629 12 E+11 through

2.143 252 223 999 9 E+11

Semantics

The volatile clock is set to 2.086 629 12 E+11 (midnight March 1, 1900) at power-on (HP BASIC/WS semantics). If there is a battery-backed (non-volatile) clock, then the volatile clock is synchronized with it at power-up. If the computer is on an SRM system (and has no battery-backed clock), then the volatile clock is synchronized with the SRM clock when the SRM and DCOMM binaries are loaded. The clock values represent Julian time, expressed in seconds.

HP BASIC/UX Specifics

The volatile clock is set to the current HP-UX time at power-on. The clock values represent Julian time, expressed in seconds.

Note that this statement does NOT reset the HP-UX clock, even if the user is super-user. Instead it resets the clock which HP BASIC keeps for itself.

SET TIMEDATE without a parameter resynchronizes the time and date with the HP-UX clock. This does not affect the timezone. If the timezone is subsequently resynchronized with HP-UX (via TIMEZONE IS), then the time and date will change accordingly. The proper way to resynchronize the time, date, and timezone is to do the timezone first as in:

TIMEZONE IS

SET TIMEDATE

HP BASIC/DOS Specifics

With MS-DOS 3.1 and 3.2, SET TIMEDATE affects only the "local" HP BASIC time and MS-DOS time. With MS-DOS 3.3 and above, SET TIMEDATE also sets the CMOS battery-backed clock (the real-time clock on the PC).

SGN

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SGN returns 1 if the argument is positive, 0 if it equals zero, and -1 if it is negative.

Example Statements

Root=SGN(X)*SQR(ABS(X))
Z=2*PI*SGN(Y)

Syntax

Semantics

COMPLEX arguments are not allowed with this function.

SHIFT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SHIFT returns an integer which equals the value obtained by shifting the 16-bit binary representation of the argument the number of bit positions specified, without wraparound.

Example Statements

New_word=SHIFT(Old_word,-2)
Mask=SHIFT(1,Position)

Syntax

Item Description Range
argument numeric expression, rounded to an integer -32 768 through +32 767
bit position displacement numeric expression, rounded to an integer -15 through +15

Semantics

If the bit position displacement is positive, the shift is towards the least-significant bit. If the bit position displacement is negative, the shift is towards the most-significant bit. Bits shifted out are lost. Bits shifted in are zeros. The SHIFT operation is performed without changing the value of any variable in the argument.

SHIFT IN...OUT

See ASSIGN, DUMP DEVICE IS, PRINTALL IS, and PRINTER IS.

SHOW

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SHOW defines an isotropic current unit-of-measure for graphics operations.

Example Statements

SHOW -5,5,0,100
SHOW Left,Right,Bottom,Top

Syntax

Item Description Range
left numeric expression --
right numeric expression <>left
bottom numeric expression --
top numeric expression <> bottom

Semantics

SHOW defines the values which must be displayed within the hard clip boundaries, or the boundaries defined by the VIEWPORT statement. SHOW creates isotropic units (units the same in X and Y). The direction of an axis may be reversed by specifying the left greater than the right or the bottom greater than the top.

For information on scaling with large ranges, when using the SHOW statement, read the section "Special Considerations about Scaling" in the chapter "Using Graphics Effectively" found in the HP BASIC Programming Guide.

SIGNAL

Supported On UX WS DOS
Option Required IO
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SIGNAL generates a software interrupt.

Example Statements

SIGNAL Selector
SIGNAL 3

Syntax

Item Description Range
signal selector numeric expression, rounded to an integer 0 through 15

Semantics

If an ON SIGNAL statement for the specified signal selector exists, and all the other conditions for an event-initiated branch are fulfilled, the branch defined in the ON SIGNAL statement is taken. If no ON SIGNAL exists for the specified signal selector, the SIGNAL statement causes no action.

SIN

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SIN returns the sine of the angle represented by the argument.

Example Statements

Sine=SIN(Angle)
PRINT "Sine of";Theta;"=";SIN(Theta)

Syntax

Item Description Range\Restrictions
argument numeric expression in current units of angle when arguments are INTEGER or REAL numeric expression in radians when argument is COMPLEX absolute values less than: 1.708 312 781 2 E+10 deg or 2.981 568 26 E+8 rad ; see Range Restriction Specifics for COMPLEX arguments and underflow conditions

Semantics

If the argument is REAL or INTEGER, the value returned is REAL. If the argument is COMPLEX, the value returned is COMPLEX.

To compute the SIN of a COMPLEX value, the COMPLEX binary must be loaded.

Range Restriction Specifics

The formula used for computing the SIN of a COMPLEX argument is:

CMPLX(SIN(Real_part)*COSH(Imag_part),COS(Real_part)*SINH(Imag_part))

where Real_part is the real part of the COMPLEX argument and Imag_part is the imaginary part of the COMPLEX argument. Some values of a COMPLEX argument may cause errors in this computation. For example,

SIN(CMPLX(0,MAXREAL))

will cause error 22 (error 21 in HP BASIC/UX 700) due to the COSH(Imag_part) calculation.

Note that any COMPLEX function whose definition includes a sine or cosine function will be evaluated in the radian mode regardless of the current angle mode (i.e. RAD or DEG).

The following range restrictions apply in HP BASIC/UX 700 when underflow mode (CONTROL 32,7;mode) is set to Error or Ignore.

Range Underflow Mode\Error Underflow Mode\Ignore
Positive Maximum +1.34217728000000E+008 +1.34217728000000E+008
Negative Minimum -1.34217728000000E+008 -1.34217728000000E+008
Positive Minimum +1.02907134889717E-076 +4.94065645841247E-3241
Negative Maximum -1.02907134889717E-076 -4.94065645841247E-3242

1 An underflow in Ignore mode results in a denormalized number that is less than the value for +MINREAL.

2 An underflow in Ignore mode results in a denormalized number that is greater than the value for -MINREAL.

SINH

Supported On UX WS DOS
Option Required COMPLEX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SINH returns the hyperbolic sine of a numeric expression.

Example Statements

Result=SINH(-8.2475)
PRINT "Hyperbolic Sine = ";SINH(Expression)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression -710 through 710 for INTEGER or REAL arguments; see Range Restriction Specifics for COMPLEX arguments and underflow conditions

Semantics

If an INTEGER or REAL argument is given, this function returns a REAL value. If a COMPLEX argument is given, this function returns a COMPLEX value.

Range Restriction Specifics

The formula used for computing SINH is as follows:

(EXP(Argument) - EXP(-Argument))/2

where Argument is the argument of the SINH function. Some arguments may cause errors in intermediate values computed during this computation. For example,

SINH(MAXREAL)

will cause error 22 (error 21 in HP BASIC/UX 700) due to the EXP(Argument) computation.

The following range restrictions apply in HP BASIC/UX 700 when underflow mode (CONTROL 32,7;mode) is set to Error or Ignore.

Range Underflow Mode\Error Underflow Mode\Ignore
Positive Maximum +7.10475860073944E+002 +7.10475860073944E+002
Negative Minimum -7.10475860073944E+002 -7.10475860073944E+002
Positive Minimum +1.30133222687718E-074 +4.94065645841247E-324 1
Negative Maximum -1.30133222687718E-074 -4.94065645841247E-324 2

1 An underflow in Ignore mode results in a denormalized number that is less than the value for +MINREAL.

2 An underflow in Ignore mode results in a denormalized number that is greater than the value for -MINREAL.

SIZE

Supported On UX WS DOS IN
Option Required MAT
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SIZE returns the number of elements in a dimension of an array. This INTEGER value represents the difference between the upper bound and the lower bound, plus 1.

Example Statements

Total_words=SIZE(Words$,1)
Upperbound(2)=BASE(A1,2)+SIZE(A1,2)-1

Syntax

Item Description Range
array name name of an array any valid name
dimension numeric expression, rounded to an integer 1 through 6; < the RANK of the array

SORT

See MAT SORT.

SOUND

Supported On UX* WS
Option Required KBD
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SOUND produces a single tone or multiple tones on the sound generator of an HP-HIL interface.

Example Statements

SOUND Voice_num,Freq,Volume,Duration
SOUND 1,440,12,0.50
SOUND Instructions(*)

Syntax

Item Description Range
voice number numeric expression, rounded to an integer 1 through 3
frequency numeric expression, rounded to an integer 83 through 83 333 Hz (see following table)
volume numeric expression, rounded to an integer 0 through 15
duration numeric expression, rounded to nearest hundreth of second 0, 0.01 through 2.55
array of sound instructions INTEGER array must contain the proper number of non-zero values (see Semantics)

Semantics

If the multiple-parameter syntax is used, then the SOUND statement generates one tone on the specified voice number; the frequency, volume, and duration of the tone are as specified by the last three parameters of the statement. Note that the HP BASIC system does not wait for the tone to finish before executing the following program line or statement (if any). If you want to generate a sequence of tones, you must either generate a delay between SOUND statements (such as with WAIT), or use the SOUND syntax described below.

If the single-parameter syntax is used (that is, a numeric array is specified), then the elements of the array are read sequentially and interpreted according to the following rules:

Instruction Sound Chip Effect Produced

0

Exit the SOUND statement (and stop reading array elements)

1 to 3

The specified voice is to be used; also says to read the next three array elements, and interpret them as follows, respectively:
  • tone number--used to set the frequency (frequency = 83 333 / tone number).
  • volume--0 = off; 1 through 15 are lowest to highest volume.
  • duration--values 0 through 255 are interpreted as follows:

    0 is interpreted as "sound indefinitely".

    1 through 255 are interpreted as 10's of milliseconds (i.e., 1/100 second);

4

Specifies that the noise voice is to be used; also says to read the next three array elements and interpret them as above (the same as with voice numbers 1 to 3), except that the tone number parameter is interpreted as follows:

0 => periodic noise; fast shift register clock; 1 => periodic noise; medium shift register clock; 2 => periodic noise; slow shift register clock; 3 => periodic noise; clock shift register with voice 3;

4=> white noise; fast shift register clock; 5 => white noise; medium shift register clock; 6 => white noise; slow shift register clock; 7 => white noise; clock shift register with voice 3.

5 to 8

Wait for voice 1 to 4, respectively, to finish sounding before executing the next sound instruction (if any).

9

Read the following array element, and wait the specified interval (100 microseconds × that element's value) before executing the next instruction (if any).

If the end of the array is reached on one of these boundaries, then the SOUND statement terminates normally; however, if the last element of the array has been reached and the HP BASIC system expects to read more values, then error 17 will be reported (subscript out of range).

HP BASIC/UX Specifics

Devices to be addressed using SOUND must not have been opened by the X Windows server. These devices must also be connected to the local system since they cannot be accessed on a remote system. See the section "Opening Input Devices" in the chapter "System-Level Customization" found in the Using the X Window System, Version 11 manual, for details on how to prevent the X Window server from opening specified HIL devices.

Producing Notes in the Equal-Tempered Scale

Here is a list of the notes in the equal-tempered musical scale. The table shows that the frequencies available with the SOUND statement are close to the even-tempered notes, but are not exact. The equal-tempered scale is derived from the following relationship:

frequency of note = 2(1/12) × (frequency of preceding note)

Note Ideal\Frequency Tone\Number Closest\ Frequency
E 82.41 1011 82.43
F 87.31 954 87.35
F# 92.50 901 92.49
G 98.00 850 98.04
G# 103.83 803 103.78
A 110.00 758 109.94
A# 116.54 715 116.55
B 123.47 675 123.46
C 130.81 637 130.82
C# 138.59 601 138.66
D 146.83 568 146.71
D# 155.56 536 155.47
E 164.81 506 164.69
F 174.61 477 174.70
F# 185.00 450 185.18
G 196.00 425 196.08
G# 207.65 401 207.81
A 220.00 379 219.88
A# 233.08 358 232.77
B 246.94 337 247.28
C 261.63 319 261.23
C# 277.18 301 276.85
D 293.66 284 293.43
D# 311.13 268 310.94
E 329.63 253 329.38
F 349.23 239 348.67
F# 369.99 225 370.37
G 392.00 213 391.23
G# 415.30 201 414.59
A 440.00 189 440.92
A# 466.16 179 465.55
B 493.88 169 493.09
C 523.25 159 524.11
C# 554.37 150 555.55
D 587.33 142 586.85
D# 622.25 134 621.89
E 659.26 126 661.37
F 698.46 119 700.28
F# 739.99 113 737.46
G 783.99 106 786.16
G# 830.61 100 833.33
A 880.00 95 877.19
A# 932.33 89 936.33
B 987.77 84 992.06
C 1046.50 80 1041.66
C# 1108.73 75 1111.11
D 1174.66 71 1173.70
D# 1244.51 67 1243.78
E 1318.51 63 1322.75
F 1396.91 60 1388.88
F# 1479.98 56 1488.09
G 1567.98 53 1572.32
G# 1661.22 50 1666.66
A 1760.00 47 1773.04
A# 1864.66 45 1851.84
B 1975.53 42 1984.12
C 2093.00 40 2083.33
C# 2217.46 38 2192.97
D 2349.32 35 2380.94
D# 2489.02 33 2525.24
E 2637.02 32 2604.16
F 2793.83 30 2777.77
F# 2959.96 28 2976.18
G 3135.96 27 3086.41
G# 3322.44 25 3333.32
A 3520.00 24 3472.21
A# 3729.31 22 3787.86
B 3951.07 21 3968.24
C 4186.01 20 4166.65
C# 4434.92 19 4385.95
D 4698.64 18 4629.61
D# 4978.03 17 4901.94
E 5274.04 16 5208.31
F 5587.65 15 5555.53
F# 5919.91 14 5952.36
G 6271.93 13 6410.23
G# 6644.88 13 6410.23
A 7040.00 12 6944.42
A# 7458.62 11 7575.73
B 7902.13 11 7575.73
C 8372.02 10 8333.30
C# 8869.84 9 9259.22
D 9397.27 9 9259.22
D# 9956.06 8 10416.63
E 10548.08 8 10416.63
F 11175.30 7 11904.71
F# 11839.82 7 11904.71
G 12543.85 7 11904.71
G# 13289.75 6 13888.83

SPANISH

See LEXICAL ORDER IS.

SPOLL

Supported On UX WS DOS IN
Option Required IO
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SPOLL returns an integer containing the serial poll response from the addressed device.

Example Statements

Stat=SPOLL(707)
IF SPOLL(@Device) THEN Respond

Syntax

Item Description Range
I/O path name name assigned to a device any valid name (see ASSIGN)
device selector numeric expression, rounded to an integer must include a primary address (see Glossary)

Semantics

A SPOLL may be executed under the following conditions:

If the SPOLL terminates prematurely with an ON TIMEOUT or CLEARIO, the bus may be left in the Serial Poll Enabled state (SPE). This could happen if the device being SPOLLed was non-existent, disconnected, or had some type of failure keeping it from responding. To set the bus to the correct state, either do a RESET SC, or use SEND CMD to complete the SPOLL cleanup, such as ATN, SPD, or UNT.

Refer to the documentation provided with the polled device for information concerning the device's status byte.

Summary of SPOLL Bus Actions
Interface Select\Code Only Primary Address\Specified
error ATN

UNL

MLA

TAD

SPE

____

ATN

Read data

ATN

SPD

UNT

SQRT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SQRT returns the square root of the argument. The keywords SQR and SQRT behave identically.

Example Statements

Amps=SQRT(Watts/Ohms)
PRINT "Square root of";X;"=";SQR(X)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression any valid INTEGER or REAL value for INTEGER and REAL expressions; for COMPLEX arguments, the range restriction for ABS applies here.

Semantics

If the argument is REAL or INTEGER, the value returned is REAL. If the argument is COMPLEX, the value returned is COMPLEX.

To compute the SQR or SQRT of a COMPLEX value, the COMPLEX binary must be loaded.

The following range restrictions apply in HP BASIC/UX 700 when underflow mode (CONTROL 32,7;mode) is set to Error or Ignore.

Range Underflow Mode\Error Underflow Mode\Ignore
Positive Maximum +1.79769313486232E+308 +1.79769313486232E+308
Positive Minimum +2.22507385850720E-308 +4.94065645841247E-324 1

1 An underflow in Ignore mode results in a denormalized number that is less than the value for +MINREAL.

STANDARD

See LEXICAL ORDER IS.

STATUS

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

STATUS returns the contents of interface or I/O path name status registers.

Example Statements

STATUS Interface,Reg;Val1 ! Read status of a hardware interface.
STATUS @File,5;Record ! Read status of a file.
STATUS 1;Xpos,Ypos
STATUS 1,9;Screenwidth

Syntax for Files

Item Description Range
I/O path name name assigned to a device, devices, mass storage file, buffer, or pipe any valid name (see ASSIGN)
interface select code numeric expression, rounded to an integer 1 through 40
register number numeric expression, rounded to an integer; Default = 0 interface dependent
numeric name name of a numeric variable any valid name

Semantics

Using STATUS with Files and Hardware Interfaces

The value of the beginning register number is copied into the first variable, the next register value into the second variable, and so on. The information is read until the variables in the list are exhausted; there is no wrap-around to the first register. An attempt to read a nonexistent register generates an error.

The register meanings depend on the specified interface or on the resource to which the I/O path name is currently assigned. Register 0 of I/O path names can be interrogated with STATUS even if the I/O path name is currently invalid (i.e., unassigned to a resource). Note that the status registers of an I/O path are different from the status registers of an interface. All status and control registers are summarized in the "Interface Registers" section at the back of the book.

STEP

See FOR...NEXT.

STOP

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

STOP terminates execution of the program.

Example Statements

STOP
IF Done THEN STOP

Syntax

Semantics

Once a program is stopped, it cannot be resumed by CONTINUE. RUN must be executed to restart the program. PAUSE should be used if you intend to continue execution of the program.

A program can have multiple STOP statements. Encountering an END statement or pressing the [STOP] key ([Shift]-[Stop] on the ITF keyboards) has the same effect as executing STOP. After a STOP, variables that existed in the main context are available from the keyboard.

STORE

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

STORE creates a file and stores the program or typing-aid key definitions into it.

Example Statements

STORE Filename$
STORE "Dir<SRM_RW_pass>/Program"

The following example is valid on HP BASIC/UX/WS/DOS and requires the KBD binary.

STORE KEY "Typing_aids"

Syntax

Item Description Range
file specifier string expression (see drawing)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
LIF protect code literal; first two non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

STORE writes the program in memory to the specified PROG-type file (PROG on Series 200/300/400 and PROG2 on Series 700). This format is different from the ASCII format used by SAVE. The PROG-type format uses less disk space and loads more quickly into HP BASIC. The ASCII format is more portable (it can be read by other versions of HP BASIC) and it is human-readable.

In all STORE statements, an error occurs if the storage media cannot be found, the media or directory is full, or the file specified already exists. Also, if a LIF protect code is specified, it is applied to the new LIF file. To update a file which already exists, see RE-STORE.

STORE

The STORE statement creates a PROG-type file and stores an internal form of the program into that file.

STORE KEY

STORE KEY creates a file of type BDAT, and stores the current typing-aid softkey definitions (not ON KEY softkey definitions) into it. These definitions can be subsequently reloaded with the LOAD KEY statement.

For each defined typing-aid softkey, an integer and a string are sent to the file. The integer is the key number, and the string is the key definition. The data is written with FORMAT OFF (see the OUTPUT statement). Keys with no definition are not written to the file.

HFS Permissions

In order to STORE a file on an HFS volume, you need to have W (write) and X (search) permission on the immediately superior directory, as well as X permission on all other superior directories.

When a file is stored on an HFS volume, access permission bits are set to RW-RW-RW-. You can modify the access permission bits with PERMIT, if desired.

DFS and HFS File Headers

On DFS or HFS volumes, STORE creates a PROG-type file that contains a 512-byte header (at the beginning of the file's contents). This header allows HP BASIC to recognize the file as being a PROG-type file. (The header is handled automatically by HP BASIC, so you do not have to take any special actions.)

SRM Passwords and Exclusive Mode

In order to STORE an SRM file, you need to have R (read) and W (write) capabilities on the immediately superior directory, and R capabilities on all other superior directories.

Including an SRM password with the file name does not protect the file. You must use PROTECT to assign passwords. You will not receive an error message for including a password, but a password in the file name portion of the STORE statement will be ignored.

STORE opens the remote file in exclusive mode (denoted as LOCK in a CAT listing) and enforces that status on the file until the STORE is complete. While in exclusive mode, the file is inaccessible to all SRM workstations other than the one executing the STORE.

STORE SYSTEM

Supported On UX* WS DOS*
Option Required None
Keyboard Executable Yes
Programmable No
In an IF ... THEN ... No

STORE SYSTEM stores the entire HP BASIC operating system currently in memory including any BINs that are loaded (use only with HP BASIC/WS or HP BASIC/DOS).

Example Statements


  STORE SYSTEM "SYSTEM_B1:INTERNAL"
  STORE SYSTEM "BACKUP1"
  STORE SYSTEM "/SYSTEMS/SYSTEM_NEW"

Syntax

Item Description Range
file specifier string expression (see drawing)
directory path literal (see MASS STORAGE IS)
file name literal (see Semantics)
volume specifier literal (see MASS STORAGE IS)

Semantics

If the file name already exists, an error is reported.

On LIF volumes, SYSTM file names can be up to 10 characters long. On SRM volumes, they can be up to 16 characters long.

On HFS volumes, SYSTM file names can be a maximum of 9 characters long, since the HFS loader assumes that strings will be terminated with the null character, CHR$(0). In addition, SYSTM file names on HFS volumes less than 9 characters long will be padded with null characters to a length of 10 characters. This may cause unexpected results, since null characters act as "wild cards" on HFS volumes. For instance, suppose that there are two SYSTM files on the same HFS volume named SYSTEM_BA and SYSTEM_B, and that they are listed as 1B and 2B, respectively, by the Boot ROM. Typing 1B will boot SYSTEM_BA, as expected. However, typing 2B will also boot SYSTEM_BA because of the null (wild card) character in the 9th position in the SYSTM file named SYSTEM_B.

HP BASIC and any BINs in memory are stored in the SYSTM file. If the file name begins with SYSTEM_, the Boot ROM can find it and load it at power up or SYSBOOT. (Note that Boot ROM 3.0 and A, and later versions, can find and load files beginning with SYS.) On SRM, the system must be located in /SYSTEMS for the Boot ROM to find it. On HFS, the system must be stored in the root ("/") for the Boot ROM to find it.

Note that if you did a SCRATCH BIN to remove the CRT driver you did not need, and then stored the system, when you reboot, the CRT driver for the other display is not available. If the CRT needs the other driver, you cannot use the display. Execute a LOAD BIN command to load the needed driver.

STORE SYSTEM cannot be used with ROM HP BASIC systems.

HFS Permissions and File Headers

In order to use STORE SYSTEM on an HFS volume, you need to have W (write) and X (search) permission on the root directory. ON HFS, you can STORE SYSTEM only to the root directory.

Do not RENAME a file stored into the root directory of an HFS volume by STORE SYSTEM.

A SYSTM file (or an HP-UX file stored by STORE SYSTEM) which is placed in the root directory of an HFS volume by COPY or LINK will not be found by the Boot ROM.

The R (read) access capability on the system file created with STORE SYSTEM must be public to allow use of the file for booting.

On HFS volumes, STORE SYSTEM creates an HP-UX file that contains a special header (at the beginning of the file's contents) to make the file conform to the HP-UX "a.out" file format. (The header is handled automatically by HP BASIC, so you do not have to take any special actions.)

SRM Access Capabilities  

In order to use STORE SYSTEM on an SRM volume, you need to have R (read) and W (write) capabilities on the immediately superior directory, and R capabilities on all other superior directories.

The R (read) access capability on the system file created with STORE SYSTEM must be public to allow use of the file for booting.

Including an SRM password with the file name does not protect the file. You must use PROTECT to assign passwords. You will not receive an error message for including a password, but a password in the file name will be ignored.

HP BASIC/UX Specifics

STORE SYSTEM is not necessary nor supported on HP BASIC/UX as HP BASIC/UX is a unified system.

HP BASIC/DOS Specifics

A system stored from HP BASIC/DOS will not run correctly on HP BASIC/WS, or vice versa.

SUB

Supported On UX WS DOS IN*
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... No

SUB is the first statement in a SUB subprogram and specifies the subprogram's formal parameters.

Example Statements

SUB Parse(String$)
SUB Process
SUB Transform(@Printer,INTEGER Array(*),Text$)
SUB Transform(@Printer,INTEGER Array(*), OPTIONAL Text$)
SUB Extract(Buff$ BUFFER,Pointer)

Item Description Range
subprogram name name of the SUB subprogram any valid name
numeric name name of a numeric variable any valid name
string name name of a string variable any valid name
I/O path name name assigned to a device, devices, or mass storage file any valid name (see ASSIGN)
program segment any number of contiguous program lines not containing the beginning or end of a main program or subprogram --

Semantics

SUB subprograms must appear after the main program. The first line of the subprogram must be a SUB statement. The last line must be a SUBEND statement. Comments after the SUBEND are considered to be part of the subprogram.

Parameters to the left of the keyword OPTIONAL are required and must be supplied whenever the subprogram is invoked (see CALL). Parameters to the right of OPTIONAL are optional, and only need to be supplied if they are needed for a specific operation. Optional parameters are associated from left to right with any remaining pass parameters until the pass parameter list is exhausted. An error is generated if the subprogram tries to use an optional parameter which did not have a value passed to it. The function NPAR can be used to determine the number of parameters supplied by the CALL statement invoking the subprogram.

Variables in a subprogram's formal parameter list must not be duplicated in COM or other declaratory statements within the subprogram. A subprogram may not contain any SUB statements, or DEF FN statements. Subprograms can be called recursively and can contain local variables. A uniquely labeled COM must be used if the local variables are to preserve their values between invocations of the subprogram.

Use SUBEXIT to exit the subprogram at some point other than the SUBEND. Multiple SUBEXITs are allowed, and SUBEXIT can appear in an IF ... THEN statement. SUBEND can only occur once in a subprogram, and SUBEND cannot be used in an IF ... THEN statement. ERROR SUBEXIT can be used in the same way as SUBEXIT.

If you want to use a formal parameter as a BUFFER, it must be declared as a BUFFER in both the formal parameter list and the calling context.

SUBEND

See SUB.

SUBEXIT

Supported On UX WS DOS IN
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... Yes

SUBEXIT returns program control from a subprogram at some point other than the SUBEND statement. It allows multiple exits from a subprogram.

See also ERROR SUBEXIT.

Example Statements

SUBEXIT
IF Done THEN SUBEXIT

Syntax

SUM

Supported On UX WS DOS
Option Required MAT
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SUM returns the sum of all the elements in a numeric array. The returned value is of the same type as the array.

Example Statements

Total=SUM(Array)
PRINT SUM(Squares)

Syntax

Item Description Range
array name name of a numeric array any valid name

SUSPEND INTERACTIVE

Supported On UX WS DOS
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SUSPEND INTERACTIVE disables the program control keys during a running program. Control keys include [EXECUTE], [ENTER], [Return], [PAUSE], [STOP], [CLR I/O], [Break], and (optionally) [RESET].

Example Statements

SUSPEND INTERACTIVE
SUSPEND INTERACTIVE,RESET

Syntax

Semantics

Execution of a PAUSE statement, a TRACE PAUSE statement, or a fatal execution error temporarily restores the suspended key functions. CONTINUE after a PAUSE will again disable the keys.

SUSPEND INTERACTIVE is canceled by RESUME INTERACTIVE, STOP, END, RUN, SCRATCH, GET, LOAD, or [RESET]. Although LOAD cancels SUSPEND INTERACTIVE, LOADSUB does not. SUSPEND INTERACTIVE has no effect unless a program is running.

NOTE
Suspending the [RESET] key will prevent you from stopping a program before it ends.

[EXECUTE], [ENTER], and [Return] can still be used to respond to an ENTER or INPUT statement, but cannot be used for live keyboard execution.

SWEDISH

See LEXICAL ORDER IS.

SYMBOL

Supported On UX WS DOS
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SYMBOL allows labeling with user-defined symbols.

Example Statements

SYMBOL My_char(*)
SYMBOL Logo(*),FILL,EDGE

Syntax

Item Description Range
array name name of a two-dimensional, two-column or three-column REAL array any valid name

Semantics

The user-defined symbol is created with moves and draws defined in a symbol coordinate system. The symbol coordinate system is a rectangular area nine units wide and fifteen units high, that is, a character cell. A symbol can extend outside the limits of the 9×15 symbol coordinate system rectangle. A symbol defined in the symbol coordinate system is affected by the label transformations CSIZE, LDIR, and LORG. The symbol is drawn using the current pen and line type, and it will be clipped at the current clip boundary.

When defining a symbol in the symbol coordinate system, coordinates may be outside the 9×15 character cell; thus, characters can be made which are several character cells wide and several character cells high. For this reason, the current pen position is not updated to the next character's reference point, but it remains at the last X,Y coordinate specified in the array. A move is made to the first point regardless of the value in the third column of that row in the array.

The symbol may have polygons defined in its data, and the polygons may be filled and/or edged. The fill color and pen number/line type used are those defined at the time the polygon is closed.

FILL and EDGE

When FILL or EDGE is specified, each sequence of two or more lines forms a polygon. The polygon begins at the first point on the sequence, includes each successive point, and the final point is connected or closed back to the first point. A polygon is closed when the end of the array is reached, or when the value in the third column is an even number less than three, or in the range 5 to 8 or 10 to 15. Unexpected results can occur in attempts to FILL a polygon of zero area.

If FILL and/or EDGE are specified on the SYMBOL statement itself, it causes the polygons defined within it to be filled with the current fill color and/or edged with the current pen color. If polygon mode is entered from within the array, and the FILL/EDGE directive for that series of polygons differs from the FILL/EDGE directive on the SYMBOL statement itself, the directive in the array replaces the directive on the statement. In other words, if a "start polygon mode" operation selector (a 6, 10, or 11) is encountered, any current FILL/EDGE directive (whether specified by a keyword or an operation selector) is replaced by the new FILL/EDGE directive.

If FILL and EDGE are both declared on the SYMBOL statement, FILL occurs first. If neither one is specified, simple line drawing mode is assumed; that is, polygon closure does not take place.

If you attempt to fill a figure on an HPGL plotter, the figure will not be filled, but will be edged, regardless of the directives on the statement.

Applicable Graphics Transformations
Scaling PIVOT CSIZE LDIR PDIR
Lines (generated by moves and draws) X X [4]
Polygons and rectangles X X X
Characters (generated by LABEL) X X
Axes (generated by AXES & GRID) X
Location of Labels [1] [3] [2]

[l]The starting point for labels drawn after lines or axes is affected by scaling.

[2]The starting point for labels drawn after other labels is affected by LDIR.

[3]The starting point for labels drawn after lines or axes is affected by PIVOT.

[4]RPLOT and IPLOT are affected by PDIR.

When using a SYMBOL statement, the following table of operation selectors applies. An operation selector is the value in the third column of a row of the array to be plotted. The array must be a two-dimensional, two-column or three-column array. If the third column exists, it will contain operation selectors which instruct the computer to carry out certain operations. Polygons may be defined, edged (using the current pen), filled (using the current fill color), pen and line type may be selected, and so forth. See the list below.

Column 1 Column 2 Operation\Selector Meaning
X Y -2 Pen up before moving
X Y -1 Pen down before moving
X Y 0 Pen up after moving (Same as =2)
X Y 1 Pen down after moving
X Y 2 Pen up after moving
pen number ignored 3 Select pen
line type repeat value 4 Select line type
color ignored 5 Color value
ignored ignored 6 Start polygon mode with FILL
ignored ignored 7 End polygon mode
ignored ignored 8 End of data for array
ignored ignored 9 NOP (no operation)
ignored ignored 10 Start polygon mode with EDGE
ignored ignored 11 Start polygon mode with FILL and EDGE
ignored ignored 12 Draw a FRAME
pen number ignored 13 Area pen value
red value green value 14 Color
blue value ignored 15 Value
ignored ignored >15 Ignored

Moving and Drawing

If the operation selector is less than or equal to two, it is interpreted in exactly the same manner as the third parameter in a non-array SYMBOL statement. Even is up, odd is down, positive is after pen motion, negative is before pen motion. Zero is considered positive.

Selecting Pens

An operation selector of 3 selects a pen. The value in column one is the pen number desired. The value in column two is ignored.

Selecting Line Types

An operation selector of 4 selects a line type. The line type (column one) selects the pattern, and the repeat value (column two) is the length in GDUs that the line extends before a single occurrence of the pattern is finished and it starts over. On the CRT, the repeat value is evaluated and rounded down to the next multiple of 5, with 5 as the minimum.

Selecting a Fill Color

Operation selector 13 selects a pen from the color map with which to do area fills. This works identically to the AREA PEN statement. Column one contains the pen number.

Defining a Fill Color

Operation selector 14 is used in conjunction with operation selector 15. Red and green are specified in columns one and two, respectively, and column three has the value 14. Following this row in the array (not necessarily immediately), is a row whose operation selector in column three has the value of 15. The first column in that row contains the blue value. These numbers range from 0 to 32 767, where 0 is no color and 32 767 is full intensity. Operation selectors 14 and 15 together comprise the equivalent of an AREA INTENSITY statement, which means it can be used on a monochromatic, gray scale, or color display.

Operation selector 15 actually puts the area intensity into effect, but only if an operation selector 14 has already been received.

Operation selector 5 is another way to select a fill color. The color selection is through a Red-Green-Blue (RGB) color model. The first column is encoded in the following manner. There are three groups of five bits right-justified in the word; that is, the most significant bit in the word is ignored. Each group of five bits contains a number which determines the intensity of the corresponding color component, which ranges from zero to sixteen. The value in each field will be sixteen minus the intensity of the color component. For example, if the value in the first column of the array is zero, all three five-bit values would thus be zero. Sixteen minus zero in all three cases would turn on all three color components to full intensity, and the resultant color would be a bright white.

Assuming you have the desired intensities (which range from 0 through 1) for red, green, and blue in the variables R, G, and B, respectively, the value for the first column in the array could be defined thus:

    Array(Row,1)=SHIFT(16*(1-B),-10)+SHIFT(16*(1-G),-5)+16*(1-R)

If there is a pen color in the color map similar to that which you request here, that non-dithered color will be used. If there is not a similar color, you will get a dithered pattern.

If you are using a gray scale display, Operation selector 5 uses the five bit values of the RGB color specified to calculate luminosity. The resulting gray luminosity is then used as the area fill. For detailed information on gray scale calculations, see the chapter "More About Color Graphics" in the HP BASIC Advanced Programming Techniques manual.

Polygons

A six, ten, or eleven in the third column of the array begins a "polygon mode". If the operation selector is 6, the polygon will be filled with the current fill color. If the operation selector is 10, the polygon will be edged with the current pen number and line type. If the operation selector is 11, the polygon will be both filled and edged. Many individual polygons can be filled without terminating the mode with an operation selector 7. This can be done by specifying several series of draws separated by moves. The first and second columns are ignored and should not contain the X and Y values of the first point of a polygon.

Operation selector 7 in the third column of a plotted array terminates definition of a polygon to be edged and/or filled and also terminates the polygon mode (entered by operation selectors 6, 10, or 11). The values in the first and second columns are ignored, and the X and Y values of the last data point should not be in them. Edging and/or filling of the most recent polygon will begin immediately upon encountering this operation selector.

Doing a FRAME

Operation selector 12 does a FRAME around the current soft-clip limits. Soft clip limits cannot be changed from within the SYMBOL statement, so one probably would not have more than one operation selector 12 in an array to SYMBOL, since the last FRAME will overwrite all the previous ones.

Premature Termination

Operation selector 8 causes the SYMBOL statement to be terminated. The SYMBOL statement will successfully terminate if the actual end of the array has been reached, so the use of operation selector 8 is optional.

Ignoring Selected Rows in the Array

Operation selector 9 causes the row of the array it is in to be ignored. Any operation selector greater than 15 is also ignored, but operation selector 9 is retained for compatibility reasons. Operation selectors less than -2 are not ignored. If the value in the third column is less than zero, only evenness/oddness is considered.

If you attempt to fill a figure on an HPGL plotter, the figure will not be filled, but will be edged, regardless of the directives on the statement.

SYSBOOT

Supported On UX* WS DOS*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SYSBOOT returns control to the BOOT ROM to restart the system selection and configuration process.

Example Statements

SYSBOOT
SYSBOOT "SYSTEM_BA5"
SYSBOOT "SYSBAS:,1400,0"

Syntax

Item Description Range
file specifier string expression, specifying a SYSTM file to be booted (see drawing)
file name literal (see Semantics)
volume specifier literal (see MASS STORAGE IS)

Semantics

If no file specifier is included, the normal Boot ROM power-up search sequence is initiated. (See &usws; or &usux; for a sequence of mass storage devices searched.)

If a file specifier is included, it must a valid LIF file specifier (10 characters or less). The Boot ROM restricts the file name, if included, to 10 characters. System names on SRM can be up to 16 characters. To boot a system whose name is more than 10 characters, do not specify the file name and use the Boot ROM to select the correct file.

If no volume specifier is included in the file specifier, the current default volume is assumed.

To boot a system from the SRM, public read access is required and the system must be located in /SYSTEMS. The directory path, /SYSTEMS must be omitted from the file specifier. The Boot ROM looks for the file in /SYSTEMS.

To boot from HFS the system must be located in the root directory (/). System names on HFS must be 9 characters or less.

HP BASIC/UX Specifics

Not supported on HP BASIC/UX. It generates an error.

HP BASIC/DOS Specifics

If a file specifier is included, it is ignored. Any boot options given on the HP BASIC command line when HP BASIC/DOS is first invoked will be in effect.

SYSTEM KEYS

Supported On UX WS DOS
Option Required KBD
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SYSTEM KEYS changes the softkey definitions on an ITF keyboard to the System menu.

Example Statements

SYSTEM KEYS
IF Change_keys THEN SYSTEM KEYS

Syntax

Semantics

This statement only affects the normal mode of the ITF Keyboard (i.e. it does nothing on an HP 98203A/B/C Keyboard and causes no visible change on an ITF Keyboard when the Keyboard Compatibility Mode, KBD CMODE, is on).

Note that the functionality of this statement can be achieved through KBD CONTROL register 2.

For information on the softkey definitions, see &usws; or &usux;.

SYSTEM PRIORITY

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SYSTEM PRIORITY sets the system priority to a specified level.

Example Statements

SYSTEM PRIORITY Level
SYSTEM PRIORITY 15

Syntax

Item Description Range
new priority numeric expression, rounded to an integer 0 through 15

Semantics

Zero is the lowest user-specifiable priority and 15 is the highest. The END, ERROR, and TIMEOUT events have an effective priority higher than the highest user-specifiable priority. If no SYSTEM PRIORITY has been executed, minimum system priority is 0.

This statement establishes the minimum for system priority. Once the minimum system priority is raised with this statement, any events of equal or lower priority will be logged but not serviced. In order to allow service of lower-priority events, minimum system priority must be explicitly lowered.

If SYSTEM PRIORITY is used to change the minimum system priority in a subprogram context, the former value is restored when the context is exited.

Error 427 results if SYSTEM PRIORITY is executed in a service routine for an ON ERROR GOSUB or ON ERROR CALL statement.

SYSTEM$

Supported On UX* WS DOS* IN*
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

SYSTEM$ returns a string containing system status and configuration information.

Example Statements

IF SYSTEM$("TRIG MODE")="RAD" THEN Radian
System_prior=VAL(SYSTEM$("SYSTEM PRIORITY"))
SYSTEM$("VERSION:OS") ! HP BASIC/UX only.

Syntax

Item Description Range
topic specifier string expression see the following table

Semantics

The topic specifier is used to specify what system configuration information SYSTEM$ will return.

The following table lists the valid topic specifiers and the information returned for each one.

Topic Specifier Information Returned
AVAILABLE MEMORY Bytes of available memory. HP BASIC/UX returns both the physical RAM available before swapping becomes necessary and available workspace.
CONVERSION BUFFER A string containing the current contents of the keyboard input conversion buffer (Japanese localized HP BASIC/WS only). (Requires INPUT)
CRT ID
6:nnwxyzaa
6 distinguishes this format from Series 500 BASIC
nn CRT width in characters
w H=CRT highlights available, space=No highlights
x C=Color available, space=Monochrome/Gray scale
y G=Graphics available, space=No graphics
z B=Bit mapped display, space=Not bit mapped
aa highest graphics pen number, 1 if monochrome, 15 if 236C, 2^n-1 if bit mapped
DICTIONARY IS:SYSTEM A string containing the current file specifier for system input conversion dictionaries (Japanese localized HP BASIC/WS only). If no dictionary is assigned, the null string is returned. (Requires INPUT)
DICTIONARY IS:USER A string containing the current file specifier for user-defined input conversion dictionaries (Japanese localized HP BASIC/WS only). If no dictionary is assigned, the null string is returned.(Requires INPUT)
DUMP DEVICE IS A string containing numerals which specify the device selector for the currently assigned DUMP DEVICE IS device or path name of the current DUMP DEVICE IS file.
GFONT IS A string containing the file specifier for the vector fonts used by LABEL (HP BASIC/WS only). If no file has been assigned, the null string is returned.(Requires LANGUAGE)
GRAPHICS INPUT IS A string containing numerals which specify the device selector for the currently assigned GRAPHICS INPUT IS device. Zero is returned if no device is currently selected. (Requires GRAPH)
KBD LINE A string containing the current contents of the keyboard input line(s). Note that this operation does not change the contents of the line(s).
KEYBOARD LANGUAGE ASCII, BELGIAN, CANADIAN ENGLISH, CANADIAN FRENCH, DANISH, DUTCH, FINNISH, FRENCH, GERMAN, ITALIAN, KANJI, KATAKANA, LATIN, NORWEGIAN, SPANISH, SWEDISH, SWISS FRENCH, SWISS GERMAN, SWISS FRENCH*, SWISS GERMAN*, or UNITED KINGDOM (Requires LEX)
LANGUAGE A string containing the current system language (HP BASIC/WS only). If no localized LANGUAGE binary is loaded or if CRTD is not active, the returned string is the null string. If a localized LANGUAGE binary is loaded and CRTD is active, then the returned string is the language supported by LANGUAGE, such as JAPANESE. (Requires LANGUAGE)
LEXICAL ORDER IS ASCII, GERMAN, FRENCH, SPANISH, SWEDISH or USER DEFINED (Requires LEX)
MASS MEMORY X000YZ0000000000

X=Number of internal disk drives Y=Number of initialized EPROM cards Z=Number of bubble memory cards If Y or Z exceed 9, an asterisk appears.

HP BASIC/DOS and HP BASIC/UX: value is always a string of 0's as internal LIF disk drives, EPROM or bubble memory cards are not supported.

MASS STORAGE IS, MSI The mass storage unit specifier of the current MASS STORAGE IS device, as it appears in a CAT heading.
PLOTTER IS A string containing numerals which specify the device selector of the current PLOTTER IS device or the path name of the current PLOTTER IS file. (Requires GRAPH)
PRINTALL IS A string containing numerals which specify the device selector of the current PRINTALL IS device or the path name of the current PRINTALL IS file.
PRINTER IS A string containing numerals which specify the device selector of the current PRINTER IS device or the path name of the current PRINTER IS file.
PROCESS ID Returns the process identifier of the main process. HP BASIC/WS and HP BASIC/DOS always returns 0.(Requires CRTX)
SERIAL NUMBER Returns the product/exchange, and serial numbers from an HP HIL ID module if present; otherwise it returns the null string. This is a non-ASCII string. See the HP-HIL Interface chapter of the &inter; for more information about the ID Module.
SYSTEM ID S300:40 on Series 300 computers with an MC68040 processor; or S300:30 on Series 300 computers with an MC68030 processor; or S300:20 on Series 300 computers with an MC68020 processor; or bytes 15 through 21 of the ID PROM in a Series 200 computer (if present); or 9816, 9826A, or 9836A padded with trailing spaces to make a seven character string; PC300 for 82300 Measurement Coprocessor or PC300:30 for 82324 High Performance Measurement Coprocessor; S700 on Series 700 computers.
SYSTEM PRIORITY A string containing numerals which specify the current system priority.
TIMEZONE IS A string specifying the seconds from Greenwich Mean Time that represent the current timezone value. (Requires RMBUX,CLOCK)
TRIG MODE DEG or RAD
VERSION: option name A string containing numerals which specify the revision number of the specified binary (also displayed after LOAD BIN or LIST BIN) or option. BASIC, BCD, BUBBLE, CLOCK, COMPLEX, CRTA, CRTB, CRTX, CS80, DCOMM, DFS, DISC, EDIT, EPROM, ERR, FHPIB, GPIO, GRAPH, GRAPHX, HFS, HP9885, HPIB, IO, KBD, LEX, MAT, MS, PDEV, RMBUX SERIAL, SRM, TRANS, XREF, etc.: VERSION:OS returns the operating system version and name.
VERSION:special_file A string containing the revision of the specified graphics font file or dictionary file (Japanese localized HP BASIC/WS only). If the file has not been assigned (using GFONT IS, DICTIONARY is), the null string is returned.
WILDCARDS Returns: OFF: DOS: UX:<esc.char>.
WINDOW SYSTEM Returns data on the window environment.(HP BASIC/UX/WS only) X Windows -- for the X Windows manager Console -- for the bare screen console (or HP BASIC/WS or HP BASIC/DOS with RMBUX binary) Terminal -- for a terminal Windows/9000 -- for the HP Windows/9000 manager.

SYSTEM$ with SRM, DFS, and HFS Systems

When SYSTEM$ of MASS STORAGE IS (MSI), PLOTTER IS, or PRINTER IS is executed on a system using SRM, DFS or HFS volumes, the information returned includes the full file specifier describing the file or directory about which the information is requested. (SRM passwords are not included in the specifier.)

The system remembers a maximum of 160 characters for any one specifier. If a specifier contains more than 160 characters, the excess characters are removed from the beginning of the specifier and are not retained. An asterisk (*) as the left-most character in the specifier indicates that leading characters were truncated for the function.

HP BASIC/UX Specifics

The system remembers a maximum of 1024 characters for any one specifier. If a specifier contains more than 1024 characters, the excess characters are removed from the beginning of the specifier and are not retained. An asterisk (*) as the left-most character in the specifier indicates that leading characters were truncated for the function.

HP BASIC/DOS Specifics

Four additional keywords are provided for HP BASIC/DOS:

Topic Specifier Information Returned
DISPLAY SIZE Viewable size of display in pixels in <horiz>x<vert> format (e.g., "640" x "480").
PIXEL RATIO The X/Y ratio of the physical pixel size on the display (e.g., 1.00 for VGA).
VERSION:MCP_HW "82300" for Measurement Coprocessor, "82324" for High Performance Measurement Coprocessor.
VERSION:MCP_SW Version of Measurement Coprocessor Software being used (e.g., "D 00.00").