LABEL - LWC$

LABEL

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

LABEL draws text labels with the graphics pen at the pen's current position. For information about LABEL as a secondary keyword, see ON KEY.

Example Statements

LABEL Number,String$
LABEL Array(*)
LABEL USING 160;X,Y,Z
LABEL USING "5Z.DD";Money

Item Description Range
image line number integer constant identifying an IMAGE statement 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
image line label name identifying an IMAGE statement any valid name
image specifier string expression (see drawing)
string array name name of a string array any valid name
numeric array name name of a numeric array any valid name
image specifier list literal (see diagram)
repeat factor integer constant 1 through 32 767
literal string constant composed of characters from the keyboard, including those generated using the [ANY CHAR] key quote mark not allowed

Semantics

The label begins at the current logical pen position, with the current pen. Labels are clipped at the current clip boundary. The current pen position is updated at the end of the label operation.

The color and line type used for the label are determined by PEN and LINE TYPE respectively. The size (width and height) of the label is set by CSIZE. LABEL output is affected by origins specified by LORG, and rotations specified by LDIR

Standard Numeric Format

The standard numeric format depends on the value of the number being output. If the absolute value of the number is greater than or equal to 1E-4 and less than 1E+6, it is rounded to 12 digits and displayed in floating-point notation. If it is not within these limits, it is displayed in scientific notation. The standard numeric format is used unless USING is selected, and may be specified by using K in an image specifier.

COMPLEX numbers are treated like two REAL numbers separated by a semicolon.

Automatic End-Of-Line Sequence

After the label list is exhausted, an End-of-Line (EOL) sequence is sent to the logical pen, unless it is suppressed by trailing punctuation or a pound-sign image specifier. The EOL sequence is also sent after every 256 characters. This "plot buffer exceeded" EOL is not suppressed by trailing punctuation, but is suppressed by the pound-sign specifier.

Control Codes

Character Keystroke Name Action
CHR$(8) [CTRL]-[H] backspace Back up the width of one character cell.
CHR$(10) [CTRL]-[J] line-feed Move down the height of one character cell.
CHR$(13) [CTRL]-[M] carriage-return Move back the length of the label just completed.

Any control character that the LABEL statement does not recognize is treated as an ASCII blank [CHR$(32)].

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]

[1]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.

Arrays

Entire arrays may be output by using the asterisk specifier. Each element in an array is treated as an item by the LABEL statement, as if the items were listed separately, separated by the punctuation following the array specifier. If no punctation follows the array specifier, a comma is assumed. COMPLEX array elements are treated as if the real and imaginary parts are separated by a semicolon. The array is output in row major order (rightmost subscript varies fastest).

LABEL Without USING

If LABEL is used without USING, the punctuation following an item determines the width of the item's label field; a semicolon selects the compact field, and a comma selects the default label field. When the label item is an array with the asterisk array specifier, each array element is considered a separate label item. Any trailing punctation will suppress the automatic EOL sequence, in addition to selecting the label field to be used for the label item preceding it.

The compact field is slightly different for numeric and string items. Numeric items are output with one trailing blank. String items are output with no leading or trailing blanks.

The default label field labels items with trailing blanks to fill to the beginning of the next 10-character field.

Numeric data is output with one leading blank if the number is positive, or with a minus sign if the number is negative, whether in compact or default field.

LABEL With USING

When the computer executes a LABEL USING statement, it reads the image specifier, acting on each field specifier (field specifiers are separated from each other by commas) as it is encountered. If nothing is required from the label items, the field specifier is acted upon without accessing the label list. When the field specifier requires characters, it accesses the next item in the label list, using the entire item. Each element in an array is considered a separate item.

The processing of image specifiers stops when there is no matching display item (and the specifier requires a display item). If the image specifiers are exhausted before the display items, they are reused, starting at the beginning.

COMPLEX values require two REAL image specifiers (i.e. each COMPLEX value is treated like two REAL values.)

If a numeric item requires more decimal places to the left of the decimal point than provided by the field specifier, an error is generated. A minus sign takes a digit place if M or S is not used, and can generate unexpected overflows of the image field. If the number contains more digits to the right of the decimal point than are specified, it is rounded to fit the specifier.

If a string is longer than the field specifier, it is truncated, and the right-most characters are lost. If it is shorter than the specifier, trailing blanks are used to fill out the field.

Effects of the image specifiers on the LABEL statement are shown in the following table:

Image\Specifier Meaning

K

Compact field. Outputs a number or string as a label in standard form with no leading or trailing blanks.

-K

Same as K.

H

Similar to K, except the number is output using the European number format (comma radix). (Requires IO)

-H

Same as H. (Requires IO)

S

Outputs the number's sign (= or -) as a label.

M

Outputs the number's sign as a label if negative, a blank if positive.

D

Digit specifier outputs one-digit character as a label. A leading zero is replaced by a blank. If the number is negative and no sign image is specified, the minus sign will occupy a leading digit position. If a sign is output, it will float to the left of the left-most digit.

Z

Same as D, except that leading zeros are output.

*

Same as Z, except that asterisks are output instead of leading zeros. (Requires IO)

.

Outputs a decimal-point radix specifier as a label.

R

Outputs a comma radix specifier as a label (European radix). (Requires IO)

E

Outputs as a label: an E, a sign, and a two-digit exponent.

ESZ

Outputs as a label: an E, a sign, and a one-digit exponent.

ESZZ

Same as E.

ESZZZ

Outputs as a label: an E, a sign, and a three-digit exponent.
Image\Specifier Meaning

A

Outputs a string character as a label. Trailing blanks are output if the number of characters specified is greater than the number available in the corresponding string. If the image specifier is exhausted before the corresponding string, the remaining characters are ignored. Use the specifier AA or 2A for two-byte globalization characters.

X

Outputs a blank as a label.

literal

Outputs as a label the characters contained in the literal.

B

Outputs as a label the character represented by one byte of data. This is similar to the CHR$ function. The number is rounded to an INTEGER and the least-significant byte is sent. If the number is greater than 32 767, then 255 is used; if the number is less than -32 768, then 0 is used.

W

Outputs as a label two characters represented by the two bytes of a 16-bit, two's-complement integer. The corresponding numeric item is rounded to an INTEGER. If it is greater than 32 767, then 32 767 is used; if it is less than -32 768, then -32 768 is used. The most-significant byte is sent first.

Y

Same as W. (Requires IO)

#

Suppresses the automatic output of the EOL (End-Of-Line) sequence following the last label item.

%

Ignored in LABEL images.

=

Changes the automatic EOL sequence that normally follows the last label item to a single carriage-return. (Requires IO.)

-

Changes the automatic EOL sequence that normally follows follows the last label item to a single line-feed. (Requires IO)

/

Sends a carriage-return and a line-feed to the PLOTTER IS device.

L

Same as /.

@

Sends a form-feed to the PLOTTER IS device; produces a blank.

LDIR

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

LDIR defines the angle at which labels or symbols are drawn. The angle is measured counter-clockwise from the X axis using the current angle mode.

Example Statements

LDIR 90
LDIR ACS(Side)

Syntax

Item Description Range
angle numeric expression in current units of angle; Default = 0 (same as COS)

Semantics

LDIR affects the appearance of LABEL and SYMBOL output only; it does not affect the output of other graphics commands.

The rotation angle specified with LDIR is measured counterclockwise from the positive X axis. Thus, the positive X axis is at zero degrees, the positive Y axis is at 90 degrees, and so on. The unit of measure for angles can be set using DEG and RAD.

The angle is interpreted as shown in the following figure.

LEN

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

LEN returns the current number of bytes in the specified string.

ASCII and Japanese Katakana characters are one byte long. Some languages use two-byte characters, such as Japanese Kanji.

Example Statements

Last=LEN(String$)
IF NOT LEN(A$) THEN Empty

Syntax

Semantics

The length of the null string ("") is 0.

Two-Byte Language Specifics

Certain localized versions of HP BASIC, such as Japanese localized HP BASIC, support two-byte characters. If you use LEN to determine the length of a two-byte string in characters, you must divide the returned value by two. For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.

LET

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

LET assigns values to variables. The keyword LET is optional.

Example Statements

LET Number=33
Array(I+1)=Array(I)/2
String$="Hello Scott"
A$(7)[1;2]=CHR$(27)&"Z"

Item Description Range
numeric name name of a numeric variable any valid name
string name name of a string variable any valid name
subscript numeric expression, rounded to an integer -32 767 through +32 767 (see "array" in Glossary)
beginning position numeric expression, rounded to an integer 1 through 32 767 (see "substring" in Glossary)
ending position numeric expression, rounded to an integer 0 through 32 767 (see "substring" in Glossary)
substring length numeric expression, rounded to an integer 0 through 32 767 (see "substring" in Glossary)

Semantics

The assignment is done to the variable which is to the left of the equals sign. Only one assignment may be performed in a LET statement; any other equal signs are considered relational operators, and must be enclosed in a parenthetical expression, as in this statement:

     A=A+(B=1)+5

A variable can occur on both sides of the assignment operator, as in these statements:

     I=I+1
     Source$=Old$

A real expression will be rounded when assigned to an INTEGER variable, if it is within the INTEGER range. Out-of-range assignments to an INTEGER give an error. If a REAL or INTEGER value is assigned to a COMPLEX variable, the imaginary part receives the value 0. If a COMPLEX value is assigned to a REAL or INTEGER variable, the imaginary part is dropped.

The length of the string expression must be less than or equal to the dimensioned length of the string it is being assigned to. Assignments may be made into substrings, using the normal rules for substring definition. The string expression will be truncated or blank-filled on the right (if necessary) to fit the destination substring when the substring has an explicitly stated length. If only the beginning position of the substring is specified, the substring will be replaced by the string expression and the length of the recipient string variable will be adjusted accordingly; however, error 18 is reported if the expression overflows the recipient string variable.

If the name of the variable to the left of the equal sign begins with AND, DIV, EXOR, MOD or OR (the name of an operator) and the keyword LET is omitted, the prefix must have at least one uppercase letter and one lowercase letter in it. Otherwise, a live keyboard execution is attempted and fails, even though the line number is present.

LEXICAL ORDER IS

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

LEXICAL ORDER IS defines the collating sequence for all string operations. It is valid for one-byte character sets.

Example Statements

LEXICAL ORDER IS ASCII
LEXICAL ORDER IS FRENCH
LEXICAL ORDER IS My_lex_table(*)

Syntax

Item Description Range
array name the name of a one-dimensional INTEGER array, with at least 257 elements any valid name

Semantics

The STANDARD lexical order is determined by the internal keyboard jumper preset to match the language on the keyboard. For example, with an English language or Katakana keyboard, the STANDARD lexical order is the same as the ASCII lexical order.

The default lexical order is STANDARD. This is also true after a SCRATCH A. The most recent LEXICAL ORDER IS statement overrides any previous definition and affects all contexts.

Lexical order allows languages to be properly collated. This includes such treatments as ignoring characters, dealing with accents, and character replacements. See HP BASIC Programming Guide for the details of pre-defined and user-defined lexical order tables.

Two-Byte Language Specifics

Certain localized versions of HP BASIC, such as Japanese localized HP BASIC, support two-byte characters. LEXICAL ORDER definitions are not supported for two-byte characters. For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.

LGT

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

LGT returns the common logarithm (base 10) of its argument.

Example Statements

Decibel=20*LGT(Volts)
PRINT "Log of";X;"=";LGT(X)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression > 0 for INTEGER and REAL arguments; 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 LGT of a COMPLEX value, the COMPLEX binary must be loaded.

Range Restriction Specifics

The formula used for computing the LGT of a COMPLEX value is:

        LOG(Argument)/LOG(10)

where Argument is a COMPLEX argument to the LGT function. Some values of a COMPLEX argument may cause errors in this computation. For example,


       LGT(CMPLX(MAXREAL,MAXREAL))

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

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

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

LINE TYPE

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

LINE TYPE selects a line type and repeat length for all lines, labels, frames, axes, and grids drawn with the graphics pen.

Example Statements

LINE TYPE 1
LINE TYPE Style,Repeat_len

Syntax

Item Description Range
type selector numeric expression, rounded to an integer; Default = 1 1 through 10
repeat length numeric expression, rounded to an integer; Default = 5 greater than 0

Semantics

At power-up the default line type is a solid line (type 1), and the default repeat length is 5 GDUs. The repeat length establishes the number of GDUs required to contain an arbitrary segment of the line pattern.

When plotting to the graphics display, the repeat length is evaluated and taken as the next lower multiple of 5, with a minimum value of 5.

When plotting to an external plotter, the line produced by the line identifier is device dependent. Refer to your plotter's documentation for further information.

The available CRT line types are shown here.

HP BASIC/UX Specifics

When using HP BASIC/UX with the sox11 driver in the X-Windows environment, the line pattern is reset at the beginning of each new vector when using DRAW, MOVE, or PLOT without an array. This may cause the line pattern to look different on a CRT than what you expect when the vectors are shorter than the repetition of the line pattern. Plotters do not exhibit this behavior. To get a continuous pattern, use PLOT A(*) with operation selector 10. HP BASIC/UX 700 uses the sox11 driver by default. Other HP BASIC/UX versions use the sox11 driver in X-Windows if initiated with the command rmb -X.

LINK

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

LINK allows the linking of two file names on the same HFS or SRM volume to a single physical file. If a wildcard specification for the source matches multiple files, the destination must be a directory.

Example Statements

LINK "Org_file:CS80,700,0" TO "New_file"
LINK "old" TO "new";PURGE
LINK "source/*" TO "dest_dir"
LINK "exists" TO "file_[ABC]]" ! WILDCARDS UX only

Syntax

Item Description Range
file specifier string expression (see diagram)
volume specifier string expression (see MASS STORAGE IS)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)

Semantics

The LINK statement works only with HFS or SRM.

LINKing files that are on different volumes is not possible. Since the files that are linked must be on the same volume, you need to give the volume specifier only with the first file used by the link statement. For example,

"File1:INTERNAL,4" TO "File2"

is a legal statement because the second file specifier's default msvs is the first file specifier's msvs. However, the following statement:

"News1:CS80,700,1" TO "News2:9133,702,0"

will give an error because the files are on different volumes.

If you RE-STORE or RE-SAVE to an HFS file that has links to it, the links will be broken. (This is not true of SRM or SRM/UX files.)

If you OUTPUT to a file that has links to it, the linked files will all have the same contents.

Using LINK with PURGE

You must use LINK with the secondary keyword PURGE to redefine an existing LINK, or an error will result. For example:


100 LINK "exists1" TO "new" 
110 LINK "exists2" TO "new"           this will cause an error




100 LINK "exists1" TO "new" 
110 LINK "exists2" TO "new";PURGE     executes without error

Note that line 110 in the second example breaks the link between new and exists1 and creates a link between new and exists2.

Using Wildcards with LINK

If you are using a version of HP BASIC that supports wildcards, you can use them in file specifiers with LINK. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details. While the old file specifier (source) may match more than one item, the new file specifier (destination) must match one and only one item in all cases. If the wildcard specification for the source matches multiple files, the destination must be a directory.

Note that HP BASIC handles the command

LINK "file_name" TO "dir_name"

in a different manner when wildcards are enabled than when they are disabled.

When wildcards are enabled, HP BASIC permits you to link a file to a directory. It interprets the above command as link the file file_name to the directory called dir_name.

When wildcards are disabled, HP BASIC interprets the above command as link the file file_name to the file called dir_name.

The PURGE secondary keyword allows the LINK command to redefine existing links. It can be used regardless of the state of wildcards.

LINPUT

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

LINPUT accepts alphanumeric input from the keyboard for assignment to a string variable. The LINPUT statement allows commas or quotation marks to be included in the value of the string, and leading or trailing blanks are not deleted.

Example Statements

LINPUT "Next Command?",Response$
LINPUT Array$(I)[3]

Syntax

Item Description Range
prompt a literal composed of characters from the keyboard, including those generated using the ANY CHAR key; Default = question mark --
string name name of a string variable any valid name
subscript numeric expression, rounded to an integer -32 767 through +32 767 (see "array" in Glossary)
beginning position numeric expression, rounded to an integer 1 through 32 767 (see "substring" in Glossary)
ending position numeric expression, rounded to an integer 0 through 32 767 (see "substring" in Glossary)
substring length numeric expression, rounded to an integer 0 through 32 767 (see "substring" in Glossary)

Semantics

A prompt, which remains until the LINPUT item is satisfied, appears on the CRT display line. If the last DISP statement suppressed its CR/LF, the prompt is appended onto the current display line contents. If the last DISP did not suppress the CR/LF, the prompt replaces the current display line contents. Not specifying a prompt results in the question mark being used as the prompt. Specifying the null string ("") for the prompt suppresses the question mark.

[CONTINUE], [ENTER], [EXECUTE], [Return], or [STEP] must be pressed to indicate that the entry is complete. If no value is provided from the keyboard, the null string is used. If [CONTINUE], [ENTER], [EXECUTE], or [Return] is pressed to end the data input, program execution continues at the next program line. If [STEP] is pressed, the program execution continues at the next program line in single step mode. (If the LINPUT was stepped into, it is stepped out of, even if [CONTINUE], [ENTER], [EXECUTE], or [Return] is pressed.)

Live keyboard operations are not allowed while a LINPUT is waiting for data entry. [PAUSE] (or [Stop] on an ITF keyboard) can be pressed so live keyboard operations can be performed. The LINPUT statement is re-executed from the beginning when [CONTINUE] or [STEP] is pressed.

ON KBD, ON KEY and ON KNOB events are deactivated during an LINPUT statement. Errors do not cause an ON ERROR branch. If an input response results in an error, the LINPUT statement is re-executed.

LIST

Supported On UX* WS DOS IN*
Option Required EDIT
Keyboard Executable Yes
Programmable Yes (Except LIST BIN)
In an IF ... THEN ... Yes

LIST lists the program or key definitions currently in memory. LIST BIN lists the names of all the binaries currently loaded in HP BASIC.

Example Statements

LIST
LIST 110,250
LIST #701
LIST #701;Label1,Label2 

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

LIST KEY #Printer

Item Description Range
device selector numeric expression; is rounded to an integer. Default is PRINTER IS device. (see Glossary)
beginning line number integer constant identifying 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 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

Semantics

When a label is used as a line identifier, the lowest-numbered line in memory having that label is used. When a number is used as a line identifier, the lowest-numbered line in memory having a number equal to or greater than the specified line is used. An error occurs if the ending line identifier occurs before the beginning line identifier or if a specified line label does not exist in the program.

Executing a LIST from the keyboard while a program is running causes the program to pause at the end of the current line. The listing is sent to the selected device, and program execution resumes. After the listing is finished, the amount of available memory, in bytes, is displayed.

Note that the default width of the PRINTER IS device is 80 characters, which means that a carriage-return (CR) and line-feed (LF) character will be sent after 80 characters are printed on any one line. You can change this with the WIDTH attribute of the PRINTER IS statement.

LIST #device selector is always done as if the WIDTH OFF printer attribute was in effect.

LIST KEY (Requires KBD and Does Not Require EDIT)

The LIST KEY statement lists the current typing-aid key definitions (not the labels of ON KEY definitions) to the specified device. If a key does not currently have a definition, it will not be listed.

LIST BIN (Does Not Require EDIT)

The LIST BIN statement is not programmable; it can only be used on the command line. LIST BIN lists the binaries currently loaded in memory. The name, version and brief description of the BIN is listed. For example:

NAME VERSION DESCRIPTION
GRAPH 5.0 Graphics
MAT 5.0 Matrix Statements

HP BASIC/UX Specifics

The "available memory" displayed at the end of a LIST, shows the available HP BASIC/UX workspace (not the system memory available).

LISTEN

See SEND.

LIST WINDOW

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

LIST WINDOW lists the currently defined windows and their attributes. This statement can be entered in the HP BASIC/UX/WS editor, but it executes only in HP BASIC/UX in X.

Example Statements

LIST WINDOW

Syntax

Item Description Range
device_selector numeric expression, rounded to integer. Default is PRINTER IS device (see Glossary)

Semantics

This statement is only valid when running under X Windows. It then outputs a table of all currently defined windows and their attributes to the specified device, or if absent to the PRINTER IS device.

When not in a window system, this statement causes an error.

LOAD

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

LOAD loads programs, binaries, or typing-aid softkey definitions into memory.

Example Statements

LOAD Filename$
LOAD "UTIL",Run_line
LOAD BIN "MAT" ! HP BASIC/WS/DOS
LOAD BIN "dir1/dir2/bin_file<SRM_READ_pass>
 :REMOTE 21,5;LABEL Disc" ! HP BASIC/WS/DOS

The following example requires the KBD binary.

LOAD KEY "Typing_aids"

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)
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)
run line number integer constant identifying program line 1 through 32 765 (1 through 2 147 483 646 for HP BASIC/UX 700)
run line label name of a program line any valid name

Semantics

The HP BASIC program currently in memory and all variables not in COM are lost when a LOAD is executed. Every COM block in the newly-loaded program is compared with the COM blocks of the program in memory. If a COM area of the newly-loaded program does not match an existent COM area, the values in the old COM area are lost. Thus, some COM areas may be retained while others are lost.

If a PROG-type file requires a binary program that is not compatible with the current version of HP BASIC, the binary is skipped, a warning is printed, and the program is loaded. If it contains a binary that is compatible with the current version of HP BASIC, the binary is loaded.

LOAD is allowed from the keyboard if a program is not running. If no run line is specified, you must press [RUN] to initiate program execution, and execution will begin on the first line in the program. If a run line is specified, prerun initialization (see RUN) is performed, and program execution begins at the line specified. The line on which execution begins must exist in the main program context of the newly-loaded program. If you specify a line number and it doesn't exist, execution begins with the next higher-numbered line, provided that line is in the main program context.

Executing LOAD from a program causes the new program file to be loaded, prerun, and program execution to resume. Execution begins at the line specified, or the lowest-numbered program line if a run line is not specified.

You can use wildcards to match a file specifiers with LOAD. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details. Wildcard file specifiers used with LOAD must match one and only one file name.

Autostart Program Files

HP BASIC/WS automatically loads and runs a file called AUTOST if the file exists on the boot mass storage device (and if it is of type PROG). If the system is loaded from an HFS volume, the autostart file is /WORKSTATIONS/AUTOST. If the system is loaded from SRM, the autostart file is /SYSTEMS/AUTOSTnn, where nn is the node number of the SRM interface installed in the computer you are booting; if this file does not exist, HP BASIC looks for /AUTOST.

HP BASIC/UX first checks if an autostart file (PROG, PROG2, ASCII, or HP-UX) was specified in the rmb command line. If not, it checks the rmbrc environment file(s). If one is not found, it checks the current directory, and then the home directory, for a file called AUTOST.

HFS Permissions

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

LOAD with SRM Volumes

In order to LOAD a file from an SRM volume, you need to have READ access capability on the file, on the immediately superior directory, and on all other superior directories.

LOAD from an SRM volume is executed in shared mode, which means that several users can LOAD a file at the same time. Files being stored with the STORE or RE-STORE statements are locked during that operation and cannot be accessed for loading.

LOAD Requirements for Device Drivers

With HFS volumes, you must have all drivers for the disk from which you are loading the program. For instance, if you are loading from a CS80-type disk, you must have HPIB, CS80, and HFS binaries currently in memory. (This is not like other volumes. It is required because the Boot ROM does not contain drivers for HFS volumes, but it does contain drivers for LIF and SRM volumes.)

HP BASIC has binaries permanently loaded, but it is necessary to have the correct drivers configured into the HP-UX kernel. For example, if you are loading from a CS80-type disk, you must have the CS80 driver in the kernel. Check by using the rmbconfig program with the -s option.

LOAD BIN (HP BASIC/WS/DOS only)

LOAD BIN is used to load BIN files. (A BIN file contains either language extensions, such as MAT or GRAPH, or drivers, such as DISC and HPIB.) A BIN file may contain more than one of the extensions or drivers; if so only the entensions or drivers not already present in memory are loaded. Executing a LOAD BIN does not affect the currently loaded HP BASIC program or any variables.

HP BASIC/UX has permanently loaded binaries, so this statement is not appropriate for HP BASIC. It generates an error message.

LOAD BIN Requirements for Device Drivers (HP BASIC/WS/DOS only)

BIN files can usually be loaded from a mass storage device even though the BIN(s) to access that device are absent (as long as the Boot ROM has the required drivers). Most Boot ROMs have drivers for LIF and SRM volumes and HP-IB interfaces, but not for HFS volumes. If the Boot ROM does not have the drivers for the device from which you want to load a BIN file, then you will need to first install all required drivers for that device (such as HFS, CS80, and HP-IB).

LOAD BIN with WILDCARDS

Before using a wildcard expression with LOAD BIN, you must load the binaries required to access the file system. For example, before using LOAD BIN with a wildcard on an SRM disk you must first load the SRM and DCOMM binaries.

LOAD BIN with SRM Volumes (HP BASIC/WS/DOS only)

LOAD BIN is executed in shared mode, which means that several users can load a BIN file at the same time. BIN files can be loaded into a workstation from the SRM without the SRM and DCOMM binaries present in the workstation (as described in the preceding paragraph). However, you cannot perform operations like STORE without these binaries.

LOAD KEY (Requires KBD)

LOAD KEY sets the typing-aid definitions of the softkeys according to the contents of the specified BDAT file. If the file is not in the proper format, an error occurs. The file containing the key definitions may be created by a user program. See the STORE KEY statement for file format.

All existing key definitions are cleared before the file's key definitions are loaded.

If LOAD KEY is executed without a file specifier, the keys are reset to their power-on values.

ON KEY definitions are not affected by LOAD KEY.

LOAD KEY with SRM Volumes

In order to LOAD KEY a file on an SRM volume, you need to have READ access capability on the immediately superior directory, as well as READ capability on all other superior directories.

LOAD KEY is executed in shared mode, which means that several users can perform a LOAD KEY from a BDAT file at the same time. Files being stored with the STORE KEY or RE-STORE KEY statements are locked during that operation and cannot be accessed for loading.

HP BASIC/UX Specifics

LOAD BIN generates an error message as it is not appropriate for HP BASIC/UX (binaries are permanently loaded).

LOADSUB

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

LOADSUB loads subprograms from a PROG file into memory.

Example Statements

LOADSUB FNReplace$ FROM "Subs_file"
LOADSUB ALL FROM Subfile$
LOADSUB ALL FROM "/Dir3/Progfile<SRM_READ_pass>"
LOADSUB ALL FROM "/Dir1/Dir2/Prog23"

The following examples requires the PDEV binary.

LOADSUB FROM "My_subs:HP9895,700,1"
LOADSUB FROM "Subs_file"

Item Description Range
subprogram name name of a SUB or CSUB subprogram any valid name
function name name of a user-defined function any valid name
file specifier string expression (see drawing)
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

LOADSUB FROM

The command LOADSUB FROM (without a subprogram name) is not programmable; it is used before a program is run. It looks through the program and notices all the subprogram references which are unsatisfied. Unsatisfied references are statements which reference subprograms that don't yet exist in memory. It then accesses the specified file (which must be a PROG file), (which must have been saved as a .PRG program file), and loads all the needed subprograms, appending them to the end of the current program, renumbering as necessary. It also looks through the subprograms it just loaded to see if they call anything which is not yet in memory. If so, those references will be satisfied. This process repeats for each set of subprograms loaded until all the routines that are referenced are loaded or until it is determined they are not in the specified file. At the end of the LOADSUB FROM command, if there are still unsatisfied references, an error message and a list of the subprograms names still needed is displayed.

LOADSUB with ALL or Subprogram Name

When LOADSUB is used with a subprogram name or ALL, LOADSUB loads the matching subprogram(s) from the specified file. This form of LOADSUB is programmable. If either the file name or the subprogram name specified is not found, or the file name is not a PROG file, an error will occur. As the subprogram is loaded, it will be renumbered to fit at the end of the program. LOADSUB does not cause the program or any data currently in memory to be lost.

HFS Permissions

In order to LOADSUB from a file on an HFS volume, you need to have R (read) access permission on the file, and X (search) permission on the immediately superior directory and on all other superior directories.

LOADSUB with SRM Volumes

In order to LOADSUB from a file on an SRM volume, you need to have READ access capability on the immediately superior directory, as well as READ capability on all other superior directories.

With SRM, LOADSUB is executed in shared mode, which means that several workstations can perform a LOADSUB of a file at the same time. PROG files being stored with the STORE or RE-STORE statement are locked during that operation and cannot be accessed for loading.

LOADSUB with Wildcards

If you are using a version of HP BASIC that supports wildcards, you can use them in file specifiers with LOADSUB. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details. Wildcard file specifiers used with LOADSUB must match one and only one file name.

LOCAL

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

LOCAL returns all specified devices to their local state.

Example Statements

LOCAL @Dvm
LOCAL 728
LOCAL Isc

Syntax

Item Description Range
I/O path name name assigned to a device or devices any valid name (see ASSIGN)
device selector numeric expression, rounded to an integer (see GLOSSARY)

Semantics

If only an interface select code is specified by the I/O path name or device selector, all devices on the bus are returned to their local state by setting REN false. Any existing LOCAL LOCKOUT is canceled.

If a primary address is included, the GTL message (Go To Local) is sent to all listeners. LOCAL LOCKOUT is not canceled.

Bus Actions

Summary of Bus Actions
System Controller Not System Controller
Interface Select Code Only Primary Address Specified Interface Select Code Only Primary Address Specified
Active Controller ___

REN

ATN

MTA

UNL

LAG

GTL

ATN

GTL

ATN

MTA

UNL

LAG

GTL

Not Active Controller ___

REN

Error Error Error

LOCAL LOCKOUT

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

LOCAL LOCKOUT sends the HP-IB LLO (local lockout) message, preventing an operator from returning the specified device from the remote state to local (front panel) control.

Example Statements

LOCAL LOCKOUT 7
LOCAL LOCKOUT Isc
LOCAL LOCKOUT @Hpib

Syntax

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

Semantics

The following conditions must be met to use LOCAL LOCKOUT without error:

Either System Controllers or Non-system Controllers may send LOCAL LOCKOUT.

If a device is in the LOCAL state when this message is sent, it does not take effect on that device until the device receives a REMOTE message and becomes addressed to listen.

LOCAL LOCKOUT does not cause bus reconfiguration, but issues a universal bus command received by all devices on the interface whether addressed or not. The command sequence is ATN and LLO.

Bus Actions

Summary of LOCAL LOCKOUT Bus Actions
System Controller Not System Controller
Interface Select Code Only Primary Address Specified Interface Select Code Only Primary Address Specified
Active Controller ATN

LLO

Error ATN

LLO

Error
Not Active Controller Error Error Error Error

LOCATOR

See READ LOCATOR and SET LOCATOR.

LOCK

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

LOCK prevents other SRM workstations from accessing the remote file to which the I/O path is currently assigned. before closing the file. No locking mechanism is available for LIF.

In HP BASIC/UX, LOCK prevents other processes from accessing a locked HFS file.

Example Statements

LOCK @File;CONDITIONAL Result
IF A THEN LOCK @File;CONDITIONAL Result

Syntax

Item Description Range
I/O path name name identifying an I/O path any valid name (See Glossary)
return variable name of a numeric variable any valid name (See Glossary.)

Semantics

This statement establishes sole access to an SRM file that has been opened with an ASSIGN statement. This exclusive access remains assigned to the workstation (or SRM, or HP BASIC/UX process) executing the LOCK statement until an UNLOCK statement is executed by that workstation. The UNLOCK function is also a result of SCRATCH A, [RESET], and ASSIGN ... TO * (explicitly closing an I/O path).

A file may be locked several times. The system counts the number of LOCKs on a file, and an equal number of UNLOCKs must be executed to unlock the file. When an I/O path name is closed (for example, by ASSIGN ... TO *), all LOCKs of that I/O path name are cleared.

If the LOCK is successful, the value of the return variable will be zero. Otherwise, the return variable's value will be the error number corresponding to the cause of the LOCK's failure.

HP BASIC/UX Specifics

HP BASIC/UX supports LOCK for HFS files: establishing exclusive access to a file by the HP BASIC/UX process. In order to LOCK the file exclusively, you must have write permission on the file. You may LOCK a file with read-only permission if you have the LOCKRDONLY kernel privilege (see setprivprg(1M)). In addition, you must either own the file, or the file must have the set group-id bit on and the group search bit off. If this is not the case, an attempt is made to set up an advisory lock.

HP BASIC/UX does not support locking of RFA, NFS, or LIF files, although no error is generated when the LOCK statement is executed. Locking of pipes is not allowed; an attempt to LOCK a pipe generates a run-time error.

Also note that if two or more HP BASIC/UX processes are running on the same workstation, commands such as ENTER and OUTPUT will not block waiting for an SRM file to be unlocked. Instead, they generate an error.

HP BASIC/DOS Specifics

HP BASIC/DOS does not support LOCK for DFS files.

LOG

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

LOG returns the natural logarithm (base e) of the argument.

Example Statements

Time=-1*Rc*LOG(Volts/Emf)
PRINT "Natural log of";Y;"=";LOG(Y)

Syntax

Item Description/Default Range\Restrictions
argument numeric expression > 0 for INTEGER and REAL arguments; see Range Restriction Specifics for COMPLEX arguments and underflow restrictions

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 LOG of a COMPLEX value, the COMPLEX binary must be loaded.

Range Restriction Specifics

The formula used for computing the LOG of a COMPLEX value is:

CMPLX(LOG(ABS(Argument)),ARG(Argument))

where Argument is a COMPLEX argument to the LOG function. The imaginary part of the result (ARG(Argument)) is always given in radians and is between -&pi; and =&pi;. Some values of a COMPLEX argument may cause errors in this computation. For example:

LOG(CMPLX(MAXREAL,MAXREAL))

will cause error 22 (error 21 in HP BASIC/UX 700) due to the ABS(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 +1.79769313486232E+308 +1.79769313486232E+308
Positive Minimum +2.22507385850720E-308 +4.94065645841247E-324 1

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

LOOP

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

LOOP defines a loop which is repeated until the expression in an EXIT IF statement is evaluated as true (non-zero).

Example Program Segments


100  ! Reading to the end of a file
110  ASSIGN @File TO "MYFILE"
110  ON EOF GOSUB Done
120  LOOP
130     ENTER @File;Text$
140  END LOOP
150  Done: ! 

100  ! Process control loop
110  LOOP
120     Level=FNGet_level
130     EXIT IF Level>High_level
140     Pressure=FNSet_press(Decrease)
150     EXIT IF Pressure Low_press
160 END LOOP 

Syntax

Item Description Range
boolean expression numeric expression; evaluated as true if nonzero and false if 0 --
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

The LOOP...END LOOP construct allows continuous looping with conditional exits which depend on the outcome of relational tests placed within the program segments. The program segments to be repeated start with the LOOP statement and end with END LOOP. Reaching the END LOOP statement will result in a branch to the first program line after the LOOP statement.

Any number of EXIT IF statements may be placed within the construct to escape from the loop. The only restriction upon the placement of the EXIT IF statements is that they must not be part of any other construct which is nested within the LOOP...END LOOP construct.

If the specified conditional test is true, a branch to the first program line following the END LOOP statement is performed. If the test is false, execution continues with the next program line within the construct.

Branching into a LOOP...END LOOP construct (via a GOTO) results in normal execution from the point of entry. Any EXIT IF statement encountered will be executed. If execution reaches END LOOP, a branch is made back to the LOOP statement, and execution continues as if the construct had been entered normally.

Nesting Constructs Properly

LOOP...END LOOP may be placed within other constructs, provided it begins and ends before the outer construct can end.

LORG

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

LORG specifies the relative origin of labels or symbols with respect to the current pen position.

Example Statements

LORG New_lorg
IF Y>Limit THEN LORG 3

Syntax

Item Description Range
label origin position numeric expression, rounded to an integer; Default = 1 1 through 9

Semantics

The following drawings show the relationship between a label and the logical pen position. The pen position before the label is drawn is represented by a cross marked with the appropriate LORG number.

LWC$

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

LWC$ replaces any uppercase characters with their corresponding lower-case characters.

Example Statements

Lower$=LWC$(Mixed$)
IF LWC$(Answer$)="y" THEN True_test

Syntax

Semantics

The LWC$ function converts only uppercase alphabetic characters to their corresponding lowercase characters and will not alter numerals or special characters.

The corresponding characters for the Roman Extension alphabetic characters are determined by the current lexical order. When the lexical order is a user-defined table, the correspondence is determined by the STANDARD lexical order.

Two-Byte Language Specifics

Certain localized versions of HP BASIC, such as Japanese localized HP BASIC, support two-byte characters. The LWC$ function converts only one-byte characters and does not change two-byte characters. For more information about two-byte characters, refer to the globalization chapters of the HP BASIC Porting and Globalization manual.