ECHO - EXPANDED

ECHO

See SET ECHO.

EDGE

EDGE is a secondary keyword used to draw a border around the regions specified by these graphics keywords:

EDIT

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

EDIT activates the editor, letting you enter a new program or modify a program already in memory. EDIT also lets you edit typing-aid key definitions.

Example Statements

The following examples requires the EDIT binary.


  EDIT
 
  EDIT Label2

  EDIT 1000,5

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


  EDIT KEY 5

Syntax

Item Description Range
line number integer constant identifying program line; Default (see Semantics) 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
line label name of a program line any valid name
increment integer constant; Default = 10 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
key number integer constant 0 through 23

Semantics

The EDIT command allows you to scroll through a program in the computer by using the arrow keys, [Prev], [Next], or the knob. Lines may be added to the end of a program by going to the bottom of the program. A new line number will be provided automatically. Lines may be added between existing program lines by using the insert line key, and lines may be deleted by using the delete line key. Lines may be modified by typing the desired characters over the existing line, using the insert character and delete character keys as necessary. [ENTER], [EXECUTE] or [Return] are used to store the newly created or modified lines.

Edit mode is exited by pressing [CONTINUE], [CLR SCR], [Clear display], [PAUSE], [Stop], [RESET], [RUN], or [STEP] or by executing CAT, LIST (if PRINTER IS CRT), GET, or LOAD. In general any PRINT to the CRT (e.g., executing DISP) will exit you from the EDIT mode.

If the program was changed while paused, pressing [CONTINUE] will cause an error. Modifying a program moves it to the stopped state, making it impossible to continue.

EDIT Without Parameters

If no program is currently in the computer, the edit mode is entered at line 10, and the line numbers are incremented by 10 as each new line is stored. If a program is in the computer, the line at which the editor enters the program is dependent upon recent history. If an error has paused program execution, the editor enters the program at the line flagged by the error message. Otherwise, the editor enters the program at the line most recently edited (or the beginning of the program after a LOAD operation).

EDIT With Parameters

If no program is in the computer, a line number (not a label) must be used to specify the beginning line for the program. The increment will determine the interval between line numbers. If a program is in the computer, any increment provided is not used until lines are added to the program. If the line specified is between two existing lines, the lowest-numbered line greater than the specified line is used. If a line label is used to specify a line, the lowest-numbered line with that label is used. If the label cannot be found, an error is generated.

EDIT KEY

To enter the EDIT KEY mode, type EDIT KEY, followed by the key number, and press [EXECUTE], [ENTER], or [Return]. Also, the desired softkey can be pressed after typing or pressing EDIT. When EDIT KEY mode is entered, the current key definition (if any) is displayed. You then edit the contents as if it were any other keyboard line. Non-ASCII keys may be included in the key definition by holding [CTRL] while pressing the desired key. Non-ASCII keystrokes are represented by an inverse-video "K" followed by another character associated with the key. The table Second Byte of Non-ASCII Key Sequences in the "Useful Tables" section of this manual has a list of the characters associated with the special keys.

NOTE
On the HP 98203A keyboard, many non-ASCII keys cannot be accessed by the method of holding [CTRL] while pressing the desired key. However, any of the non-ASCII keys can be entered into a softkey definition by pressing [ANY CHAR] 255, followed by the character associated with that non-ASCII key.

To accept the modified key definition, press [ENTER] or [Return]; to abort without changing the current definition, press [PAUSE], [CLR SCR] or [Clear display].

When a program is waiting for a response to an INPUT, LINPUT or ENTER, the typing aid definitions (defined with EDIT KEY) are in effect. When a program is running but not waiting for user input, the active ON KEY definitions supersede the typing aid definitions. Softkeys without ON KEY definitions retain their typing-aid function.

ELSE

See IF...THEN.

ENABLE

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

ENABLE re-enables all event-initiated branches which were suspended by DISABLE. ON END, ON ERROR, and ON TIMEOUT are not affected by ENABLE and DISABLE.

Example Statements

ENABLE

Syntax

ENABLE EXT SIGNAL

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

ENABLE EXT SIGNAL enables the specified system-generated signal which can cause end-of-statement branches or default actions. This statement can be entered in the HP BASIC/UX/WS editor, but executes only in HP BASIC/UX .

Example Statements

ENABLE EXT SIGNAL 4
ENABLE EXT SIGNAL Sigsys

Syntax

Item Description Range
signal number numeric expression, rounded to integer 1 through 32 (see ON EXT SIGNAL)

Semantics

EXT SIGNALs default to enabled, and thus this statement is only needed if a DISABLE EXT SIGNAL statement has been executed. Note that the default action will take place unless an ON EXT SIGNAL statement is executed (see ON EXT SIGNAL).

Only supported system signals may be specified. See ON EXT SIGNAL for a list of valid signal numbers.

ENABLE INTR

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

ENABLE INTR enables the specified interface to generate an interrupt which can cause event-initiated branches.

Example Statements

ENABLE INTR 7
ENABLE INTR Isc;Mask

Syntax

Item Description Range
interface select code numeric expression, rounded to an integer 5, and 7 through 31
bit mask numeric expression, rounded to an integer -32 768 through +32 767

Semantics

If a bit mask is specified, its value is stored in the interface's interrupt-enable register. See the interface documentation for the correct bit mask value interpretation.

If no bit mask is specified, the previous bit mask for the select code is restored. A bit mask of all zeros is used when there is no previous bit mask.

END

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

END marks the end of the main program. For information about END as a secondary keyword, see OUTPUT and SEND

Example Statements

END

Syntax

Semantics

END must be the last statement (other than comments) of a main program. Only one END statement is allowed in a program. Program execution may also be terminated with a STOP statement, and multiple STOP statements are allowed. END terminates program execution, stops any event-initiated branches, and clears any unserviced event-initiated branches. CONTINUE is not allowed after an END statement.

Subroutines used by the main program must be located before the END statement. Subprograms and user-defined functions must be located after the END statement.

END IF

See IF...THEN.

END LOOP

See LOOP.

END SELECT

See SELECT...CASE.

END WHILE

See WHILE.

ENTER

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

ENTER is used to input data from a device, file, string, buffer, window, or pipe, and assign the entered values to variables.

Example Statements

ENTER 705;Number,String$
ENTER Device;X;Y;Z
ENTER Command$;Parameter
ENTER @File;Array(*)
ENTER @Random,Record USING 20;Text$(Line)
ENTER @Source USING Fmt5;Item(1),Item(2),Item(3)
ENTER 12 USING "#,6A";A$[2;6]

Syntax

Item Description Range
I/O path name name assigned to a device(s), mass storage file, buffer, window, or pipe any valid name (see ASSIGN)
record number numeric expression, rounded to an integer 1 through 231-1
device selector numeric expression, rounded to an integer (see Glossary)
source 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)
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)
numeric name name of a numeric variable any valid name
string name name of a string variable any valid name
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)
image specifier list literal (see next drawing)
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 Number Builder

If the data being received is ASCII and the associated variable is numeric, a number builder is used to create a numeric quantity from the ASCII representation. The number builder ignores all leading non-numeric characters, ignores all blanks, and terminates on the first non-numeric character, or the first character received with EOI true. (Numeric characters are 0 through 9, +, -, decimal point, e, and E, in a meaningful numeric order.) If the number cannot be converted to the type of the associated variable, an error is generated. If more digits are received than can be stored in a variable of type REAL or COMPLEX, the rightmost digits are lost, but any exponent will be built correctly. Overflow occurs only if the exponent overflows. COMPLEX numbers are treated like two real numbers, the first representing the real part and the second representing the imaginary part. When an ENTER statement contains a COMPLEX variable, that variable is satisfied with two REAL values.

Arrays

Entire arrays may be entered by using the asterisk specifier. Each element in an array is treated as an item by the ENTER statement, as if the elements were listed separately. The array is filled in row major order (rightmost subscript varies fastest). COMPLEX arrays are treated as if they were REAL arrays with twice as many elements.

Files as Source

If an I/O path has been assigned to a file, the file may be read with ENTER statements. The file must be an ASCII, BDAT, DFS, or HP-UX file. The attributes specified in the ASSIGN statement are used only if the file is a BDAT, DOS, or HP-UX file. Data read from a LIF ASCII file (a file created using CREATE ASCII) is always in ASCII format (i.e., you cannot use ENTER..USING); however, you can enter the data into a string variable, and then use ENTER..USING from the string variable. Data read from a BDAT or HP-UX file is considered to be in internal representation with FORMAT OFF, and is read as ASCII characters with FORMAT ON.

Serial access is available for ASCII, BDAT, DOS, and HP-UX files. Random access is available for BDAT and HP-UX files. The file pointer is important to both serial and random access. The file pointer is set to the beginning of the file when the file is opened by an ASSIGN. The file pointer always points to the next byte available for ENTER operations.

Random access uses the record number parameter to read items from a specific location in a file. The record specified must be before the end-of-file pointer. The ENTER begins at the beginning of the specified record.

It is recommended that random and serial access to the same file not be mixed. Also, data should be entered into variables of the same type as those used to output it (e.g. string for string, REAL for REAL, etc.).

In order to read a file in an SRM directory, you need to have READ capability on the immediately superior directory, as well as READ capabilities on all other superior directories. If this capability is not public or if a password protecting this capability was not used at the time the file was assigned an I/O path name (with ASSIGN), an error is reported.

Devices as Source

An I/O path name or a device selector may be used to ENTER from a device. If a device selector is used, the default system attributes are used (see ASSIGN). If an I/O path name is used, the ASSIGN statement determines the attributes used. If multiple devices were specified in the ASSIGN, the ENTER sets the first device to be talker, and the rest to be listeners. You can improve performance for some interfaces on Series 300/400 computers by enabling io_burst, and on Series 700 computers by enabling ENTER buffering. See the HP BASIC Interface Reference for more information about improving performance.

If FORMAT ON is the current attribute, the items are read as ASCII. If FORMAT OFF is the current attribute, items are read from the device in the computer's internal format. Two bytes are read for each INTEGER, eight bytes for each REAL, and sixteen bytes for each COMPLEX value. Each string entered consists of a four byte header containing the length of the string, followed by the actual string characters. The string must contain an even number of characters; if the length is odd, an extra byte is entered to give alignment on the word boundary.

CRT as Source

If the device selector is 1, the ENTER is from the CRT. The ENTER reads characters from the CRT, beginning at the current print position (print position may be modified by using TABXY in a PRINT statement.) The print position is updated as the ENTER progresses. After the last non-blank character in each line, a line-feed is sent with a simulated "EOI". After the last line is read, the print position is off the screen. If the print position is off screen when an ENTER is started, the off-screen text is first scrolled into the last line of the display.

Keyboard as Source

ENTER from device selector 2 may be used to read the keyboard. An entry can be terminated by pressing [ENTER], [EXECUTE], [Return], [CONTINUE], or [STEP]. Using [ENTER], [EXECUTE], [Return] or [STEP] causes a CR/LF to be appended to the entry. The [CONTINUE] key adds no characters to the entry and does not terminate the ENTER statement. If an ENTER is stepped into, it is stepped out of, even if the [CONTINUE] key is pressed. An HP-IB EOI may be simulated by pressing [CTRL] [E] before the character to be sent, if this feature has been enabled by an appropriate CONTROL statement to the keyboard (see the Control and Status Registers in the back of this book).

Strings as Source

If a string name is used as the source, the string is treated similarly to a file. However, there is no file pointer; each ENTER begins at the beginning of the string, and reads serially within the string.

Buffers as Source

When entering from an I/O path assigned to a buffer, data is removed from the buffer beginning at the location indicated by the buffer's empty pointer. As data is received, the current number-of-bytes register and empty pointer are adjusted accordingly. Encountering the fill pointer (buffer empty) produces an error unless a continuous inbound TRANSFER is filling the buffer. In this case, the ENTER will wait until more data is placed in the buffer.

Since devices are logically bound to buffers, an ENTER statement cannot intercept data while it is traveling between the device and the buffer. If an I/O path is currently being used in an outbound TRANSFER, and an ENTER statement uses it as a source, execution of the ENTER is deferred until the completion of the TRANSFER. An ENTER can be concurrent with an inbound TRANSFER only if the source is the I/O path assigned to the buffer.

An ENTER from a string variable that is also a buffer will not update the buffer's pointers and may return meaningless data.

Pipes as Source

If an I/O path has been assigned to a pipe, the pipe may be read with ENTER statements. The attributes specified in the ASSIGN statement are used. Data is considered to be in internal representation with FORMAT OFF, and is read as ASCII characters with FORMAT ON. (See "Devices as Source" for a description of these formats.) The pipe must be read serially. You can also use ENTER with pipes named in SRM/UX on HP BASIC/UX , and in HP BASIC/WS .

ENTER With USING

When the computer executes an ENTER 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 no variable is required for the field specifier, the field specifier is acted upon without referencing the enter items. When the field specifier references a variable, bytes are entered and used to create a value for the next item in the enter list. Each element in an array is considered a separate item.

The processing of image specifiers stops when a specifier is encountered that has no matching enter item. If the image specifiers are exhausted before the enter items, the specifiers are reused, starting at the beginning of the specifier list.

Entry into a string variable always terminates when the dimensioned length of the string is reached. If more variables remain in the enter list when this happens, the next character received is associated with the next item in the list.

When USING is specified, all data is interpreted as ASCII characters. FORMAT ON is always assumed with USING, regardless of any attempt to specify FORMAT OFF.

ENTER with USING cannot be used to enter data from LIF ASCII files (files created by CREATE ASCII. Instead, enter the item(s) into a string variable, then use ENTER with USING to enter the item(s) from the string variable. For example, use ENTER @File;String$ then ENTER String$ USING "5A,X,5DD"; Str2$,Number.

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

Image\Specifier Meaning

K

Freefield Entry. Numeric Entered characters are sent to the number builder. Leading non-numeric characters are ignored. All blanks are ignored. Trailing non-numeric characters and characters sent with EOI true are delimiters. Numeric characters include digits, decimal point, +, -, e, and E when their order is meaningful. String Entered characters are placed in the string. Carriage-return not immediately followed by line-feed is entered into the string. Entry to a string terminates on CR/LF, LF, a character received with EOI true, or when the dimensioned length of the string is reached.

-K

Like K except that LF is entered into a string, and thus CR/LF and LF do not terminate the entry.

H

Like K, except that the European number format is used. Thus, a comma is the radix indicator and a period is a terminator for a numeric item. (Requires IO)

-H

Same as -K for strings; same as H for numbers. (Requires IO)

S

Same action as D.

M

Same action as D.

D

Digit specifier demands a character. Non-numerics are accepted to fill the character count. Blanks are ignored, other non-numerics are delimiters.

Z

Same action as D.

*

Same action as D. (Requires IO)

.

Same action as D.

R

Like D, R demands a character. When R is used in a numeric image, it directs the number builder to use the European number format. Thus, a comma is the radix specifier and a period is a terminator for the numeric item. (Requires IO)

E

Same action as 4D.

ESZ

Same action as 3D.

ESZZ

Same action as 4D.

ESZZZ

Same action as 5D.

A

Demands a string character. Any character received is placed in the string. Use AA or 2A for two-byte globalization characters.

X

Skips a character.

literal

Skips one character for each character in the literal.

B

Demands one byte. The byte becomes a numeric quantity.

W

Demands one 16-bit word, which is interpreted as a 16-bit, two's-complement integer. If either an I/O path name with the BYTE attribute or a device selector is used to access an 8-bit interface, two bytes will be entered; the most-significant byte is entered first. If an I/O path name with the BYTE attribute is used to access a 16-bit interface, the BYTE attribute is overridden and one word is entered in a single operation. If an I/O path name with the WORD attribute is used to access a 16-bit interface, one byte is entered and ignored when necessary to achieve alignment on a word boundary. If the source is a file, string variable, or buffer, the WORD attribute is ignored and all data are entered as bytes; however, one byte will be entered and ignored when necessary to achieve alignment on a word boundary.

Y

Like W, except that pad bytes are never entered to achieve word alignment. If an I/O path name with the BYTE is used to access a 16-bit interface, the BYTE attribute is not overridden (as with W specifier above). (Requires IO)

#

Statement is terminated when the last ENTER item is terminated. EOI and line-feed are item terminators, and early termination is not allowed.

%

Like #, except that an END indication (such as EOI or end-of-file) is an immediate statement terminator. Otherwise, no statement terminator is required. Early termination is allowed if the current item is satisfied.

+

Specifies that an END indication is required with the last character of the last item to terminate the ENTER statement. Line-feeds are not statement terminators. Line-feed is an item terminator unless that function is suppressed by -K or -H. (Requires IO)

-

Specifies that a line-feed terminator is required as the last character of the last item to terminate the statement. EOI is ignored, and other END indications, such as EOF or end-of-data, cause an error if encountered before the line-feed. (Requires IO)

/

Demands a new field; skips all characters to the next line-feed. EOI is ignored.

L

Ignored for ENTER.

@

Ignored for ENTER.

NOTE
Some localized versions of HP BASIC , such as Japanese localized HP BASIC , support two-byte characters. When using this localized language remember that the IMAGE, ENTER USING, OUTPUT USING, and PRINT USING statements define a one-byte ASCII character image with A. Use the image AA to designate a two-byte character.

For a general discussion of globalization and localization, refer to the HP BASIC Porting and Globalization manual. For LANGUAGE specific details, refer to Using LanguageX With HP BASIC , where LanguageX is your local language.

ENTER Statement Termination

A simple ENTER statement (one without USING) expects to give values to all the variables in the enter list and then receive a statement terminator. A statement terminator is an EOI, a line-feed received at the end of the last variable (or within 256 characters after the end of the last variable), an end-of-data indication, or an end-of-file. If a statement terminator is received before all the variables are satisfied, or no terminator is received within 256 bytes after the last variable is satisfied, an error occurs. The terminator requirements can be altered by using images.

An ENTER statement with USING, but without a % or # image specifier, is different from a simple ENTER in one respect. EOI is not treated as a statement terminator unless it occurs on or after the last variable. Thus, EOI is treated like a line-feed and can be used to terminate entry into each variable.

An ENTER statement with USING that specifies a # image requires no statement terminator other than a satisfied enter list. EOI and line feed end the entry into individual variables. The ENTER statement terminates when the variable list has been satisfied.

An ENTER statement with USING that specifies a % image allows EOI as a statement terminator. Like the # specifier, no special terminator is required. Unlike the # specifier, if an EOI is received, it is treated as an immediate statement terminator. If the EOI occurs at a normal boundary between items, the ENTER statement terminates without error and leaves the value of any remaining variables unchanged.

When entering FORMAT ON text into string variables, care should be taken to avoid unexpected interactions between terminating on dimensioned string length and termination on line feeds in the text. It is recommended that the string variable be dimensioned at least two characters longer than the text if it will be terminated by a carriage return/line feed.

See the HP BASIC Programming Guide,"Entering Data" for more information.

EOL

See ASSIGN, PRINTALL IS, and PRINTER IS.

EOR

See OFF EOR, ON EOR, and TRANSFER.

EOT

See OFF EOT and ON EOT.

ERRDS

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

ERRDS returns an INTEGER representing the device selector of the I/O resource involved in the most recent I/O error.

Example Statements

IF ERRDS=701 THEN GOSUB Print_error
IF ERRN=163 THEN Missing=ERRDS

Syntax

Semantics

The device selector will include a primary address if the interface addressed allows it (i.e. HP-IB). If the resource is a file, the device selector of the drive containing the file is returned. If the resource is not a device, 0 is returned. If no I/O error has occurred in a running program since power-up, SCRATCH A, or pre-run, 0 is returned.

If an error occurs in a TRANSFER statement without WAIT, the error number is recorded in the assignment table associated with the I/O path name assigned to the non-buffer end of the transfer instead of being reported immediately. It is not reported until the next reference to the I/O path name, and ERRDS will not be updated until this time.

ERRL

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

ERRL returns a value of 1 if the most recent error occurred in the specified line; otherwise, it returns 0.

Example Statements

IF ERRL(220) THEN Parse_error
IF NOT ERRL(Parameters) THEN Other

Syntax

Item Description Range
line number integer constant 1 through 32 766 (1 through 2 147 483 646 for HP BASIC/UX 700)
line label name of a program line any valid name

Semantics

The specified line must be in the same context as the ERRL function, or an error will occur.

If an error occurs in a TRANSFER statement without WAIT, the error number is recorded in the assignment table associated with the non-buffer end of the transfer instead of being reported immediately. It is not reported until the next reference to the I/O path name, and ERRL will not be updated until this time. Therefore, ERRL will actually refer to the line containing the new reference to the I/O path name, not the line containing the TRANSFER statement that caused the error.

CLEAR ERROR resets ERRL to 0.

Data Communications

This function returns 0 for all data communications errors.

ERRLN

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

ERRLN returns the number of the program line on which the most recent error occurred. If no error has occurred, this function returns a value of 0.

Example Statements

Bad_line=ERRLN
IF ERRLN=240 THEN GOSUB Fix_240

Syntax

Semantics

ERRLN will return 0 if no error has occurred since one of these events:

If an error occurs in a TRANSFER without WAIT, the error number is recorded in the assignment table associated with the non-buffer end of the TRANSFER instead of being reported immediately. It is not reported until the next reference to the I/O path name, and ERRLN will not be updated until this time. Therefore, ERRLN will actually refer to the line containing the new reference to the I/O path name, not the line containing the TRANSFER statement that caused the error.

Data Communications

This function returns 0 for all Data Communications errors (which occur while using the HP 98628 Datacomm Interface).

ERRM$

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

ERRM$ returns the text of the error message associated with the most recent program execution error.

Example Statements

PRINT ERRM$
Em$+ERRM$
ENTER Em$;Error_num,Error_line

Syntax

Semantics

The line number and error number returned in the ERRM$ string are the same as those used by ERRN and ERRL. This may give surprising results when a TRANSFER is in effect. For details on the interaction, see ERRL and ERRN.

ERRM$ will return the null string if no error has occurred since one of these events:

HP BASIC/UX Specifics

Additional error messages specific to HP BASIC/UX are returned.

ERRN

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

ERRN returns the number of the most recent program execution error. If no error has occurred, a value of 0 is returned.

Example Statements

IF ERRN+80 THEN Disc_out
DISP "Error Number = ";ERRN

Syntax

Semantics

CLEAR ERROR resets ERRN to 0.

If an error occurs in a TRANSFER statement without WAIT, the error number is recorded in the assignment table associated with the non-buffer end of the transfer instead of being reported immediately. It is not reported until the next reference to the I/O path name, and ERRN will not be updated until this time.

HP BASIC/UX Specifics

ERRN returns additional error values specific to HP BASIC/UX .

ERROR

See CAUSE ERROR, CLEAR ERROR, OFF ERROR and ON ERROR.

ERROR RETURN

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

ERROR RETURN returns program control to the line following the line which caused the most recent GOSUB. It is used with ON ERROR GOSUB to avoid retrying the line that caused the error.

Example Statements

ERROR RETURN
IF Dont_retry THEN ERROR RETURN

Syntax

Semantics

When this statement is executed, it causes program execution to resume at the line following the line that caused the most recent GOSUB (usually the line whose error initiated the most recent ON ERROR GOSUB branch). If you want to return to the line that caused the error, use RETURN.

If the error occurred in an END, SUBEND, or FN END statement, then execution returns to that statement since there is no following executable line. If the statement is used to return from a GOSUB, then it behaves as a RETURN.

ERROR SUBEXIT

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

ERROR SUBEXIT returns program control to the line following the line which invoked the subprogram.

Example Statements

ERROR SUBEXIT
IF Dont_retry THEN ERROR SUBEXIT

Syntax

Semantics

When this statement is executed, it causes program execution to resume at the line following the line that caused the subprogram to be called (usually the line whose error initiated the most recent ON ERROR CALL branch). If you want to return to the line that caused the error, use SUBEXIT.

If the error occurred in an END, SUBEND, or FN END statement, then execution returns to that statement since there is no following executable line. If this statement is used from a CALL, then it behaves as a SUBEXIT.

EXCHANGE

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

EXECUTE

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

EXECUTE allows access to the underlying operating system for executing commands and programs. This statement can be entered in the HP BASIC editor, but it executes only in HP BASIC/UX or HP BASIC/DOS .

Example Statements

EXECUTE
EXECUTE ; SAVE ALPHA OFF, RETURN Success

EXECUTE "cat mydat sed -e 's/real/longreal' |myfilt>foo";WAIT OFF
EXECUTE "DIR > C:\TMP\DIRLST"

Syntax

Item Description Range
command string expression -
return variable name name of a numeric variable any valid name

Semantics ( HP BASIC/UX )

This statement suspends the operation of HP BASIC and transfers control to the operating system. If a command string is specified, then the operating system executes that command string. If the command string is omitted, then control is passed to the command specified in the user's SHELL environment variable (this is usually a shell). If the user has no SHELL environment variable, then control is passed to a Bourne shell (/bin/sh).

If the RETURN attribute is specified, then the return status from the command is returned in the associated variable. The return status consists of 16 bits of information defined as:

MSB                                                                                         LSB

15   14   13   12   11   10   9   8   7   6   5   4   3   2   1   0  

return code

cd

terminating signal

where:

terminating signal is the signal causing process termination
cd indicates whether a core dump resulted
return code is the process exit code if the terminating signal field is 0.

Note that when a command is specified, a /bin/sh is used to control the execution of the command. This shell translates certain return codes from the command. Specifically, return codes indicating a signal has killed the process returns as 0x8000+0x100*signal number, rather than the expected signal number. Thus a distinction cannot be made between a process terminated by SIGTERM and one which exited with return code 0x8f, since both would be received as ox8f00.

If a simple command is executed (i.e., a single command and no pipes), then there is a workaround to this problem. The SHELL command exec can be inserted before the actual command to indicate that the shell should exec the command rather than forking a new process for it. The result of this is that without the shell around to translate the return code, the expected return code is received. For example, consider a "ps -ef" command. The statement:


     EXECUTE "ps -ef"; WAIT OFF,RETURN A

would set A to 0x8f00 if terminated by SIGTERM. If we wanted the return code to be the same as the process actually returned (without shell translation), we would use:


    EXECUTE "exec ps -ef"; WAIT OFF,RETURN A

which sets A to 0x0f when terminated by SIGTERM. Note also that the most significant bit of the return status is weighted as -32768, thus the status is negative when this bit is set.

When running within a window system, the command is executed in the window which started HP BASIC . Note that this is not the standard HP BASIC window, as HP BASIC automatically spawns a new window for itself. All input and output from the EXECUTEd process takes place in this original window. HP BASIC spawns a new process from which to execute the command. During this time, the HP BASIC process waits for the command to complete. A new runlight state "Execute" indicates when HP BASIC is waiting for a system command to complete. HP BASIC continues to accept keys and echo them, but no keyboard commands are executed until the system call completes. The "Reset" key aborts the system call and returns HP BASIC to the idle state. Note that RESET sends SIGHUP to the partially completed command and all of its subprocesses, which causes them to die.

When this command is executed outside of a window system, HP BASIC first clears the screen and then spawns a new process to execute the command. At this point HP BASIC waits for the command to complete. HP BASIC relinquishes control of the keyboard so the user's command may access it. To return to HP BASIC the user must either wait for the process to complete, or kill it. To kill the process the user must use either SIGTERM or SIGKILL, or possibly "exit" for a shell. When the user process completes, HP BASIC first prompts the user before resuming. The prompt "PRESS RETURN TO CONTINUE:" appears at the bottom of the screen. This allows the user time to read any output from the command before HP BASIC clears the screen. The cursor and paging keys are not transmitted, and may be used to view text that has scrolled off the screen; other keys are ignored. After receiving the response, HP BASIC continues. It first clears the screen of the output from the command, and then repaints the alpha screen.

The WAIT OFF attribute disables the prompting after completion of the command. In this case HP BASIC immediately resumes operation. This attribute only affects operation outside a window system. If a command is not specified in the EXECUTE statement, then HP BASIC does not prompt before resumming control. It will continue as soon as the shell is exited.

The SAVE ALPHA OFF attribute only affects operation outside a window system. In this case, the screen is not cleared before executing the command, and it is not cleared and the alpha not repainted upon returning to HP BASIC . This option thus allows any graphics information to be saved. It should generally be used only when the command does not produce output to the CRT. Otherwise the commands output can cause scrolling of the alpha and graphics in an undesirable way. If the command does produce output, it should be redirected to a file, or discarded in /dev/null as follows:


      EXECUTE "rmbclean >/dev/null 2>&1"; SAVE ALPHA OFF

The string "2>&1" causes the standard error output to also be discarded. Note that the WAIT prompting also writes text to the screen (and possibly cause scrolling). Thus this attribute should in general be used with the WAIT OFF attribute.

Semantics ( HP BASIC/DOS )

This statement suspends the operation of HP BASIC and transfers control to a copy of COMMAND.COM. If a command string is specified, then COMMAND.COM executes that command string. If a command string is omitted, then COMMAND.COM accepts commands from the user. The user returns to HP BASIC by typing EXIT at the prompt.

If the SAVE ALPHA OFF attribute is specified, then the screen is not cleared before control is passed to COMMAND.COM, and it is not cleared and repainted upon returning to HP BASIC . This option allows any graphics information to be saved. It should generally be used only when the command does not produce output to the CRT. Otherwise, undesirable scrolling of the alpha and graphics may occur.

The WAIT OFF attribute disables prompting after completion of the command or when the user exits COMMAND.COM. HP BASIC resumes operation immediately after COMMAND.COM terminates.

If the RETURN attribute is specified, then the return status from COMMAND.COM is returned in the associated variable. Note that this indicates only if COMMAND.COM was successfully run. It does not indicate whether or not COMMAND.COM was able to successfully execute the command string.

If the command string is "BACKGROUND", then COMMAND.COM is not run as described above. Instead, HP BASIC is put into background mode and continues to run concurrently with DOS. The WAIT OFF and ALPHA OFF attributes are ignored, and the value returned by the RETURN attribute is always 1. See the Installing and Using HP BASIC/DOS 6.2 manual for more detailed information on background mode.

EXIT IF

See LOOP.

EXOR

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

EXOR returns a 1 or a 0 based on the logical exclusive OR of its arguments.

Example Statements

   Ok=First_pass EXOR Old_data
   IF A EXOR Flag THEN Exit

Syntax

Semantics

A non-zero value (positive or negative) is treated as a logical 1; only a zero is treated as a logical 0.

The EXOR function is summarized in this table.

A B A EXOR B
0 0

0

0 1

1

1 0

1

1 1

0

EXP

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

EXP raises e to the power of the argument. Internally, Napierian e=2.718 281 828 459 05.

Example Statements

Y=EXP(-X^2/2)
PRINT "e to the";Z;"=";EXP(Z)

Syntax

Item Description/Default Range\Restrictions
argument     numeric expression    -708.396 418 532 264 through

+709.782 712 893 383 8 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 EXP of a COMPLEX value, the COMPLEX binary must be loaded.

Range Restriction Specifics

The formula used to compute the EXP of a COMPLEX argument is:

CMPLX(EXP(Real_part)*COS(Imag_part),EXP(Real_part)*SIN(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,

EXP(CMPLX(710,0))

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

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 +7.09782712893384E+002 +7.09782712893384E+002
Negative Minimum -7.08396418532264E+002 -7.44440071921381E+002
Positive Minimum +2.10953732297368E-154 +4.94065645841247E-3241
Negative Maximum -2.10953732297368E-154 -4.94065645841247E-3242

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

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

EXPANDED

See DUMP DEVICE IS.