Providex Reference Lenguaje

Welcome to the
ProvideX Language Reference Version 4.20x
Introduction:
This Language Reference describes the ProvideX programming language: its directives, functions,
system variables, mnemonics, parameters, specialty files and limitations. The definitions of directives,
functions and system variables form an alphabetical resource. A series of appendices describe other
facets of the language. The Language Reference is intended primarily for programmers and analysts.
Before you begin, you'll find it helpful to familiarize yourself with the Glossary of Common Syntax
Elements and the list of descriptive Format Conventions, next. Following those, youll find a section on
Finding Your Topic, p. 5, which you can use as a guide to finding items in this manual.
If Youre New to ProvideX:

Hot links give you quick access to cross-referenced topics in other parts of this manual. Just point and
<Mouse-click> on any text that is in a magenta font and double-underlined, as in "See: If Youre New to
ProvideX, p. 8".
NOTE: Some Operating Systems are no longer supported.

Due to a change in bitmap handling, ProvideX versions 4.14 or higher will no longer run on MS-
Windows NT version 3.51. The following Operating Systems will no longer be supported:
MS-Windows NT Version 3.51
MS-Windows 3.1 (16-Bit)
MS-DOS will only be available on request.
NOTE that this is a BETA release of the ProvideX Language

Reference. The information contained herein is subject to
change.
1 ProvideX Language Reference (Ver. 4.20x) 10/10/01 1

Glossary
Common Syntax Elements
Description:
The following syntax items appear throughout The ProvideX Language Reference to tell you what is
needed in the Format of a statement. The list below shows you what to use in your statement or code for
each element:
Syntax Element What to Use

chan Use your channel or logical file number. It must be an integer between 0 and
127. The integer identifies the channel to which your directive applies, e.g.
CLOSE (14). Note that:
Channel zero (0) is the console. If you omit the channel, the system
defaults to 0 (the console).
Channel numbers from 1 to 63 are commonly used for LOCAL files.
Channel numbers from 64 to 127 are used for GLOBAL files.
Exception: In extended file mode (System Parameter 'XF') the channel
numbers range from 0-32767 for local files, and 32768-65000 for
global files.
col,line, Position / coordinates. Numeric expressions, column and line for top left corner.
width,height Number of columns for width and number of lines for height.
col, line Cell or column and line location / coordinates. Numeric expressions. Use
column and line numbers.
column, line as x,y X,Y location / coordinates. Use graphical units or @X(col) for the x-axis and
coordinates @Y(line) values for the y-axis. Numeric expressions.
control objects Controls are objects you can include in screen displays to provide information,
PERFORM / EXECUTE a piece of code or CALL another program or a NOMADS
panel object. ProvideX supports both its own common control objects (such as
BUTTONs, LIST_BOXes, scrollbars ...) and external controls, such as VBX
applications and bitmaps.
fileopt Use the various INPUT / OUTPUT file options. These are three-character codes
(e.g. DOM) followed by an equals sign "=" and a parameter (e.g. a line number or
variable name, etc.). In this example, you might use DOM=3250. For a list of
typical options, see File Options, p. 581 in the appendices.
ioref Use a cross reference to an IOLIST statement. This can be either a statement
label or the line number, e.g. IOL=1200. You can also use a variable containing
the object code of a compiled IOLIST statement. The IOLIST and statement
reference must exist. See also CPL( ) Compile String, p. 50(f) and PGM( )
Return Program Line, p. 310(f).

Syntax Element What to Use
numeric When a syntax format in this manual includes a numeric variable like chan,
expressions index or num (lowercase), you can normally substitute a numeric expression
consisting of variables, literals, functions, operators ... For instance, your value
and/or
could be something like HFN or 4 or NUM(A1$)*3-2. (NUM in upper case is
numeric variables the function.) When you use numeric variables in numeric expressions,
subscripts are allowed, e.g. COST(4).
NOTE: Exceptions and valid values are stated when there are
restrictions on the use of numeric expressions in a format
(e.g. where only a variable name is allowed). See individual
directives and functions for more information.
Example:
To apply the format FOR var=first TO last[ STEP val]:
FOR I=1 TO 10 or
FOR LEAPS=-10 TO XYZ STEP ABC*.1
stmtref Use a statement reference. This can be either a statement label or the line
number of a statement in the current program. Line numbers must be in the
range of 0 to 64999.
If your given line number does not exist, ProvideX goes to the statement with the
next higher line number. For example, if line 1000 doesn't exist and 1010 is the
next lineno, then for GOTO 1000 ProvideX will go to 1010 and proceed with
execution from there. See also Labels: Logical Statement References, p. 582.
Exception: ProvideX verifies the existence of an IOLIST and stmtref for

IOL=stmtref. It does not proceed to the next higher statement
number.
string expressions When a format includes a string variable like prog_name$ or title$ in the
syntax, you can normally substitute a string expression consisting of variables,
and/or
literals, functions, operators ...e.g. PRINT "Printing "+REPORT$. When you
string variables use string variables in string expressions, subscripts and substrings are allowed,
e.g. CUSTOMER$(15,4).
NOTE: Exceptions and valid values are stated whenever there are
restrictions on the use of string expressions in a format (e.g.
where only a variable name is allowed). See individual
directives and functions for more information.
Example:
For the CHECK_BOX READ [*]ctl_id,state$[,mode$][,ERR=stmtref]
format, you need string variables to receive the current state and optionally, the
mode of selection:
CHECK_BOX READ 14000,ON_OFF$,KEYSTROKE$
varlist Use a list of comma-separated variables. Typically, a mix of string and/or
numeric variables is acceptable, e.g. DEPT,ITEM,DESC$... (See individual
directives for restrictions.) In the case of arrays the variable name is followed by
{ALL}.
See also: Operators Supported in ProvideX, p. 587.

The word application in this manual refers to any programming application, for example, a date function, a
few lines of code, a subroutine controlling a process (e.g. inventory allocation) in a single program, or a
complex series of programs (e.g. a lead program with subprograms, a full Web Site).

Format Conventions
Symbols in Use
Description:
The following conventions have been applied to the syntax Formats for each directive and function in The
ProvideX Language Reference. (Exceptions are noted for individual commands where the brackets are
"real", i.e. part of the syntax.)
Symbol(s) Meaning
... Dots indicate the continuation of a list of elements.
<> Less-than and greater-than signs around a value in a syntax format indicate that you
should use your own value. For example, with the format <path>\PVX\PVXWIN32.EXE
you could use C:\YOUR_PATH\PVX\PVXWIN32.EXE. These signs also denote
keystrokes, as in <Enter>.
[] Square brackets enclose optional elements in the format. For example, in
ABS(num[,ERR=stmtref]) you can omit the ",ERR=stmtref" portion of the
statement as in ABS(X-Y).
{} Curly brackets enclose a list of elements in syntax formats where it is mandatory to
select one item. For example, with {yes | no}, you must select either yes or no. In
descriptions in this manual, they denote {bitmap / icon} buttons.
| Vertical bars | pipes separate a series of possible values as in {yes | no}.

Finding Your Topic
Topic Types & Locations
Description:
In many of the descriptions in this language reference, you'll see cross references to related topics. (Hot
links are in magenta font, double-underlined.) Superscripts in brackets mark the type of topic being cross-
referenced:
Symbol Cross Reference Is To A

(d) ProvideX Directive(d)
(f) System Function(f)
(m) Mnemonic(m)
(p) System Parameter(p)
(v) System Variable(v)
The elements of the ProvideX language are described in general terms, below, to help guide you to their
locations in this manual.
If Youre New to ProvideX See If Youre New to ProvideX, p. 8

Some of the ProvideX language conventions are listed for you.
Directives: See Directives, System Functions and Variables, p. 10

Directives are ProvideX commands. These are described in the alphabetical listing of Directives, System
Functions and Variables, complete with mandatory and optional syntax elements. For instance, the format
for the CLOSE directive is CLOSE (chan[,ERR=stmtref])[,(chan[,ERR=stmtref])...]. When you apply a
directive, you can exclude all but the mandatory syntax elements, as in CLOSE (14).
System Functions: See Directives, System Functions and Variables, p. 10

Various standard functions are included in ProvideX and can be used in any Business Basic expression.
These are described in the alphabetical listing of Directives, System Functions and Variables. String
functions usually evaluate and return character strings. Numeric functions usually evaluate and return
numeric values.
A ProvideX function consists of a three-character function name, e.g. AND, followed by an open
parenthesis, the parameter(s) for the function, an optional error transfer and finally a close parenthesis,
e.g. AND(A$,B$,ERR=0300). The number and type of parameters vary from function to function. All
functions include an ERR= option (even those where an error is unlikely). If you include the ERR= transfer
in your statement, it is only active during the actual evaluation of the function. It has no effect on any other
ERR= option in your statement.
Example:
0020 WRITE (1,ERR=1000) AND(A$,B$,ERR=0300)

If an error occurs in the above statement during the AND( ) function, control goes to statement 0300. An
error on the WRITE will transfer control to statement 1000.
FID( ), FIB( ), FIN( ) See Directives, System Functions and Variables, p. 10

FID( ), FIB( ) and FIN( ) are system functions that return file information, descriptors and blocks. They are
included in the alphabetical listing of Directives, System Functions and Variables.
See also: FIB( ), FID( ) and FIN( ) File Information, p. 141(f)
FIB( ) Return File Information Block, p. 142(f)
FID( ) Return File Information Descriptor, p. 145(f)
FIN( ) Return File Information, p. 149(f)
System Variables: See Directives, System Functions and Variables, p. 10

The ProvideX language includes various system variables. These variables, described in the alphabetical
listing of Directives, System Functions and Variables, provide system information such as date and time.
Some variables have string values, while some have numeric values. You can use them wherever normal
program variables would be used, but you cant modify them in your program.
NOTE: All system variables have reserved three-character names, e.g. CTL. To avoid
potential conflicts with the reserved list (since ProvideX might include more three-
character variables in the reserved list in future), Best Software Canada Ltd.
recommends strongly that you do not use three-character variable names.
ALSO: String system variables, unlike their normal variable counterparts, do not have the
trailing dollar sign$.
Mnemonics: Mnemonics, p. 486

You can use mnemonics to control output to terminals and/or printers. Mnemonic instructions are
enclosed in single quotation marks. The alphabetical listing of Mnemonics, complete with formats and
descriptions, follows the listing of Directives, System Functions and Variables.
See also: MNEMONIC Define File Command Sequence, p. 265(d)
PRM Current ProvideX Parameter Settings, p. 324(v)
PRM( ) Return Parameter Value, p. 325(f)
Examples:
5000 PRINT @(5,5),'CL' ! Clears screen-line 5 to its end, starting at column 5
5150 OPEN (30) PRINTER$
5160 PRINT (30)'FF' ! Form-feed instruction to PRINTER$ on Channel 30
System Parameters: System Parameters, p. 537

System parameters are normally for use at start-up, to define your system's operation under ProvideX.

For example, you can use the 'BY' parameter to define your base year for your JUL( ) and DTE( )
functions. The alphabetical listing of System Parameters, complete with formats and descriptions, follows
the listing of Mnemonics. Like mnemonics, these parameters are enclosed in single quotation marks.
Special Files: Specialty *File* Handling, p. 589

ProvideX supports the use of a series of specialty files. For the commands you can use with these special
*device* files, see:
*MEMORY* Create & Use Memory File, p. 590
*VIEWER* Device File: Print Preview, p. 591
*WINDEV* Device File: RAW Mode Printing, p. 593
*WINPRT* Device File: Windows Printing, p. 596
Specialty Command [Tags]: [WDX] and Other Specialty Command [Tags], p. 608
ProvideX supports the use of a series of special file tags, e.g. for [DLL] and [TCP], many of which can be
used with the [WDX] tag. For information about specialty commands and tags, see:
[DDE] Tag: Dynamic Data Exchange, p. 609
[DLL] Tag: Dynamic Link Library, p. 611
[OCX] Tag: Object Component Extension, p. 612
[ODB] Tag: Open DataBase, p. 613
[RPC] Tag: Remote Procedure Control, p. 614
[TCP] Tag: Transmission Control Protocol, p. 619
[VBX] Tag: Custom VBX, p. 625
[WDX] Tag: Directs Action to Client Machine, p. 626
List of Appendices
Other appendices in this Language Reference are in alphabetical order (with the exceptions of Reserved
Words and Error Codes, which are at the end). They include:
COM Ports and Serial Devices, p. 567
Command Line, Launching ProvideX, p. 569
Dynamic Control Object PROPERTIES, p. 572
File Options, p. 581
Labels: Logical Statement References, p. 582
Negative CTL Definitions, p. 583
Operators Supported in ProvideX, p. 587
System Limits, p. 606
Reserved Words, p. 632
Error Codes and Messages, p. 634

If Youre New to ProvideX
General Information
Description:
When you launch ProvideX for WINDOWS, youll see your programming workspace with a {ProvideX} icon
above it (top left corner of the window). You can load, create / edit and run your programs in the
workspace.
See the ProvideX Users Guide for information about using the options available to you when you click on
the icon.
ProvideX Punctuation/Syntax Conventions

If you're new to the language itself, these are some of the ProvideX standard punctuation conventions:
Symbol(s) Meaning
! ProvideX accepts an exclamation mark plus a blank as a substitution for the REM
directive, as in: ! this remark.
Exclamation
An exclamation mark as the leading character of a string denotes one of Best
Software Canada Ltd.s embedded bitmaps, e.g. !STOP.
" Standard quotation marks enclose string literals. You can also use a leading
quotation mark plus a blank at the start of a statement as the equivalent of the
Quotes
INVOKE directive. For example, " WAIT .05 is the same as INVOKE WAIT .05
$ A dollar sign at the end of a variable name marks a string variable, e.g. CUST$. You
also use dollar signs to enclose hex values, for example $8A$.
Dollar sign
% A leading percent sign for a variable name denotes a global variable, for example,
%DEPT.
Percent sign
' Single quotation marks (apostrophes) enclose System Parameters and
Mnemonics, for instance TL and CS.
Apostrophe
* Best Software Canada Ltd. supplies a number of utility applications. Their names
are preceded by an asterisk (e.g. *CMD, *UPB and the search utility described
Asterisk
below).
; Separator for directives and entrypoints in program statements.
Semicolon
*[ ] Use the Best Software Canada Ltd. ProvideX search utility to search your program
for one or more characters (string or numeric) by enclosing the character(s) in a set
Asterisk + square
of square brackets preceded by an asterisk. The search is not case-sensitive.
brackets
Examples:
->*[print]
0090 REM Printing
0100 PRINT DAY
0120 PRINT "Today's date is ",DAY
0610 IF LEN(X$)>100 THEN PRINT "TOO LONG"; GOTO 0210
->*[26]
0110 SETDAY "02/26/99"
*[ ]=[ ] You can use global search and replace to make changes in your program. For
example: *[CST$]=[CUST$] changes all instances of CST$ to CUST$.

Symbol(s) Meaning
Prompts When your ProvideX prompt is a dash with a colon, that indicates that your current
-: program has not been SAVEd. After you SAVE your program, the prompt reverts to
-> an arrow.
-} Under WindX, the prompt is a dash and a left brace.
/ or \ You can use either slash as a substitute for the word "list" in a LIST directive.
XXXXXX: Use a trailing colon to denote that your string is a line label (statement reference or
entry point). For instance:
String
0110 IF UPDATE$="Y" GOSUB CUSTOMER
with trailing colon
...
2000 CUSTOMER:
2010 INPUT 'CS',@(5,5),"Enter customer number",CST
2020 ! REST OF ROUTINE ...
2200 RETURN
? You can use a leading question mark plus a blank at the start of a statement as the
Question mark equivalent of the PRINT directive (i.e. ? CUST$ is the same as PRINT CUST$).
ProvideX also places a question mark between a line number and program
statement to denote a syntax error.
` ProvideX accepts the back apostrophe as a substitute for the word "edit" in an EDIT
directive.
Back apostrophe

Directives, System Functions and Variables
Alphabetical Listing
This part of The ProvideX Language Reference describes the ProvideX programming language's
directives, system functions and system variables, in alphabetical order. Each description shows you the
format of a directive, function or variable, including any parameters associated with it, values returned, a
general description, and, for most, an example.

@X( ) and @Y( ) Convert X/Y Coordinates
Functions @X( ) and @Y( )
Format:
1 Return Column Position @X(col[,chan][,ERR=stmtref])

2 Return Line Position @Y(line[,chan][,ERR=stmtref])
Where =
col,line Standard print positions. Numeric expressions. Column and line numbers.
chan Channel or logical file number of the device or file.
stmtref Program line number or statement label to which to transfer control.
Return: Integers (x-axis coordinate for column and y-axis coordinate for line, in graphical units -
similar to pixels)
Description:
Use these functions to convert column and line number addresses for graphics output into X- and Y-axis
coordinates in graphical units (similar to pixels). The values returned are integers. In the example below,
the functions return 16 graphical units as the coordinate for column 1 and 60 for line 2:
->0010 LET A=1, B=2
-:0020 PRINT @X(A),@Y(B)
-:RUN
16 60
->PRINT 'TEXT'(A,B),"X MARKS THE SPOT" ! Starts at column 1, line 2

These functions take the column/line numbers and, based on your given channel, return the corresponding
graphics coordinates. Numeric variables, fractions and negative numbers are allowed as column and line
values.
If you don't include a channel number, the default is 0 (zero), the terminal/console. If you use either of
these functions in a PRINT statement, the output will go to the channel or logical file number you specify in
the PRINT directive (i.e. to a terminal, file or printer).
Example:
1010 PRINT @(5,5),"CUSTOMER LISTING",
1020 PRINT 'FILL'(0,0),'RECTANGLE'(@X(4),@Y(5),@X(22),@Y(6)),
When the example above is RUN, the words CUSTOMER LISTING are displayed on the screen, outlined
by a RECTANGLE. The @X(col) values start the rectangle at the graphical equivalent of column 4 (one
column before the text) and end it one column after the text. The @Y(line) values equivalent to lines 5 and
6 define the rectangle as 1 line high starting at the top of line 5.

ABS( ) Absolute Value
Function ABS( )
Format:
Return Absolute Value ABS(num[,ERR=stmtref])
Where =
num Numeric expression for which you want the absolute value.
Returns: Numeric, absolute value of expression. Always positive or zero.
Description:
The ABS( ) function returns the absolute value of the numeric expression you enclose in the brackets. The
value returned is a positive numeric value or zero. For instance, the absolute value of the numeric
expression (X) is returned as follows:
ABS (X) - If X>0 - Returns X
ABS (X) - If X<0 - Returns X * -1 (positive result)
ABS (X) - If X=0 - Returns X (zero)
Example:
In the examples below, the value returned is an absolute value reflecting current PRECISION type. The
first value, for instance, is returned in FLOATING POINT. Although the result is less than zero, ABS( )
returns a positive result.
0010 INPUT "Give me your first number ",X
0020 INPUT "Give me another one ",Y
0030 PRINT "The difference is ",ABS(X-Y)
-:PRECISION -1
-:RUN
Give me your first number 12.345
Give me another one 23.456
The difference is .11111E+02
-:PRECISION 2
-:RUN
Give me your first number 12.345
Give me another one 23.456
The difference is 11.111

ACCEPT Read Single Keystroke
Directive ACCEPT
Format:
Read a Keystroke ACCEPT (chan[,fileopt])char$
Where =
chan Channel or logical file number.
fileopt File options. Valid options for ACCEPT include:
ERR=stmtref Error transfer
NUL=stmtref No input available
TIM=num Time-out value
(stmtref= Program line number or statement label to which to transfer control.)
char$ String variable. Receives the input character.
Description:
Use the ACCEPT directive to read a single keystroke (character) from a terminal. The ACCEPT directive
doesn't echo the keystroke/character to the terminal. If no input is in the input buffer, the ACCEPT
directive waits for terminal input. Control transfers to the stmtref if you include a NUL= option and the
terminal input buffer has no data in it.
See also: INPUT Get Input from Terminal, p. 192(d)
OBTAIN Get Hidden Terminal Input, p. 293(d)
Example:
0100 READ RECORD (1,END=0130)R$
0110 PRINT R$
0120 ACCEPT (0,NUL=0100)X$
0130 PRINT "<Display halted>"

ACS( ) Arc-Cosine Function
Function ACS( )
Format:
Return Arc-Cosine ACS(num[,ERR=stmtref])
Where =
num Numeric expression (range: -1 to +1) for which you want the Arc-Cosine.
Returns: Numeric value between 0 (zero) and (pi=3.14159...)
Description
The ACS( ) function returns the Arc-Cosine of the numeric expression you enclose in brackets. It returns
a value between 0 (zero) and (pi) rounded to the current PRECISION in effect. This is the inverse of the
COS( ) function.
The value of your numeric must be in the range of -1 to +1 inclusive. Otherwise ProvideX returns an
Error #40: Divide check or numeric overflow.
Example:
0060 FOR I=-1 TO 1 STEP .1
0070 PRINT ACS(I),
0080 NEXT
0090 PRINT " DONE"
0100 END
-:run
3.14 2.69 2.5 2.35 2.21 2.09 1.98 1.88 1.77 1.67 1.57 1.47 1.37 1.27 1.16 1.05
0.93 0.8 0.64 0.45 0 DONE

ADDR Load and Lock Program in Memory
Directive ADDR
Format:
Load Program in Memory ADDR prog_name$[, ERR=stmtref]
Where =
prog_name$ Name of the program to be loaded and kept in memory. String expression. If you omit
the pathname, ProvideX search rules apply.
Description:
The ADDR directive loads your specified program into memory and keeps it there until you unload it.
For as long as the ADDR-loaded program is in memory, the string always refers to that specific program
(using its absolute path) even if you change the system PREFIX or current directory after executing the
ADDR directive. That is, all subsequent references to any program whose name matches that string will
still refer to the ADDR-loaded program.
You can see this in the example below. When the program is executed, ProvideX ADDR-loads
"DATECHK", changes directories and RUNs the ADDR-loaded program even though there is a different
current directory and a different program with the same name might exist in that directory.
To unload a program which is ADDR-loaded, either use the DROP directive or execute the START
directive.
See also: DROP Removes Program from Memory, p. 98(d)
START Restart ProvideX, p. 404(d)
Example:
0010 CWDIR "USR/UTILS"
0020 ADDR "DATECHK"! USR/UTILS/DATECHK is loaded in memory.
0030 CWDIR "USR/AR"! New working directory: could contain a different DATECHK.
0040 RUN "DATECHK" ! Still runs USR/UTILS/DATECHK

AND( ) 'AND' Strings
Function AND( )
Format:
Logical AND AND(string_1$,string_2$[,ERR=stmtref])
Where =
string_1$ Initial string value. String expression.
string_2$ Second string value. String expression. Must be the same length as string_1$.
Returns: String result of bit-wise logical AND comparison
Description:
The AND( ) function performs a bit-wise "AND" comparison of two strings. The value it returns is the string
generated by the AND( ) function. ProvideX returns an Error #26: Variable type invalid if the
length of the second string is not identical to the length of the initial string.
Binary Result
0 AND 0 0
1 AND 0 0
0 AND 1 0
1 AND 1 1
Examples: AND(A$,B$) HEX Equivalent Binary

A$="A"(i.e.$41$) and B$="B"(i.e.$42$) Returns @ (i.e. Hex $40$) 01000000
A$="%"(i.e.$25$) and B$="B"(i.e.$42$) Yields Hex 01 ($01$) 00000001
A$=2 (i.e. $5A$) and B$= CHR(221) Yields Hex 58 ($58$) 01011000
(i.e. B is $DD$, extended ASCII character 221
Examples:
0010 LET A$="A", B$="B"
0020 AB$=AND(A$,B$)
0030 PRINT AB$," ",HTA(AB$)
run
@ 40
0140 READ (1,END=1000)F$

0150 R$=AND(F$(1,2),$7F7F$) ! Turn off high bit

ARG( ) Command-Line Argument
Function ARG( )
Format:
Return Argument Value ARG(position[,ERR=stmtref])
Where =
position Position of the argument you want returned. Numeric expression. Range: integer value
from -1 to the number of arguments in the command that launched ProvideX.
Returns: String, value of start up argument
Description:
The ARG( ) function returns the string value of one of the arguments specified in the operating system
command that launched ProvideX. Your numeric expression in brackets indicates which argument you
want returned. If you refer to an invalid argument, ProvideX returns an Error #41: Invalid integer
encountered (range error or non-integer).
Given PVX -SZ=20 -ARG TOM JONES:

ARG(-1) would yield the INI filename in use for the current session (Ver. 4.10).
ARG(0) would yield: "PVX" (the command that launched ProvideX)
ARG(1) would yield: "TOM"
ARG(2) would yield: "JONES"
ARG(3) would yield Error #41: Invalid integer encountered
See also: NAR Number of Arguments, Start Providex, p. 284(v)

Example:
0010 FOR I=-1 TO 5
0020 PRINT "ARG(",I,") is ",ARG(I,ERR=0060)
0030 NEXT I
0060 PRINT "not valid, Error #",ERR; STOP
-:run
ARG(-1) is C:\software\pvx410\pvx.ini
ARG( 0) is C:\SOFTWARE\PVX410\PVXWIN32.EXE
ARG( 1) is not valid, Error # 41

ASC( ) Get Internal Character Value
Function ASC( )
Format:
Return ASCII Value ASC(char$[,ERR=stmtref])
Where =
char$ Single-character for which you want the ASCII numeric value. String expression.
Returns: Integer, ASCII character set number, range 0 (zero) to 255
Description:
The ASC( ) function returns the internal numeric value of your given character, based on its position in the
ASCII character set/table. The value returned is an integer, range 0 to 255 (ASCII character set number).
Only the first character in your string is converted to its internal value.
Examples:
?ASC("A")! yields 65
string$="a";?ASC(string$) ! yields 97
?ASC("abc") ! also yields 97 (the ASCII value for "a")

ASN( ) Arc-Sine Function
Function ASN( )
Format:
Return Arc-Sine ASN(num[,ERR=stmtref])
Where =
num Numeric expression for which you want the Arc-Sine. Range -1 to +1 inclusive.
Returns: Numeric, range -1.57 to +1.57
Description:
The ASN( ) function returns the Arc-Sine of your given numeric expression. The function returns a value
between - (-pi) divided by 2 and +(+pi) divided by 2. That is, the values returned range from -1.57 to
+1.57 rounded to the current PRECISION in effect. This is the inverse of the SIN( ) function.
If your numeric expression is not in the range -1 to +1 inclusive, the result is an Error #40: Divide
check or numeric overflow.
Example:
0060 FOR I=-1 TO 1 STEP .1
0070 PRINT ASN(I),
0080 NEXT
0090 PRINT " DONE"
0100 END
-:run
-1.57-1.12-0.93-0.78-0.64-0.52-0.41-0.3-0.2-0.1 0 0.1 0.2 0.3 0.41 0.52 0.64
0.7 8 0.93 1.12 1.57 DONE

ATH( ) Convert Hex
Function ATH( )
Format:
Convert Hex to ASCII ATH(hex_string$[,ERR=stmtref])
Where =
hex_string$ Hex data to be converted to ASCII. Hex string expressions. Your hex string must be an
even number of bytes in length and consist of only the characters 0 (zero) through 9
and A through F.
Returns: ASCII value corresponding to string of hex data
Description:
The ATH( ) function converts your string of hex data to its corresponding ASCII value. The ASCII string
returned by the ATH( ) function is the converted value of each set of two hex characters to one ASCII
character.
Examples:
-:h$="414243"
-:?ath(h$)
ABC
ATH ("414240") ! yields AB@ (Hex 40= "@")

ATN( ) Arc-Tangent Function
Function ATN( )
Format:
Return Arc-Tangent ATN(num[,ERR=stmtref])
Where =
num Numeric expression for which you want the Arc-Tangent.
Returns: Numeric value, range -1.57 to +1.57
Description:
The ATN( ) function returns the Arc-Tangent of your numeric expression in the brackets. It will return a
value between - (negative pi) divided by 2 and + divided by 2, rounded to the current PRECISION in
effect. This is the inverse of the TAN( ) function.
Example:
0060 FOR I=-10 TO 10 STEP 1
0070 PRINT ATN(I),
0080 NEXT
0090 PRINT " DONE"
0100 END
-:RUN
-1.47-1.46-1.45-1.43-1.41-1.37-1.33-1.25-1.11-0.79 0 0.79 1.11 1.25 1.33 1.37
1.41 1.43 1.45 1.46 1.47 DONE

AUTO Automatic Line Generation
Directive AUTO
Format:
Automatic Line Numbering AUTO [lineno[,incr]]
Where =
lineno Starting program line number you want ProvideX to use. Optional.
incr Increment you want ProvideX to add automatically to generate each subsequent line
number. Default: 10. Optional.
As of Ver. 4.20, you can set a different default. See 'AI'=num Automatic Line-
Numbering Increment, p. 539(p).
Description:
NOTE: This directive only works in COMMAND mode.

Use the AUTO directive to have ProvideX automatically generate line numbers and implement them
prefixing your statement input.
If you omit the starting line number in this directive, then ProvideX uses either the last generated line
number (if any), or the next higher line in the current program. If you don't specify an increment, the default
is 10. If you change the increment in command mode, it stays at your new setting until you change it
again.
The AUTO function remains active until you enter a NULL line (e.g. hit <Enter>) or execute a command.
You can backspace over and change the generated line number.
Example:
->AUTO 100,10
0100 ! ProvideX generates lineno 0100 for you. Add your statement.
0110 ! ProvideX adds 10, generates line 0110. 1st and ten, do it again.
0120

BEGIN Reset Files and Variables
Directive BEGIN
Format:
Resets BEGIN [[EXCEPT]varlist]
Where =
varlist List of variables. Optional.
Description:
The BEGIN directive performs the following functions:
1. Closes all LOCAL files currently open. (GLOBAL files remain open)
2. Resets PRECISION to the default value of 2
3. Clears local variables. (Global variables are not affected)
(a) All if no varlist appears on directive
(b) Only those in varlist if no EXCEPT clause given
(c) All but those in varlist if EXCEPT clause present
4. Sets ERR, RET, and CTL to zero
5. Clears FOR/NEXT, GOSUB/RETURN stack
6. Resets pointer to the first DATA item in the program
See also: CLEAR Reset Variables, p. 45(d),
RESET Reset Program State, p. 359(d)
ERR( ) Test Error Value, p. 124(f)
CTL Control Code: Key Used to End Input, p. 53(v)
RET Operating System's Last Error Code, p. 361(v)
Examples:
e.g. 3a 0100 BEGIN
or e.g. 3b 0100 BEGIN A3$,B3$,C3,D3
or e.g. 3c 0100 BEGIN EXCEPT CST_ID$,TX_VAL,TX_TBL${ALL}

BIN( ) Binary String from Numeric Value
Function BIN( )
Format:
Numeric to Binary of String BIN(num,len[,ERR=stmtref])
Where =
num Numeric value to convert to a string. Use a numeric expression. Integer value.
len Length of the string to be returned. Use a numeric expression. Integer value.
Returns: Binary value of ASCII string corresponding to your numeric expression
Description:
The BIN( ) function converts your numeric expression to an ASCII string (as its binary value). The string
returned will be the length you specify. The value is right justified in the resultant string.
The value is converted to two's complement format before the string is generated. If the number was
negative the leading bits will all be set to ON (binary 1).
2 is binary 00000010
-1 is binary 11111111
-2 is binary 11111110
Examples:
B$=BIN( ) HTA(B$) Binary Value

BIN(40,1) HTA(B$) yields $28$ 00101000
BIN(40,2) HTA(B$) yields $0028$ 00000000 00101000
BIN(2048,2) HTA(B$) yields $0800$ 00001000 00000000
BIN(-64,2) HTA(B$) yields $FFE0$ 11111111 11100000

BKG Background Process Status
Numeric System Variable BKG
Returns: Numeric status code, 0 (zero) or 1
Description:
This numeric system variable returns the following numeric status codes:
Status =
0 (zero) Current program is directly connected to a terminal user (background/ghost process).
1 For all other cases.
Example:
->?BKG
0

BREAK Immediate Exit of Loop
Directive BREAK
Format:
Exit Loop BREAK
Description:
Use the BREAK directive to perform an immediate exit from a loop. Execution resumes following the
directive that would normally have ended the loop (e.g. NEXT, or WEND...etc.). The *BREAK label
emulates a BREAK directive for use as a statement reference (Ver. 4.01).
NOTE: Prior to Ver. 4.20, BREAK directives (and corresponding *BREAK labels) are not
supported for use with SELECT / NEXT RECORD directives. As of Ver. 4.20, you can
use BREAK commands in SELECT structures.
See also: CASE Branch Points, p. 36(d)
SWITCH Branch Control, p. 411(d)
EXITTO Premature Exit of FOR/NEXT, GOSUB, p. 134(d)

Example:
0010 FOR I=1 TO 100
0020 IF X$[1]="" THEN BREAK
0030 NEXT
0040 ! Program skips line 0030, resumes here if conditional BREAK is executed.

BSZ( ) Bank Memory Size
Function BSZ( )
Format:
Return Core Size BSZ(num[,ERR=stmtref)
Where =
num Bank number (ignored). Numeric expression.
Returns: 0 (zero) in most ProvideX implementations
Description:
NOTE: Included for compatibility with other languages.

The BSZ( ) function is primarily included in ProvideX for compatibility with other Business Basic languages.
The value it returns is 0 (zero) in most ProvideX implementations. In MS-DOS it returns the amount of
core left in the system.
Example:
->?BSZ
0

BUTTON Define/Control BUTTON
Directive BUTTON
Formats:
1 Define/Create BUTTON [*]ctl_id,@(col,line,width,height)=contents$[,fileopt]

2 Delete Button BUTTON REMOVE [*]ctl_id[,ERR=stmtref]
3 Disable/Enable BUTTON {DISABLE | ENABLE} [*]ctl_id[,ERR=stmtref]
4 Set Focus To BUTTON GOTO [*]ctl_id[,ERR=stmtref]
5 Logically Push/Release BUTTON {ON | OFF} [*]ctl_id[,ERR=stmtref]
6 Read Activation Mode BUTTON READ [*]ctl_id,mode$[,ERR=stmtref]
7 Hide/Show BUTTON {HIDE | SHOW} [*]ctl_id[,ERR=stmtref]
Where =
* (asterisk) Optional. Use a leading asterisk to denote a global BUTTON.
ctl_id Unique logical identifier for the BUTTON. Numeric expression. Use integers, range:
-32000 to +32000. Avoid integers that conflict with keyboard definitions (e.g.
function key CTLs like 4).
@(col,line, Position and size of the BUTTON region. Numeric expressions. Column and line
width,height) coordinates for top left corner, width in number of columns, height in number of lines.
Use line value -1 to display the BUTTON on the tool bar.
contents$ Text/pictures to appear on the BUTTON. As of Ver. 4.20, ProvideX supports both
{bitmap} and {icon} images. String expression. See BUTTON Contents$, p. 29
fileopt File options. Valid options for BUTTONs include:
FNT="font$,size[,attr] Font name, size, properties
MSG=text$ Message line
OPT=char$ Single character parameter / option. (See BUTTON
OPT=char$, p. 29.)
TIP=text$ Mouse pointer message. See also 'TC'=num TIP Window
Colour, p. 559(p) to change the colour.
mode$ String variable. ProvideX returns a single-character hex value in this variable to
report the last method / keystroke the user chose to activate the BUTTON (e.g. $01$
for a <Mouse-Click> or $0D$ for <Enter>).
Description:
Use the BUTTON directive to create BUTTON control objects on the screen. A BUTTON can send a
signal to your application when your user presses it. The signal typically indicates that the user wants to
end a function (e.g. exit) or initiate a new function (e.g. update a file, link to another panel).
See also: RADIO_BUTTON Define/Control RADIO_BUTTON, p. 336(d)
CHECK_BOX Define/Control CHECK_BOX, p. 37(d)
TRISTATE_BOX Define/Control TRISTATE_BOX, p. 433(d)


BUTTON =
OPT=char$
"s" Scroll: The BUTTON can scroll within a resizable/scrollable dialogue box.
"B" Bitmap Button: A bitmap button has a bitmap whose width is divided into four images.
As of Ver. 4.20, you can use this attribute to custom design BUTTONS of any colour,
style or shape by controlling the bitmap image that appears. Each of the four divisions
represents what your BUTTON will look like in a particular state:
1st quarter: Bitmap image when BUTTON is disabled.
2nd quarter: Bitmap image when BUTTON is in its normal (released) state.
3rd quarter: Bitmap image when the mouse is over the BUTTON.
4th quarter: Bitmap image when the BUTTON is pressed.
NOTE: You can apply this attribute to BUTTON, RADIO_BUTTON,

CHECK_BOX and TRISTATE_BOX directives. When a directive
allows for more than one bitmap, each bitmap you define is broken
into quarters (yielding, for instance, 12 bitmap images for a
TRISTATE_BOX).
"D" Disabled: The user and your program cannot gain access to the BUTTON.
"F" Flat Button: BUTTON shows no raised outline unless the mouse is over the BUTTON
or the BUTTON is pushed (Ver. 4.20). For example:
BUTTON 10,@(10,10,10,2)="&OK",OPT="F"

CHECK_BOX and TRISTATE_BOX directives.
"H" Hide: The user cant see the BUTTON even though it is still active and accessible
through your program.
"S" Signal Only: ProvideX generates a CTL value, but does not shift Focus to the BUTTON
automatically (the default), but only when Focus is explicitly passed to it. You can use
this to have a BUTTON act like a function key.
Format 1 Creates: BUTTON [*]ctl_id,@(col,line,width,height)=contents$[,fileopt]

Use this format to create your BUTTON control object, giving it a unique identifier in ctl_id. Your ctl_id is
used to generate a CTL value whenever the user presses the BUTTON. For example:
0010 REM Create button: CTL=4000 when pressed, 'Stop Sign' picture, "Exit" text
0020 BUTTON 4000,@(2,14,12,2)="{!Stop}Exit"
If your ctl_id has a leading asterisk, the BUTTON is considered global (not tied to a specific window):
0010 REM To add a global button to the Toolbar with the text "Help":
0020 BUTTON *1000,@(0,-1,10,1)="Help"
BUTTON Contents$
Your contents$ string expression defines the text/picture (bitmap or icon) to appear on the BUTTON. In the
text, you can use an ampersand "&" preceding a character to identify it as a hot key the user can press in
conjunction with the <Alt> key to activate the BUTTON from the keyboard.
Bitmaps and Icons:

To add a bitmap to a BUTTON, you can include the absolute path to the .bmp file in the contents$ or use
the name of one of Best Software Canada Ltd.s embedded bitmaps. As of Ver. 4.20, ProvideX supports

{icon} images for use on BUTTONS. Your icon filename must have .ico as an extension. When you use
both text and an image filename, the relative positions of the image and the text set their relative
placement on the BUTTON.
Enclose image filenames in curly braces and use a leading exclamation point (!) to identify Best Software
Canada Ltd.s embedded bitmaps. You can use a leading exclamation point to designate that an icon is
internal, but in that case ProvideX only searches in the *BMP directory. There are no icons in the ProvideX
executable and ProvideX does not support retrieving icons from either resource libraries or other system
DLLs /executables.
NOTE: Icon files often contain extra images for different sizes and color depths. If you use
an icon file in ProvideX, the file can only contain one image.
Examples:
As examples of contents$ expressions:
"{!Add}Add" ! Displays the {!Add} bitmap in front of the text "Add"
"Delete{!Del}" ! Displays the {!Del} bitmap after the text "Delete"
If your contents$ expression includes two images separated by a vertical bar inside a single set of curly
brackets, the first will be displayed when the BUTTON is released (normal state), the second while the
BUTTON is pressed. For example:
"{!Stop|C:\MYBMP\Go}"
You can also use the OPT="B" clause for a Bitmap Button to display different images for different states.
Format 2 Deletes: BUTTON REMOVE [*]ctl_id[,ERR=stmtref]

Use the BUTTON REMOVE format to delete a BUTTON. For example, to remove the BUTTON created
above:
0030 BUTTON REMOVE 4000

Note that, by default, if BUTTONs are not global they are deleted when a window is removed or dropped,
and on a BEGIN. You can remove global BUTTONs manually or clear them with a START directive.
Format 3: BUTTON {DISABLE | ENABLE} [*]ctl_id[,ERR=stmtref]

Use the BUTTON DISABLE format to gray out a BUTTON so that users can see it, but users and your
programs don't have access to it. Use BUTTON ENABLE to restore to a disabled BUTTON:
0030 BUTTON DISABLE 4000

...
0500 BUTTON ENABLE 4000
Format 4 Sets Focus: BUTTON GOTO [*]ctl_id[,ERR=stmtref]

Use the BUTTON GOTO format to set the Focus on a BUTTON.
0030 BUTTON GOTO 4000
Format 5 Logically Pushes, Releases: BUTTON {ON | OFF} [*]ctl_id[,ERR=stmtref]

Use the BUTTON ON/OFF format to make it seem that the BUTTON was pressed or released:
0030 BUTTON ON 4000

Format 6 READs Activation Mode: BUTTON READ [*]ctl_id,mode$[,ERR=stmtref]
Use the BUTTON READ format to receive your users method of selecting the BUTTON. ProvideX returns
a hex value in your string variable to tell you what keystroke last activated the BUTTON. Once read, this
field is reset to $00$. Some possible values are:
$01$ for <Mouse-Click>

$02$ for <Double-Mouse-Click>
$0D$ for <Enter>
$20$ for <Space-Bar> (and keyboard HotKey, as in the example below)
$09$ for <Tab> to go to the BUTTON
$00$ when the user exits the BUTTON control
Other specific characters include: $81$ for <F1>, $82$ for <F2> ...
Example
Note that you must read your users selection(s) to make them available to your applications. In the
example below, the STROKE$ variable returns the users method of selection (by mouse, carriage return or
space bar). The value returned for keyboard strokes (the hot key <Alt-B> and the space bar for this
example, is $20$).
0010 ! BUTTON Example

0020 PRINT 'CS'
0030 LIST
0040 BUTTON 2000,@(24,17,7,3)="{!BUG|!STOP}Hit the &Bug"
0050 LET BTN=2000
0060 SETCTL BTN:READ_BOX
0070 BUTTON GOTO BTN
0080 PRINT @(24,24),"HotKey=<Alt-B>. Try Mouse and keyboard too. END=<F4>"
0090 OBTAIN (0,SIZ=1,ERR=0090)@(0,0),'CURSOR'("off"),'ME',IN_VAR$,'MN'; LET
0090:CT=CTL
0100 IF CTL=4 THEN GOTO END
0110 READ_BOX:
0120 BUTTON READ BTN,STROKE$
0130 PRINT @(24,20),"Your HTA(selection)=",HTA(STROKE$),", CTL=",CT
0150 GOTO 0090
0160 END:
0170 BUTTON REMOVE BTN; PRINT 'CS'
Format 7: BUTTON {HIDE | SHOW} [*]ctl_id[,ERR=stmtref]

Use the BUTTON HIDE format to hide the display of an active BUTTON. (The user can't see or use the
button when it's hidden, even though its still active for your application.) Use the BUTTON SHOW format
to redisplay a hidden BUTTON and restore access to it.

BYE Terminate ProvideX
Directive BYE
Format:
End ProvideX Session BYE
Description:
Use the BYE directive to end your ProvideX session and return to the Operating System. If the ERR
system variable has a value other than zero (i.e. an error has occurred) then the Operating System is
informed that an error has occurred within ProvideX. This allows you to do external testing of error
conditions.
The ProvideX compiler converts the BYE directive internally into a QUIT directive. When you use it in a
compound statement, the BYE directive must be the final directive.
See also: QUIT Terminate ProvideX, p. 334(d)
RELEASE Terminate ProvideX, p. 353(d)

CALL Transfer to Subprogram
Directive CALL
Format:
Call Subprogram CALL subprog$[;entry$][,ERR=stmtref][,arg,arg...]varlist
Where =
subprog$ Name of the subprogram to call. String expression.
;entry$ Name of starting statement label to use as entrypoint in the subprogram. Optional.
If included, use a leading semicolon and add it to the subprog string expression
(e.g. CALL "get_pizza;order",top_1,top_2 ...).
arg,arg... Arguments to pass to the subprogram.
varlist List of variables, literals, mnemonics, IOL= options, and/or location functions, e.g.
"@(5,4)". The listed items must be comma-separated.
Description:
Use the CALL directive to transfer control to a subprogram. The current program state is saved and the
specified subprogram is loaded and executed. If you use arguments, they are passed to the called
subprogram for its use via the ENTER directive.
Arguments for CALL and ENTER

Normally, the total number of argument variables in the CALL and ENTER statements must match. Each
argument variable in the CALL statement must correspond in relative position and in type (numeric or
string) to a variable in the ENTER statement. If you use a shorter list of argument variables in your CALL
statement than in the ENTER statement, make sure you maintain relative position and type up to the point
where you shorten the list and make sure you include error handling options. Otherwise, ProvideX returns
an Error #36: ENTER parameters don't match those of the CALL.
Warning: If you pass an argument to the subprogram using a simple variable (e.g. A$, Z) then
any changes to the variable in the subprogram will have an effect in the CALLing
program. Subscripted variables/expressions (including substrings) or any values
enclosed in parentheses only have their values passed one way: to the subprogram.
Changes made to these will not affect the calling program. You can protect simple
variables from change by placing the variable names in parentheses, e.g. CALL
"PROG",(A$).
IOLISTs can also be used as arguments for CALL statements (e.g. CALL "PROG",IOL=8000).
You can pass a complete array to a subprogram by specifying the array name followed by {ALL}. In this
case, all values are passed to the subprogram and any changes made are returned to the calling program.
See the Users Guide for more details on this directive.

CALL Using Entry-Point Labels
This directive also has an optional ProvideX feature you'll find useful for applications like subprogram
"libraries" (with multiple stand-alone routines, each accessed by a statement label). To use this form of
access, append a semicolon plus the label name of the starting statement to the subprogram name (e.g.
CALL "PROG;STARTING_LABEL",ERR=1000,X$,A,CT$). After the CALLed subprogram is loaded,
ProvideX internally issues a GOTO STARTING_LABEL (e.g.) directive and starts execution there. You can
use this to create a single subprogram with multiple entry points and ENTER directives.
CALL and ENTER from ASCII Programs

When you run programs from ASCII text files, the CALL and ENTER with no arguments will always fail
because the system thinks that the variables have already been assigned. To work around this:
Use the PERFORM directive.

Save the CALLed program in a PROGRAM file.
See also: ENTER Specify Arguments, p. 117(d)
PERFORM Call Subprogram, Pass All Variables, p. 307(d)
PROGRAM Create a Program File, p. 329(d)

Example:
0170 REM In Calling Program:
0180 LET A=1,F=2,Z$="Cat",X$="*Pig*****Dog",Q=9
0190 PRINT "Values before CALL:",@(26),A,F,Z$,X$,@(45),Q
0200 CALL "ABCDEF;TEST",ERR=9000,A,4*F,Z$,X$(5,5),(Q)
0210 PRINT "Values after subprogram: ",@(26),A,F,Z$,X$,@(45),Q
9000 STOP
->END
->RUN
Values before CALL: 1 2Cat*Pig*****Dog 9
TEST in subprogram ABCDEF
In ENTER: 1 8Cat***** 9
Change : 6 7Pig*****Cat**** 4
Values after subprogram: 6 2Pig*Pig*****Dog 9
Subprogram ABCDEF is listed below. ProvideX issues a GOTO TEST directive (CALL directives starting
label reference) to begin execution.
0010 REM
0020 HEADING:
0030 ENTER T$,X,Y,DT$
0020 PRINT CS,T$," REPORT",@(X,Y),DT$
0030 EXIT
0040 TEST: !Entry point starting label
0050 PRINT "TEST in subprogram ABCDEF"
0060 ENTER R,S,D$,E$,V
0070 PRINT @(8),"In ENTER:",@(26),R,S,D$,E$,@(45),V
0080 LET Z=6,X=7,A$="Pig",B$="*****Cat****",V=4
0090 PRINT @(8),"Change :",@(26),R,S,D$,E$,@(45),V
0100 EXIT

The chart below shows the values received in the ENTER statement and what is/is not returned:
Value Subprogram:
R Receives the value of A and will return changes to A in the calling program
S Receives value of 4*F but subprogram changes won't affect the calling program
D$ Receives the value of Z$ and will return changes to Z$ in the calling program
E$ Receives substring X$(5,5) but will not change the value in the calling program (no exact
type match, because X$ is subscripted, but E$ is not)
V Receives the value of (Q) but will not return changes to (Q)
Note that if you have duplicate variables in your CALL statement, only the ENTER variable corresponding
to the first occurrence will return a value to the CALLing program. For example:
0010 CALL "PROG01",A$,A$
In Prog01:
0010 ENTER B$,C$
0020 B$="Cat"
0030 C$="Dog"
0040 EXIT
The value returned in A$ will be "Cat" (the value assigned to B$).

CASE Branch Points
Directive CASE
Format:
Define Branch Points CASE expression[$]
Where =
expression[$] List of possible branch points in your program. String or numeric expression.
Description:
Use your expression in the CASE directive to list the possible branch points in your program.
See also: SWITCH Branch Control, p. 411(d)
Example:
Preset the value of A$ if you RUN this example, or see the chart below the LISTing for sample results of
CASE placement and definition.
5000 SWITCH A$
5010 CASE "Alligator"
5020 CASE "Cat","Dog"
5030 PRINT "Domestic Animal"
5040 CASE "Nephew"
5050 PRINT "Break"; BREAK
5060 DEFAULT
5070 PRINT "Wild Animal"
5080 END SWITCH
5090 PRINT "DONE"
Preset Value of A$: Results When RUN: Notes:

A$="Alligator" Domestic Animal CASE matched.
Break
Note that "Alligator" in this example drops through
DONE
because there is no BREAK to intervene. As a result,
"Alligator" doesnt DEFAULT to "Wild Animal".
ProvideX treats it as a defined CASE for "Domestic
Animal". Your CASEs dont have to be all on one line.
If you dont "give them a BREAK", theyll drop through
the way "Alligator" did.
A$="Cat" Domestic Animal CASE matched. Defined as Domestic Animal.
Break
DONE
a$="cat" Wild Animal DEFAULT. Not defined. (Note that CASE is case-
DONE sensitive.)
a$="Nephew" Break CASE matched. Defined, but the CASE statement
DONE occurs after the instruction to PRINT "Domestic
Animal". (Processing continues from the CASE
definition on, without printing the animal type.)
a$="Fox" Wild Animal DEFAULT. Not defined.
DONE

CHECK_BOX Define/Control CHECK_BOX
Directive CHECK_BOX
Formats:
1 Define/Create CHECK_BOX [*]ctl_id,@(col,line,width,height)=contents$[,fileopt]

2 Delete CHECK_BOX REMOVE [*]ctl_id[,ERR=stmtref]
3 Disable/Enable CHECK_BOX {DISABLE | ENABLE}[*]ctl_id[,ERR=stmtref]
4 Set Focus To CHECK_BOX GOTO [*]ctl_id[,ERR=stmtref]
5 Logical On/Off CHECK_BOX {ON | OFF} [*]ctl_id[,ERR=stmtref]
6 READ Activation Status CHECK_BOX READ [*]ctl_id,state$[,mode$][,ERR=stmtref]
7 Update CHECK_BOX WRITE [*]ctl_id,state$[,ERR=stmtref]
8 Hide/Show CHECK_BOX {HIDE | SHOW} [*]ctl_id[,ERR=stmtref]
Where =
* (asterisk) Optional. Use a leading asterisk to denote a global CHECK_BOX.
ctl_id Unique logical identifier for the CHECK_BOX. Numeric expression. Integers,
range: -32000 to +32000. Avoid integers that conflict with keyboard definitions
(e.g. function key CTLs like 4).
@(col,line, Position and size of the CHECK_BOX region. Numeric expressions. Column and
width,height) line coordinates for top left corner, width in number of columns, height in number of
lines. Note that width and height are for the total area (box plus text/description).
Use line value -1 to display the CHECK_BOX on the tool bar.
contents$ Text/pictures to appear on the CHECK_BOX. As of Ver. 4.20, ProvideX supports
both {bitmaps} and {icons}. See CHECK_BOX Contents$, p. 38.
fileopt File options. Valid options for CHECK_BOXes include:
OPT=char$ Single character parameter. See CHECK_BOX OPT=char$,
p. 38.
TBL=char$ Single character translation
report the last method / keystroke the user chose to toggle the CHECK_BOX (e.g.
$01$ for a <Mouse-Click> or $0D$ for <Enter>).
state$ Current state of the CHECK_BOX (0=OFF, 1=ON).
Description:
Use the CHECK_BOX directive to create CHECK_BOX control objects on the screen. Your user can
toggle CHECK_BOXes between two states: ON to select an option, OFF to disable it. (If you need a third
state for a check box, use the TRISTATE_BOX directive.)
BUTTON Define/Control BUTTON, p. 28(d)

CHECK_BOX =
OPT=char$
"s" Scroll: Allows CHECK_BOX control to scroll within a resizable/scrollable dialogue box
"B" Bitmap Button: A bitmap button is a bitmap whose width is divided into four images.
As of Ver. 4.20, you can use this attribute to custom design CHECK_BOXes of any
colour, style or shape by controlling the bitmap image that appears. Each of the four
divisions represents what your CHECK_BOX will look like in a particular state:
1st quarter: Bitmap image when CHECK_BOX is disabled.
2nd quarter: Bitmap image when CHECK_BOX is in its normal (released) state.
3rd quarter: Bitmap image when the mouse is over the CHECK_BOX.
4th quarter: Bitmap image when the CHECK_BOX is pressed.

allows for more than one bitmap, each bitmap you define is
broken into quarters (yielding, for instance, 12 bitmap images for
a TRISTATE_BOX).
"D" Disabled: User cannot access the CHECK_BOX.
"F" Flat Button: CHECK_BOX shows no raised outline unless the mouse is over the
CHECK_BOX or the CHECK_BOX is pushed (Ver. 4.20).

Example: BUTTON 10,@(10,10,10,2)="&OK",OPT="F"
"H" Hide: Do not display the CHECK_BOX.
"S" Signal Only: ProvideX generates a CTL value, but does not shift Focus to the
CHECK_BOX unless Focus is explicitly passed to it.
Format 1 Creates: CHECK_BOX [*]ctl_id,@(col,line,width,height)=contents$[,fileopt]

Use this format to create your CHECK_BOX. Your ctl_id is used to generate a CTL value whenever the
user toggles the box and must be unique. If the ctl_id has a leading asterisk, the CHECK_BOX is
considered global (not tied to a specific window).
Example:
0010 ! Create a Check_Box, CTL=100, Text="Post Month End", ALT-P to select box
0020 CHECK_BOX 100,@(60,20,20,2)="&Post Month End"
CHECK_BOX Contents$
Your contents$ string expression defines the text/picture (bitmap or icon) to appear on the CHECK_BOX.
In the text, you can use an ampersand "&" preceding a character to identify it as a hot key the user can
press in conjunction with the <Alt> key to activate the CHECK_BOX from the keyboard. By default, the
text is displayed to the right of a CHECK_BOX. You can add a colon ( : ) to the end of the text field to
force the text to display to the left side.

Bitmaps and Icons
To add a bitmap to a CHECK_BOX, you can include the absolute path to the .bmp file in the contents$ or
use the name of one of Best Software Canada Ltd.s embedded bitmaps. As of Ver. 4.20, ProvideX
supports {icon} images for use on CHECK_BOXes. Your icon filename must have .ico as an extension.
DLLs /executables.
Examples:
"{!Add}Add" ! Displays the bitmap {!Add} in front of the text "Add"
"Delete{!Del}" ! Displays the bitmap {!Del} after the text "Delete"
If you enclose two images separated by a pipe | vertical bar in a single set of curly brackets, the first will be
displayed when the CHECK_BOX state is 0 (zero for OFF/normal state), the second when the
CHECK_BOX state is 1 (ON). For example:
"{!Stop|C:\USR\MAPS\Go}"
Format 2 Deletes: CHECK_BOX REMOVE [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX REMOVE format to delete a CHECK_BOX. Note that, by default, all
CHECK_BOXes which are not global are deleted when a window is removed or dropped, and on a BEGIN.
You can remove global CHECK_BOXes manually or clear them with a START directive.
0030 CHECK_BOX REMOVE *17000 ! Removes global check-box 17000
Format 3: CHECK_BOX {DISABLE | ENABLE}[*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX DISABLE format to gray out a CHECK_BOX and make it unavailable to users and
programs. (Users can see it but not gain access to it.) Use the CHECK_BOX ENABLE format to restore
access to a disabled CHECK_BOX.
0030 CHECK_BOX ENABLE 100
Format 4 Sets Focus: CHECK_BOX GOTO [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX GOTO format to set the Focus on a CHECK_BOX, ready for the users next input:
0030 CHECK_BOX GOTO 110
Format 5 for Logical ON/OFF: CHECK_BOX {ON | OFF} [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX ON/OFF format to make it appear that a CHECK_BOX has been toggled ON or
OFF:
0030 CHECK_BOX OFF 110,ERR=0040

Format 6 READs State: CHECK_BOX READ [*]ctl_id,state$[,mode$][,ERR=stmtref]
Use the CHECK_BOX READ format to receive the current state of the CHECK_BOX ("0"=OFF and
"1"=ON). Use the second (optional) string variable to have ProvideX return your users method of toggling
the CHECK_BOX. Once read, this field is reset to $00$. Some of the possible values are:
$0D$ for <Enter>
$20$ for <Space Bar> (and Hot Key: see the example below)
$00$ when the user exits the CHECK_BOX
Example:
Note that you must read your users selection(s) to make them available to your applications. The
ON_OFF$ variable in the example below receives the current ON/OFF state. For STROKE$ in the example
below, ProvideX returns $20$ when the user makes the selection using either the space bar or the &T hot
key <Alt-T>.
0010 ! CHECK_BOX Example

0020 PRINT 'CS'; LIST
0030 CHECK_BOX 90,@(24,17,25,3)="&Toggle for Status"
0040 LET C_BX=90; LET C_BX'BACKCOLOUR$="LIGHT CYAN"
0050 SETCTL C_BX:READ_BOX
0060 CHECK_BOX GOTO C_BX
0070 PRINT @(24,24),"HotKey=<Alt-T>. Try Mouse and keyboard too. END=<F4>"
0080 OBTAIN (0,SIZ=1,ERR=0080)@(0,0),'CURSOR'("off"),'ME',IN_VAR$,'MN'
0090 IF CTL=4 THEN GOTO END
0100 READ_BOX:
0110 CHECK_BOX READ C_BX,ON_OFF$,STROKE$
0120 ! WRITE_BOX
0130 CHECK_BOX WRITE C_BX,ON_OFF$
0140 PRINT @(24,20),"Current Status: ",ON_OFF$
0150 PRINT @(24,21),"Key Stroke : ",HTA(STROKE$)
0160 GOTO 0080
0170 END:
0180 CHECK_BOX REMOVE C_BX; PRINT 'CS'
Format 7 Updates: CHECK_BOX WRITE [*]ctl_id,state$[,ERR=stmtref]

Use the CHECK_BOX WRITE format to update the CHECK_BOXs state.
Example:
0100 ! WRITE C_BX
0110 LET ON_OFF$="0"
0130 CHECK_BOX WRITE C_BX,ON_OFF$
Format 8: CHECK_BOX {HIDE | SHOW} [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX HIDE format to keep a CHECK_BOX from being displayed. (The user can't see or
use it, even though it is still active for your application.) Use the CHECK_BOX SHOW format to restore the
display of a hidden CHECK_BOX.

CHG( ) Notify if Variable Has Changed
Function CHG( )
Format:
1 Notify & Change Status CHG(varlist[,ERR=stmtref])

2 Non-Destructive Read CHG(READ varlist[,ERR=stmtref])
Where =
varlist Comma-separated list of variable names to be tested.
Returns: String, listing variables that have changed
Description:
Use the CHG( ) function to determine whether or not the value of a variable has changed. Given a
comma-separated list of variable names, the CHG( ) function will return a comma-separated list of those
variables that have changed. You can use += (add to), -= (subtract from) and other operators with the
CHG( ) function.
NOTE: You should not use the CHG( ) function with NOMADS applications (except for
variables not referenced by the screen), because when you set the REFRESH_FLG,
NOMADS itself uses the CHG( ) function to determine which variables are to be
refreshed.
Format 1: CHG(varlist[,ERR=stmtref])
The "changed" status of a variable is changed when the data in the variable changes or when the CHG( )
function is applied. Format 1 of the CHG( ) function will reset the "changed" status of the variables listed.
0010 PRINT CHG("A,B,D$,E$")

0020 LET A=1.234
0030 LET E$="MIKEY"
0040 PRINT CHG("A,B,D$,E$") ! Will print A,E$
Format 2: CHG(READ varlist[,ERR=stmtref])

The CHG(READ ) format lets you do a non-destructive read of the value returned by the CHG( ) function.
The "changed" status will not be reset when the function is applied.
0010 ! Using CHG( ) to test for changes in values in an embedded IOL

0020 LET PROD_MF=HFN; OPEN (PROD_MF,IOL=*)"PROD_MF"
0030 DEF FN_CHANGED$(FILE_HFN,CHG_FLAG$)
0040 LET C$=LST(IOL(FILE_HFN))
0050 LET C$=C$(8)
0060 IF CHG_FLAG$="D" THEN LET A$=CHG(C$) ELSE LET A$=CHG(READ C$)
0070 IF A$<>"" THEN RETURN "YES" ELSE RETURN "NO"
0080 END DEF
0090 LET B$=FN_CHANGED$(PROD_MF,"R",ERR=*NEXT)
0100 PRINT B$
0110 LET CODE$="1"
0120 LET B$=FN_CHANGED$(PROD_MF,"D",ERR=*NEXT)
0130 PRINT B$

-:run
NO
YES
-:?c$
CODE$,DESC$,TYPE$

CHN Channels OPEN
Numeric System Variable CHN
Returns: String of numeric two-byte values
Description:
This numeric system variable returns a listing of all currently open channels. The value returned is a string
of numeric two-byte values. The CHN variable returns channel values below 65000 (Ver. 4.10).
Example:
0100 OPEN (30)"FILENAME"
->?CHN

To obtain the hex values, use the HTA( ) function.
->?HTA(CHN)
0000001E
In the above example, DEC($0000$)=0 (i.e. the console) and DEC($001E$)=30 (the OPEN files
channel).
5000 READ (30)IOL=8000

CHR( ) ASCII Character of Value
Function CHR( )
Format:
Get ASCII Character CHR(ascii_num[,ERR=stmtref])
Where =
ascii_num Value of the character to return. Numeric expression. Range: integer from 0 to 255 (the
character's number in the ASCII table).
Returns: Single ASCII character
Description:
The CHR( ) function returns a single-character ASCII string containing the character whose numeric ASCII
value you supply. The value of your numeric expression must be an integer in a range from 0 to 255 (the
position of the character in the ASCII table). The first printable character in the ASCII character set is the
blank, $20$, which is CHR(33).
See also: LCS( ) Return Lower Case String, p. 217(f)
UCS( ) Return Upper Case String, p. 443(f)
Examples:
0320 LET X$=CHR(65) ! (Sets X$ to "A")
0560 LET X$=CHR(34) ! (Sets X$ to "!")

CLEAR Reset Variables
Directive CLEAR
Format:
1 Clear, Reset CLEAR [EXCEPT] [varlist]

2 Clear Composite String CLEAR template$
Where =
varlist List of variables. Optional.
template$ Name of a variable DIMensioned as a string template. String expression.
Description:
The CLEAR directive performs the following functions:
1. Resets PRECISION to the default value of 2
2. Clears the following local variables (GLOBAL variables are not affected):
a) All if no varlist appears on directive
b) Only those in varlist if no EXCEPT clause given
c) All but those in varlist if EXCEPT clause present
5. Resets the pointer to the first DATA item in the program
See also: BEGIN Reset Files and Variables, p. 23(d)
ERR Last System-Detected Error Value, p. 123(v)
RET Operating System's Last Error Code, p. 361(v)
Format 1: Examples
The examples here show, respectively, CLEARing all variables, clearing only a selected list of variables,
and clearing all EXCEPT a selected list of variables:
0100 CLEAR
1100 CLEAR A3$,B3$,C3,D3
2100 CLEAR EXCEPT CST_ID$,TX_VAL,TX_TBL${ALL}
Format 2 CLEAR Variable$

You can use this Format to CLEAR the attributes of a variable DIMensioned as a string template (Ver.
4.12). For example: CLEAR CUST$.

CLIP_BOARD Use Windows CLIP_BOARD
Directive CLIP_BOARD
Formats:
1 Read Clipboard Data CLIP_BOARD READ var$[,ERR=stmtref]

2 Write Clipboard Data CLIP_BOARD WRITE text$[,ERR=stmtref]
Where =
var$ String variable. Receives the contents of the clip board.
text$ The data to place into the Windows clipboard.
Description:
NOTE: This directive is for WINDOWS or WindX only.

Use the CLIP_BOARD directive to have your ProvideX application READ or WRITE to the WINDOWS
clipboard. You can only pass text to/from the clipboard. You can read or write a maximum of 32000 bytes
using ProvideX to access the clip board.
ProvideX does not interpret the data in the clipboard. Because of this, carriage return $0D$ and LineFeed
$0A$ characters are present in multi-line clipboard data when you READ it and you should place these
characters between the lines when you WRITE to the clipboard.
Example:
1000 INPUT "Enter customer ID:",C$
1010 READ (1,KEY=C$)C.NM$,C.ADR1$,C.ADR2$
1020 CLIP_BOARD WRITE C$+" "+C.NM$+$0D0A$+C.ADR1$+$0D0A$+C.ADR2$
1030 PRINT "Your information is in the clipboard.."

CLOSE Close File
Directive CLOSE
Format:
Close Logical File Number CLOSE {(*) | (chan)}[,(chan)...[,ERR=stmtref])]
Where =
* (asterisk) Asterisk denotes "all OPEN local channels". CLOSE (*) closes all OPEN files and
devices.
Description:
Use the CLOSE directive to close your given logical file number. The memory used for buffers and control
information is returned to the system. Once closed, the file (channel) number can be reused for a different
file.
NOTE: A CLOSE directive will delete a *MEMORY* file. See *MEMORY* Create & Use
Memory File, p. 590. When you CLOSE (chan), ProvideX returns all memory that was
occupied by the *memory* file to the system.
The ERR= option sets up a program transfer if the file being closed is not currently OPEN. If you omit the
ERR= option, no error is returned when you CLOSE an unopened file.
See also: OPEN Open a File for Processing, p. 299(d)
BEGIN Reset Files and Variables, p. 23(d)
Examples:
CLOSE (30)
OPEN (30)"PRINT_DEVICE"
0500 LET CSTFILE=HFN; OPEN (CSTFILE)"ORDFILE"
0510 LET PRDFILE=UNT; OPEN (PRDFILE)"PRDFILE"
0520 LET ORDFILE=7; OPEN (ORDFILE)"ORDFILE"
0530 PRINT CSTFILE,PRDFILE,ORDFILE
0540 STOP
-:run
63 5 7
Either of the two statements below will close channels 63, 5 and 7. The second statement closes all other
open channels as well.
CLOSE (CSTFILE),(PRDFILE),(ORDFILE) ! Just closes channels 63,5,7
CLOSE (*,ERR=0500) ! Closes ALL open file channels (i.e. 63,5,7 and 30)

CONTINUE Initiates Next Iteration of Loop
Directive CONTINUE
Format:
Loop Again CONTINUE
Description:
Use the CONTINUE directive to go immediately to the next iteration of a loop (i.e. as soon as your
condition is true). ProvideX ends execution of the CONTINUE directive when the condition is false. The
*CONTINUE label emulates a CONTINUE directive for use as a statement reference (Ver. 4.01).
NOTE: The CONTINUE directive and *CONTINUE label are not supported for use with
SELECT / NEXT RECORD directives.
See also: Labels: Logical Statement References, p. 582
Examples:
0010 FOR I=-1 TO 3 STEP 1
0020 IF I<=0 THEN PRINT " TESTING ",; CONTINUE
0030 PRINT I,
0040 NEXT
-:run
TESTING TESTING 1 2 3-:
0110 FOR I=1 TO 100

0120 IF X$[1]<K$ CONTINUE
0130 PRINT X$[1]
0140 NEXT

COS( ) Cosine Function
Function COS( )
Format:
Return Cosine COS(num[,ERR=stmtref])
Where =
num Numeric expression for which you want the Cosine.
Returns: Value between -1 and +1
Description:
The COS( ) function returns the Cosine of your numeric expression. It returns a value between -1 and +1,
rounded to the current PRECISION in effect. ACS( ) is its inverse function.
Example:
0060 FOR I=-10 TO 10 STEP 1
0070 PRINT COS(I),
0080 NEXT
0090 PRINT " DONE"
0100 END
-:run
-0.84-0.91-0.15 0.75 0.96 0.28-0.65-0.99-0.42 0.54 1 0.54-0.42-0.99-0.65 0.28
0.96 0.75-0.15-0.91-0.84 DONE

CPL( ) Compile String
Function CPL( )
Format:
Return Compiled Format CPL(statement$[,ERR=stmtref])
Where =
statement$ String containing the statement to compile.
Returns: ProvideX compiled format of your statement
Description:
The CPL( ) function returns the ProvideX internal (compiled) format of the statement you give in the string
argument. The internal format of a statement consists of:
Bytes 1-2: Statement number in binary
Bytes 3-(n-1): Internal format of statement
Byte n: Binary value =$FF$ end of statement
Example:
0100 LET X$=CPL("20 PRINT A")
0110 PRINT HTA(X$)
-:run
$0014BD0101A1FF$

CRC( ) Cyclic-Redundancy-Check
Function CRC( )
Format:
Return Checksum CRC(chars$[,basis$][,ERR=stmtref])
Where =
chars$ String of characters on which to calculate a cyclic redundancy check.
basis$ Optional initial value to be used as the basis of the CRC. It must be two characters
long if included in the statement. Default: $0000$.
Returns: Cyclic redundancy checksum (in internal format)
Description:
NOTE: The CRC( ) function is used primarily for generating transmission checksums on
synchronous communications.
The CRC( ) function returns the cyclic redundancy checksum of a string of characters.
You can use the initial value (basis$) to generate an overall CRC( ) of multiple strings. See the example
below, where CRC(B$) with an initial value of CRC(A$) will be the same as CRC(A$+B$). If you omit the
initial value, ProvideX uses the default value, $0000$.
Example:
A$="Hello",B$="WORLD"
0010 LET C$=CRC(A$)
0020 LET C$=CRC(B$,C$)
will yield the same result as:
0030 LET C$=CRC(A$+B$)
That is: ,
HTA(C$) Value:
After Line 0010 $F353$
After Line 0020 $6053$
After Line 0030 $6053$

CSE( ) Case Function
Function CSE( )
Format:
1 Case Using Numerics CSE(num,compare_1,compare_2 [,ERR=stmtref])

2 Case Using Strings CSE(string$,compare_1,compare_2 [,ERR=stmtref])
Where =
num or string$ Value (numeric or string expression) to be used for comparison.
compare_1[$] First value (numeric or string expression) for comparison.
compare_2[$] Second value (numeric or string expression) for comparison. The dots ...
represent the third to nth values.
Returns: CTL value if match found, or 0 (zero) if no match found
Description:
The CSE( ) function is used to compare an expression with a series of values. Your expression is
compared with each of the argument variables. If there is a match, the CTL value returned tells you which
of the comparisons was a successful match. If no match is found the CSE( ) function returns 0 (zero).
Examples:
1000 INPUT X$
1010 ON CSE(CTL,1,2,1000,1020,1030)
1020 REM This handles cases via GOTO NOFKY,FK1,FK2,QRY_CST,DEL_CST,ADD_CST
That is, in the example above, if the value of CTL is 1 then control transfers to 1:FK1. Other CTL values
transfer to 2:FK2; 1000:QRY_CST; 1020:DEL_CST; 1030:ADD_CST. If no match is found the function
returns 0 (zero) and control transfers to NOFKY.
The example below shows strings in the comparison. In this case, no string match is found, so the CTL
value is 0 (zero) and control transfers to line 1000.
1010 ON CSE(TEST$,"ANTIDISESTABLISHMENTARIANISM","DOG","CAT","PIG") GOTO 1000,
1010:2000,3000,4000

CTL Control Code: Key Used to End Input
Numeric System Variable CTL
Returns: Integer (code), default range 0 (zero) to 5
Description:
This numeric system variable returns its current value as a numeric control code (integer) which indicates
how the user ended the last INPUT statement at the terminal. The following are the default values:
0 - Input terminated by <Return> key (normal)
1 - Input terminated by <F1> key
5 - Input terminated due to SIZ= option

CTL( ) Return CTL Definition
Function CTL( )
Format:
Return CTL Value CTL(chan,input[$][,ERR=stmtref])
Where =
chan Channel or logical file number or channel about which to return information. Usually 0
(zero), the terminal.
input[$] Either the keyboard character string received or the invalid CTL value. String or numeric
expression.
Returns: CTL values associated with input
Description:
The CTL( ) function is designed for use in programs that interact directly with the terminal. It gives you
access to the CTL lookup tables maintained internally in ProvideX. To use the CTL( ) function, you should
pass the input sequence to it. The function will return the CTL values associated with the input. For
example, PRINT CTL(0," ") returns -1099.
See also: Negative CTL Definitions, p. 583
Example:
The CTL( ) function will return a string value containing a list of control sequences for a specified control
value. The string is made up of a series of fields where the 1st byte indicates the number of characters in
the control sequence. The rest of the field shows the actual control sequence. To print control sequences
for function keys <F1> through <F4>:
0010 FOR CTL_CODE=1 TO 4
0020 PRINT 'LF',STR(CTL_CODE:"#0")," ",
0030 LET X$=CTL(READ 0,CTL_CODE)
0040 IF X$="" THEN GOTO 0070
0050 LET X=DEC(X$(1,1)); PRINT PAD(HTA(X$(2,X)),10),
0060 LET X$=X$(X+2); GOTO 0040
0070 NEXT
0080 PRINT " DONE"; STOP
-:RUN
1 000070
2 000071
3 000072
4 1B 000073 00FF82 DONE
If your expression is numeric, ProvideX will return any alternate CTL value that has been assigned. For
PRINT CTL(0,$000070$) ProvideX will return 1 (CTL=1 or the F1 key).
Example 2:
0010 REM Read an uppercase string into Y$ without editing. Stop on a CTL>0
0020 OPEN (1) FID(0); Y$=""
0030 READ RECORD (1,SIZ=1)X$
0040 IF X$<" " OR X$=$7F$ THEN GOTO 0100
0050 LET X$=UCS(X$),Y$=Y$+X$
0060 PRINT X$,; GOTO 0030
0100 LET C=CTL(0,X$,ERR=0050); GOTO 0130

0110 READ RECORD (1,SIZ=1)X1$
0120 LET X$=X$+X1$; GOTO 0100
0130 IF C>0 THEN GOTO 1000 ! Found it
0140 LET C=CTL(0,C,ERR=0160) ! Check alternates
0150 GOTO 0130
0160 PRINT 'RB',; GOTO 0030
1000 PRINT "DONE"; STOP

CUSTOM_VBX Create/Control VBX
Directive CUSTOM_VBX
Formats:
1 Define VBX, Logical ID CUSTOM_VBX id,@(col,line,width,height),name$,control$[,fileopt]

2 Define Event-CTL CUSTOM_VBX DEFCTL id,ctl_val,event$[,fileopt]
3 List of Event Names CUSTOM_VBX DEFCTL id,*,list$[,fileopt]
4 Add Item to List CUSTOM_VBX LOAD id,index,val$[,fileopt]
5 Remove List Item CUSTOM_VBX LOAD id,index,*[,fileopt]
6 Read Property Value CUSTOM_VBX READ id,property$,var$[,array_element][,fileopt]
7 Listing of Properties CUSTOM_VBX READ id,*,list$[,fileopt]
8 Write Property CUSTOM_VBX WRITE id,property$,val$[,array_element][,fileopt]
9 Disable/Enable CUSTOM_VBX {DISABLE | ENABLE} id[,fileopt]
10 Set Focus On CUSTOM_VBX GOTO id[,fileopt]
11 Remove VBX CUSTOM_VBX REMOVE id[,fileopt]
12 Hide/Show VBX CUSTOM_VBX {HIDE | SHOW} id[,fileopt]
Where =
id Unique logical identifier for the CUSTOM_VBX control object. Numeric expression:
integer.
@(col,line, Position and size of the CUSTOM_VBX region. Numeric expressions. Column and
lines.
name$ Name of the .VBX file containing the logic. String expression.
control$ Name of the control to use in the file (usually only one per VBX file). String
expression.
fileopt File options. Valid options for CUSTOM_VBX include:
KEY=char$ Hot key
OPT=char$ Single character parameters. See the list below.
TBL=properties$ Delimited initialization properties
The single-character parameters for OPT= are:
"s" - Scroll: Allows VBX to scroll within a resizable/scrollable dialogue box
"D" - Disabled: User cant access the VBX
"H" - Hide: Dont display the VBX
ctl_val CTL to be generated when an event occurs.
event$ Name / number of the VBX event.
NOTE: This directive will convert numerics/strings as required. This

means that you can READ or WRITE a numeric property into a
string variable. ProvideX will automatically convert the value
using current PRECISION.
list$ String variables receive the list of event / property names.

Where =
index Array index. Numeric expression, integer.
val$ Value of an item / property.
property$ Name / number of the VBX property.
var$ Variable to receive current value of the property.
Description:
Warning: VBXes are third party / proprietary utilities used to define objects. Please make sure
you have the right to use and subsequently distribute external tools.
Use the CUSTOM_VBX directive to load and define your given VBX custom control object. You must use
the same logical ID number (assigned in Format 1) for all subsequent references to your CUSTOM_VBX.
NOTE: You can use VBXes in both WINDOWS and UNIX systems when running in graphics
modes of ProvideX. There is no text mode support since VBXes are WINDOWS
programs and need a WINDOWS graphics device.
Whenever an error is detected in the VBX interface logic, ProvideX returns the VBX status or error code in
TCB(80). The chart below lists the status codes.
TCB(80) Returns Where VBX Status / Error =

03 RETURN without GOSUB
05 Illegal function call
06 Overflow
07 Out of memory
09 Subscript out of range
10 Duplicate definition
11 Division by zero
13 Type mismatch
14 Out of string space
16 String formula too complex
17 Can't continue
19 No Resume
20 Resume without error
28 Out of stack space
35 Sub or Function not defined
48 Error in loading DLL
49 Bad DLL calling convention
51 Internal error
52 Bad file name or number
53 File not found
54 Bad file mode
55 File already open
57 Device I/O error

58 File already exists
59 Bad record length
61 Disk full
62 Input past end of file
63 Bad record number
64 Bad file name
67 Too many files
68 Device unavailable
70 Permission denied
71 Disk not ready
74 Can't rename with different drive
75 Path/File access error
76 Path not found
91 Object variable not set
92 FOR loop not initialized
93 Invalid pattern string
94 Invalid use of Null
95 Cannot destroy active form instance
281 No More DDE channels
282 No foreign application responded to a DDE initiate
283 Multiple applications responded to a DDE initiate
284 DDE channel locked
285 Foreign application won't perform DDE method or operation
286 Time-out occurred while waiting for DDE response
287 User pressed ESC key during DDE operation
288 Destination is busy
289 Data not provided in DDE operation
290 Data in wrong format
291 Foreign application quit
292 DDE conversation closed or changed
293 DDE method invoked with no channel open
294 Invalid DDE Link format
295 Message queue filled; DDE message lost
298 DDE requires DDEML.DLL
320 Can't use character device names in filenames: 'item'
321 Invalid file format
341 Invalid object array index
342 Not enough room to allocate control array 'item'

343 Object not an array
344 Must specify index for object array
360 Object already loaded
361 Can't load or unload this object
362 Can't unload controls created at design time
363 Custom control 'item' not found
364 Object was unloaded
365 Unable to unload within this context
380 Invalid property value
382 'item' property cannot be set at run time
383 'item' property is read-only
384 'item' property can't be modified when form is minimized or maximized
385 Must specify index when using property array
386 'item' property not available at run time
387 'item' property can't be set on this control
388 Can't set Visible property from a parent menu
391 Name not available.
392 MDI Child forms cannot be hidden
393 'item' property cannot be read at runtime
394 'item' property is write-only
400 Form already displayed; can't show modally
401 Can't show non-modal form when a modal form is displayed
402 Must close or hide topmost modal form first
403 MDI forms cannot be shown modally
404 MDI child forms cannot be shown modally
420 Invalid object reference
421 Method not applicable for this object
422 Property 'item' not found
424 Object required
425 Invalid object use
426 Only one MDI form allowed
460 Invalid clipboard format
461 Specified format does not match format of data
480 Can't create AutoRedraw image
481 Invalid picture
482 Printer error
708 File not found: |
710 File already open: |

712 Device IO error: |
713 File already exists: |
716 Disk full: |
719 Bad file name: |
722 Too many files: |
725 Permission denied: |
730 Path access error: |
731 Path not found: |
732 Must have startup form or Sub Main( )
735
Format 1 Creates: CUSTOM_VBX id,@(col,line,width,height),name$,control$[,fileopt]

Use this format to define or create a CUSTOM_VBX control object and assign it a unique logical ID.
0020 CUSTOM_VBX 100, @(10,10,10,10),"MHCD200.VBX","MhCardDeck"

When you create the CUSTOM_VBX you can set default properties. Use the TBL="property=value"
option. The last character in the list sets the delimiter for the rest of the list.
Format 2 Defines Event-CTL: CUSTOM_VBX DEFCTL id,CTL_val,event$

Use the CUSTOM_VBX DEFCTL format to define the control values for events. For example:
0030 CUSTOM_VBX DEFCTL 100,101,"Click"
Format 3 Lists Event Names: CUSTOM_VBX DEFCTL id,*,list$

We recommend that you refer to your proprietary VBX documentation for information on VBX events and
properties. However, you can also obtain a list of VBX events by using ProvideX to create a
CUSTOM_VBX on the screen and then using the CUSTOM_VBX DEFCTL format. Your string variable
receives a list of events (comma-separated and in numeric order).
For example:
0030 CUSTOM_VBX DEFCTL 100,*,A$
Format 4 Adds Item to List: CUSTOM_VBX LOAD id,index,val$

Use the CUSTOM_VBX LOAD format to add an item to a CUSTOM_VBX list. For example:
0130 CUSTOM_VBX LOAD 150,6,"abc"
Format 5 Removes Item from List: CUSTOM_VBX LOAD id,index,*

Use this CUSTOM_VBX LOAD format to remove an item from a CUSTOM_VBX list. Note the asterisk in
place of a value to indicate that you want an item removed. For example, to remove item 86 from the
CUSTOM_VBX whose id is 15000:
0190 CUSTOM_VBX LOAD 15000,86,*

Format 6 READs Property: CUSTOM_VBX READ id,property$,var[,array_element]
Use the CUSTOM_VBX READ format to read the current value of a property. For example:
CUSTOM_VBX READ 100,"Suit",RND(4)
Format 7 Lists Properties: CUSTOM_VBX READ id,*,var$

We recommend that you refer to the proprietary VBX documentation for each product for information on
VBX events and properties. However, you can also obtain a list of event Properties by using ProvideX to
create a CUSTOM_VBX on the screen and then using the CUSTOM_VBX READ format. Your string
variable receives the list (comma-separated and in numeric order).
If you then issue a CUSTOM_VBX READ id,"",X$ (with a null value in place of the asterisk), you will
receive a string of characters indicating the Property types. Lower case values indicate arrays.
Where =
"S" String
"I" 16-bit integer (numeric)
"L" 32-bit integer (numeric)
"F" Single bit Boolean value/flag (numeric)
"C" Color reference (string)
"B" 8-bit byte ENUM value (numeric)
"R" Real floating point value (numeric)
"X" 32-bit X position in Twips (numeric)
"Y" 32-bit Y position in Twips (numeric)
"P" Picture / bitmap (string, output only)
"S" String in VBasic format (string)
Format 8 Updates Property: CUSTOM_VBX WRITE id,property,val$[,array_element]

Use the CUSTOM_VBX WRITE format to update or write a property. For example:
0080 CUSTOM_VBX WRITE 100,"Value",RND(13)+1

0090 CUSTOM_VBX WRITE 100,"Suit",RND(4)
Format 9: CUSTOM_VBX {DISABLE | ENABLE} id

Use the CUSTOM_VBX DISABLE format to gray out the selection of a CUSTOM_VBX. This prevents the
user and programs from gaining access to it. To restore access to a disabled CUSTOM_VBX control, use
the CUSTOM_VBX ENABLE format.
0150 CUSTOM_VBX DISABLE 100
Format 10 Sets Focus: CUSTOM_VBX GOTO id

Use the CUSTOM_VBX GOTO format to set the Focus on a CUSTOM_VBX. For example:

0130 CUSTOM_VBX GOTO 100
Format 11 Deletes: CUSTOM_VBX REMOVE id

Use the CUSTOM_VBX REMOVE format to remove or delete a CUSTOM_VBX. For example:
0150 CUSTOM_VBX REMOVE 100
Format 12: CUSTOM_VBX {HIDE | SHOW} id

Use the CUSTOM_VBX HIDE format to prevent the display of a CUSTOM_VBX. Use the CUSTOM_VBX
SHOW format to restore the display.
0150 CUSTOM_VBX HIDE 100
Sample CUSTOM_VBX Routine:

A simple SHUFFLE the Deck program uses the Microhelp Card Deck VBX. It will shuffle the deck
whenever the mouse is clicked on the card displayed on the screen.
0010 PRINT 'CS'

0020 CUSTOM_VBX 100,@(10,10,10,10),"MHCD200.VBX","MhCardDeck"
0030 CUSTOM_VBX DEFCTL 100,101,"Click"
0040 OBTAIN (0,SIZ=1)'ME',A$,'MN',;CTLVAL=CTL'
0050 IF CTL=4 THEN END
0060 IF CTL<>101 THEN GOTO 0040
0070 FOR I=1 TO 10
0080 CUSTOM_VBX WRITE 100,"Value",RND(13)+1
0090 CUSTOM_VBX WRITE 100,"Suit",RND(4)
0100 WAIT .05
0110 NEXT
0120 GOTO 0040
This program randomly updates the two properties "Value" (card 1-13) and "Suit" (0-3) with a short delay
between updates. Note that the event is defined as CTL 101 whenever the mouse is clicked on the card.

CVS( ) Convert String
Function CVS( )
Format:
1 Reformat String CVS(data$,[cvs_code[:ctl_char$],...][,ERR=stmtref])

2 Return Accent Table CVS(*)
Where =
data$ Data to convert. String expression.
cvs_code Conversion type. Numeric expression. See the chart below.
ctl_char$ Optional control character. String expression. Default: the blank.
* To return the current 256-byte accent translation table (Ver. 4.20).
Returns: Converted value of string expression, or accent translation table
Description:
The CVS( ) function converts your string of data to different forms based on the numeric values you use for
cvs_code (e.g. to convert to upper case, stripped string, etc.). Your numeric expression tells ProvideX the
type of conversion to perform. If you append a colon ":" and string value, the control character used in the
conversion will be the first character of the string. Otherwise, it will be a space.
You can also use the function to return the current accent translation table and to do translations based on
it (Ver. 4.20). See DEF CVS / DTE / LCS / UCS Define System Tables, p. 70(d).
The value of cvs_code is made up of a series of binary values indicating the following:
Value Conversion to Take Place:

1 Strip leading control characters
2 Strip trailing control characters
4 String to upper case
8 String to lower case
16 Replace non-printable characters with the control character
32 Replace multiple occurrences of the character with one
64 Replace $ with a defined currency symbol, comma with a defined thousands separator,
and period with a defined decimal point.
See also: 'CU'=num Currency Symbol, p. 540(p)
'DP'=num Decimal Point Symbol, p. 542(p)
'TH'=num Thousands Separator, p. 559(p)

128 Replace a defined currency symbol, thousands separator and decimal point with $,
comma, and period respectively (inverse of value 64 above).
256 String to mixed case (first letter of each word is upper case, the rest of the letters are
lower case).
512 ProvideX translates the string expression provided in data$ based on the current accent
translation table (Ver. 4.20).

Example Result
PRINT "|",CVS(" The Cat ",1:" "),"|" yields |The Cat |
PRINT "|",CVS(" The Cat ",2:" "),"|" yields |The Cat|
PRINT "|",CVS(" The Cat ",39),"|" yields |THE CAT|
32+4+2+1=39 (you can use a sum)
PRINT CVS("$$$123",32:"$") yields $123
See also: STP( ) Strip Leading/Trailing Characters, p. 407(f)
LCS( ) Return Lower Case String, p. 217(f)

CWDIR Change Working Directory
Directive CWDIR
Format:
Change Directory CWDIR new_dir$[,ERR=stmtref]
Where =
new_dir$ String expression. Name of the new directory in which you want to work or run
applications. You can include a disk letter and colon ":" to change to another drive.
Description:
Use the CWDIR directive to change from your current working directory to a new one. If your given
directory name does not exist, ProvideX returns an Error #12: File does not exist (or
already exists).
See also: LWD Current Working Directory, p. 253(v)
HWD Starting/Home Directory, p. 183(v)
Examples:
0010 CWDIR "C:\"+C$+"PROGS"
0020 RUN "SOMETHING"
0030 CWDIR HWD ! Return home

DATA Define Data Elements
Directive DATA
Format:
Define DATA Values DATA expression[$][, ...]
Where =
expression[$], ... A series of string or numeric expressions
Description:
Use the DATA directive to define the values for your READ DATA directive. The values to be read can
include constants, variables, and/or expressions. You can use formatted IOLISTs with a READ DATA
statement. When ProvideX executes the READ DATA directive, it evaluates each expression in order and
places its value into the corresponding variable(s) you define in your READ DATA directive.
When ProvideX progresses through reading the data, it increments an internal pointer to the next data
expression. When the end of DATA statement is reached, ProvideX proceeds to the next DATA statement
in the program. ProvideX returns an Error #2: END-OF-FILE on read or File full on write
when no further DATA statements exist in the program.
You cant use the DATA directive in a compound statement.
See also: READ DATA Read Data from Program, p. 345(d)
RESTORE Reset/Change Program Data Position, p. 360(d)
LOAD Read Program into Memory, p. 245(d)
Example:
0010 DATA "Dog","Cat","Pig"
0020 DATA "Pig","Cat","Dog"
0030 READ DATA X$
0040 PRINT X$," | ",
0050 GOTO 0030
-:BEGIN
-:RUN
Dog | Cat | Pig | Pig | Cat | Dog | 0030 READ DATA X$

Error #2: END-OF-FILE on read or File full on write
1:END
-:EDIT 30
-:0030 READ DATA X$,ERR=1000
-:RUN
Dog | Cat | Pig | Pig | Cat | Dog | DONE

-:?ERR
0

DAY Return Current System Date
String System Variable DAY
Returns: Current system date, formatted
Description:
The DAY variable returns the current system date (e.g. 11/15/00), in a format based on the date style set in
the DAY_FORMAT directive (the mask is MM/DD/YY by default). Changes in the DAY_FORMAT mask are
reflected in the value returned in the DAY variable.
See also: DAY_FORMAT Specify DAY Format, p. 68(d)
Example:
0100 PRINT DAY," ",
0110 DAY_FORMAT "DD/MM/YYYY"; PRINT DAY
-:run
11/15/99 15/11/2000

DAY_FORMAT Specify DAY Format
Directive DAY_FORMAT
Format:
1 Set Date Format Mask DAY_FORMAT [new_mask$]

2 Read Date Format Mask DAY_FORMAT READ current_mask$
Where =
new_mask$ String expression containing the format for the variable DAY. Optional. Defaults to
"MM/DD/YY".
current_mask$ String expression containing the current DAY_FORMAT setting.
Description:
Use the DAY_FORMAT directive to change the format mask for the DAY variable. The format string
contains the new format for the DAY variable. Characters in the format string control the following:
DD Insert current day
MM Insert current month
YY Insert current year (last two digits only)
YYYY Insert four digit year
AA Insert current year using 00-99 for 1900 thru 1999,
A0-A9 for 2000 thru 2009, B0-B9 for 2010 thru 2019, etc.
All other characters in the mask are returned as literals in the DAY variable. The DAY_FORMAT stays in
effect until a START directive is executed.
The DAY_FORMAT directive mask can now contain the letters AA (e.g. MM/DD/AA) to help you with
Y2K conversions (Ver. 4.10). The format AA indicates a packed two-character year field. ProvideX
returns $A0$ for the year 2000, $A1$ for 2001, $B0$ for 2010, etc up to $Z9$ for the year 2269. This
format was added to assist with conversion issues in legacy applications.
See also: DAY Return Current System Date, p. 67(v)
DTE( ) Convert Date, p. 106(f)
JUL( ) Return Julian Date, p. 200(f)
Example 1:
0010 PRINT DAY
0020 DAY_FORMAT "YYYY MM/DD"
0030 PRINT DAY
->RUN
11/15/00
2000 11/15
Example 2:
0010 LET X$="01/01/A0"
0020 DAY_FORMAT "MM/DD/AA"
0030 PRINT JUL(X$)
0040 PRINT DTE(10957:"%Y %Ml %D")
->RUN
10957
2000 January 1

DEC( ) Get Binary of String
Function DEC( )
Format:
String to Binary Integer DEC(string$[,ERR=stmtref])
Where =
string$ Character string or variable containing the value to be converted to binary
Returns: Twos complement binary equivalent of your string
Description:
The DEC( ) function converts a string to its corresponding binary equivalent. (The value returned is a two's
complement binary integer which corresponds to the value of your string.)
Example:
0020 LET A$="a"; PRINT DEC(A$),
0030 LET B$=$0040$; PRINT " | ",DEC(B$),
0040 LET C=DEC("A"); PRINT " | ",C,
0050 LET A=DEC($FE$); PRINT " | ",A,
0060 PRINT " | DONE"
-:RUN
97 | 64 | 65 | -2 | DONE

DEF CVS / DTE / LCS / UCS Define System Tables
Directives DEF
Format:
1 Define Accent Conversion DEF CVS(new_table$)

2 Define Date Table DEF DTE(new_table$)
3 Define Lower-Case Table DEF LCS(new_table$)
4 Define Upper-Case Table DEF UCS(new_table$)
Where =
new_table$ String expression. Contains the new definition (contents) of the table.
Description:
Use these DEF directives to DEFINE new system TABLES for Accent Conversion, Date, Lower Case and
Upper Case.
See also: CVS( ) Convert String, p. 63(f)
LCS( ) Return Lower Case String, p. 217(f)
Format 1: Define Accent Translation Table

You can use the DEF CVS directive to set the values for the accent conversion table (Ver. 4.20). The value
of each byte to be translated is used as an offset into the table. The character at the particular offset is
used in place of the original character.
See also: Key Definition Attributes, p. 213
CVS( ) Convert String, p. 63(f)
Format 2: Define Date Table

The DEF DTE( ) directive uses a string made up of 46 comma-delimited fields. These fields are used by
the DTE function and should have the following values:
Number of Fields Field Contents:

12 fields Long form month names (%Ml)
7 fields Long form day names (%Dl)
2 fields Long form lower-case am/pm (%pl)
2 fields Long form upper-case AM/PM (%Pl)
12 fields Short form month names (%Ms)
7 fields Short form day names (%Ds)
2 fields Short form lower-case am/pm (%ps)
2 fields Short form upper-case AM/PM (%Ps)

Formats 3 and 4: Define Lower- and Upper-Case Tables
The DEF LCS and DEF UCS directives both take a 256 character string and replace the standard case
conversion table with the strings value. Whenever ProvideX converts the case of a character, it uses the
characters binary value as an offset into the tables.
Warning: Be careful when changing the UCS conversion table because the ProvideX compiler
uses this table to convert keywords to upper case before scanning its syntax tables.
If you define an incorrect table, you may be unable to enter any subsequent
commands in ProvideX. See the list of Reserved Words, p. 632.

DEF FN Define Function
Directive DEF FN
Format to Define Functions:
1 Single Line DEF FNvar[$]([LOCAL ]argvar[,[LOCAL ]argvar][, ])=expression[$]

2 Multi-Line DEF FNvar[$]([LOCAL ]argvar[,[LOCAL ]argvar][, ])
RETURN expression[$]
END DEF
Where =
FNvar[$] Name of the function, appended to "FN". Use a valid string or numeric variable
name, e.g. FNX or FNABC$.
LOCAL Optional keyword. Indicates that an argument variable is local to the function. Use
LOCAL to prevent permanent changes to your program variables. ProvideX defers
processing the LOCAL clause in functions until all arguments are parsed.
argvar ... Comma-separated list of variables that correspond to arguments passed to the
function or returned in the expression.
expression[$] String or numeric expression. In multi-line functions the expression is the value
returned. In single-line functions, the expression defines the value of the function.
Description:
Use the DEF FN directive to create your own single- or multi-line functions. Your functions are
considered string or numeric depending on the type of variable you use in the function name. (In
EXECUTION mode, Providex skips past the function without executing it. ProvideX resumes after the DEF
FN directive, executing the rest of your code until it reaches your statement invoking the FNvariable( )...
whereupon it applies the function.)
1. Single Line Function: DEF FNvar([LOCAL ]argvar[,LOCAL argvar[, ]])=expression

In a single-line function assignment, your expression defines the value to be returned by the function.
Include the optional keyword LOCAL to define your argument variables as local.
Example:
0010 DEF FNX(A,B)=A^B
0020 LET A=1, B=2
0030 PRINT A,B,FNX(3,4),A,B
0040 STOP
->RUN
1 2 81 3 4
When FNX is invoked (as in PRINT FNX(3,4)), the values in the variable list are assigned to the
variables in the function definition.
NOTE: The variables in the function definitions argument list represent actual variables in
the program. Their values are subject to change every time the function is invoked.
Unless you define your variables as LOCAL, changes to the variables in your
program will be permanent. In the example above, variables A and B in the program
are changed by FNX(3,4), because they arent defined as LOCAL.

Format 2: Multi-Line Function
DEF FNvar[$](LOCAL argvar[,[LOCAL ]argvar][, ])
RETURN expression[$]
END DEF
When ProvideX encounters a multi-line definition, execution skips the subsequent statements until an
END DEF directive is found. (Again, the function is not executed until it's invoked.) Include the optional
keyword LOCAL to define your variables as local.
Use the RETURN expression to specify the value to be returned by the multi-line function. To generate an
error value in a multi-line function, use the ESCAPE directive followed by your given value.
Example, Multi-Line Function:

0010 DEF FNX(A,B)
0020 IF A<0 OR B<0 ESCAPE 40 ! Variables' values must be >=0
0030 RETURN SQR(A^2+B^2) ! Length of hypotenuse
0040 END DEF
0100 PRINT FNX(7,8)
->RUN
10.63

DEFAULT Branch If No Matching CASE
Directive DEFAULT
Format:
Define Default Case DEFAULT; statement$
Where =
statement$ Directive to handle default (undefined) cases. String expression. It doesnt have to
be on the same line as the DEFAULT directive, but it can be if you include the
semicolon.
Description:
Use the DEFAULT directive to create branch points to handle situations where there is no corresponding
CASE. If a matching CASE is not found and the DEFAULT is found, execution continues at this point.
CASE Branch Points, p. 36(d)
Example:
Preset the value of A$ if you RUN this example, or see the chart below the LISTing for sample DEFAULTs.
5000 SWITCH A$
5040 CASE "Sasquatch"
5060 DEFAULT
5080 END SWITCH
5090 PRINT "DONE"

Break
Note that "Alligator" in this example drops through with
DONE
no BREAK to intervene. "Alligator" doesnt DEFAULT
to "Wild Animal" because ProvideX treats it as a
defined CASE for "Domestic Animal".
Break
DONE
a$="cat" Wild Animal DEFAULTs. Not defined. (Note that CASE is case-
DONE sensitive.)
a$="Sasquatch" Break CASE matched. Defined, but the CASE statement
a$="Fox" Wild Animal DEFAULTs. Not defined.
DONE

DEFCTL Define/Redefine CTL Values
Directive DEFCTL
Format:
1 Define/Delete CTL Values DEFCTL [WINDOW] eom_string$={ctl-val | *}

2 Redefine Invalid CTLs DEFCTL [WINDOW | WINDOW+] invalid_ctl={alternate | *}
Where =
eom-string$ EOM (End of Message) character sequence. Hex string expression.
ctl-val CTL variables value. Numeric expression, integer.
* (asterisk) To delete a previously defined CTL value (e.g. DEFCTL eom$=* ).
WINDOW[+] Optional keyword.
WINDOW: CTL setting is for the current window only.
WINDOW+: DEFCTL will cascade to apply to lower level windows.
invalid_CTL Invalid CTL value to be redefined. Numeric expression.
alternate Alternate integer to set as the CTL value. Numeric expression.
Description:
Use the DEFCTL directive to define additional CTL values. If you use the the DEFCTL WINDOW format,
the definition is only maintained for the current window. Use WINDOW+ if you want the definition to
cascade to lower level windows.
Format 1 Defines/Deletes CTL Values: DEFCTL [WINDOW] eom-string$={ctl-value | *}

Use the DEFCTL directive to define an additional CTL value to be returned for a given EOM (End of
Message) value or to delete one. The EOM string is the sequence of characters that was received from
the terminal to end the current input. The first character of the string must be a non-printable character
between $00$ and $1F$, or $7F$.
Positive CTL values will be returned to your program. Negative CTL values have special significance to
ProvideX. (See the list of Negative CTL Definitions, p. 583 at the end of this Language Reference and
see Function & Control Keys.)
See also: CTL Control Code: Key Used to End Input, p. 53(v)
EOM End of Message Character String, p. 120(v)
Examples:
0010 DEFCTL $09$=6 ! Set TAB key to return CTL=6
0020 DEFCTL $1B38$=7 ! Set HOME <esc>H to CTL=7
0030 DEFCTL $09$=* ! Delete control value setting defined @line 0010
Format 2 Redefines Invalid CTL: DEFCTL [WINDOW | WINDOW+] invalid_ctl={alternate | *}

Use this format of the DEFCTL directive to define alternate CTL values to be applied whenever an invalid
CTL value is received. For example, the Up-Arrow is CTL=-1011. You can redefine it to return a CTL
value of 3, which in turn could be interpreted in your ProvideX program as go back one field.
See also: CTL( ) Return CTL Definition, p. 54(f)

Example:
0010 SETTRACE
0020 DEFCTL -1011=3 ! Return CTL 3 on up arrow
0030 INPUT "Enter name:",N$
0040 ON CTL GOTO 0050,0030,0030,0060,0060
0050 INPUT "Enter Addr:",A$
0060 ENDTRACE ; PRINT "DONE"; END
-:run
0010 SETTRACE
Enter name: ! User hit up arrow
0040 ON CTL GOTO 0050,0030,0030,0060,0060
DONE
To Create a Hot Key

ProvideX allows you to create a hot key that will call a program when struck and will be operative whenever
the system is awaiting input.
To create such a hot key, define the control sequence that is generated by the key as a negative CTL value
in the range -10 through -999. Then create and save your hot key program using the naming convention
$CTL-num where num is the CTL value. Remember in your hot key program not to disturb the
environment ( i.e. dont close any files that are already open, but close any files you open in this program
and remove any windows you create).
Example:
The keystroke <Ctrl-A> returns $01$, which is defined in MY_START_UP program as a hot key:
1000 DEFCTL $01$=-500
ProvideX will call $CTL-500 whenever anyone hits the hot key <Ctrl-A> throughout the current session.
(The $CTL-500 program created for this example draws a pop-up window, allows some functions and
closes the window when done. The code is not included here.)
During Conversions
When you convert BBx style programs to ProvideX, it is sometimes necessary to have function and edit
keys return single-character values. To do this, set both the 'EL' and 'FL' mnemonics and then use
DEFCTL to redefine the mapped values and allow standard ProvideX functions to continue to operate.
See also: 'EL' Start Edit_Key Load, p. 506(m)
'FL' Begin Function_Key Load, p. 509(m)
Example:
The following example redefines function keys <F5> through <F8> to return a single hex character ($F5$
through $F8$ respectively). It also maps some of the input edit keys to single character codes.
0010 DEFCTL $000074$=5 ! Reset F5 TO CTL=5
0100 ! ^ 100 - Map F5-F8 to return $F5$ through $F8$
0110 PRINT 'FL',"2"+CHR(4)+CHR(1)+$F5$, ! F5 = $F5$

0150 DEFCTL $F5$=5
0160 DEFCTL $F6$=6
0170 DEFCTL $F7$=7
0180 DEFCTL $F8$=8
0200 ! ^ 100 - Change Edit keys to single character
0210 PRINT 'EL',"2"+CHR(4)+CHR(1)+$01$, ! Home = $01$
0220 PRINT 'EL',"2"+CHR(5)+CHR(1)+$1A$, ! End = $1A$
0230 PRINT 'EL',"2"+CHR(6)+CHR(1)+$15$, ! PGUP = $15$
0240 PRINT 'EL',"2"+CHR(7)+CHR(1)+$06$, ! PGDN = $06$
0250 PRINT 'EL',"2"+CHR(8)+CHR(1)+$14$, ! Insert = $14$
0260 PRINT 'EL',"2"+CHR(9)+CHR(1)+$18$, ! Delete = $18$
0270 DEFCTL $01$=-1010 ! Home
0280 DEFCTL $1A$=-1018 ! End
0290 DEFCTL $15$=-1014 ! PGUP
0300 DEFCTL $06$=-1013 ! PGDN
0310 DEFCTL $14$=-1009 ! Insert
0320 DEFCTL $18$=-1007 ! Delete

DEFPRT Define Printer
Directive DEFPRT
Format:
Define as Printer DEFPRT (chan)col,line
Where =
chan Logical file number or channel of the file to define as a printer.
col Default maximum number of columns supported by the printer. This must be an
integer value, range 0 to 255.
line Default maximum number of lines supported by the printer. This must be an integer
value, range 0 to 255.
Description:
Use the DEFPRT directive to specify that your given channel refers to a printer. Specify the default
maximum lines and columns supported by the printer. If you dont designate your file as a printer,
ProvideX doesnt apply printer mnemonics and the values for the MXC( ) and MXL( ) functions are not
reset.
You can use the DEFPRT directive for TCP files.
Example:
0010 DEFPRT (LFO)80,25

DEFTTY Define Terminal Size
Directive DEFTTY
Format:
Define as Terminal DEFTTY [(chan)]col,line
Where =
chan Channel or logical file number of the file to define as a terminal.
col Default maximum number of columns for the terminal. This must be an integer value,
range 0 to 255.
line Default maximum number of lines for the terminal. This must be an integer value,
range 0 to 255.
NOTE: The number of lines has an additional limit based on a maximum

of 8190 characters per window (i.e. the maximum number of lines
is 8190/col ).
Description:
Use the DEFTTY directive to designate that your logical file number refers to a terminal. You can specify
the default maximum lines and columns supported by the terminal. If you dont designate your file as a
terminal, windows and other mnemonics are not supported.
Example:
0010 DEFTTY (LFO)80,25

DELETE Remove Lines from Program
Directive DELETE
Format:
Delete Program Statements DELETE [start_stmtref][,[end_stmtref]]
Where =
start_stmtref Starting program statement to be deleted. Line label or number.
end_stmtref Last program statement to be deleted. Line label or number.
Description:
Use the DELETE directive to delete a range of statements from your current program. For example,
DELETE SECT1,450 deletes from statement label SECT1: to line 0450, inclusive
If you only include a starting statement reference, only that statement is deleted.
DELETE 510 ! Deletes statement 0510
510 ! Is the same as DELETE 510
If you include both a starting reference and a comma, all statements from the reference to the end of the
program are deleted. If you include a comma and an ending reference, statements from the start of the
program up to and including the ending reference are deleted.
DELETE 260, ! Deletes statements from line 0260 to program end
DELETE ,890 ! Deletes from program start, up to and including line number 0890
If you omit statement references, the complete program is deleted from memory.
Example:
->LIST
0010 REM "TEST"
0020 PRINT "TEST"
0030 STOP
->DELETE
->LIST
No program is in memory, so ProvideX doesnt return a LISTing and will report errors if you try to EDIT or
SAVE:
->EDIT 20
Error #21: Statement number is invalid
->SAVE
Error #10: Illegal pathname specified
You can reLOAD your program to LIST, EDIT or SAVE:
-:LOAD "TEST"
-:EDIT 20
0020 PRINT "TEST DONE"
-:SAVE

DICTIONARY Data Dictionary Access
Directive: Restricted DICTIONARY
Format:
NOTE: Use of the DICTIONARY directive is reserved exclusively for Best Software Canada
Ltd.. (Its not available for your applications.) Its use is beyond the scope of this
document and its syntax has been provided here only for the sake of completeness.
1 Read DICTIONARY READ (chan,fileopt)varlist
2 Write DICTIONARY WRITE(chan,fileopt)varlist
3 Remove DICTIONARY REMOVE (chan,fileopt)
Where =
chan Channel or logical file number of the file containing the data dictionary to access.
fileopt File options. Valid options for DICTIONARY include:
IND=num Field number
<0 for external key
>0 for internal fields
=0 file info. record
varlist Comma-separated list of variables, literals, mnemonics, IOL= options, and/or
location functions - '@(...)'.
Description:
The DICTIONARY directive allows Best Software Canada Ltd. to gain access to the internal ProvideX data
dictionary portions of the ProvideX databases and to maintain them.

DIM Define Arrays and Strings
Directive DIM
Formats:
1 Define Array DIM array_name[$](subscript_1[,subscript_2[,subscript_3]])

2 DIM Composite String DIM var$:IOL=iol_ref
3 Initialize String DIM var$(len[,char$])[,...]
Where =
array_name[$] Numeric or string variable to be dimensioned as an array.
subscript_1 1st dimensions (minimum:maximum) of array. Numeric expression, integers.
subscript_2 2nd dimensions (minimum:maximum) of array. Numeric expression, integers.
subscript_3 3rd dimensions (minimum:maximum) of array. Numeric expression, integers.
var$ Name of string variable to be defined or initialized.
iol_ref Either a string variable containing the object code of an IOLIST or a statement
reference to an IOLIST (statement number or label).
len Desired length of the string variable. Numeric expression, integer.
char$ Value whose 1st character will be used to fill the variable up to the length specified.
String expression.
Description:
You can use the DIM directive to define an array, to define a composite string or to initialize a string.
See DIM( ) Generate String, p. 85(f) to read the total number, minimum number and maximum number
of elements in an array.
The maximum number of elements in an array (regardless of the number of dimensions) is 32767 for 32-
bit ProvideX (Ver. 4.10). That is, you can use either DIM A$[1:32767] or DIM A$[32766] (zero
based). (The limit in 16-Bit Windows and DOS remains 8192 elements.)
NOTE: For numeric arrays you can use either parenthesis ( ) or square brackets [ ] to define
arrays or select elements. For string arrays, to avoid confusion with substrings, use
only square brackets [ ]. All arrays have three subscripts. An array defined as X$[4]
has values 0:4 for subscript 1, 0:0 for subscript 2, and 0:0 for subscript 3.
Format 1 Defines Array: DIM array_name[$](subscript_1[,subscript_2[,subscript_3]])[,...]

You can use the DIM directive to define an array with one, two or three dimensions. Specify the
dimensions using the values in the DIM statement. The dimensions of the array are defined as:
[minimum]:maximum
If you omit the minimum dimension, then ProvideX uses the default minimum, 0 (zero). When you refer to
items in arrays, the lowest subscript is the minimum value specified, the highest is the maximum value
specified.
You can redefine existing arrays using the DIM statement. The values of all elements in the array are
automatically initialized to zero by the DIM statement.
Examples:
DIM A(2,2,2)

The example above defines a three-dimensional array with three elements (0 thru 2) in each dimension for
a total of 27 elements.
DIM CATS[1:10] ! Defines dimension one with 10 elements (1 thru 10). Dimensions 2 and 3 are 0:0
Format 2 Defines Composite String: DIM var$:IOL=iol_ref

Use this format of the DIM directive to define a composite string variable consisting of the fields specified in
your IOLIST. The variable returns a string made up of the fields you specified in the IOLIST. If you modify
the variable (e.g. by adding a field) ProvideX will modify the fields in your IOLIST.
Field names in the IOLIST are all prefixed by the name of the variable and a dot ("."). For example:
0010 DIM CST$:IOL=1000
1000 IOLIST NAME$,ADDR$,CITY$,ZIP
yields the string CST$ consisting of CST.NAME$, CST.ADDR$, CST.CITY$, and CST.ZIP. Each field is
separated by the SEP or delimiter in the default record format.
You can use a CLEAR directive to reset a variable DIMensioned as a string template (VER. 4.01 ), e.g.
CLEAR CST$.
See also: IOLIST Specify Variable List, p. 198(d)
CLEAR Reset Variables, p. 45(d)
Example:
0010 DIM PRD$:IOL=2000
2000 IOLIST DESC$:[CHR(30)],COST:[NUM(6,2)]
This defines PRD$ as a 36 character string consisting of PRD.DESC$ for 30 characters and PRD.COST
for 6 digits with a scale of 2 (2 implied decimal digits).
Composite Strings vs BBx Templates

ProvideX composite strings are made up of the variables you specify in your composite string definition,
whereas string templates are strings which are parsed to obtain the various logical variables. This has the
following impact, which you should consider when you design your applications:
You can pass a variable that is part of a composite string (e.g. CST.NAME$) to a subroutine
and have a value returned in it. In a string template, however, CST.NAME$ would be
considered a substring which could not be altered by a subroutine.
There is no performance impact when referencing individual variables in a composite string.
There can be a performance impact when referencing logical variables in a template,
especially when the template has variable length fields. On the other hand, when you
reference the complete composite string, the string will be reconstructed each time. The
string template always exists in memory, with no reconstruction required.
Unlike string templates, composite strings can be reconstructed on the fly.
Example:
0010 IOLIST NAME$,ADDR$,CITY$,AMT
0020 IOLIST NAME$,ADDR$,CITY$,ZIP$,AMT
0030 CST.ZIP$=""
0050 READ RECORD (1)CST$

0070 WRITE RECORD (1)CST$
The logic above automatically inserts CST.ZIP$ into the composite string while preserving the
other data elements. Note that composite string variables are not implicitly cleared when the
composite string is defined, whereas templates are.
Since composite strings reference real variables, fields in composite strings are not typeless.
That is, in a composite string, ProvideX considers CST.AMT, CST.AMT$, and CST.AMT% to
be three different fields, whereas in a string template these would all refer to the same field.
ProvideX does not currently support subscripting with composite strings.
Format 3 Initializes String With Fill Character: DIM var$(len[,char$])[,...]

You can use the DIM directive to define a string variable of a specific length. You can also use the DIM
statement to define the value of the string variable. ProvideX uses the first character of the value you set
in your char$ string as the fill character for the string being defined. The fill character is repeated for the
length of the string, as seen below:
DIM A$(5,"*Cat") is the same as DIM A$(5,"*") - both yield A$="*****"

If a value is not given (or is NULL) then the string is initialized to spaces.
You can combine this string initialization with the definition of string arrays (above) to pre-initialize all the
elements of a string array. For example, the DIM statement DIM ACC_IDS[10](6,"0") defines an
array of 11 strings, each pre-initialized with 6 zeroes.

DIM( ) Generate String
Function DIM( )
Format:
1 Generate String DIM(len[,fill$][,ERR=stmtref])

2 Read Total in Array DIM(READ NUM(array_name[$][,subscript]))
3 Read Max. in Array DIM(READ MAX(array_name[$][,subscript]))
4 Read Min. in Array DIM(READ MIN(array_name[$][,subscript]))
Where =
array_name[$] Name of a previously dimensioned array.
len Desired length of the string variable. Numeric expression, integer.
fill$ Text string or value which will be used to fill the variable up to the length specified.
String expression.
subscript Arrays dimensions (first, second, or third).
Returns: Initialized string, or information about dimensions of array
Description:
You can use the DIM( ) function to generate or initialize a string. You can also use it to obtain information
about the size of an array you have already DIMensioned using the DIM directive.
Format 1 Generates or Initializes String: DIM(len[,fill$][,ERR=stmtref])

Use this format to generate or initialize a string whose length you specify. The function fills the string by
using your value for fill$.
NOTE: This format of the function behaves almost like the DIM directives format to initialize
strings. However, instead of repeating only the first character of the string, as in the
directive, the function repeats the complete value of the fill string. (See also DIM
Define Arrays and Strings, p. 82(d) for the format to initialize strings).
The maximum length of string that can be generated by this function is 32767 bytes. If you omit the fill
string, ProvideX uses spaces as fill characters.
Examples:
0100 PRINT ":",DIM(11,"*Cat"),":"
->RUN
*Cat*Cat*Ca:
0100 PRINT 'CS',"A Title",@(0,1),DIM(80,"-")

0110 REM The DIM( ) above returns a string of hyphens "-" 80 characters long
->RUN
A Title
-------------------- ... etc.
See also: +S and -S Solid Lines: Substitution ON/OFF, p. 526(m)

Formats 2,3,4 (below): Read Dimensions (Size) of Array:
Use Formats 2, 3, and 4 of the DIM( ) function (listed below) to READ a given array's total number of
elements, the minimum element's number and the maximum element's number. If the variable you specify
is not an array, NUM and MIN will return 0, MAX will return -1.
Format 2 READs Total Number of Elements: DIM(READ NUM(array_name[$][,subscript]))

Use the DIM(READ NUM( )) function to read the total number of elements in a DIMensioned array.
Example:
0100 DIM X[0:15]
0110 PRINT DIM(READ NUM(X))
->run
16
Format 3 READs Maximim Element Number: DIM(READ MAX(array_name[$][,subscript]))

Use the DIM(READ MAX( )) function to read the maximum element number in a DIMensioned array.
Example:
0110 DIM X[0:15]
0120 PRINT DIM(READ MAX(X))
->run
15
Format 4 READs Minimum Element Number: DIM(READ MIN(array_name[$][,subscript]))

Use the DIM(READ MIN( )) function to read the minimum element number in a dimensioned array.
Example:
0110 DIM X[0:15]
0120 PRINT DIM(READ MIN(X))
->run
0

DIR( ) Get Current Directory
Function DIR( )
Format:
Return Directory Name DIR(id[$][,ERR=stmtref])
Where =
expression Numeric or string expression indicating which disk directory to return.
Returns: String, name of current directory
Description:
NOTE: This function is primarily for use in a DOS environment. Under UNIX, ProvideX
assumes that there is only one disk drive and this function only returns the current
directory.
The DIR( ) function returns a string naming the current directory for your given disk drive. You can use
either a string or numeric value to specify your drive.
If you use a string, the first character indicates the drive ("A","B","C" and so on). If you use a NULL string,
the DIR( ) function returns the name of the current directory for the current drive.
If you use a numeric value, then the value must be an integer in a positive range starting at zero. A value
of zero (0) indicates the first drive, 1 the second ...
Examples:
->?dir(0)
\
->?dir("")
\other\PGM\APPS\

DIRECT Create File with Keyed Access
Directive DIRECT
Format:
Create Direct (Keyed) File DIRECT filename$,max_len[,max_rec[,max_datasize]][,ERR=stmtref]
Where =
filename$ File name of the DIRECT (keyed) file. String expression. Mandatory.
max_len Maximum length of the key for all records in the file. Mandatory. Numeric
expression, integer.
max_rec Maximum number of records in the file. Optional. Numeric expression. Valid values:
0 (zero) to create an expanding file
Integer other than zero to set a maximum limit.
max_datasize Maximum size of the data portion of each record (excluding the key). Optional.
Numeric expression. You can use:
No Value Default is a variable-length record with maximum size=256.
Positive Integer Fixed-length records of specific size
Negative Integer Variable-length records, maximum length=integer specified
Description:
Use the DIRECT directive to create a direct file with an external key field. ProvideX considers a DIRECT
file to be the same as a KEYED file with an external key.
If you use a filename that already exists, ProvideX returns an Error #12: File does not exist
(or already exists). The maximum size of the key to the file is mandatory along with the filename.
You can limit the number of records by specifying a maximum (an integer other than zero). If you do set a
maximum and that maximum is exceeded (e.g. on a WRITE statement) an error is generated. You can use
zero (0) to create an expanding file, limited only by the amount of available drive space.
If you include the maximum data length, it must be long enough to hold the combined length of all the data
fields for each record written to the file.
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag, e.g.,
DIRECT "[WDX]somefile.ext"... (If you are running an earlier version of
ProvideX on a WindX PC, you still need to encapsulate your command in an
EXECUTE "[WDX]..." directive.) See [WDX] Tag: Directs Action to Client Machine, p.
626.
See also: KEYED Create Single/Multi-Keyed File, p. 211(d)
Examples:
0110 DIRECT A$+""+B$,10,100,50,ERR=1090
0200 DIRECT "CSTFLE",6,0,128
Line 0200 creates a file with the following structure:
Keyed file: C:\MANUALS\PVX\CST\CSTFLE
Maximum Record size ..........: 128
Maximum # records ............: (No limit)
Current # records ............: 0
Size of key block ............: 2048 bytes
External key size ............: 6

DIRECTORY Create Subdirectory
Directive DIRECTORY
Format:
Create Directory DIRECTORY name$[,ERR=stmtref]
Where =
name$ String variable contains the name of the directory to create.
Description:
Use the DIRECTORY directive to create a directory in the Operating System's file structure.
DIRECTORY "[WDX]somefile.ext"... (If you are running an earlier version of
626.
Examples:
0010 DIRECTORY "DATA"
0020 DIRECTORY "WRK."+GID

DISABLE Disable Use of Prefix Table Entry
Directive DISABLE
Format:
Disable Prefix DISABLE (prefix[,ERR=stmtref])
Where =
prefix Numeric value of the PREFIX to disable. Numeric expression, integer.
Description:
NOTE: This directive is included in ProvideX for compatability with other languages.
Use the DISABLE directive to notify ProvideX that you don't want to use a given PREFIX. This directive is
used primarily in the conversion to or from old Business Basic languages where you could DISABLE a
specific disk drive.
To re-enable the PREFIX use the ENABLE directive.
See also: ENABLE Re-Enable Use of Prefix Table Entry, p. 110(d),
PREFIX Set File Search Rules, p. 318(d)
Example:
0010 PREFIX (1)"/disk1/data/"
0020 PREFIX (2)"/disk2/data/"
0030 PRINT PFX(1)," ",PFX(2)
0040 GOSUB SOMEWHERE
0050 PRINT "DISABLED"; STOP
0060 SOMEWHERE:
0070 REM Subroutine
0080 DISABLE (1); DISABLE (2) ! Notifies ProvideX to ignore PREFIXes 1 and 2
0090 PRINT PFX(1,ERR=0110)
0100 RETURN
0110 PRINT "PREFIXES ",; GOTO 0050
-:run
/disk1/data/ /disk2/data/
PREFIXES DISABLED

DISABLE CONTROL Disable Custom Control
Directive DISABLE CONTROL
Formats to Disable a Custom Control:
Format 1: DISABLE CONTROL ctl_id1[:sub_id][,ctl_id2[:sub_id]...][,ERR=stmtref]

Format 2: DISABLE CONTROL bin_list$[,ERR=stmtref]
Where =
ctl_id Value of the control(s) to disable. Numeric expression, integer. If you include a list,
use the comma as the separator.
bin_list$ One or more three-byte binary strings identifying controls:
bin(control_ID,2)+$00$ for most controls or
bin(control_ID,2)+bin(sub_id,1) for RADIO_BUTTONs
sub_id Unique RADIO_BUTTON id. Numeric expression (range 1 to 254).
Description:
Use the DISABLE CONTROL directive to notify ProvideX that you want the specified custom control
(BUTTON, CHECK_BOX, RADIO_BUTTON, etc.) disabled. The bin_list$ expression will support up to 30
controls (90 characters).
To re-enable the control use the ENABLE CONTROL directive
See also: ENABLE CONTROL Enable Control, p. 111(d)

DLL( ) and DLX( ) Call Windows DLL/DLX
Functions DLL( ) and DLX( )
Format:
1 Load Library lib_num=DLL(ADDR lib_string$[,ERR=stmtref])

2 Unload Library DLL(DROP lib_num[,ERR=stmtref])
3 Get Function Address fnc_address=DLL(FIND lib_num,fnc_name$[,ERR=stmtref])
4 Call Using String DLL(lib_string$,fnc_name$,arg[,arg,arg...][,ERR=stmtref])
5 Call Using Library# DLL(lib_num,fnc_name$,arg[,arg,arg...][,ERR=stmtref])
6 Call Using Address DLL(*,fnc_address,arg[,arg,arg...][,ERR=stmtref])
Where =
lib_string$ Name of the DLL (Dynamic Link Library) or EXE which contains the function to be
used. String expression.
fnc_name Name of the function. The function name is the case-sensitive entrypoint in the DLL.
Some API functions have an appended letter A for ASCII, others have an appended
W for wide character UNICODE. String expression.
lib_num Internal library identifier used to reference a loaded library. Numeric expression.
fnc_adr Address of the desired function. Numeric expression.
arg, arg... Parameters or arguments to pass to the function. The number and type of arguments
you use vary from function to function. See Passing DLL( ) Parameters:
Arguments, p. 94.
Returns: CALLs external function or returns DLL identifiers and addresses
Description:
NOTE: DLL( ) and DLX( ) functions are only available while running on a WINDOWS-based
computer platform. Under WindX, remember that the DLL runs on the host. Use a
call to a WindX program to invoke the DLL.
Use the ProvideX DLL( ) function to access functions within DLLs which are external to ProvideX. Its
similar to a call to execute external DLL functions from inside ProvideX applications. The ProvideX DLL( )
function will also return any function identifiers and addresses, as defined by the DLL routine.
In 32-bit environments, the DLX( ) function is unneccesary, since both DLX( ) and DLL( ) functions return
32-bit values. In 16-bit environments, DLL( ) returns 16-bit values while the DLX( ) function returns 32-bit
values.
A DLL is a free-standing library of C-style functions used in the Microsoft Windows environment. All
functions controlling the WINDOWS environment are done through DLL calls with function names as the
entrypoints in the DLL. Most WINDOWS API functions reside in the following DLLs:
32-bit DLL Purpose

USER32.DLL User interface
KERNEL32.DLL System interface
GDI32.DLL Graphics interface
Warning: You can use third-party DLLs, but make sure you have good documentation on what

youre passing and getting back. We can provide assistance on how to call a DLL,
but do not provide support for third-party DLLs. There is no validation on what you
pass. Bad pointers can cause memory corruption and GPFs are not uncommon.
Format 1 Loads Library: lib_num=DLL(ADDR lib_string$[,ERR=stmtref])

Use the DLL(ADDR ...) format to ADDRess or load the DLL. This lets you load and lock a library into
memory and obtain the addresses of its functions and the internal identifier. You can then use this
identifier on subsequent DLL( ) functions to avoid having to reload the DLL. Note that the return value is
the handle to the DLL and should be used in all subsequent DLL( ) calls.
NOTE: In some instances (e.g. when the DLL maintains internal data structures) it is
mandatory to keep the DLL loaded in order to use or call the function. When in
doubt, load the DLL (not needed for WINDOWS API DLLs). Keeping the DLL loaded
has memory consequences, but commonly lets you gain access speed.
Format 2 Unloads Library: DLL(DROP lib_num[,ERR=stmtref])

Use the DLL(DROP ...) format to unload a loaded DLL when you no longer need it. Note that if you LOAD
a DLL, you must DROP or unload it to free up the memory that was allocated to it.
Format 3 Gets Function Address: fnc_address=DLL(FIND lib_num,fnc_name$[,ERR=stmtref])

You can obtain the address of a DLL( ) function in an ADDRessed (loaded) library by using the FIND
format. This format asks the DLL( ) function to return its current address, which you can then use in
subsequent calls. The address is only valid while the library is loaded.
In some cases, you may need to use the return value as a memory pointer. The MEM( ) function can be
used to obtain memory information (address, contents, etc.). If you need a 32-bit result from a DLL( ) call,
use the function DLX( ) instead.
When you call an external function and pass your arguments to it, you can identify it using a string, a library
number or a function address.
See also: Passing DLL( ) Parameters: Arguments, p. 94
DLL( ) Parameters: Examples, p. 94
MEM( ) Return Memory Value, p. 255(f)
Format 4 CALLs DLL( ) Using String: DLL(lib_string$,fnc_name$,arg[,arg,arg...][,ERR=stmtref])

Use this format to call the DLL( ) function using strings to identify the library and function by name.
Format 5 CALLs by Library Number: DLL(lib_num,fnc_name$,arg[,arg,arg...][,ERR=stmtref])

Use this format to call the DLL( ) function using a numeric to identify the library by its internal identifier and
the function name.
Format 6 CALLs Using Function Address: DLL(*,fnc_address,arg[,arg,arg...][,ERR=stmtref])

Use this format to call a DLL( ) function in a loaded library using the the internal function address as a
memory pointer.
NOTE: The address is only valid while the library is loaded.

Passing DLL( ) Parameters: Arguments
Note that DLLs normally expect one of two types of parameters: integers and pointers. The arguments/
parameters you use when you call the DLL( ) function are passed to the function in the following ways:
Example Type 32-Bit Data Format Passed 16-Bit Data Format Passed
X$ Strings Address of string Address of string
X Numeric Variables Double word value (32-bit) Double word value (32bit)
X% Integer Variables 16-bit value passed as 32-bit Single word value (16bit)
INT(X+1) INT( ) Function Standard 32 bit Single word value (16 bit)
X+Y Numeric Expression 32-bit value 32-bit value
DLL( ) Parameters: Examples

The example here swaps the left and right mouse buttons:
0010 A=DLL("USER.EXE",""SwapMouseButton",1) ! Passes 32-bit value
or:
0010 A=DLL("USER.EXE","SwapMouseButton",INT(1)) ! Passes 16-bit value
0020 IF A<>0 THEN PRINT "Could not swap button"
An integer value of zero swaps the mouse buttons back.
Pointers are commonly used to pass string values, usually terminating with a NULL byte. The next
example passes a pointer to a DLL to return the handle of a window with the title "Notepad":
0030 A=DLL("USER.EXE",""FindWindowA","Notepad"+$00$,0)
Sometimes a pointer refers to a region of memory or a structure to receive information from a DLL. You
must pre-allocate a string variable to receive the data. The example below returns the window title,
given the handle. The returned string terminates with a NULL byte ($00$).
DIM X$(256)
0030 A=DLL("USER.EXE",""GetWindowTextA",Hndl,X$,LEN(X$))
To pass a pointer to a number, define a two- or four-byte string and read the value after swapping the
bytes, as in this example:
DIM X$(256)
A=DLL("SOME.DLL",""GetSomething",Hndl,X$)
X=DEC($00$+SWP(X$)
Program DLLS1 in this example starts NOTEPAD, locates the handle and closes the window handle:
0010 !dlls1 Start Notepad and Close It
0020 INVOKE NOTEPAD
0030 INPUT "Press enter after Notepad has started ",X$
0040 LET HWND%=DLL("USER32.DLL","FindWindowA","Notepad"+$00$,0)
0050 IF HWND%<=0 THEN PRINT "Notepad not found!"; STOP
0060 LET WM_CLOSE=DEC($0010$),WPARAM%=0,LPARAM=0
0070 LET
X=DLL("USER32.DLL","SendMessageA",HWND%,INT(WM_CLOSE),WPARAM%,LPARAM

Inter-Task Communication: DireXions 4.10 Example
The Ver. 4.10 DireXions example which follows illustrates inter-task communication. The program DLLS3
starts a second PVXWIN32 session, finds its Window handle, sends CTL values 101 through 103, defines
an atom (pointing to a string variable in a global string table) and passes the atom reference to the second
session. Then it waits for the second session to terminate.
0010 ! DLLS3 - Inter-task communication - Send CTLs & a string

0020 MAX_COL=MXC(0)+1,MAX_ROW=MXL(0)+1
0030 PRINT 'SHOW'(-1),'DIALOGUE'(0,0,MAX_COL,INT(MAX_ROW/2)-1,"Inter-task com
0030:munication",'MODE'($000F$)+'CS'),
0040 IF ARG(1,ERR=*NEXT)="Receiver" THEN GOTO RECEIVER
1000 ! ^1000
1010 LOOP=0
1100 ! ^100 - Find Receiver & start if necessary
1110 IF LOOP++>1 THEN PRINT "Cannot start/find the Receiver!"; STOP
1120 HWND%=DLL("USER32.DLL","FindWindowA",0,"PVXWIN32 - Receiver"+$00$)
1130 IF HWND%>0 THEN GOTO 1200
1140 INVOKE ARG(0)+" "+PGN+" -ARG Receiver"
1150 WAIT 1
1160 GOTO 1100
1200 ! ^100 - Send CTL 101 to 103 to Receiver
1210 WM_USER=DEC($0400$),WPARAM%=0,LPARAM=0
1220 FOR WPARAM%=101 TO 103
1230 PRINT "Sending CTL value of",WPARAM%," to Receiver"
1240 X=DLL("USER32.DLL","SendMessageA",HWND%,INT(WM_USER),WPARAM%,LPARAM)
1250 NEXT
1300 ! ^100 - Send CTL 104 & the address of a String
1310 WM_USER=DEC($0400$),WPARAM%=104,LPARAM=0
1320 ATOM$="Message to Send ",LPARAM=DLL("KERNEL32.DLL","GlobalAddAtomA",ATOM$
1320:+$00$)
1330 PRINT " Sending CTL Value ",WPARAM%,"to Receiver with message:",'BR',ATOM
1330:$,'ER'
1340 X=DLL("USER32.DLL","SendMessageA",HWND%,INT(WM_USER),WPARAM%,LPARAM)
2000 ! ^1000
2010 LOOP=0; PRINT "Waiting for Receiver to shutdown",
2020 HWND%=DLL("USER32.DLL","FindWindowA",0,"PVXWIN32 - Receiver"+$00$)
2030 IF HWND%<=0 THEN GOTO 2100
2040 PRINT ".",; IF LOOP++<30 THEN WAIT 1; GOTO 2020
2100 ! ^100
2110 X=DLL("KERNEL32.DLL","GlobalDeleteAtom")
2120 PRINT 'DROP'(-1),'SHOW'(2),
2130 STOP
3000 ! ^1000 - Receive CTL values from Sender
3010 RECEIVER:
3020 PRINT 'CAPTION'("PVXWIN32 - Receiver"),'MOVE'(0,INT(MAX_ROW/2)+1),
3030 INPUT "Press F4 when finished ",*; PRINT @(0),'BR',"Received CTL =",CTL,'E
3030:R','CL'
3040 IF CTL=4 THEN GOTO 3200
3060 ATOM=TCB(81) ! Atom identifier
3070 DIM ATOM$(512)
3080 X=DLL("KERNEL32.DLL","GlobalGetAtomNameA",ATOM,ATOM$,LEN(ATOM$))
3090 X=DLL("KERNEL32.DLL","GlobalDeleteAtom") ! Release Atom
3100 X=POS($00$=ATOM$); IF X THEN ATOM$=ATOM$(1,X-1)

3110 PRINT "Received: ",'BR',ATOM$,'ER'
3120 GOTO 3030
3200 ! ^100
3210 STOP

DLM Return System Directory Delimiter
Numeric System Variable DLM
Returns: Operating Systems directory delimiter
Description:
This numeric system variable returns the operating system's directory delimiter (e.g. "/"... for UNIX, "\"... for
DOS). For example, on a Windows PC:
->?DLM
\
TIP: You can use SEP=DLM when READing directories, for instance in LIST_BOXes, to
have ProvideX append the operating system delimiter to subdirectory names. See
also SEP ProvideX Field Delimiter, p. 373(v).
Example:
(Treeview LIST_BOX example)
0010 LIST_BOX 10,@(5,5,25,10),OPT="e|",
0010:FMT="!diskette|!File|!File_open",SEP=DLM
0020 LET F=1,D$="."
0030 NXTDIR:
0040 OPEN (F)D$
0050 NXTFILE:
0050:READ (F,END=ENDDIR)F$
0060 IF F$(1,1)="."
0060:THEN GOTO NXTFILE
0070 IF MID(F$,-1)<>DLM
0070:THEN LIST_BOX LOAD 10,0,PTH(F)+DLM+F$;
0070:GOTO NXTFILE
0080 LET D$=PTH(F)+DLM+F$
0090 F++
0100 GOTO NXTDIR
0110 ENDDIR:
0110:CLOSE (F)
0120 F--
0130 IF F>0
0140 ESCAPE

DROP Removes Program from Memory
Directive DROP
Format:
Unload Program DROP prog$[,ERR=stmtref]
Where =
prog$ Name of the program to be unloaded from memory. String expression.
Description:
Use the DROP directive to unload a program previously loaded into memory by the ADDR directive. The
memory used while your program was loaded is returned to the system. ProvideX returns an Error
#18: Program not loaded/Invalid program format if you use a DROP statement for a program
which is not currently loaded in memory.
See also: ADDR Load and Lock Program in Memory, p. 15(d)
Example:
->DROP "ARDATE"

DROP_BOX Define/Control DROP_BOX
Directive DROP_BOX
Format:
1 Define/Create DROP_BOX ctl_id,@(col,line,width,height)[,fileopt]

2 Delete DROP_BOX REMOVE ctl_id[,ERR=stmtref]
3 Disable/Enable DROP_BOX {DISABLE | ENABLE}ctl_id[,ERR=stmtref]
4 Set Focus To DROP_BOX GOTO ctl_id[,ERR=stmtref]
5 Load Via Delimited String DROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]
6 Load Via Array DROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]
Note that the curly braces enclosing {ALL}, above, are "real" brackets (i.e. part of the syntax).
7 Load / Delete Index Element DROP_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]
8 Find Element DROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]
9 Read Current String DROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]
10 Read Current Index DROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
11 Write Selection DROP_BOX WRITE ctl_id,element$[,ERR=stmtref]
12 Write Using Index DROP_BOX WRITE ctl_id,index[,ERR=stmtref]
13 Set Focus Notification DROP_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]
14 Report All Changes DROP_BOX AUTO ctl_id[,ERR=stmtref]
15 Hide/Show DROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the DROP_BOX. Numeric expression. Integers, range: -
32000 to +32000. Avoid integers that conflict with keyboard definitions (e.g. function
key CTLs like 4).
@(col,line, Position and size of the DROP_BOX region when expanded. Numeric expressions.
width,height) Column and line coordinates for top left corner, width in number of columns, height in
number of lines. (Note that DROP_BOX height when not expanded is governed by
the system and is roughly 1.5 times the standard graphic font height.)

Where =
fileopt File options. Valid options for DROP_BOX include:
KEY=char$ Hot key
OPT=char$ Single-character parameter. See the list below.
TBL=char$ Single-character translation
Valid single-character values for OPT= are:
D - Disabled: User cannot access the drop box
H - Hide: Do not display the drop box
S - Signal: Generates CTL value but does not alter focus
A - Auto: Generates a CTL signal for every character entered
T - Strip trailing spaces
X - Signal on Exit
s - Scroll: Allows control to scroll within a resizable/scrollable dialogue box
dlm_list$ Delimited list of elements to load. String expressions.
array_name$ Name of array to load into the DROP_BOX. String variable followed by {ALL}.
index Position of the element in the DROP_BOX. Numeric expression. Integers: the index
of the 1st element is 1.
element$ Single element to load. String expression. You can use the asterisk (*) instead, to
delete an element. For instance, DROP_BOX LOAD 86,4,* will "eighty-six"
(remove) element 4 from DROP_BOX 86.
var[$] Variable to receive the value. String variable for element / numeric for index.
report the last method / keystroke the user chose to select an item from the
DROP_BOX (e.g. $01$ for a <Mouse-Click> or $0D$ for <Enter>).
alt_ctl CTL value to generate when the DROP_BOX gains focus.
Description:
Use the DROP_BOX directive to create and control DROP_BOX control objects on the screen. A
DROP_BOX normally displays a single line on the screen with a {down arrow} on the right side. Your user
can select any element from a list of items you assign to the DROP_BOX, but variable input is not allowed.
That is, the user can only select - not enter - values. To view the list, the user clicks on the {down arrow}.
When the user selects a DROP_BOX item, the associated ctl_id is used to generate a CTL.
Use VARDROP_BOX Define/Control Variable Drop Box, p. 454(d) if you need a DROP_BOX that
allows both variable input and selection from a list.
Because a DROP_BOX list is in dropdown form, a DROP_BOX takes a smaller amount of space on your
screen than a comparable LIST_BOX. In addition, ProvideX automatically supplies vertical scrollbars if the
number of elements overflows dropdown DROP_BOX size. You can combine these features to optimize
your screen design when display space is at a premium.
See Dynamic Control Object PROPERTIES, p. 572 for a list of properties you can use with

DROP_BOXes.
Format 1 Creates: DROP_BOX ctl_id,@(col,line,width,height)[,fileopt]

Use this format to define or create your DROP_BOX and give it a unique identifier in ctl_id. You can use
the FNT= option to establish the font for it. If you omit the font option, ProvideX uses the system default
font. Use FNT="*" (asterisk) to set the font as standard text mode fixed font.
Example:
0010 DROP_BOX 100,@(2,14,12,6)
0020 DROP_BOX LOAD 100,"Cat/Dog/Pig/"
This creates a DROP_BOX that generates a CTL=100 when any item is selected from it. It's loaded with
the items Cat, Dog, and Pig.
Format 2 Deletes: DROP_BOX REMOVE ctl_id[,ERR=stmtref]

Use the DROP_BOX REMOVE Format to delete a DROP_BOX.
Format 3: DROP_BOX {DISABLE | ENABLE}ctl_id[,ERR=stmtref]

Use the DROP_BOX DISABLE format to gray out a DROP_BOX to make it inaccessible to the user ahd
your programs. Use the DROP_BOX ENABLE format to restore the display and access to a disabled
DROP_BOX.
Format 4 Sets Focus: DROP_BOX GOTO ctl_id[,ERR=stmtref]

Use the DROP_BOX GOTO format to set the Focus on your DROP_BOX, ready for the users next input.
LOAD Formats 5, 6 and 7 Load a Drop Box

Use the DROP_BOX LOAD formats below to add or delete the elements listed in a DROP_BOX. To add
elements, you can load them from a delimited string, as an array of string elements, or individually. If you
load more items into the list than the drop down box can display at one time (because of its physical size),
ProvideX automatically supplies scrollbars.
Format 5 Loads String: DROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

When you LOAD a DROP_BOX from a delimited string, the last character in the string must be your
delimiter. That delimiter must be identical to the separator between the elements in the string. For
example, in the delimited string below, the delimiter is the slash "/". It ends the string and separates the
elements:
DROP_BOX LOAD 12000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
Format 6 Loads Array: DROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

Use this format to LOAD a complete array into your DROP_BOX. Note that the curly braces around ALL
are "real" (part of the syntax), as in DROP_BOX LOAD 16000,A${ALL}.

Format 7 Loads/Deletes Element: DROP_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]
When you LOAD individual DROP_BOX elements, use an integer value to state the index of the element
before which to insert the element being loaded. For instance, if your index value is 1, the new element will
be inserted before 1, at the start of the list. If your index is 0 (zero), the new element will be appended to
the end of the list.
To delete or remove a specified element from a DROP_BOX, use an asterisk in place of the element
string:
DROP_BOX LOAD 86,4,* ! Deletes list element 4 from a box whose ctl_id is 86.
Format 8 Retrieves Element: DROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]

Use the string variable in DROP_BOX FIND to retrieve a specific element from a DROP_BOX.
READ Formats 9 and 10: Read Current Selection

Use the DROP_BOX READ formats to read which element in the DROP_BOX has been selected by the
user. Note that you must READ your users selection before your application can use it.
Use the (optional) mode$ variable to have ProvideX return your users method of selecting an item from
the DROP_BOX. Some possible return values are:

$0D$ for <Enter>
$00$ when the user <Tab>s away from the DROP_BOX
After this value is read, the value in mode$ is reset to $00$ (NULL).
Format 9 READs Contents: DROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

ProvideX returns the string contents of the users currently selected element in your string variable (var$)
and (optionally) the users method of selection in your mode$ variable.
Format 10 READs Index: DROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]

Use this DROP_BOX READ format to read the index of the users current selection and (optionally) the
mode$ of selection.
DROP_BOX Example
0010 ! DROP_BOX Creation and Use

0030 DROP_BOX 88,@(30,18,15,10)
0040 DROP_BOX LOAD 88,"CAT,DOG,PIG,FOX,"
0050 DROP_BOX WRITE 88,"CAT"
0060 LET D_BX=88
0070 SETCTL D_BX:READ_BOX
0080 DROP_BOX GOTO D_BX
0090 PRINT @(30,24),"Try Mouse and/or keyboard to select. END=<F4>"
0110 LET CT=CTL; IF CT=4 THEN GOTO END
0120 READ_BOX:
0130 DROP_BOX READ D_BX,ANIMAL$,STROKE$,ERR=0001
0140 DROP_BOX READ D_BX,IND_NUM

0150 PRINT @(30,20),"HTA(selection) : ",HTA(STROKE$)," and CTL=",CT
0160 PRINT @(30,21),"Index for ",ANIMAL$,@(44,21)," : ",IND_NUM,""
0170 GOTO 0100
0180 END:
0190 DROP_BOX REMOVE D_BX
0200 PRINT 'CS'
WRITE Formats 11 and 12: Write Current Selection

Use the DROP_BOX WRITE formats described below to update a DROP_BOX to show the current
selection.
Format 11 Updates Contents: DROP_BOX WRITE ctl_id,element$[,ERR=stmtref]

If you use this format to WRITE an element to a DROP_BOX as the current selection, the contents of your
string must exactly match the value of one of the elements in the DROP_BOX. Otherwise ProvideX
returns an Error #11: Record not found or Duplicate key on write.
Format 12 Updates Index: DROP_BOX WRITE ctl_id,index[,ERR=stmtref]

You can use the elements index number to WRITE it to the DROP_BOX as the current selection.
Format 13 for Focus Notification: DROP_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

Use the DROP_BOX SET_FOCUS format to define an alternate CTL value to generate whenever focus
shifts to a DROP_BOX.
Format 14 Reports All Changes: DROP_BOX AUTO ctl_id[,ERR=stmtref]

Use the DROP_BOX AUTO format to have ProvideX generate a CTL to report all changes whenever your
user highlights an element from a DROP_BOX list.
Format 15: Hide/Show DROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]

Use the DROP_BOX HIDE format to prevent the display of your DROP_BOX. (The user can't see or use
it, even though it's still active for use in your programs.) Use the DROP_BOX SHOW format to restore the
display and the users access to it.

DSK( ) Get Current Disk Drive
Function DSK( )
Format:
Return Drive Identifier DSK(disk_id[$][,*][,ERR=stmtref])
Where =
disk_id[$] Which disk to check. String or numeric expressions.
* (asterisk) To return the name of the volume (rather than the drive).
Returns: Current disk drive identifier
Description:
NOTE: This function is primarily for use in a DOS environment. Under UNIX, it is assumed
that there is only one disk drive and this function returns a NULL string.
The DSK( ) function checks for the existence of a disk drive and returns the current disk drive identifier or
volume name. You can use either a string or numeric value to specify the drive.
If you use a string, the first character indicates the drive ("A","B","C" and so on). If you use a NULL string
as your expression, the current disk identifier is returned. The function will return the Operating Systems
drive prefix ("A:", "B:", etc.). If you use DSK("*"), the function returns the name of the volume mounted on
your drive, if any. If your disk drive or volume doesnt exist, ProvideX returns an Error #17: Invalid
file type or contents.
If you use a numeric value, then the value must be a positive integer in a range starting at zero. Use 0
(zero) as the value for the first drive, 1 for the second, and so on.
Examples:
->?dsk("")
C:
->?dsk(0)
A:
->?dsk("*")
Error #17: Invalid file type or contents

DSZ Data Space Size Available to User
Numeric System Variable DSZ
Returns: Integer, size (in bytes) of data work space available to your user
Description:
This numeric system variable returns the size (in bytes) of the available data work space for the user. The
value returned is an integer. You can set the size value either in the START directive or as an argument in
the PVX command (using -SZ).
Example:
->?DSZ
291094

DTE( ) Convert Date
Function DTE( )
Format:
1 Convert Using Numeric DTE(jul_date[,time][:mask$][,ERR=stmtref])

2 Convert Using String DTE(date$[:mask$][,ERR=stmtref])
Where =
jul_date Julian date to convert. Numeric expression. If the value is zero, the current date is
used. DTE(-1) will return a NULL string if the System Parameter BY=0
time Time value containing hours and fractions of hours since midnight. Optional.
Numeric expression. If you omit this, the current time is used.
mask$ Format of the date to be returned. If you omit the format, the format %Mz/%Dz/%Yz
is the default (date formatted as MM/DD/YY).
date$ Date string in the same format as the DAY_FORMAT (MM/DD/YY).
Returns: Formatted date (converted from Julian)
Description:
The DTE( ) function converts a date (and time) from Julian form to a formatted string. Your mask string
formats the returned value. The various components of the date mask are a percent sign (%) followed by
a one- or two-letter code. The first letter indicates a source for the data (day, month, year etc.). Include
the second character to indicate how to format the returned value. The chart below shows the results
when you use the various options:
% + 1st Format For: No 2nd Char. 2nd Char=l 2nd Char=s 2nd Char=z
Char.
%h Hour 0-12 0-12 0-12 00-12
%m Minute 0-59 0-59 0-59 00-59
%p Am/Pm am,pm am,pm am,pm am,pm
%s Hour in seconds 0-59 0-59 0-59 00-59
%A Year 00-99, A0-Z9
%D Day of month 1-31 Monday-Sunday Mon-Sun 01-31
%H Hour 0-24 0-24 0-24 00-24
%J Day in year 1-365 1-365 1-365 01-99
%M Month in year 1-12 January-December Jan-Dec 01-12
%P Am/Pm AM,PM AM,PM AM,PM AM,PM
%S Day in seconds 0-86399 0-86399 0-86399 00-86399
%W Day of week 1-7 Monday-Sunday Mon-Sun 01-07
%Y Year 1970-1993 1970-1993 1970-1993 70-93

Notes re: Formats
In general, if the second character is l (lower-case el) the result is long text format, an "s" indicates a
short text format. ProvideX maintains the exact contents of the text internally. The contents can be
changed using a DEF DTE( ) directive. If the second letter is z, ProvideX supplies the value converted
to a two digit value. For compatibility with other languages, if the second letter is "p", ProvideX returns a
1 byte binary value.
Your format mask can contain 'YYYY', 'YY', 'MM' and 'DD' for the current Century+Year, Year, Month and
Day values as well as the formats above. If you include any other characters in the date format mask
(e.g. punctuation: slashes, spaces, etc.) ProvideX copies them, as literals, to the output. To include a
percent sign as a literal in the output, use %% in the format.
ProvideX includes the DTE("%A") format to deal with legacy application Y2K conversions (Ver. 4.10).
The current year is returned using 00-99 for 1900 through 1999, A0-A9 for 2000 through 2009, B0-B9
for 2010 through 2019, etc.
ProvideX supports fractional values in the DTE( ) function, using the DTE(fraction,*:"form")
format (Ver. 4.03).
Examples:
PRINT DTE(0:"%Dl %Ml %D/%Y %hz:%mz %p")
Monday July 24/1995 10:27 pm
0010 PRINT 'CS',DTE(0:"%Dl %Ml %D/%Y"),@(70),

0010:DTE(0:"%hz:%mz %p")
0020 INPUT "Enter Date (MM/DD/YY):",X$:"00/00/00"
0030 LET M=NUM(X$(1,2))
0040 LET D=NUM(X$(3,2))
0050 LET Y=NUM(X$(5,2))
0060 LET N=JUL(Y,M,D,ERR=0100)
0070 PRINT "That is a ",DTE(N:"%Dl") ! Day value from N, in text, long form.
0080 STOP
0100 PRINT "Invalid date"; GOTO 0010
-:run
Saturday March 27/1999 03:32 pm
Enter Date (MM/DD/YY):03/31/99
That is a Wednesday
The DTE( ) function will support a valid DAY formatted string value (Ver. 4.02). For example:
PRINT DTE("01/01/A0":"%Y %Ml %D")
2000 January 1
PRINT DTE("01/01/A0":"%Dz/%Mz/%Y")
01/01/2000
See also: DAY_FORMAT Specify DAY Format, p. 68(d)
DAY Return Current System Date, p. 67(v)
JUL( ) Return Julian Date, p. 200(f)
DEF CVS / DTE / LCS / UCS Define System Tables, p. 70(d)

DUMP Display Variables
Directive DUMP
Format:
Print Variables, Values DUMP [(chan)][*]
Where =
chan Channel or logical file number of the file to receive the dump / output of all variables
in use by the current program.
* (asterisk) If you use the asterisk as your parameter, all levels are dumped.
Description:
Use the DUMP directive to get a printout of all variables in use by the current program. The output is sent
to the specified file number. If you omit the file number, the console, file (0), is the default. The output
includes the value of the system variable ERR, the current program name, line number, the FOR/NEXT-
GOSUB/RETURN stack, and all variables.
Example:
->DUMP
! ERR=0, CTL=0, RET=2
! Level=1
! PGN="C:\OTHER\PGMS\PVX\PVX_TESTS"
A$=$000000$+"T0 "+$0F0000000000000000$+"*"+$0100000700$+"CON
"+$0000$+"P"+$190100000000$+"P"+$190000$+"P"+$19000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000$+"WINDOWS "
CUST$="<*> IOLIST NAME$,ADR1$,ADR2$"
CUST.ADR1$="123 SOME ST."
CUST.ADR2$="ANYTOWN SK S0M 0V0"
CUST.NAME$="M MOUSE"
DT$="04/01/99"
F$="abcd"
R$="ab"
X$="M MOUSE"+SEP+"123 SOME ST."+SEP+"ANYTOWN SK S0M 0V0"+SEP
%NORM_SCR$=ESC+"F7"+ESC+"B4"
%ST_ATTR$=$000007$
%W_MSG$=ESC+"F0"+ESC+"B6"
->

EDIT Edit Line in Program
Directive EDIT
Format:
1 Edit EDIT stmtref{D[string] | C[string] | R[string] | [string]}

2 Edit using ` ` stmtref{D[string] | C[string] | R[string] | [string]}
NOTE: The square brackets above are "real". Include them in the statement's syntax.
Where =
` (back ProvideX accepts the back apostrophe as a substitute for typing the word "EDIT".
apostrophe)
D[string] Deletes: string literal contains the final character(s) of the string to be deleted.
C[string] Copies: string literal contains the final character(s) of string to be copied.
R[string] Replaces: string literal is the new text to replace the existing string.
[string] Adds: string literal to add to the statement.
Description:
NOTE: The EDIT directive is used in COMMAND mode.

Use the EDIT directive to change an existing statement in your program. ProvideX builds a new statement
based on the commands you use in the EDIT directive. The new statement then replaces the existing one,
unless you change the line number. (In the latter case, the original statement remains in your program at
the original line number and the new or resultant statement is added to the program at the new line
number.)
If you don't include parameters following the statement reference, ProvideX displays the specified line so
that you can EDIT it directly using the keyboard.
Four options are available in the EDIT directive.
Delete text from statement. Use the D option to scan along the original statement up to and
including your given string without copying the data to the new statement. The result omits
the deleted portion of the string from the new statement.
Copy text from current statement to the new statement. Use the C option to scan along the original
statement from the cursor up to and including your given string, copying the data to the new
statement.
Replace text from current line in the new statement. Use the R option to append your given string
to the new statement while advancing over the corresponding number of characters in the
original statement.
Add text to the new statement. This option adds your given string to the new statement.
After all your options have been processed, any remaining portion of the original statement is appended to
the new statement.
Example:
0200 LET A=4*M; PRINT "ANSWER =",A
EDIT 200 C[=] D[*] C[A] R[nswer] [ now]
After the EDIT:
0200 LET A=M; PRINT "Answer now =",A

ENABLE Re-Enable Use of Prefix Table Entry
Directive ENABLE
Format:
Enable Prefix ENABLE (prefix[,ERR=stmtref])
Where =
prefix Numeric value of the PREFIX to re-enable. Numeric expression.
Description:
NOTE: This directive is used primarily in the conversion to or from old Business Basic
languages where you could DISABLE and ENABLE a specific disk drive.
Use the ENABLE directive to notify ProvideX that you want your given PREFIX reactivated. To disable a
PREFIX use the DISABLE directive.
See also: DISABLE Disable Use of Prefix Table Entry, p. 90(d)
PREFIX Set File Search Rules, p. 318(d)
Example:
0100 PREFIX (1) "/disk1/data/"
0500 DISABLE (1) ! Tell ProvideX to ignore PREFIX (1)
1000 ENABLE (1) ! Reactivate PREFIX (1)

ENABLE CONTROL Enable Control
Directive ENABLE CONTROL
Format:
Enable Custom Control ENABLE CONTROL ctl_id[,ERR=stmtref]
Where =
ctl_id Numeric value of the CONTROL to disable. Numeric expression, integer.
Description:
Use the ENABLE CONTROL directive to notify ProvideX to re-enable your given custom control
(BUTTON, CHECK_BOX, etc.). To disable the control use the DISABLE CONTROL directive
See also: DISABLE CONTROL Disable Custom Control, p. 91(d)

END Halt Execution of Program
Directive END
Format:
Halt Program END
Description:
Use the END directive to halt the currently running program. If the current program is a subprogram (i.e.
CALLed or PERFORMed), then control is immediately passed back to the calling program. Otherwise,
ProvideX CLOSEs all open files, performs a RESET operation and sets the next-location counter to the
start of the program.
If ProvideX encounters your END directive in EXECUTION mode with a program name specified (i.e. when
RUNning from a menu), then ProvideX issues an automatic QUIT directive, returning the user to the
Operating System. If ProvideX receives your END directive in COMMAND mode, it returns you to
COMMAND mode.
When you use the END directive in a compound statement, it must be the final directive. (Exception: A
remark can follow the END directive.)
The *END label emulates an END directive for use as a statement reference (Ver. 4.01).
STOP Halt Program Execution, p. 406(d)

Example in COMMAND mode:

0010 PRINT 'CS',DTE(0:"%Dl %Ml %D/%Y"),@(70),DTE(0:"%hz:%mz %p")
0030 LET M=NUM(X$(1,2))
0040 LET D=NUM(X$(3,2))
0050 LET Y=NUM(X$(5,2))
0070 PRINT "That is a ",DTE(N:"%Dl") ! Day value from N, in text, long form.
0080 END
->RUN
Saturday March 27/1999 03:43 pm
That is a Wednesday
->
In the example above, ProvideX returns you to the COMMAND prompt. However, if your user is in
EXECUTION mode (i.e. having selected this same date routine from a menu), ProvideX will perform a
QUIT directive when it encounters your END directive, returning your user to the Operating System.

END DEF End Definition of Multi-line Function
Directive END DEF
Format:
End Function Definition END DEF
Description:
Use the END DEF directive to mark the end of your multi-line function. In EXECUTION mode, when
ProvideX encounters a DEF FN directive for a multi-line function, it skips forward until it encounters an
END DEF directive. (That is, control is transferred to the line or statement after the END-DEF.) If you use
an END DEF directive without a preceding DEF FN directive, ProvideX returns an Error #45:
Referenced statement invalid.
See also: DEF FN Define Function, p. 72(d)
Example:
0010 DEF FNX(A,B)
0020 IF A<0 OR B<0 ESCAPE 40 ! Variables' values must be >=0
0030 RETURN SQR(A^2+B^2) ! Length of hypotenuse
0040 END DEF
0100 PRINT FNX(7,8)
->RUN
10.63

END SWITCH End Branching of a Program
Directive END SWITCH
Format:
Stop Branching END SWITCH
Description:
Use the END SWITCH directive to stop the branching that has been activated in an application by a
SWITCH directive.
Example:
Preset the value of A$ if you RUN this example, or see the chart below the LISTing for sample results.
5000 SWITCH A$
5040 CASE "Nephew"
5060 DEFAULT
5080 END SWITCH
5090 PRINT "DONE"

Break
Note that "Alligator" drops through with no BREAK to
DONE
intervene. "Alligator" doesnt DEFAULT to "Wild
Animal" because ProvideX treats it as a defined CASE
for "Domestic Animal".
Break
DONE
a$="cat" Wild Animal DEFAULT. Not defined. (Note that CASE is case-
DONE sensitive.)
a$="Fox" Wild Animal DEFAULT. Not defined.
DONE

END_IF End IF Directive
Directive END_IF
Format:
1 End IF Before Line Ends IF {expression} THEN {...} ELSE {...} END_IF {...}
2 FI=END IF IF {expression} THEN {...} ELSE {...} FI {...}
Where =
expression Condition to control processing.
... Directives, processing.
Description:
Use the END_IF directive to terminate an IF directive before the end of your statement or line. When an
END_IF directive follows an IF directive, execution resumes immediately after the END_IF directive,
regardless of whether the condition was found to be TRUE or FALSE.
NOTE: "FI" is an accepted substitute for "END_IF".
See also: IF ... THEN ... ELSE Test Condition, p. 187(d)
Example:
0100 PRINT "The customer has ",
0200 IF BAL<=0 THEN PRINT "NO", ELSE PRINT "$",BAL, END_IF; PRINT " credit
0200: available"
->BAL=0
->GOTO 100
->RUN
The customer has NO credit available.
->BAL=1.98
->GOTO 100
->RUN
The customer has $ 1.98 credit available

ENDTRACE End Trace Output
Directive ENDTRACE
Format:
Stop Tracing Program ENDTRACE
Description:
Use the ENDTRACE directive to stop the tracing of program statements (activated by a previous
SETTRACE directive).
See also: SETTRACE Enable Program Tracing, p. 393(d)
Example:
0010 SETTRACE
0040 ON CTL GOTO 0050,0030,0030,0060,0060
0050 INPUT "Enter Addr:",A$
-:run
0010 SETTRACE
Enter name: ! User hit up arrow
0040 ON CTL GOTO 0050,0030,0030,0060,0060
DONE

ENTER Specify Arguments
Directive ENTER
Format:
Variables from CALLer ENTER [argvar[,argvar][, ...]][,ERR=stmtref]
Where =
argvar ... Variables in a subprogram to receive variables passed as arguments to that
subprogram by a calling program. You can use:
IOL=stmtref (e.g. ENTER IOL=8000),
a complete numeric array (e.g. ENTER ARRAY_NAME{ALL}), or
a comma-separated list of simple numeric and/or string variables, no
subscripts / substrings.
Description:
Restriction: You can only use this directive in subprograms.

Use the ENTER directive in a CALLed subprogram to define the variables it will receive. These are
passed to the subprogram via the calling program's CALL statement.
The total number, relative positions and types of variables are determined by the subprogram's ENTER
statement. The variable list in the calling program's CALL statement must ordinarily match those in the
subprogram exactly. That is, each argument variable in the CALL statement must correspond by position
and in type (numeric or string) to a variable in the ENTER statement. Otherwise ProvideX returns an
Error #36: ENTER parameters don't match those of the CALL.
If the calling program is passing a complete numeric array, the name of the array must be specified,
followed by {ALL} in both the ENTER and CALL statements. Note that the curly brackets are "real" (i.e.
part of the syntax).
The subprogram will not return changes in a variable to the calling program if parentheses enclosing a
variable name are not matched by parentheses enclosing the same variable ("same" by relative position
and type). See LEN(A$) and ENTER A, below.
Where your CALL statement specifies a simple variable, all changes made to the variable ENTERed in
your subprogram will be reflected in the calling program when the subprogram terminates.
See also: CALL Transfer to Subprogram, p. 33(d)
Example:
In calling program:
0170 CALL "SUBR",LEN(A$),N,A$,T{ALL}
In subprogram "SUBR":
0020 ENTER A,B,Z$,N{ALL}

ENV( ) Get Environment Values
Function ENV( )
Format:
1 Using Numeric ID ENV(env_id[,ERR=stmtref])

2 Using String ID ENV(env_name$[,ERR=stmtref])
Where =
env-id Numeric value of the environment variable to be returned.
env_name$ Character string containing the environment variable to be returned.
Returns: Value of an environment variable
Description:
Use the ENV( ) function to obtain the value of an environment variable (specified numerically or in a string)
from the externally defined environment table. Environment variables are typically external to ProvideX
and are used by the Operating System and other utilities for defining the users environment.
Format 1 Using Numeric ID: ENV(env_id[,ERR=stmtref])

If your numeric value in your ENV( ) function exceeds the size of the Environment Table, ProvideX returns
an Error #41: Invalid integer encountered (range error or non-integer). Otherwise,
the function returns the current value of the given environment variable.
Example:
Program to display all the environment variables:
0010 LET I=1
0020 LET X$=ENV(I,ERR=0050)
0030 PRINT X$
0040 LET I=I+1; GOTO 0020
0050 STOP
-:run
TEMP=C:\WINDOWS\TEMP
PROMPT=$p$g
winbootdir=C:\WINDOWS
COMSPEC=C:\WINDOWS\COMMAND.COM
CLASSPATH=.;c:\COREL\OFFICE7\SHARED\BARISTA;c:\COREL\OFFICE7\SHARED\TRUEDOC
LD_LIBRARY_PATH=c:\COREL\OFFICE7\SHARED\TRUEDOC\BIN
PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;C:\COREL\OFFICE7\SHARED\TRUEDOC\BIN;C:\SOFT
WA
RE\WP60;C:\OTHER\BAT;C:\SOFTWARE\WINSIM\CA_APPSW
CMDLINE=WIN
windir=C:\WINDOWS
BLASTER=A220 I5 D1 H5 P330 T6

Format 2 Using String ID: ENV(env_name$[,ERR=stmtref])
If your string value in your ENV( ) function does not match an environment variable, the ENV( ) function
returns a NULL ("") string. Otherwise, the function returns the current value of the given environment
variable.
Example:
Program to test and display the environment variables TERM and PROMPT;
0010 LET T_TYP$=ENV("TERM"); LET P_TYPE$=ENV("PROMPT")
0020 IF T_TYP$="" THEN PRINT "No terminal defined"
0030 IF P_TYPE$="" THEN PRINT "No prompt defined" ELSE GOTO 0060
0040 STOP
0050 PRINT "You are using a "+T_TYP$+" terminal"
0060 PRINT "Your prompt is ",P_TYPE$; END
-:run
No terminal defined
Your prompt is $p$g

EOM End of Message Character String
String System Variable EOM
Returns: String, End-of-Message character
Description:
This string system variable returns the End-of-Message character string that ended the users last input
from the terminal. The contents of this string will vary based on the type of terminal being used.
Example:
With carriage return (not printable) as EOM:
->?EOM
->?HTA(EOM)
0D

EPT( ) Return Exponent Value
Function EPT( )
Format:
Return Exponent EPT(num[,ERR=stmtref])
Where =
num Numeric expression for which you want the exponent returned.
Returns: Numeric exponent (power of ten)
Description:
The EPT( ) function returns the numeric exponent (power of ten) for the numeric expression you enclose in
the brackets.
Examples:
->EPT(10) ! Same as EPT(1*10^2) - yields 2
->EPT(5) ! Same as EPT(5*10^1) - yields 1
->EPT(.02) ! Same as EPT(2*10^-1) - yields -1
0610 LET B=27*9

0620 PRINT EPT(B), EPT(9*2)
-:run
3 2

ERASE Delete File/Directory from System
Directive ERASE
Format:
Delete File/Directory ERASE name$[,ERR=stmtref]
Where =
name$ Name of the file or directory to be deleted from the system. String expression.
Description:
NOTE: Some restrictions apply.

Use the ERASE directive to delete the file or directory you name. When you use this directive, the disk
space that was used by the file or directory is returned to the system. If you erase a file, all data in the file
is lost.
Restrictions:
A directory can only be deleted if it does not contain any files.
In some Operating Systems, the ERASE directive is not accepted and will not delete the
directory.
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag, e.g., ERASE
"[WDX]somefile.ext"... (If you are running an earlier version of ProvideX on a
WindX PC, you still need to encapsulate your command in an EXECUTE "[WDX]..."
directive.) See [WDX] Tag: Directs Action to Client Machine, p. 626.
Example:
0010 ERASE "PRNTFL"
0030 ERASE "SRTFL1",ERR=0040

ERR Last System-Detected Error Value
Numeric System Variable ERR
Returns: Integer, last system-detected error value
Description:
This numeric system variable returns an integer reporting the last system-detected error value. It is reset
by the BEGIN, CLEAR, END, RESET, STOP, and START directives. See Error Codes and Messages, p.
634 at the end of this Language Reference for a complete list of values.
Example:
With "TEST" file already open:
0100 OPEN (5)"TEST"
Error #14: Invalid I/O request for file state
->?ERR
14

ERR( ) Test Error Value
Function ERR( )
Format:
Return ERR Position ERR(compare_1,compare_2,...compare_n[,ERR=stmtref])
Where =
compare_1...n Comma-separated list of numeric values for comparison with the value of the internal
ERR variable.
Returns: Integer, relative position if match found, 0 (zero) if no match found
Description:
Use the ERR( ) function to compare the value of the internal ERR variable with a list of possible external
ERRor values. If a match is found, the function returns an integer reporting the relative position of the
value which matches the value in the external ERR system variable. The function returns 0 (zero) if no
match is found.
Example:
0040 ON ERR(1,11,2) GOTO 1000,1010,1110,1020
Results:
If ERR=1, control transfers to line 1010
If ERR=11, control transfers to 1110
If ERR=2, control transfers to 1020
Else ERR=0 and control transfers to 1000

ERROR_HANDLER Define Generic Handler
Directive ERROR_HANDLER
Format:
1 Define/Remove ERROR_HANDLER [prog$]

2 Find Current Name ERROR_HANDLER READ var$
Where =
prog$ Name of the error handler program. String expression. Omit the name to cancel the
current error handler.
var$ String variable. Receives the name of the current error handler.
Description:
Use the ERROR_HANDLER directive to assign a generic error-handling program to be invoked internally
by the system whenever an error occurs that is not already handled (i.e. by an ERR= statement reference
or a SETERR directive).
See also: START Restart ProvideX, p. 404(d)
Format 1 Defines Generic Handler: ERROR_HANDLER [prog$]

You can design the ERROR HANDLER to take corrective action and then return to the offending statement
via the EXIT directive. If you have an error handler program in place when an error occurs without
handling instructions, ProvideX calls your ERROR_HANDLER program to deal with it.
If you use an EXIT ERR directive to return from the ERROR_HANDLER, the normal error processor is
invoked and control can be transferred to COMMAND mode.
To cancel the current error handler, omit the program name (i.e. use ERROR_HANDLER).
Your error handler program remains in effect until a START directive is executed.
Example:
A typical START_UP program:
0010 PREFIX "===/ MISC/"
0020 IF WHO<>"BOSS" THEN SETESC OFF
0030 ERROR_HANDLER "*ERROR"
0040 ! The asterisk marks "*ERROR" as a Best Software Canada Ltd. utility
Format 2 READs Name: ERROR_HANDLER READ var$

Use the READ format to find out the name of the program currently in effect as the error handler.
-:ERROR_HANDLER READ A$
-:?a$
*error

ERS Line Number of Last Error
Numeric System Variable ERS
Returns: Integer, line number that generated last error
Description:
This numeric system variable returns an integer reporting the line number that generated the last error
detected in the program.
Example:
0030?LET X$="" PRINT "Reset"
Error #20: Syntax error
1>END
->?ERS
30
-> EDIT 30

ESC ASCII ESCape Character
String System Variable ESC
Returns: ASCII ESCape character, $1B$
Description:
This string system variable returns the ASCII ESCape character $1B$. ProvideX returns an Error #29:
Invalid Mnemonic or position specification if you try to print the ESC value without using a
function like HTA( ) to obtain its hex value.
Example:
->?ESC
Error #29: Invalid Mnemonic or position specification
->?HTA(ESC)
1B
->

ESCAPE Interrupt Program Execution
Directive ESCAPE
Format:
Suspend Process ESCAPE [err_val]
Where =
err_val Optional numeric value to be placed in the ERR variable. (ProvideX interprets this as
an error code and the system logic kicks in.)
Description:
In EXECUTION mode, when you use the ESCAPE directive, ProvideX suspends execution of the current
program, lists the current statement (the line number with the ESCAPE directive), and returns you to
COMMAND mode. You can use a RUN directive to have the program resume where it left off.
You can use the ESCAPE directive to simplify your debugging process by placing ESCAPE statements
strategically in your program. (Then, when the ESCAPE is executed, you are returned to COMMAND
mode, where you can evaluate execution and the values of your variables, etc., up to the line where you
placed the ESCAPE in your application.)
If you use the ESCAPE directive in COMMAND mode, ProvideX lists the next statement to be processed,
if any. If you specify an error value, the ESCAPE directive will generate an error with that specific error
value. You can use this to provide an error exit in a multi-line function.
The *ESCAPE label emulates an ESCAPE directive for use as a statement reference (Ver. 4.01).
See also: DEF FN Define Function, p. 72 (Multi-Line Function)(d)

Example:
For current record: CUST$="ABC,INC",INV_DT$="19990317",TERMS=30
3000 REM ESCAPE to "TEST" subprogram results
3010 PRINT "TEST"
3020 READ (5,END=9000)CUST$,INV$,INV_DT$,TERMS
3030 LET AGE=TERMS,XX=0,DD=0,CT$=""
3070 PRINT CUST$," Invoice: ",INV$," ",INV_DT$," or ",
3080 CALL "TEST;AGE",INV_DT$,AGE,XX,DD,CT$
3081 PRINT "DEBUGGING. Due Date is ",DTE(DD:"%Ys%Mz%Dz")," or ",DD
3082 ESCAPE
3090 LET DUE_DT$=DTE(DD:"%Ys%Mz%Dz"); PRINT "AGED DATE IS: ",DTE(DD)
9000 STOP
-:run
TEST
ABC, INC. Invoice: 234567 19990317 or 10667
DEBUGGING. Due Date is 19990416 or 10697
3082 ESCAPE
1:run
AGED DATE IS: 04/16/99
-:DELETE 3000,3010
-:DELETE 3081,3082
-:SAVE

EVN( ) Evaluate Numeric Expression
Function EVN( )
Format:
Evaluate Numeric EVN(var$[,val][,ERR=stmtref])
Where =
var$ String expression containing numeric variable name. Receives the returned
evaluated contents of the variable. You can build the variable name using string
expressions, as in the example below.
val If you supply a value to be returned if the evaluation fails at run-time (with any error
except a syntactical error), the error will be ignored and the value will be returned
instead (Ver. 4.20). For instance, PRINT EVN("40/0",0) would return val=0 rather
than generating Error #40: Divide check or numeric overflow.
Returns: Processed numeric value
Description:
The EVN( ) function evaluates and returns the processed numeric value of a numeric variable or computed
expression. You can use this function to process a stored or computed expression and obtain its value.
See also: EVS( ) Evaluate String Expression, p. 130(f)
Example 1:
In this example, EVN("GL_"+X$) builds the variable name based on user input and returns the value
stored in the variable.
0010 OPEN (1)"GL_BAL"
0020 INPUT "Enter Key:",K$
0030 READ (1,KEY=K$)GL_YTD,GL_MTD,GL_CUR
0040 INPUT "Which field (YTD,MTD,CUR):",X$
0050 PRINT EVN("GL_"+X$):"$###,##0.00-"
0060 GOTO 0020
For the example above, if the users input is CUR for X$, the variable name will be GL_CUR. If the value
stored in GL_CUR in the current record is, for example, 9999.63, ProvideX prints that value (formatted by
the mask) as $9,999.63.
Example 2:
In this example, EVN(V$) will print the numeric value stored in V$ for the current record of logical file
number RPT_FN.
0090 K$=KEY(RPT_FN); IF K$(1,12)<>RPT_ID RETURN
0100 READ (RPT_FN)L,C,V$
0110 PRINT (RPT_FN) @(C,L),EVN(V$)
0120 GOTO 0090

EVS( ) Evaluate String Expression
Function EVS( )
Format:
Evaluate String EVS(var$[,val$][,ERR=stmtref])
Where =
var$ String variable name. Receives the returned evaluated contents of the variable.
You can build the variable name using string expressions, as in the example below.
val$ Value to be returned if the evaluation fails at run-time (with any error except a
syntactical error). Optional. If you include a value, the error will be ignored and the
value will be returned instead (Ver. 4.20).
For example, A=9999; PRINT EVS("str(a:""##0"")"),"<OverFlow>"
would return the value <Overflow> rather than generating Error #43: Format
mask invalid.
Returns: Evaluated contents of string variable
Description:
The EVS( ) function evaluates and returns the value (evaluated contents) of a string variable.
See also: EVN( ) Evaluate Numeric Expression, p. 129(f)
Example:
In the example below, the EVS( ) function builds the string variables field name ("CST_"+X$+"$")
based on the users input and returns the value stored in it.
0010 OPEN (1) "CSTDB"
0020 INPUT "Enter Key:",K$
0030 READ (1,KEY=K$)CST_NAME$,CST_ADDR$,CST_CITY$,CST_CONTACT$
0040 INPUT "Which field (NAME,ADDR,CITY,CONTACT):",X$
0050 PRINT EVS("CST_"+X$+"$")
0060 GOTO 0020
For instance, if the users input for X$ in the example above is NAME, the variable name will be
CST_NAME$. The value in EVS(CST_NAME$) for the current record could be something like Smith &
Sons Mfg., which is what ProvideX would return and then print.

EXECUTE Execute Basic Instruction
Directive EXECUTE
Format:
Embed COMMAND in Pgm EXECUTE statement$[,ERR=stmtref]
Where =
statement$ Character string to be processed by the system as if entered in COMMAND mode.
String expression.
Description:
Use the EXECUTE command to embed COMMAND mode statements directly into a program. A typical
use of the EXECUTE directive would be to modify the current program dynamically.
If you use this directive in a compound statement, EXECUTE must be the last directive in the line.
NOTE: By default ProvideX changes the current program. If the EXECUTE directive starts
with a line number, ProvideX modifies the current program and the line becomes part
of the current program, unless the system parameter EX is ON, in which case it
modifies the program at level 1 (the main level).
ALSO: Under WindX, you can use EXECUTE "[WDX]..." to encapsulate a directive that is
not supported across a WindX connection . (See [[WDX] Tag: Directs Action to Client
Machine, p. 626.)
Example:
3000 REM To EXECUTE a function, FND$, and add it to the program
3010 READ (14)*,*,*,D$,DT$
3020 PRINT 'CS',@(1),DT$,@(1,1),D$
3025 EXECUTE D$ ! EXECUTE uses line 3030
3040 PRINT @(1,2),"Formatted date is: ",FND$(DT$)
GOTO 3000
RUN
03051999
3030 DEF FND$(DT$)=DT$(1,2)+"/"+DT$(3,2)+"/"+DT$(7,2)
Formatted date is: 03/05/99
Now line 3030 is in the code:
LIST 3000,3040
3000 REM To EXECUTE a function, FND$, and add it to the program
3010 READ (14)*,*,*,D$,DT$
3020 PRINT 'CS',@(1),DT$,@(1,1),D$
3025 EXECUTE D$ ! EXECUTE uses line 3030
3030 DEF FND$(DT$)=DT$(1,2)+"/"+DT$(3,2)+"/"+DT$(7,2)
3040 PRINT @(1,2),"Formatted date is: ",FND$(DT$)
SAVE (or not:- line 3025 will add line 3030 each time its executed.)
Warning: Dynamic advantages, but you can see the pitfall. If its unsaved and unREMarked,
you might use 3030 (seemingly available) for another statement, only to have that
overwritten through the magic of the EXECUTE directive at line 3025. If you
EXECUTE a lot of lines, you risk overwriting nnn lines . Did someone say "Ouch"?

One Solution:
To avoid overwriting, you can also use the EXECUTE directive to create a dynamic in-line effect in your
application without using a line number. In this case, your program is not modified. The example below
sets up a variable, J$, to set conditions based on the users selections or input, and then EXECUTEs J$.
1010 J$="IF POS("+JOB1$+"=EF.JOB$,4)>0 AND POS("+JOB2$+"=EF.JOB$,4)>0
1010:THEN GOTO 2050"
2050 EXECUTE J$

EXIT Terminate Subprogram and Return
Directive EXIT
Format:
End Subprogram EXIT [ERR | err_val ]
Where =
err_val Numeric expression whose value will be returned as an error status to the program
initiating the subprogram (e.g. via a CALL directive).
Description:
Restriction: You can only use this directive in subprograms. Otherwise, ProvideX returns an
Error #37: Directive can only execute in subprogram.
Use the EXIT directive in a subprogram to terminate the subprogram and return control to the initiating
program.
You can have the subprogram return an error code value to the calling program by using EXIT ERR or by
specifying the error value following the EXIT directive. Use an integer from 0 to 32767 for your error value.
You can have the calling program process an error value other than zero by using the ERR= option in the
CALL directive (or by using SETERR numeric expression). If your value is 0 (zero), ProvideX does not
initiate error processing.
When you use the EXIT directive in a compound statement, it must be the final directive:
9000 PRINT "Subroutine done"; EXIT
Example:
(The first example below works, but is less informative than the actual ProvideX error message and code.
Its here as illustration only.)
10000 ! In subprogram "SUBPR"
10005 TEST_EXIT:
10010 SETERR UNKNOWN_ERROR
10020 ENTER TEST$
10030 LET T=NUM(TEST$(5,6))
10040 EXIT
10050 UNKNOWN_ERROR:
10060 EXIT 8686
With subprogram still loaded:
->CALL "SUBPR;TEST_EXIT",""
Unknown error
->?ERR
8686
In this instance, the actual ProvideX error message and code, returned when you use EXIT ERR, would
be more informative:
-:call "subpr;test_exit",""
10030 LET T=NUM(TEST$(5,6))
Error #47: Substring reference out of string
2>?err
47

EXITTO Premature Exit of FOR/NEXT, GOSUB
Directive EXITTO
Format:
End Loop, Transfer Control EXITTO [stmtref]
Where =
Description:
The EXITTO directive terminates the currently active FOR / NEXT, GOSUB / RETURN, REPEAT / UNTIL
or WHILE / WEND loop prematurely and transfers control to the statement number indicated.
EXITTO lets you terminate one of these processes early by removing its associated entry from the top of
the stack. If there is no active entry on the stack, ProvideX returns an Error #27: Unexpected or
incorrect WEND, RETURN, or NEXT.
If you use this in a compound statement, the EXITTO directive must be the final directive.
See also: FOR ... NEXT Loop While Incrementing, p. 155(d)
NEXT End of Loop, p. 285(d)
GOSUB ... RETURN Execute Subroutine, p. 165(d)
RETURN Return from a Subroutine, p. 363(d)
WHILE Repeat Statements, p. 470(d)
REPEAT Repetitive Execution, p. 358(d)
UNTIL End of REPEAT Loop, p. 447(d)
Example 1:
0010 FOR I=1 TO 10
0020 PRINT I,
0030 IF I>7 THEN EXITTO 0050
0040 NEXT I
0050 REM
0060 PRINT "DONE AT ",I; STOP
-:RUN
1 2 3 4 5 6 7 8
DONE AT 8

EXP( ) Raise to Base Ten
Function EXP( )
Format:
Raise to Base Ten EXP(num[,ERR=stmtref])
Where =
num Power of 10 (ten) to be returned. Numeric expression.
Returns: Value of ten raised to the power of your numeric value
Description:
The EXP( ) function returns the value of 10 (ten) raised to the power of your given numeric value (i.e.
10^num). Fractions are allowed in your numeric. The numeric value returned is rounded to the current
PRECISION in effect. This is the inverse of the LOG( ) function.
Examples:
0010 PRINT EXP(LOG(90)/3), ! Print cube root of 90
0020 PRINT EXP(3),EXP(2.1)
-> RUN
.30 1000 125.89

EXTRACT Read and Lock Data
Directive EXTRACT
Format:
Extract Data From File EXTRACT (chan[,fileopt])varlist
Where =
chan Channel or logical file number of the file from which to read the data.
fileopt File options. Valid options for EXTRACT include:
DOM=stmtref Missing record jump
END=stmtref END-OF-FILE transfer
IND=num Record index value
KEY=rec_key Record key value
KNO=key_num File access key to use (primary or alternate key)
REC=prefix$ Record prefix
RNO=rec_num Record number
RTY=retries Number of times to retry
SIZ=chars Number characters to read
TBL=stmtref Data translation table
TIM=max_wait Maximum time to wait
varlist List of variables, literals, mnemonics, IOL= options, and/or location functions -
'@(...)'. The items in the list must be comma-separated.
Description:
Use the EXTRACT directive to read data from the file you specify as the channel. When ProvideX READs
the data, it is split into one or more fields (either separated by the current delimiter or in an embedded
IOLIST format) with the contents of the first field placed into variable 1, the second field into variable 2, and
so on.
ProvideX automatically converts numeric data when moving it into numeric variables while processing your
EXTRACT directive. Numeric data converted during an EXTRACT directive does not use the DP or TH
System Parameters, p. 537 for European decimal settings.
If you want a field to be skipped, use an asterisk '*' as a place holder for a variable name.
If you specify more variables than there are fields in the record, ProvideX will initalize the additional
variables to either zero (if a numeric variable) or a NULL string (if a string variable). The EXTRACT
directive advances the file position to the next record (or a record you can specify using the KEY= or IND=
option). You can use the KNO= option to change the current file access key.
NOTE: The EXTRACT directive locks the record being read to prevent other users from
issuing another EXTRACT for it. This lock stays active until the next I/O request for
the same file or until the file is closed. When a record is locked, you can obtain it by
retrieving the next record using a KEY option or a READ, FIND or EXTRACT
statement.
See also: FIND Locate and Read Data, p. 152(d)
KEY( ) Return Key of Next Record, p. 209(f)
READ Read Data from File, p. 343(d)
Examples:
0410 EXTRACT (1,ERR=1000,DOM=1200)A,B,*,*,Z$

0100 IOLIST CUST$,NAME$,ADDR1$,ADDR2$,CITY$,PROV$,POSTAL$
0200 REM 200
0210 OPEN (2)"PVX_KEY" ! 2 alternate keys
0220 EXTRACT (2,IND=21)IOL=0100
0225 LET CITY$="CLARENDON"
0230 WRITE (2)IOL=0100
0370 CLOSE (2)
0380 PRINT "IND=21 CITY NAME CHANGED"; STOP
-:RUN
IND=21 CITY NAME CHANGED
Result for record key '123460' (index=21)
123460,ACME,SUITE 1900,2000 1ST ST,CLARENDON,ON,K0K0K0

EXTRACT RECORD Read-Lock Data Record
Directive EXTRACT RECORD
Format:
Lock & Read Record EXTRACT RECORD (chan[,fileopt])var$
Where =
fileopt File options. Valid options for EXTRACT RECORD include:
KEY=key Record key value
RTY=retries Number of times to retry
SIZ=chars Number characters to read
TIM=max_wait Maximum time to wait
var$ String variable. Receives the contents of the record being read.
Description:
Use the EXTRACT RECORD directive to read a record from the file you specify (channel). ProvideX will
return the record's complete data portion in the string variable you specify.
Apply the EXTRACT RECORD statement when dealing with native-mode operating system files, when
exchanging data with applications other than ProvideX, or when you want to read a complete record
including data field separators.
The EXTRACT RECORD directive advances the file position to the next record (or the record specified in a
KEY= or IND= option). You can use the KNO= option to change the current file access key.
NOTE: This directive locks the record being read to prevent other users from issuing
another EXTRACT RECORD. This lock remains active until the next I/O request for
the same file or until the file is closed. While a record is locked, you can obtain it by
retrieving the next record using either a KEY= option or a READ, FIND or EXTRACT
statement.
See also: FIND Locate and Read Data, p. 152(d)
KEY( ) Return Key of Next Record, p. 209(f)
READ RECORD Read Record from File, p. 348(d)
Example 1:
This example uses a KEYED file:
0010 OPEN (1)"PVX_KEY"
0020 READ (1,KEY="",DOM=0030)
0030 LET K$=KEY(1,END=0070) ! Sets file position
0040 EXTRACT RECORD (1,KEY=K$)R$
0050 PRINT R$ ! Prints complete current record
0055 READ (1) ! Next I/O (unlocks the record)

0060 GOTO 0030 ! To advance file position to next record
0070 STOP
Example 2:
In this example, PVX-SER is a SERIAL file with SEP/$8A$ delimiters (created using an IOLIST).
4010 OPEN (1)"PVX_SER"
4020 OPEN LOCK (2)"NEWFIL"
4050 EXTRACT RECORD (1,END=5000)R$
4060 PRINT R$
4070 WRITE RECORD (2)R$
4090 GOTO 4030
5000 CLOSE (1); CLOSE (2)
5010 PRINT "DONE"; END
The data fields for each record in PVX_SER are delimited by the SEP character $8A$:
123456+SEP+ABC INC+SEP+213 ANY ST+SEP+SEP+ANYTOWN+SEP+ON+SEP+K0K0K0+SEP+
19990315+SEP+9999+SEP+30+SEP+SEP
and when RUN, each extracted record prints in this form:
123456
ABC INC
213 ANY ST
ANYTOWN
ON
K0K0K0
19990315
9999
30
Serial files dont typically include the SEP character, so they would normally be displayed as a single line
for each record. For instance, using a sample C:\AUTOEXEC.BAT as the serial file results in this display:
SET
CLASSPATH=.;c:\COREL\OFFICE7\SHARED\BARISTA;c:\COREL\OFFICE7\SHARED\TRUEDOC
SET LD_LIBRARY_PATH=c:\COREL\OFFICE7\SHARED\TRUEDOC\BIN
SET PATH=%PATH%;c:\COREL\OFFICE7\SHARED\TRUEDOC\BIN;C:\SOFTWARE\WP60
SET PATH=%PATH%;C:\OTHER\BAT;c:\software\WINSIM\ca_appsw

FFN( ) Find File Number
Function FFN( )
Format:
Find File Number FFN(filename$[,ERR=stmtref])
Where =
filename$ Name of the file to locate. String expression.
Returns: Integer, channel number for open file (-1 if not open)
Description:
The FFN( ) function checks all the OPEN files for any reference to the file name you specify by filename.
The function returns the channel number as an integer if your file is open. If your file is not currently open
on any channel number, the FFN( ) function will return a value of -1.
Examples:
Read a record from the CUSTDB file. If the file is not open, then OPEN it on a GLOBAL file number.
0100 LET X=FFN("CUSTDB")
0110 IF X=-1 THEN LET X=GFN; OPEN (X)"CUSTDB"
0120 READ (X,KEY=CST_ID$,ERR=9000)IOL=%CST_IOL$
This function is case-sensitive (as is necessary, for instance, in UNIX where "CSTfile" and "cstFILE" would
be two different files). To perform a case-insensitive search for your filename, use either FL (set to lower
case) or FU (set to upper case). For example:
0100 OPEN (5)"CSTfile" ! With neither FL nor FU set
-:PRINT FFN("CSTFILE")
-1
-:SET_PARAM FL
-:PRINT FFN("CSTFILE")
5
-:PRINT FFN("cstFILE")
5
See also: 'FL' Filename in Lower Case, p. 545(p)
'FN' Filename Asis: No Case Conversion, p. 545(p)
FU' Filename in Upper Case, p. 547(p)

FIB( ), FID( ) and FIN( ) File Information
Functions FIB( ), FID( ) and FIN( )
FIB( ), FID( ) and FIN( ) are functions that return file information, descriptors and blocks.
FID( ) returns file characteristics or descriptors such as the type of file, size, keys (if applicable) and
absolute location (path name) of the file on the disk system.
ProvideX returns file identifiers for a file through either the FID( ) or FIB( ) function. Normally these two
functions will both provide the same information, but to simplify conversion to ProvideX from various
Business Basics, ProvideX returns one of 5 different formats for the FID( ) function, based on the setting of
the 'FF' system parameter.
There is one exception to the above. For a device, the FID( ) function always returns only the device
name. For example, FID(0) will yield the terminal identifier.
You can define the value returned by FID(0) externally using the ENVIRONMENT variable PVXFID0 or
internally using the SETFID directive.
The FIB( ) function (Return File Information Block) always returns the information in the ProvideX Standard
format.
The FIN( ) function returns file information about the data structure (describing the physical aspects of a file
such as maximum record, number of records, key size, record size).
See also: The individual sections describing these functions.

FIB( ) Return File Information Block
Function FIB( )
Format:
Return Information Block FIB(chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file about which you want the information.
Returns: String, file information block description
Description:
The FIB( ) function returns a character string containing a file information block description for an existing
open file. You can make subsequent use of this information by passing it to a FILE directive to recreate the
file.
Unlike the FID( ) function, the FIB( ) function is not affected by emulation mode settings.
NOTE: If you set FF to 0 or 3 and switch PO (Path Original) ON, the FID( ) and FIB( )
functions return the original path used when the file was OPENed.
See also: FID( ) Return File Information Descriptor, p. 145(f)
FILE Create New File from File Descriptor, p. 148(d)
Example:
-:A$=FIB(0)
-:?HTA(A$)
0000005430202020200F00000000000000002A0100000700434F4E20202020202020202020202020
20202020202020202020202020202020202020202020202020202020202020202020202020202020
20202020001850190100000000501900005019000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000057494E444F57532020202020

FIB(0) and FID(0) ProvideX Standard Format
Functions FIB(0) and FID(0)
The charts on the following pages describe the Providex Standard FID(0) / FIB(0): i.e. for 'FF'=0.
Bytes Description: (Total length = 212 bytes) FIB(0) and FID(0)

1,3 Current record count (if available)
4,6 Characters 1-6 of file name
10,1 File type indicator
$00$ - Indexed
$01$ - Serial
$02$ - Keyed
$03$ - Open via ISZ= (binary)
$04$ - Program
$0D$ - Directory
$0F$ - Device
11,1 External key size
12,3 Maximum number of records
15,2 Record size
17,1 Keyed file flag ($01$ if variable length records)
18,1 Keyed file inventory threshold %
19,1 File type
"*" Device
">" I/O redirection
A Attached Printer
"B" Opened via ISZ=
"C" C-ISAM
"D" Directory
"E" DDE Connection
"I" Indexed
"K" Keyed/Direct/Sort
"M" Dynamic Memory File (*Memory*)
"N" TCP/IP (Network) Connection
"O" ODBC Data file
"P" Program
"S" Serial
"T" WindX Connected Device/File
"W" Windows Printer
20,1 External file handle
21,1 Current attribute byte
22,1 Current foreground colour
23,1 Current background colour
24,1 Reserved for future use
25,60 External file path name

ProvideX Standard FIB(0) / FID(0) 'FF'=0 for KEYED files.
Bytes DescriptionFIB(0) / FID(0)
85,384 96 * 4 byte entries containing
(1,1) Key number
(2,1) Field # in record ($FF$=key)
(3,1) Offset within field
(4,1) Length of key (descending if bit $80$ on)
Final key entry starts with $FF$ in key number (1,1)
Example:
Since ProvideX KEYED files can have offsets up to 2047, the high order 4 bits from the
Key # field include offset information. The following example extracts the field number,
offset and length from a 4-byte key entry as returned by the FID( ) / FIB( ) function:
The example assumes K_INF$ has 4-byte key descriptor.
0100 KEY_PARSE:
0110 IF K_INF$(1,1)=$FF$ THEN RETURN
0120 K_NO=DEC(AND(K_INF$(1,1),$0F$))
0130 K_FLD=DEC(K_INF$(2,1))
0140 K_OFS=16*DEC($00$+AND($F0$,K_INF$(1,1)))+DEC($00$+K_INF$(3,1))
0150 K_LEN=DEC($00$+K_INF$(4,1))
0160 K_INF$=K_INF$(5)
0170 RETURN
ProvideX Standard FIB(0) / FID(0) 'FF'=0 for TERMINAL DEVICES.

Bytes DescriptionFIB(0) / FID(0)
85,1 Current column
86,1 Current line
87,1 Maximum column
88,1 Maximum line
89,110 Window information (10 * 11 byte entries for top 10 windows)
(1,1) Window number
(2,2) Absolute column (2 Byte)
(4,2) Absolute line (2 Bytes)
(6,1) Number of columns wide
(7,1) Number of lines wide
(8,1) Column 0 of scroll region
(9,1) Line 0 of scroll region
(10,1) # columns for scroll region
(11,1) # lines for scroll region
213,12 Actual device type

FID( ) Return File Information Descriptor
Function FID( )
Format:
Return Descriptor FID(chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file to return information about.
Returns: String, file information descriptor
Description:
The FID( ) function returns a character string containing the file information descriptor for an existing
OPEN file. If the file is a device (printer, terminal, etc.), the file name used to open the file will be returned.
If the file is a disk file, a file description string is returned. You can make subsequent use of this file
description by passing it to a FILE directive to recreate the file.
See also: FIB( ) Return File Information Block, p. 142(f)
FILE Create New File from File Descriptor, p. 148(d)

If you are running ProvideX in an emulation mode, the format of the information returned will be changed to
reflect the system being emulated.
Determining FID in ProvideX under UNIX

By default, ProvideX assigns a unique FID for each terminal based on the /etc/initab entry for the
terminal. Unfortunately, when you use dynamic terminal allocation (e.g. Telnet), each time a user signs off
and then signs on, he / she will have a different FID value. There are workarounds, but no one solution
works in all instances. See the examples, below.
Examples:
If, for security purposes, you can use the user_ID rather than terminal_ID, then you can set the FID in the
users .profile by inserting the lines:
PVXFID0=desired_FID_val
export PVXFID0
As an alternative, you can assign the FID once in ProvideX, by issuing a SETFID directive to establish a
new FID(0) value.
If you don't want to use user_IDs but you are using Telnet and PCs, see if there is a host-initiated file
transfer you could use to get a file containing the FID value off the PC.
Using WINDX, you could open a file on the PC and read it to determine a FID value:
0010 OPEN (1) "[wdx]C:\PVXFID"
0020 READ RECORD (1) F$
0030 CLOSE (1)
0040 SETFID F$

Finally, you could see if the terminal emulator allows you to define values for function keys and has an
escape sequence to send the values. Some terminals send a "HEREIS" string on receipt of an ENQ (hex
$05$), but this varies from terminal to terminal.
FID(1 ) FID(1) 'FF'=1

Bytes Description: (Total length=22 bytes) FID(1)
1,3 $000000$
$00$ - Indexed
$01$ - Serial
$02$ - Keyed
$04$ - Program
$0D$ - Directory
$0F$ - Device
12,3 Maximum number of records
15,2 Record size
17,4 Reserved for future use
FID(2) FID(2) 'FF'=2

Bytes Description: (Total length=16 bytes) FID(2)
$00$ - Indexed
$01$ - Serial
$02$ - Keyed
$04$ - Program
$0D$ - Directory
$0F$ - Device
9,2 Maximum number of records (bytes reversed)
11,2 Record size (bytes reversed)
13,4 Not used

Bytes Description: (Total length=9+ bytes) FID(3)
1,1 For FILES: Type indicator
$00$ = Indexed
$01$ = Sequential
$02$ = Keyed
$03$ = Opened via ISZ= (Binary)
$04$ = Program
$05$ = Attached Printer
$06$ = BBx Mkeyed (no External Key)
$07$ = C-Isam
$0A$ = Unix Pipe
$0D$ = Directory
$0E$ = TCP/IP-Network
2,1 For FILES: External key size
3,4 For FILES: Maximum number of records
7,2 For FILES: Record size (bytes reversed)
9,... For FILES: Path name
Example:
0100 SET_PARAM 'FF'=3
0110 OPEN (30)"SESAME"
0120 LET A$=FID(30)
0130 PRINT A$,LF,HTA(A$),LF,A$(9)
->run
_ __ C:\OTHER\TESTS\SESAME
020F000000000100
C:\OTHER\TESTS\SESAME
1,... For DEVICES: Device Name
[Details for FILES, above (1,1 to 9,...) inapplicable]
Example:
0200 SET_PARAM 'FF'=3
0210 OPEN (31)PRINTER$
0220 B$=FID(31); PRINT B$
->run
LPT1
NOTE: FID(4) is the same as FID(3) but all SERIAL files return a file type indicator of $03$ for
binary. This format is only intended to facilitate program migration to ProvideX.

FILE Create New File from File Descriptor
Directive FILE
Format:
New File Descriptor FILE file_info[,ERR=stmtref]
Where =
file_info Contents provide the internal file description for the file to create. String expression.
Description:
Use the FILE directive to define a file based on the contents returned by the FID( ) or FIB( ) functions.
These functions return character strings with the file type, size, and format.
Warning: The FILE directive will not recreate an embedded Data Dictionary. When you have an
embedded Data Dictionary, use a PURGE or REFILE directive instead, to preserve the
dictionary.
NOTE: The format of the FID( ) value will depend on the current emulation mode you are
using for ProvideX. To avoid potential problems when running in emulation modes,
use the value returned from the FIB( ) function instead of the FID( ) function.
ALSO: This directive is not supported by WindX. When you need to create files on a WindX
PC, encapsulate your command in an EXECUTE "[WDX]..." directive.
See also: FIB( ) Return File Information Block, p. 142(f)
PURGE Clear Data from a File, p. 333(d)
REFILE Clear Data from File, p. 352(d)

Example:
0010 OPEN (2)"PRNTFL"
0020 F$=FID(2)
0030 CLOSE (2)
0040 ERASE "PRNTFL"
0050 FILE F$
0060 OPEN (2)F$(25,60)
-:?F$(25,60)
C:\MANUALS\PVX\PRINTFL

FIN( ) Return File Information
Function FIN( )
Format 1:
1 Return File Information FIN(chan[,ERR=stmtref])

2 Return Detailed Portion FIN(chan,field$[,ERR=stmtref] )
Where =
chan Channel or logical file number indicating the file to return information about.
field$ String expressions. Valid keywords:
CURKNO - Returns the current KNO (Ver. 4.20)
DEVHANDLE - Windows API device handle for communications port (Ver.
4.10)
DRIVER - ProvideX device driver name
EXTRACT - Extract status of file (1 if Extract pending)
FILENAME - Original file name used in OPEN
HANDLE - Operating system file handle
IPADDR TCP/IP - Address
KEY_SIZE - Key size of a keyed file
KSZ - Same as KEY_SIZE
MAXKNO - Maximum KNO value allowable for the file (Ver. 4.20)
MAXREC - Same of RECORDS_ALLOWED
NAME - Same as PATHNAME
NUMREC - Same as RECORDS_USED
PATHNAME - Full path name of file
RECORD_SIZE - Maximum record size
RECORDS_ALLOWED - Maximum # of records
RECORDS_USED - Current # of records used
RSZ - Same as RECORD_SIZE
SEPARATOR - Field separator character of *Dynamic*
TRUE_TTY - UNIX only. Returns FacetTerm tty
Returns: String, physical information about open file
Description:
The FIN( ) function returns a character string containing details about an existing OPEN file. The
information returned is not the same as that in the FIB( ) function. While some of the information in the
FIN( ) function is common with the information in the FIB( ) function, the FIN( ) function includes more
detailed information about the physical file (e.g. file size in bytes, date and time of last update, etc.).
Format 1 Returns File Information: FIN(chan[,ERR=stmtref])

In the example below, the FIN( ) function is used to find out the number of characters in IN_FILE$ (the
variable contains the name of a serial file). The FIN( ) value returned here is used to determine block size
for OPENing the given file for subsequent READs.
0140 LET IN_FILE=HFN; OPEN (IN_FILE)IN_FILE$

0150 LET F$=FIN(IN_FILE)
0160 CLOSE (IN_FILE)
0170 LET CHARS=DEC(F$(1,4))
0180 !

0190 LET BLK_SIZE=1024*10,DONE$="N",C=0
0200 IF CHARS<BLK_SIZE THEN LET BLK_SIZE=CHARS
0210 !
0220 OPEN (IN_FILE,ISZ=BLK_SIZE)IN_FILE$
0250 LET CUR_BYTE=0,ST_BYTE=0,SE_BYTE=0
Format 2 Returns Detailed Portion: FIN(chan,field[,ERR=stmtref])

Use this Format to have the FIN( ) function return the detailed portion. For instance, you can obtain the
value of the Windows API Device handle for a communications port using the "DEVHANDLE" field.
?FIN(10,"DEVHANDLE")
For UNIX FacetTerm Use Only

The FIN function reports the actual tty on which your UNIX FacetTerm session was initiated (Ver. 4.03). If
your environment variable FACETTYPE is set / ON in a current FacetTerm session, recognition is
automatic. FIN(0,"TRUE_TTY") will return the TRUE /dev/tty terminal or device.
The value returned on a system without FacetTerm will be the same as the value returned by PTH(0).
See also: PTH( ) Return Pathname, p. 331(f).
FIN( ) For Disk Resident Files

Bytes Description: For Disk Resident Files (Total length=68 bytes)FIN( )
1,4 Number of bytes in the file
5,4 Date/Time of last modification (Seconds since Jan. 1, 1970)
9,4 Date/Time of last access
13,4 Date/Time of file creation
17,2 Physical device number
19,4 Inode number (UNIX only)
23,2 Userid of file owner (UNIX only)
25,2 GroupID of file owner (UNIX only)
60,4 Maximum record count
64,4 Current record index
NOTE: As of Ver. 4.20, file times returned by the FIN( ) function on UNIX/Linux systems are
reported based on the current time zone, rather than GMT. This keeps the file time
reporting consistent with WINDOWS versions of ProvideX.

FIN( ) For disk resident KEYED files only.
Bytes Description: For disk resident KEYED files onlyFIN( )
77,4 Number of records on file
85,1 Current access key number
86,128 Key definition data. See FIB( ) and FID( ) for Keyed Files, bytes 85, 384 or use
utilities to return key information (e.g. *UFI and **KEY.INF )
FIN( ) For Device Files only.

Bytes For device files only. (TCP files are reported as devices.)FIN( )
1,1 Current column
2,1 Current line number
3,1 Maximum column number
4,1 Maximum line number
5,1 Column offset to start of scroll region
6,1 Line offset to start of scroll region
7,1 Current width of scroll region
8,1 Current height of scroll region
9,1 Reserved (always $00$)
10,1 Current window number
12,1 Current device attribute bits
13,1 Current foreground colour
14,1 Current background colour
16,1 Default attributes
17,1 Default foreground colour
18,1 Default background colour
19,2 Current device mode
21,4 Current device status words 1 and 2
25,2 Auxiliary attributes
27,2 Device option flags
29,2 Operating System handle (Windows only)
31,1 Standard character width
32,1 Standard character height
33,... Path name to device ($00$-terminated)
33+n... Device type ($00$-terminated)

FIND Locate and Read Data
Directive FIND
Format:
Find and Read Data FIND (chan[,fileopt])varlist
Where =
fileopts File options. Valid options for FIND include:
KEY=num Record key value
REC=string$ Record prefix
RNO=num Record number
RTY=num Number of times to retry
SIZ=num Number of characters to read
TIM=num Maximum time to wait
varlist List of variables, literals, mnemonics, IOL= options and/or location functions -
'@(...)'. Each entry in the list must be separated from the next by a comma.
Description:
Use the FIND directive to read data from the file (channel) you specify. When ProvideX READs the data,
its split into one or more fields (either separated by the current delimiter or defined by an embedded format
with headers, etc.). The contents of the first field are placed in variable 1, the second field in variable 2,
and so on.
ProvideX will automatically convert numeric data when executing your FIND statement and moving
numerics into variables. Numeric data converted during a FIND directive does not use the DP or TH
System Parameters, p. 537 for European decimal settings.
If you want to skip a field, use an asterisk "*" as a place holder for the variable name.
If you include more variables in your FIND directive than there are fields in the record, ProvideX initializes
the additional variables to either zero (for a numeric variable) or a NULL string (for a string variable). The
FIND directive advances the file position to the next record (or the record you specify if you use a KEY= or
IND= option). You can use the KNO= option to change the current file access key.
NOTE: If the record is not found when reading using a KEY= or IND= option, the current file
position is not changed (unlike READ).
See also: EXTRACT Read and Lock Data, p. 136(d)
Example:
0410 FIND (1,ERR=1000,DOM=1200)A,B,*,*,E$

FIND RECORD Locate & Read Data Record
Directive FIND RECORD
Format:
Locate Record FIND RECORD (chan[,fileopt])var$
Where =
fileopt File options. Valid options for FIND RECORD include:
SIZ=num Number characters to read
TIM=num Maximum time to wait
var String variable. Receives the contents of the record being read.
Description:
Use the FIND RECORD directive to read a record from the file (channel) you specify. The record's
complete data portion will be returned in the string variable you name.
Apply the FIND RECORD statement when dealing with native-mode operating system files, when
exchanging data with applications other than ProvideX, or when you want to read a complete record
including data-field separators.
When executing your FIND RECORD directive, ProvideX advances the file position to the next record (or
the record you specify in a KEY= or IND= option). You can use the KNO= option to change the current file
access key.
NOTE: If the record is not found when reading using the KEY= or IND= options, the current
file position is not changed (unlike READ).
See also: EXTRACT RECORD Read-Lock Data Record, p. 138(d)
Example:
0010 OPEN (1)"OLDFIL"
0030 FIND RECORD (1,END=1000)R$
0050 GOTO 0040
1000 CLOSE (1),(2)
1010 END

FLOATINGPOINT Switch to Scientific Notation
Directive FLOATINGPOINT
Format:
Scientific Notation ON FLOATINGPOINT
Description:
Use the FLOATINGPOINT directive to have ProvideX start using scientific notation with all numeric data.
In scientific notation, a number is represented as a fraction times ten to some power (e.g. .nnnnn*10^xx
displayed as .nnnnnExx).
In FLOATINGPOINT mode, no rounding is done on numeric calculations. If your numeric output is
unformatted, ProvideX uses scientific notation (e.g. .314159E+01).
Use the PRECISION directive to end FLOATINGPOINT mode.
PRC Precision Currently In Effect, p. 315(v)
PRC( ) Round Number to Precision, p. 316(f)
PRECISION Change Current Precision, p. 317(d)
NOTE: As of Ver. 4.20, FLOATINGPOINT notation is reset to standard decimal notation

during a RESET operation. (In previous versions FLOATINGPOINT was left ON.)
Example:
0030 FLOATINGPOINT
0040 A=5/3
0050 PRINT A
RUN
.16666666666667E+01
0010 PRECISION 2 ! Sets precision to two
0020 ROUND ON ! Sets rounding default mode
0030 A=5/3
0040 FLOATINGPOINT
0050 PRINT A
-:RUN
.167E+01

FOR ... NEXT Loop While Incrementing
Directive FOR ... NEXT
Format:
Reiterative Loop FOR var=first TO last[ STEP val]
Where =
var Numeric variable to be incremented (or decremented) during each pass through the
loop portion of the application.
first Initial value of the variable. Numeric expression.
last Ending value of the variable (the value that ends the loop when achieved). Numeric
expression.
val Optional value by which the variable will be incremented (or decremented) on each
pass through the loop. The default is +1.
Description:
Use the FOR directive to define the start of a repetitive loop in a program. When ProvideX executes the
FOR directive, your numeric variable is set to the starting value. The ending value is evaluated and saved
on the FOR / NEXT stack as the value that will end the loop.
The STEP value, if you use one, is evaluated and its value is saved as the increment (or decrement if
negative). If you don't include an increment/decrement, the default is 1 (one). An increment of 0 (zero) is
invalid and results in an Error #44: Invalid step value.
Finally the current program statement position is saved and execution continues. When ProvideX
encounters a NEXT directive with the same variable as in the FOR directive (or no variable name) it
increments/decrements the value. If the new value does not exceed the end value (or fall below it, if
decremented), control transfers back to the FOR directive to continue the loop. Otherwise the FOR /
NEXT loop ends.
If you specify a variable with your NEXT directive, it must match the variable in the FOR directive. The
NEXT directive can appear anywhere in the program except where it would be executed inside another
FOR / NEXT loop, a GOSUB / RETURN routine, a WHILE / WEND loop, or a REPEAT / UNTIL loop.
Use the EXITTO directive to halt a FOR / NEXT loop without performing all iterations. When ProvideX
executes your EXITTO directive, it removes the top entry from the FOR / NEXT stack and ends that FOR /
NEXT loop.
See also: NEXT End of Loop, p. 285(d)
Example 1:
0010 FOR I=1 TO 10
0020 PRINT I,
0030 NEXT I
-:RUN
1 2 3 4 5 6 7 8 9 10
Example 2:
This example strips trailing spaces from the A$ value:
0030 LET A$="Hello "
0040 GOSUB 1000
0050 PRINT B$,"|"
0060 STOP

...
1000 IF A$="" THEN LET I=0; RETURN
1010 FOR I=LEN(A$) TO 1 STEP -1
1020 IF A$(I,1)<>" " THEN EXITTO 1040
1030 NEXT
1040 LET B$=A$(1,I)
1050 RETURN
-:RUN
Hello|
Example 3:
This example uses nested FOR / NEXT loops to accumulate amounts from one array, A(2,5) and return
the totals in another array, B(5):
0010 DIM A(2,5),B(5)
0020 FOR I=1 TO 2
0030 FOR J=1 TO 5
0040 LET A(I,J)=J
0050 LET B(J)=B(J)+A(I,J)
0060 NEXT J; NEXT I
0070 PRINT A{ALL}
0080 PRINT B{ALL}
-:RUN
0 0 0 0 0 0 0 1 2 3 4 5 0 1 2 3 4 5
0 2 4 6 8 10

FPT( ) Return Fractional Part
Function FPT( )
Format:
Return Fractional Part FPT(num[,ERR=stmtref])
Where =
num Numeric expression whose fractional portion will be returned.
Returns: Fractional portion of numeric
Description:
The FPT( ) function returns the fractional portion of your given numeric value. The value returned is
always rounded to the PRECISION currently in effect.
Example:
0020 PRECISION 3 ! Set precision
0030 ...
0100 LET A=FPT(1.345) ! Yields .345
0110 LET B=FPT(A/10) ! Yields .035
0120 FLOATINGPOINT
0130 PRINT FPT(10/3) ! Yields .3333333333333E+00
0140 BEGIN ! Resets precision to 2

->?FPT(10/3)
.33E+00
0150 PRECISION 2 ! Turns off scientific notation
0160 LET A=FPT(10/3) ! Yields 0.33

GAP( ) Return ODD Parity String
Function GAP( )
Format:
Return String ODD Parity GAP(string$[,ERR=stmtref])
Where =
string$ Character string to convert to ODD parity. String expresssion
Returns: ODD parity value of string
Description:
The GAP( ) function converts and returns your character string expression in ODD parity. This function is
typically used with unprintable characters when dealing with communication lines. It is not normally used
in Operating Systems since the standard communications drivers handle the generation of parity.
The number of one-bits in each byte of the character string determines the parity of data. ODD parity data
always has an odd number of one-bits in each byte of data.
See also: GEP( ) Return EVEN Parity String, p. 160(f)
Illustration:
0110 PRINT "HTA(""This is a test"") =",HTA("This is a test")
0120 PRINT "GAP(""This is a test"") =",GAP("This is a test")
0130 PRINT "HTA(GAP(""This is a test""))=",HTA(GAP("This is a test"))
-:run
HTA("This is a test") =5468697320697320612074657374
GAP("This is a test") =Ths s a s
HTA(GAP("This is a test"))=5468E97320E973206120F4E573F4

GBL( ) Reference Global String Variable
Function GBL( )
Formats:
1 Return/Maintain Entries GBL(string_name$[,contents$][,ERR=stmtref])

2 Remove/List Entries GBL({DELETE | LIST}string_name$[,ERR=stmtref])
3 Remove/List TO Entry GBL({DELETE | LIST} TO string_name$[,ERR=stmtref])
4 Remove or List Table GBL({DELETE | LIST} *[,ERR=stmtref])
Where =
string_name$ Name of the global string in the internal table. String expression.
contents$ Value to assign to the global string. Optional. String expression.
* (asterisk) The asterisk indicates all global string table entries.
Returns: Values in internal table of strings
Description:
NOTE: This function is primarily provided for compatibility with other languages and has
been made virtually obsolete by GLOBAL variables, which are a much more efficient
way to handle common data elements (string, numeric, arrays, etc.).
The GBL( ) function returns and maintains the values in an internal table of string definitions.
Format 1 Gets / Maintains Entries: GBL(string_name$[,contents$][,ERR=stmtref])

You can use this format to set or obtain the current value of the global string variable whose name you
specify. If you include a contents value (optional) it will be placed into the global string variable.
Format 2 Deletes / Lists Single Value: GBL({DELETE | LIST}string_name$[,ERR=stmtref])

Use the GBL(DELETE ...) format to delete or list an individual global string from the table. Use the
GBL(LIST ...) format to have the function return an individual string.
Format 3 Deletes / Lists All up to Value: GBL({DELETE | LIST} TO string_name$[,ERR=stmtref])

Use the GBL(DELETE TO ...) format to delete items up TO an individual global string from the table. Use
the GBL(LIST TO ...) format to have the function return a list of global string names up TO an individual
item ($00$ separated).
Format 4 Deletes or Lists ALL: GBL Table GBL({DELETE | LIST} *[,ERR=stmtref])

Use the GBL(DELETE *) format to remove all entries from the table. The GBL(LIST *) format returns the
names of all strings in the table ($00$ separated).

GEP( ) Return EVEN Parity String
Function GEP( )
Format:
Return String, EVEN Parity GEP(string$[,ERR=stmtref])
Where =
string$ Character string to convert to EVEN parity. String expression.
Returns: EVEN parity value of string
Description:
The GEP( ) function converts and returns your character string expression in EVEN parity. This function is
typically used with unprintable characters when dealing with communication lines. Its not normally used
by the Operating System since the standard communications drivers handle the generation of parity.
The number of one-bits in each byte of the character string determines the parity of data. EVEN parity
data always has an even number of one-bits in each byte of data.
See also: GAP( ) Return ODD Parity String, p. 158(f)
Illustration:
0110 PRINT "HTA(""This is a test"") =",HTA("This is a test")
0120 PRINT "GEP(""This is a test"") =",GEP("This is a test")
0130 PRINT "HTA(GEP(""This is a test""))=",HTA(GEP("This is a test"))
-:run
HTA("This is a test") =5468697320697320612074657374
GEP("This is a test") =iitet
HTA(GEP("This is a test"))=D4E869F3A069F3A0E1A07465F374

GET_FILE_BOX Ask for File Name
Directive GET_FILE_BOX
Format:
1 Create File Box GET_FILE_BOX path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]

2 Check File Box GET_FILE_BOX READ path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]
3 Write File Box GET_FILE_BOX WRITE path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]
Where =
path$ String variable that contains the file path. Initialize this prior to executing this
directive. See the note, below.
dir$ Initial directory to display. String expression.
wdw_title$ Window title. String expression.
ext_list$ List of file extensions. Optional. String expression. Comma or your choice of
character as delimiter.
df_ext$ Default file extension. Optional. String expression.
Description:
Use the GET_FILE_BOX directive to display a standardized window for the user, allowing the entry or
selection of a file in the system.
NOTE: GET_FILE_BOX is supported when you use WindX with UNIX file systems and
supported CALLs to [WDX] . See [WDX] Tag: Directs Action to Client Machine, p. 626.
Format 1 Creates: GET_FILE_BOX path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]

NOTE: The path$ variable will receive the full pathname of the file selected. Because its
initial contents will be used as the default pathname, initialize it prior to executing
this directive.
If the initial directory string is NULL, ProvideX uses the current directory.
You can list standard file extensions using the form Description|*.XXX,. You can include multiple
extensions, comma-delimited (with the last extension terminated by a comma). If desired, you can choose
a character other than a comma to delimit each entry. ProvideX uses the last character in ext_list$ (the
comma or your choice) as the delimiter.
Format 2 Checks: GET_FILE_BOX READ path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]

Use the READ format to make sure that the file you want returned exists.
Example:
0010 GET_FILE_BOX READ X$,"C:\PVX","File to View"

Format 3: GET_FILE_BOX WRITE path$,dir$,wdw_title$[ext_list$[,df_ext$,]][,ERR=stmtref]
Use the WRITE format to completely erase or rewrite the file. If you do this and a user selects a file that
already exists, ProvideX will confirm that the file is to be overwritten prior returning to the program.
Example:
0010 GET_FILE_BOX WRITE X$,LWD,"Report file",
"Report files|*.RPT,All files|*.*,","RPT"
This allows the user to have a file name with the default extension .RPT and gives the user a list of files of
two typesReport files (*.RPT) and All files (*.*).

GFN Highest GLOBAL Channel Not Open
Numeric System Variable GFN
Returns: Highest available GLOBAL channel number
Description:
This numeric system variable returns the highest available (i.e., not OPEN) GLOBAL file channel. The
numeric value returned is an integer in a range from 64 to 127 (32768 to 65000 in some modes, e.g. 'XF').
Example:
->set_param 'xf'
->?gfn
65000
->SET_PARAM -'XF'
->?GFN
127

GID Operating System Process Identifier
String System Variable GID
Returns: Two-character O/S process identifier
Description:
You can use this string system variable to obtain a two-character 16-bit binary Operating System group or
process identifier (PID).
Example:
For instance, you can obtain the 16-bit UNIX Process ID by using:
->pid=dec($00$+gid)
->?pid
30633
For larger values (e.g. 32-bit) see TCB(89)in TCB( ) Return Task Information, p. 424(f). TCB(89)
returns the numeric value of the current Process ID (PID). You can use this as a replacement for
DEC($00$+GID) to retrieve the current PID value.
PID Signal under UNIX: Example

You can send a signal from another PVX session or from the UNIX shell to generate a CTL event using a
SIGNAL 2 (a SIGBREAK that initiates a program's SETESC branch) and you can also send signals from
inside a ProvideX program.
That is, you can use the PID value with the SYS( ) function to create your signal to another process:
X=SYS(pid,2)
where the first argument is the PID signal to send and the second is the signal number.

GOSUB ... RETURN Execute Subroutine
Directive GOSUB ... RETURN
Format:
Transfer to Subroutine GOSUB stmtref
Where =
Description:
Use the GOSUB directive to initiate a call to a subroutine embedded in your current program. The current
location in the program is saved on a stack and control is passed to the statement number or label you
specify (or if no statement exists with the number specified, to the next higher statement). ProvideX
continues execution from there until a RETURN directive is executed. Then it returns control to the
position saved on the stack.
If you want to exit from a GOSUB subroutine without returning to the calling point, you can use the EXITTO
directive to remove the return point from the stack. You must use either a RETURN or an EXITTO directive
to terminate each GOSUB subroutine.
Dont place your RETURN directive inside a FOR / NEXT loop or a WHILE / WEND loop.
There is no limit (apart from memory space) to the number of GOSUB - RETURN entries that you can
have on the stack.
NOTE: The BEGIN, CLEAR, RESET, STOP, and END directives reset all entries in the GOSUB
- RETURN stack.
See also: EXITTO Premature Exit of FOR/NEXT, GOSUB, p. 134(d)
Example:
D$="",D1$="",D2$=""
-:/
0100 INPUT "Enter starting date DD/MM/YY: ",D$
0110 GOSUB 1000
0120 LET D1$=D$
0130 INPUT "Enter ending date DD/MM/YY: ",D$
0140 GOSUB 1000
0150 LET D2$=D$
1000 REM Subroutine
1010 IF LEN(D$)<>8 THEN GOTO 1090
1020 IF D$(3,1)<>"/" OR D$(6,1)<>"/" THEN GOTO 1090
1030 LET D=NUM(D$(1,2),ERR=1090),M=NUM(D$(4,2),ERR=1090),Y=NUM(D$(7,2),ERR=
1030:1090)
1040 IF D<1 OR D>31 THEN GOTO 1090
1050 IF M<1 OR M>12 THEN GOTO 1090
1060 RETURN
1090 PRINT "Invalid. Restart.."
1100 EXITTO 0100
-:RUN
Enter starting date DD/MM/YY: 05/03/99
Enter ending date DD/MM/YY: 31/03/99
-:DONE

GOTO Transfer within Program
Directive GOTO
Format:
Transfer Control GOTO stmtref
Where =
Description:
Use the GOTO directive to have ProvideX transfer execution to your given statement number or label. If
your line number doesn't exist, then the statement with the next higher number will be used.
You can use the GOTO directive in either EXECUTION or COMMAND mode. In COMMAND mode, when
you issue a RUN directive, ProvideX begins executing the GOTO directive at your given statement
number.
If you use GOTO in a compound statement, it must be the final directive.
Example in EXECUTION Mode:

0010 INPUT "Enter a number: ",A
0020 IF A=0 THEN PRINT "DONE"; STOP
0030 PRINT A+" multiplied by 2 is ",A*2
0040 GOTO 0010
Example in COMMAND Mode:

-:GOTO 10
-:RUN
Enter a number: 1
1 multiplied by 2 is 2
Enter a number: 3
3 multiplied by 2 is 6
Enter a number: 0
DONE
-:

GRID Define/Control Grid
Directive GRID
Formats:
1 Define/Create GRID ctl_id,@(col,line,width,height),SEP=col_dlm[,fileopt][,ERR=stmtref]

2 Delete Grid GRID REMOVE ctl_id[,ERR=stmtref]
3 Add Row/Col GRID ADD ctl_id,col,row[,ERR=stmtref]
4 Load GRID LOAD ctl_id,col,row,contents$[,ERR=stmtref]
5 Delete Row /Col GRID DELETE ctl_id,col,row[,ERR=stmtref]
6 Clear GRID CLEAR ctl_id,col,row[,width,height][,ERR=stmtref]
7 Disable/Enable GRID {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
8 Lock/Unlock GRID {LOCK | UNLOCK} ctl_id,col,row[,width,height][,ERR=stmtref]
9 Set Focus To GRID GOTO ctl_id[,ERR=stmtref]
10 Focus on Cell Address GRID GOTO ctl_id,col,row[,ERR=stmtref]
11 Read GRID READ ctl_id,col,row,var$,eom$[,ERR=stmtref]
12 Read Next GRID READ NEXT ctl_id,col,row,var$,eom$[,ERR=stmtref]
13 Select Range GRID SELECT ctl_id,col,row[,width,height][,ERR=stmtref]
14 Select Read GRID SELECT READ ctl_id,col,row[,ERR=stmtref]
15 Select Read Next GRID SELECT READ NEXT ctl_id,col,row[,ERR=stmtref]
16 Select Reset GRID SELECT RESET ctl_id[,ERR=stmtref]
17 Find or Retrieve GRID FIND ctl_id,col,row,var$[,ERR=stmtref]
18 Write Setting GRID WRITE ctl_id,col,row,contents$[,ERR=stmtref]
19 Set Focus To GRID SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]
20 FOCUS Notification GRID AUTO ctl_id[,ERR=stmtref]
21 Hide/Show GRID {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the GRID. Numeric expression, integer. Avoid integers
that conflict with keyboard definitions (e.g. using 4 can cancel CTL=4 for the <F4>
key).
@(col,line, Position and size of the GRID region on the screen. Numeric expressions. Column
width,height) and line coordinates for top left corner, width in number of columns, height in
number of lines.
col_dlm Character to use as column delimiter
col,row Column and row refer to cell location / coordinates. Numeric expressions.
fileopt File options. You can use all standard file options when defining a GRID. See also
GRID Fileopt, p. 169.
var$ String variable. Receives cell values returned for FIND and READ.
eom$ String variable. Receives your users End of Message string / character (e.g. $0D$
for the <Enter> key).

Where =
contents$ Value(s) to be written to the cell(s) or settings. String expression(s).
alt_ctl Alternate CTL value.
Description:
Use the GRID directive to create a gridwork or table of cells in columns and rows, i.e., a spreadsheet input
format (Ver. 4.10). The GRID control object is a two-dimensional array of MULTI_LINE input fields
(default), CHECK_BOXES, BUTTONS, DROP_BOXes or any combination of control objects. Each cell
can be of a different type.
For some Formats of the GRID directive (e.g. GOTO and FIND), both column and row coordinates are
required (to act as pointers to a particular cell). For other Formats, one or both of the values can be 0
(zero). The chart below shows how ProvideX interprets the column and row values.
Column, Row Values How ProvideX Interprets These

col=1, row=1 The topmost cell is 1,1
col=0, row=0 ALL columns and rows respectively. For example, GRID DELETE
100,0,0 deletes the entire GRID whose control ID is 100.
col=num, row=0 Entire column number. For example, GRID DELETE 100,3,0 deletes
column 3 of the GRID whose control ID is 100.
(i.e. col <>0, row=0 or
omitted) Note that the GOTO and FIND formats of the GRID directive require both
column and line coordinates. You cant omit the row in those formats.
col=0, row=num Entire row number. For example, GRID DELETE 100,0,2 deletes row 2
of the GRID whose control ID is 100.
(i.e. col=0 or omitted,
row <>0) Note that the GOTO and FIND formats of the GRID directive require both
column and line coordinates. You cant omit the column in those formats.
col=num,row=num Column AND row. For example:
(both col and row are GRID DELETE 100,3,2 deletes BOTH an entire column (column 3) and
<>0) an entire row (row 2) of the GRID whose control ID is 100.
GRID GOTO 100,3,2 sets focus on the cell located in column 3, row 2.
col and/or row =-1 By default, there are also column and row headers you can gain access to
using column and/or row = -1. You cant include these headers in any
range specifications.
Many of the GRID cell attributes are only accessible through properties. For example, the only way to
change the cell type is to set the Celltype$ property to one of the following values: Button,
CheckBox, CheckBox3DRaised, CheckBox3DRecessed, CheckMark, CheckMark3DRaised,
CheckMark3DRecessed, Drop_box,DropBox, DropBoxHideBtn, Picture, Normal,
Multi_line. Also, you can use the Value$ property to read or write cell contents. (You must specify
the Column and Row to identify the desired cell.)
For a detailed list of GRID properties, see Dynamic Control Object PROPERTIES, p. 572.
Format 1 Creates: GRID ctl_id,@(col,line,width,height)[,fileopt][,ERR=stmtref]

Use this format to create your GRID. The value in ctl_id is a unique identifier for your GRID. This value is
used to generate a CTL whenever the GRID is selected and changed. Only three of the standard file
options are detailed below, but you can use all standard file options with your GRID directive.

GRID Fileopt =
SEP= String expression. You can set the SEP= option to define your column delimiter using
an ASCII or hex value or a variable. The default is the standard ProvideX separator,
$8A$.
Examples:
GRID 7050,@(5,5,35,15),SEP=":" ...
GRID 7050,@(5,5,35,15),SEP=$3A$ ...
GRID 7050,@(5,5,35,15),SEP=MY_SEP$ ...
FNT= Use FNT="font$,size[,attr] to define your font. For example:
GRID 7050,@(5,5,35,15),FNT="Courier New,1" ...
FMT= Use the FMT= option to format your column headings. You can include column titles,
alignment characters and width. The alignment characters you can use are L for left, C
for centre or R for right. (If you omit the alignment character, Left is the default.)
Enclose your list in standard quotes, with each heading in square brackets [ ] and use
spaces to separate the headings. For example:
GRID 7000,@(5,5,35,15),FMT="[Company Name]C15 [Address]L20" ...
All Others You can use all standard file options with your GRID directive. See also File Options,
p. 581.
Format 2 Deletes Grid: GRID REMOVE ctl_id[,ERR=stmtref]

Use GRID REMOVE to delete an entire GRID.
Format 3 Adds Row/Column: GRID ADD ctl_id,col,row[,ERR=stmtref]

Use the GRID ADD format to add a row or column of blank cells to your GRID. At least one of the col,row
values must be other than 0 (zero).
Format 4: GRID LOAD ctl_id,col,row,contents$[,ERR=stmtref]

Use the GRID LOAD format to load contents$ into your GRID from your string variable or expression. You
must include both the column and the row for the address at which the LOAD is to start. If column and row
are both 0 (zero) then the GRID is cleared first.
To make things easier for you, ProvideX can LOAD a number of columns and rows of data at a time. Your
column and row separators are mandatory. Set your column separator using the SEP=option. Set your
row separator by including it as the last character in your data string. (ProvideX treats the last character in
the string as your row separator.)
To Add a New (Bottom) Row:

Use row=0 to add a simple new row to the bottom of a GRID. The format is:
GRID LOAD ctl,1,0,data$+ESC ! (Using ESC as the row delimiter)
Format 5 Deletes Col/Row: GRID DELETE ctl_id,col,row[,ERR=stmtref]

Use the GRID DELETE format to delete a column or row from your GRID. You can identify a column to
delete, a row to delete, or both.
Reminder: If you use zero (0) as your value for both column and row, ProvideX interprets that as

"ALL columns and rows, respectively" and will delete the entire GRID.
Format 6: GRID CLEAR ctl_id,col,row[,width,height][,ERR=stmtref]

Use the GRID CLEAR format to clear or reset the contents of a range of cells to the default (empty). You
can clear a column or a row or both. If you use 0 (zero) as your value for both column and row, ProvideX
interprets that as "ALL columns and rows, respectively" and will clear the entire GRID.
Format 7: GRID {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use the GRID DISABLE format to gray out the GRID and make it inaccessible to users and programs. Use
the GRID ENABLE format to restore a disabled GRIDs display and access.
Format 8: GRID {LOCK | UNLOCK} ctl_id,col,row[,width,height][,ERR=stmtref]

Use the GRID LOCK format to reserve exclusive use of a range of cells in the GRID (e.g. during a WRITE
or for security reasons). Your user cant change the cells value, but if the cell is a BUTTON control the
user can still click on it. Use the GRID UNLOCK format to release the locked range of cells for other
processes.
If you use 0 (zero) as your value for both column and row, ProvideX interprets that as "ALL columns and
rows, respectively" and will LOCK or UNLOCK the entire GRID.
You can also use a GRID control objects properties to lock or unlock cells (by setting the Row, Column
and Lock properties). Set your Lock value to 1 (lock) or 0 (zero to unlock). The default background
colour for LOCKed cells is LIGHT GRAY (standard BUTTON face colour). You can use the BackColour
property to override this. See the Object Property Table, p. 574.
Format 9 Sets Focus To First Cell in Grid: GRID GOTO ctl_id[,ERR=stmtref]

Use this format of the GRID GOTO directive to set the Focus on the first cell of your GRID, ready for the
user's next action.
Format 10 Goes to Cell, Sets Focus: GRID GOTO ctl_id,col,row[,ERR=stmtref]

Use this format of the GRID GOTO directive to go to a specific cell address (other than the first cell) and
set the focus on that cell, ready for the user's next action. You must include both column and row
coordinates in this format of the directive (not zero values).
Format 11 READs First Cell: GRID READ ctl_id,col,row,var$,eom$[,ERR=stmtref]

Use the string variable (var$) in the GRID READ format to receive the modified cell address and value of
the first selected cell. If the cell doesn't exist, ProvideX returns an Error #2: END-OF-FILE on read
or File full on write is generated. If there is more to read, the CTL event is reposted.
The eom$ string tells you what input sequence ended the message (e.g. $0D$ for <Enter>).
NOTE: All of your GRID READ directives must include both column and row addresses.
ProvideX returns a queue of cells that have been changed and generates an
additional CTL event after a READ to ensure that no events are lost. There can be a
RACE problem if the host lags behind user input. To circumvent this, ProvideX
returns an Error #2: END-OF-FILE on read or File full on write if the
queue is empty.

ALSO: Under NOMADS, the READ is done automatically and should NOT be done by your
application. The data read is placed in the standard input variable with
control_name.row and control_name.col containing the associated cell information.
Format 12 READs Next Cell: GRID READ NEXT ctl_id,col,row,var$,eom$[,ERR=stmtref]

Use the string var$ in the GRID READ NEXT format to receive the modified cell address and value of the
next (not first) selected cell. If this cell doesn't exist, ProvideX returns an Error #2: END-OF-FILE on
read or File full on write. If there is more to read, no CTL event is re-posted. The CTL value is
posted when another cell is changed.
The eom$ string tells you what input sequence ended the message (e.g. $0D$ for <Enter>).
SELECT READ Formats 13 to 16:

Use the GRID SELECT formats (below) to select ranges of cells to READ or to RESET (to remove cells
from the SELECT state). Note that if you use 0 (zero) as your value for both column and row, ProvideX
interprets that as "ALL columns and rows, respectively" and will SELECT the entire GRID.
Format 13 Selects Range: GRID SELECT ctl_id,col,row[,width,height][,ERR=stmtref]

Use the GRID SELECT format to select a range of cells from your GRID.
Format 14 Reads First Selected Cell: GRID SELECT READ ctl_id,col,row[,ERR=stmtref]

Use the GRID SELECT READ format to read the first selected cell. If the cell doesn't exist, ProvideX
returns an Error #11: Record not found or Duplicate key on write.
Use GRID SELECT directives to control cell selection. (When you SELECT a range of cells, your given
cells are added to the list of selected cells.) To determine which cells are selected: use a GRID SELECT
READ directive to obtain the first selected cell, then use GRID SELECT READ NEXT directives to get
subsequent cells.
Format 15 Reads Next Selected Cell: GRID SELECT READ NEXT ctl_id,col,row[,ERR=stmtref]
Use the GRID SELECT READ NEXT format to read the next (not the first) selected cell. When ProvideX
encounters a SELECT READ NEXT directive after the last selected cell is returned, it reports an Error
#2: END-OF-FILE on read or File full on write.
Format 16 Resets all from SELECT state: GRID SELECT RESET ctl_id[,ERR=stmtref]
Use GRID SELECT RESET (i.e., to remove all cells from the SELECT state). There is no way to remove
cells from the selected state individually.
Format 17: GRID FIND ctl_id,col,row,var$[,ERR=stmtref]

Use a string var$ in the GRID FIND format to return the value for a specific cell. Note that if you use 0
(zero) as your value for both column and row, ProvideX interprets that as "ALL columns and rows,
respectively" and will retrieve the entire GRID.

Format 18 Updates Setting: GRID WRITE ctl_id,col,row,contents$[,ERR=stmtref]
Use the GRID WRITE format to update your GRID by writing settings to specified cells. Note that if you
use 0 (zero) as your value for both column and row, ProvideX interprets that as "ALL columns and rows,
respectively" and will write to the entire GRID. You must include both the column and row address.
Format 19 Sets Focus: GRID SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

Use the GRID SET_FOCUS format to have ProvideX return CTL values when focus changes to an
address in the GRID.
Format 20 for FOCUS Notification: GRID AUTO ctl_id[,ERR=stmtref]

Use the GRID AUTO format to have ProvideX return a control value whenever focus changes occur within
your GRID. You can use the values in your applications to track your users' selections.
Format 21: GRID {HIDE | SHOW} ctl_id[,ERR=stmtref]

When you use the HIDE format, even though your GRID is still active, your users can't see it or gain
access to it. It is still accessible to your program(s). Use the SHOW format to restore the users display
and access.
GRID Example
The example below demonstrates how you can use a combination of GRID directives and GRID control
object properties to perform various functions (formatting, loading, retrieving, etc.).
0010 ! GRIDDEMO - Grid demo program

0020 BEGIN ;
0020:PRINT CS,"Grid Demonstration"
0030 GRID 10,@(3,3,70,15)
0040 GRID LOAD 10,0,0,""
0050 FOR R=1 TO 10
0060 LET R$=""
0070 FOR C=1 TO 10
0080 LET R$+=STR(C*R)+SEP
0090 NEXT
0100 GRID LOAD 10,1,0,R$
0110 NEXT
0120 LET X=10
0130 FOR I=1 TO 10;
0130:LET XROW=-1,XCOLUMN=I;
0130:LET XVALUE$="Col "+STR(I);
0130:NEXT
0140 FOR I=1 TO 10;
0140:LET XROW=I,XCOLUMN=-1;
0140:LET XVALUE$="Row "+STR(I);
0140:NEXT
0150 LET XCOLUMN=-1,XCOLUMNWIDTH=6
0160 LET XCOLUMN=2,XROW=0,XLOCK=1
0170 LET XCOLUMN=3,XROW=0,XCOLUMNWIDTH=7,XCELLTYPE$="Button",XLOCK=1
0180 LET XCOLUMN=4,XROW=0,XCOLUMNWIDTH=7,XCELLTYPE$="CheckMarkRecessed"
0190 LET XCOLUMN=5,XROW=0,XCOLUMNWIDTH=7,XCELLTYPE$="DropBox",
0190:XTEXT$="car/pig/dog/"
0200 LET XCOLUMN=6,XROW=0,XCOLUMNWIDTH=7,XCELLTYPE$="DropBoxHideBtn",

0200:XTEXT$="car/pig/dog/"
0210 LET XCOLUMN=7,XROW=0,XCOLUMNWIDTH=7,XBITMAP$="!bug"
0220 LET XCOLUMN=8,XROW=0,XALIGN$="C"
0230 LET XCOLUMN=9,XROW=0,XALIGN$="R"
0240 LET XCOLUMN=0,XROW=2,XBACKCOLOUR$="LIGHT CYAN"
0250 LET XCOLUMN=0,XROW=3,XBACKCOLOUR$="LIGHT YELLOW"
0260 LET XROW=8;
0260:FOR I=1 TO 10;
0260:LET XCOLUMN=I;
0260:LET XBACKCOLOUR$="RGB:"+STR(RND(200)+55)+" "+STR(RND(200)+55)+
0260:" "+STR(RND(200)+55);
0260:NEXT
0270 LET XROW=9;
0270:FOR I=1 TO 10;
0270:LET XCOLUMN=I;
0270:LET XTEXTCOLOUR$="RGB:"+STR(RND(200)+55)+" "+STR(RND(200)+55)+
0270:" "+STR(RND(200)+55);
0270:NEXT
0280 FOR I=1 TO 10;
0280:LET XCOLUMN=I,XROW=I,XFONT$="Arial,1,BI";
0280:NEXT
0290 INPUT X$;
0290:IF CTL=4
0290:THEN STOP
0300 IF CTL<>10
0300:THEN PRINT "Recvd CTL=",CTL;
0300:GOTO 0290
0310 GRID READ 10,C,R,ZZ$,E$
0320 PRINT @(0,20),CL,"Col=",C," Row=",R," Dta=",ZZ$," Eom=$",HTA(E$),"$",
0330 GOTO 0290

H_SCROLLBAR Define/Control Horizontal Scroll Bar
Directive H_SCROLLBAR
Formats:
1 Define/Create H_SCROLLBAR ctl_id,@(col,line,width,height)[,fileopt]

2 Define at Edge H_SCROLLBAR ctl_id WINDOW[,fileopt]
3 Delete H_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]
4 Disable/Enable H_SCROLLBAR {DISABLE | ENABLE} ctl_id [,ERR=stmtref]
5 Set Focus To H_SCROLLBAR GOTO ctl_id[,ERR=stmtref]
6 Read Setting: H_SCROLLBAR READ ctl_id,setting,max,[rgn_chg][,arrow_chg][,ERR=stmtref]
7 Write Setting H_SCROLLBAR WRITE ctl_id,marker,max[,ERR=stmtref]
8 Hide/Show H_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the H_SCROLLBAR. Numeric expression. Integers,
range: -32000 to +32000. Avoid integers that conflict with keyboard definitions (e.g.
@(col,line, Position and size of the H_SCROLLBAR region. Numeric expressions. Column and
lines.
fileopt File options. Valid options for H_SCROLLBAR include:
OPT=char$ Single character
Valid OPT= parameters are:
A - Auto: Generates a CTL value for each movement
D - Disabled: User cannot access the scrollbar
H - Hide: Do not display the scrollbar
s - Scroll: Allows H_SCROLLBAR to scroll with a resizable dialogue box
setting Numeric variable to receive the current scrollbar setting.
marker Relative position to set as the H_SCROLLBAR marker. Numeric expression between
1 and the maximum.
max Logical maximum value of the H_SCROLLBAR. Numeric expression.
rgn_chg Amount to increase/decrease the H_SCROLLBAR setting when the user selects the
region left/right of the marker. Numeric expression. (Default: max/width)
arrow_chg Amount to increase/decrease the H_SCROLLBAR setting when the user selects the
arrow at the left/right edge of the H_SCROLLBAR. Numeric expression. (Default: 1)
Description:
Use the H_SCROLLBAR directive to create a horizontal scrollbar for a window. Your program logic can
read and adjust a value by increments to control logical column position within a record every time the user
moves the H_SCROLLBAR control object.
See also: V_SCROLLBAR Define/Control Vertical Scroll Bar, p. 451(d)


Format 1 Creates: H_SCROLLBAR ctl_id,@(col,line,width,height)[,fileopt]
When you create the H_SCROLLBAR, your value in ctl_id is the unique identifier for it. This value is used
to generate a CTL value whenever a user selects and moves the H_SCROLLBAR.
Example:
0010 H_SCROLLBAR 10000,@(5,20,70,1)
The example above defines a scrollbar 70 columns wide and one line high, starting at column 5 on line 20.
Whenever the H_SCROLLBAR is selected a CTL 10000 will be generated.
NOTE: Once a new position is selected, you must read it before your application can use the
value to update the actual H_SCROLLBAR position.
Example
0100 ! 100 - Horizontal Scroll Bar Example
0110 LET VAL=1,MX=400,BJMP=25,SJMP=1

0120 H_SCROLLBAR 101,@(5,16,18,1)
0130 H_SCROLLBAR 102,@(5,18,45,2)
0140 H_SCROLLBAR 103,@(5,21,60,3)
0150 H_SCROLLBAR 104 WINDOW
0160 INPUT (0,HLP="H_SCROLLBAR")@(60,18),"Select...: ",'CL',X$
0170 IF CTL<101 OR CTL>104 THEN GOTO 0210
0180 H_SCROLLBAR READ CTL,VAL,MX,BJMP,SJMP
0190 H_SCROLLBAR WRITE CTL,VAL,MX
0200 PRINT @(60,19),"Selection:",CTL,":",STR(VAL),'CL',; GOTO 0160
0210 IF CTL=0 OR CTL>=3 THEN STOP ELSE GOTO 0160
Format 2 Defines at Edge: H_SCROLLBAR ctl_id WINDOW[,fileopt]

Scrollbars can appear either within the current window or at the edge of the window. Use the WINDOW
keyword to have your H_SCROLLBAR appear at the edge of the window.
Format 3 Deletes: H_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]

Use the H_SCROLLBAR REMOVE format to delete the H_SCROLLBAR.
Format 4: H_SCROLLBAR {DISABLE | ENABLE} ctl_id [,ERR=stmtref]

When you use the H_SCROLLBAR DISABLE format to gray out the H_SCROLLBAR, your user and
program have no access to it. Use the H_SCROLLBAR ENABLE format to restore the display and access.
Format 5 Sets Focus: H_SCROLLBAR GOTO ctl_id[,ERR=stmtref]

Use the H_SCROLLBAR GOTO format to set the Focus on your H_SCROLLBAR, ready for the users
next action.

Format 6: H_SCROLLBAR READ ctl_id,setting,max,[reg_chg[,arrow_chg][,ERR=stmtref]
Use the H_SCROLLBAR READ format to read the H_SCROLLBAR settings. For example, to read the
H_SCROLLBAR position relative to 1000:
0120 H_SCROLLBAR READ 100,X,1000
Format 7 Updates: H_SCROLLBAR WRITE ctl_id,marker,max[,ERR=stmtref]

Use the H_SCROLLBAR WRITE format to update or write the H_SCROLLBAR settings.
Format 8: H_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]

Use the H_SCROLLBAR HIDE format to prevent the display of the H_SCROLLBAR. (The user can't see it
or access it, even though it's still active and accessible to your programs.) Use the H_SCROLLBAR
SHOW format to restore the display and access.

HFN Highest Available LOCAL File Number
Numeric System Variable HFN
Returns: Highest available LOCAL channel number
Description:
This numeric system variable returns the highest local file number available (not OPEN). The value
returned is an integer in the range from 0 to 63 (0 to 32767 in some modes, e.g. 'XF').
Example:
->?HFN
63

HIDE Hide Control
Directive HIDE
Format:
Hide Control Object HIDE ctl_id
Where =
ctl_id Unique numeric CTL identifier for the object (BUTTON, LIST_BOX, etc.) to be
hidden. Numeric expression, integer.
Description:
Use the HIDE directive to hide your given custom control object from display. The given control must be
either for the current window or a GLOBAL control (e.g. *100). The control is still active for purposes of
reading/writing but the user cannot see, nor can the program set Focus to, the control.
To redisplay your control object, use the SHOW directive.
See also: SHOW Show Control, p. 396(d)
Example:
0010 BUTTON BTN_VISA,@(10,10,10,2)="&Visa Info"
0020 ....
0100 READ (1,KEY=CST_ID$)IOL=0110
0110 IOLIST CST_TERM$,*,*,INV_DT$
0120 GOSUB 1000
...
1000 IF CST_TERM$="VISA" THEN SHOW BTN.VISA ELSE HIDE BTN.VISA
1010 RETURN

HLP Last Specified HLP=Value
String System Variable HLP
Returns: The HLP= value from your last INPUT or OBTAIN directive
Description:
This string system variable returns a string reporting the HLP= value which was specified in the last INPUT
or OBTAIN directive. If you omitted the HLP= option, this variable returns a NULL string.
Example:
->?HLP ! (Returns NULL in this case)

HSA( ) Highest Sector Available
Function HSA( )
Format:
Highest Sector Available HSA(drive_num[,ERR=stmtref])
Where =
drive_num Numeric value representing the disc drive number.
Returns: Always 0 (zero)
Description:

ProvideX includes the HSA( ) function for compatibility with Business Basic languages where it returns the
highest sector number available on the disk drive specified. Since this function is not applicable in
ProvideX, it always returns 0 (zero).

HSH( ) Generate Hash Value
Function HSH( )
Format:
Hash Value For String HSH(string$[,init_val$][,ERR=stmtref])
Where =
string$ String expression whose hash value is to be returned.
init_val$ Initial hash value. Optional
Returns: Two-byte hash value of your string
Description:
The HSH( ) function returns a hash value for your given string. The hash value returned in a two-byte
string can be used to check the integrity of a character string. The initial value can be used to calculate the
hash value of an entire string by taking its component parts. (See the examples below.)
Example:
0010 LET A$=HSH("HELLO ")
0020 LET B$=HSH("THERE",A$)
0030 PRINT HTA(A$)," ",HTA(B$)
73DD E270
The value of B$ equals HSH("HELLO THERE")

HTA( ) Get HEX Value of String
Function HTA( )
Format:
Hex Value of String HTA(string$[,ERR=stmtref])
Where =
string$ String expression to convert to hexadecimal format.
Returns: Hex value of your string
Description:
The HTA( ) function returns the hexadecimal value of your given character string. The string returned by
the HTA( ) function is always twice the length of the original string and consists solely of the (hex)
characters 0-9 and A-F.
Examples:
0020 LET A$=HTA("CAT") ! yields 434154
0030 LET A$=HTA("01") ! yields 3031
0040 LET A$=HTA(BIN(10,2)) ! yields 000A

HWD Starting/Home Directory
String System Variable HWD
Returns: Name of home directory (i.e. directory current when ProvideX was launched)
Description:
This string system variable returns the name of the directory that was current at start up (when ProvideX
was initialized). This is considered the HOME directory.
Example:
->?HWD
C:\MANUALS\PVX

HWN( ) Highest Unused Window Number
Function HWN( )
Format:
Highest Window Number HWN(chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the terminal device for which you want the highest
unused window number (usually device (0) or the console)
Returns: Highest unused window number
Description:
The HWN( ) function returns an integer, reporting the highest unused window number for your given file.
If all window numbers are in use, this function will return -1. If your given file is not open or not a terminal,
ProvideX returns an Error #13: File access mode invalid.
You can use the window number returned by the function in a subsequent 'WINDOW' mnemonic to create
a new window. If no window number is passed to the 'WINDOW' mnemonic, it will utilize the lowest
unused window number.
The maximum number of windows allowed on a terminal device is 250.
NOTE: The HWN( ) function is affected by your setting for 'B0' Base Zero for Level / Window,
p. 539(p).

I3E( ) Convert to/from IEEE Format
Function I3E( )
Format for Conversion:
1 To Floating Point I3E(num[,ERR=stmtref])

2 To Internal Format I3E(string$[,ERR=stmtref])
Where =
num Value to convert to an 8 byte IEEE format (scientific notation). Numeric expression.
string$ 8-byte string to convert from IEEE format to a numeric value. String expression.
Returns: Numeric data, IEEE converted to/from ProvideX internal values
Description:
The I3E( ) function allows you to convert numeric data to/from IEEE floating point format, principally so that
you can convert ProvideX internal values/data to floating point format for exchange with other applications.
Format 1 From Internal Value to Floating Point: I3E(num[,ERR=stmtref])

If the function is passed a numeric expression, it will return an 8-byte string containing the IEEE floating
point value of the number.
Format 2 From Floating Point to Internal Value: I3E(string$[,ERR=stmtref])

If the function is passed an 8-byte string, the string will be converted to an internal ProvideX numeric value.
Example:
0010 ! Program to convert values to square roots, to/from scientific notation
0020 FLOATING POINT
0030 OPEN LOCK (1)"FLTDTA" ! Serial file - must be locked to read
0040 PRINT "SQR( )",@(10),"VALUE",@(27),"HTA( ) Value",@(45),"I3E( ) Value"
0050 FOR I=1 TO 5
0060 READ (1,ERR=DONE)B$
0070 !
0080 IF B$(1,1)="." THEN { ! I3E conversion in print statement
0090 PRINT "BEFORE: ",@(10),B$,@(27),HTA(B$),@(45),"Internal format"
0100 } ELSE {
0110 PRINT "BEFORE: ",@(10),"Internal format",@(27),HTA(B$),@(45),I3E(NUM(B$))
0110:}
0120 !
0130 LET A$=I3E(SQR(NUM(B$))) ! I3E conversion, square root
0140 !
0150 IF A$(1,1)="." THEN { ! I3E conversion in print statement
0160 PRINT "AFTER : ",@(10),A$,@(27),HTA(A$),@(45),"Internal format"
0170 } ELSE {
0180 PRINT "AFTER : ",@(10),"Internal format",@(27),HTA(A$),@(45),I3E(A$) }
0190 !
0200 NEXT
0210 DONE:

0220 PRINT "DONE"; CLOSE (1); STOP
-:run
SQR( ) VALUE HTA( ) Value I3E( ) Value
BEFORE: .1E+01 2E31452B3031 Internal format
AFTER : Internal format 3FF0000000000000 .1E+01
AFTER : Internal format 400A887293FD6F38 .33166247903554E+01
AFTER : Internal format 4012548EB9151E5D .45825756949558E+01
AFTER : Internal format 401645640568C1AF .556776436283E+01
AFTER : Internal format 40199CCC999FFED2 .64031242374328E+01
DONE

IF ... THEN ... ELSE Test Condition
Directive IF ... THEN ... ELSE
Format:
Define Case Logic IF expression THEN ... [ELSE ...]
Where =
expression Numeric expression to be tested for zero.
... Directives to be processed.
Description:
Use the IF directive to set conditions controlling the execution of various ProvideX statements. If the value
returned by the numeric expression is not zero (i.e. if its TRUE) then ProvideX continues execution with
the directives following the THEN clause up to the end of the statement or until an ELSE clause is
encountered. If the value returned is zero (0=FALSE) execution of the statement continues with the
directives following the ELSE clause (if you use it) or with the next statement.
You would normally include a logical operator (such as an equals sign "=", less-than symbol "<'", etc.) in
your numeric expression, but you can use any numeric expression.
See also: END Halt Execution of Program, p. 112(d)
Example 1: Simple IF
0010 INPUT "Enter a number: ",A
0020 INPUT "Enter another: ",B
0030 IF A>B THEN PRINT "First one is larger"; STOP
0040 IF B>A THEN PRINT "Second one is larger"; STOP
0050 PRINT "Both numbers are the same"
0060 STOP
-:RUN
Enter a number: 123.45
Enter another: 123.56
Second one is larger
Example 2: Compound IF Statement

0010 FOR I=1 TO 30
0020 PRINT I," is divisible by ",
0030 IF MOD(I,2)=0 THEN IF MOD(I,3)=0 THEN PRINT
0030:"both" ELSE PRINT "2" ELSE IF MOD(I,3)=0
0030: THEN PRINT "3" ELSE PRINT "neither"
0040 NEXT I
0050 STOP
RUN
1 is divisible by neither
2 is divisible by 2
3 is divisible by 3
4 is divisible by 2
...
28 is divisible by 2
29 is divisible by neither
30 is divisible by both

Example 3: Multi-Line IF Statement
In the example below, A and B are compared if G<>Z. Note that the curly braces and spaces are "real"
(i.e. part of the syntax).
0010 IF A=B THEN {
0020 LET C=D
0030 LET E=F
0040 IF G=Z THEN STOP ! Note: you cant use BREAK in a block-style IF (V. 4.20)
0050 GOSUB SOMEWHERE
0060 } ELSE { PRINT "They are not the same" }
0070 !
0080 STOP
1000 SOMEWHERE: PRINT "They are the same"
1010 RETURN
-:BEGIN
-:RUN
Since G=Z=0 above (because of the BEGIN directive), the application stops at line 0040 unless values are
assigned. Setting the value of G to 1 (Z=0) produces the result below (since A=B=0):
-:G=1
-:?Z
-:0
-:RUN
They are the same
Setting A to a different value from B (which=0) has the following result:
-:A=2
-:RUN
They are not the same
-:

IND( ) Return Next Record Index
Function IND( )
Format:
Return Next Record Index IND(chan[,fileopt])
Where =
chan Channel or logical file number of the file to reference.
fileopts File options. Valid options for IND( ) include:
ERR=stmtref - Error Transfer
END=stmtref - End-of-file transfer
KEY=key - Record key value
RNO=rec_num - Record number
Returns: Record index (next or specified record)
Description:
The IND( ) function returns the record index of either the next record in your given file or, if you use a
DIRECT or KEYED file with the KEY= option, the record index for the record you identify in the option.
For DIRECT, KEYED, or SORT files without the KEY= option, the value returned is the record index for the
record with the next higher key value.
For variable length DIRECT/KEYED files, the value returned is the (logical block address of the record
number in the block) times 256.
See also: File Handling
Example:
KEYED "PVX_KEYD",[1:1:6],[2:1:10],,128 contains the following indices and data:
Key '123456' (Index=0) 1) 123456+SEP+ABC M ... etc.
Key '123457' (Index=2) 1) 123457+SEP+ABC C ... etc.
Key '123458' (Index=1) 1) 123458+SEP+VIPCO ... etc.
Key '123459' (Index=20) 1) 123459+SEP+NEW C ... etc.
Key '123460' (Index=21) 1) 123460+SEP+ACME ... etc.
Key '123461' (Index=22) 1) 123461+SEP+A1 MF ... etc.
Results of printing each records IND( ) value and first data field:
0010 OPEN (13)"pvx_keyd"
0020 LET I=IND(13,END=1000)
0030 READ (13,IND=I)R$
0040 PRINT "Rec#: ",I," Data: ",R$
0050 GOTO 0020
1000 PRINT "End-of-file"
1010 END
-:RUN
Rec#: 0 Data: 123456
Rec#: 2 Data: 123457
Rec#: 1 Data: 123458
Rec#: 20 Data: 123459
Rec#: 21 Data: 123460

Rec#: 22 Data: 123461
End-of-file
The result when you print the indices of an INDEXED file is a sequential list:
-:run
Rec#: 0 Data:
Rec#: 1 Data: 123456
Rec#: 2 Data: 123457
Rec#: 3 Data: 123458
Rec#: 4 Data: 123459
Rec#: 5 Data: 123460
Rec#: 6 Data: 123461
End-of-file

INDEXED Create File Access by Record Number
Directive INDEXED
Format:
Create Indexed File INDEXED filename$,[max_rec],max_datasize[,ERR=stmtref][,SEP=char$]
Where =
filename$ Name of the INDEXED file to create. String expression.
max_rec Estimated maximum number of records that the file is to contain. Default is no initial
allocation of file space, with no limit as to final size.
max_datasize Maximum size of the data portion of the record.
char$ Character to use as default separator. String expression.
Description:
Use the INDEXED directive to create an INDEXED file. You can access the records in the INDEXED file
either sequentially or by record number (index).
Make your record size long enough to contain the maximum record length (i.e. the combined length of the
data fields youll be writing to the longest record in the file). If you use a filename that already exists,
ProvideX returns an Error #12: File does not exist (or already exists).
You can use the SEP= option to set the default separator to use for your given file. You can use any
character from $00$ to $FF$, or you can use SEP=*. If you use the asterisk as your value, the fields will
not be delimited. ProvideX will write records to the file with field type and length headers. You can use this
feature for better results in overall file performance.
NOTE: This directive is not currently supported by WindX. When you need to create files on
a WindX PC, encapsulate your command in an EXECUTE "[WDX]..." directive. See
[WDX] Tag: Directs Action to Client Machine, p. 626.
Examples:
0110 INDEXED A$+""+B$,100,50,ERR=1090
0200 INDEXED "CSTFLE",,140
Line 0200 creates a file with the following structure:
Indexed file: C:\OTHER\MANUALS\PVX\CST\CSTFLE

INPUT Get Input from Terminal
Directive INPUT
Format:
Get Input from Terminal INPUT [EDIT] (chan[,fileopt])varlist
Where =
chan Channel or logical file number of the file from which to get terminal input.
fileopt File options. Valid options for INPUT include:
HLP=string$ Associated help id
IND=col Position cursor to specified column.
LEN=num Limit on input size
SIZ=max_read Maximum characters to read (number of screen columns)
TIM=max_wait Maximum time-out value
When screen positions are tight, you can combine the LEN= and SIZ= options to
have ProvideX supply a scrolling input field. For example, to allow a user to enter 60
characters in a field where you only have room for 30 on the screen, you can use:
INPUT (0,LEN=60,SIZ=30)"Name....:",N$
'@(...)'. Items in the list must be comma-separated.
Description:
Use the INPUT directive to issue prompts to terminal devices and to process responses (the users input).
You would normally use the logical file number to refer to a terminal. ProvideX treats any literals or
expressions you include in the directive as prompts.
If you use the EDIT clause, the current values for the variables are loaded into the input buffer so that the
user can edit them.
You can use a format mask with the INPUT directive to control the input. To do this, append a colon and
the mask to your given variable in the varlist. If you omit a format mask for a numeric in your INPUT
statement, the DP and TH system parameters for European decimal settings are ignored.
If your INPUT EDIT statement has both a format mask and a validation list, make sure that the validation
list contains only entries that are possible. For example, if your format mask indicates that the input value
must be a single character, dont use a NULL ("") value in the validation list. Instead, valid input for "no
value" could be a blank / space in this instance, as in:
0030 INPUT EDIT (0,ERR=0030)@(10,10),VAR$:"A":("Y"=0040,"N"=0050," "=0060)
Use the IND= option to set the position of the cursor in the INPUT field. Use IND(chan) to obtain the
position where the cursor was left after the INPUT.
See also: OBTAIN Get Hidden Terminal Input, p. 293(d)
'ME' Begin Edit_Mode, p. 518(m)
'BI' Begin Input_Transparency, p. 494(m)

Examples:
0010 INPUT 'CS',@(5,5),"Enter customer number:",C
...
0100 INPUT EDIT "Enter value:",INV_AMT:"$##,##0.00"
You can use IND=X as a parameter for the INPUT statement to set the starting point in an input field. For
example, to start the input at the tenth character of A$:
-> A$="Now is the time"
-> INPUT EDIT (0,IND=10) A$
You can use IND(0) to find out the character position where the user terminated input. For example, if the
user enters "Now is the time", and presses <Home> and <Tab> the cursor moves to the 10th position, just
after the "e" in "the". Then, if the user presses <Enter> or any other function key to terminate the input, the
value returned in IND(0) is 10.

INT( ) Return Integer
Function INT( )
Format:
Return Integer Portion INT(num[,ERR=stmtref])
Where =
num Numeric expression whose integer portion is to be returned.
Returns: Integer portion of numeric value
Description:
The INT( ) function returns the integer portion of your numeric expression. No rounding is performed on
the value. The fractional part of the value is just dropped.
The maximum value that can be processed by the INT( ) function is 1,000,000,000,000,000. If this value is
exceeded, ProvideX returns an Error #41: Invalid integer encountered (range error or
non-integer).
Examples:
A=INT(3.23) ! yields A=3
A=INT(-5.6) ! yields A=-5
A=INT(.9999) ! yields A=0

INVOKE Execute Operating System Command
Directive INVOKE
Format:
1 Invoke INVOKE command$[,ERR=stmtref]

2 Minimize (In WINDOWS) INVOKE HIDE task$[,ERR=stmtref]
3 Wait (In WINDOWS) INVOKE WAIT task$[,ERR=stmtref]
Where =
" (initial quote) In COMMAND mode, if you use an initial quotation mark at the beginning of a line
ProvideX interprets the statement as an INVOKE directive.
command$ String expression to be passed to the Operating System command processor for
execution.
task$ WINDOWS task. String expression.
Description:
Use the INVOKE directive to have the Operating System treat a character string from your program as a
command from the terminal. The INVOKE directive gives you access to most Operating System utilities
and facilities from within a ProvideX program.
NOTE: In WINDOWS, to accommodate the way WINDOWS searches for programs and
determines the type of program to run, we recommend that you identify the type of
file in your command line (e.g. "XCOPY.EXE" or "MYJOB.BAT").
ALSO: Under WindX, you can use INVOKE "[WDX]...". (See [WDX] Tag: Directs Action to
Client Machine, p. 626.)
TIP: Use the SYS( ) function instead of the INVOKE directive if you wish to test the
successful conclusion of an Operating System command.
(If you are not concerned about the return status of a command and are running
under UNIX and DOS, there is no difference between using an INVOKE directive and
the SYS( ) function. When you use the SYS( ) function under WINDOWS, ProvideX
waits for the spawned task to complete or for the user to reactivate your program by
using the mouse. When you use the INVOKE directive under WINDOWS, ProvideX
spawns the task and continues without waiting for the task to complete. You can use
an INVOKE WAIT directive if you wish to wait for the task (same as the SYS function).
You can also use an INVOKE HIDE directive which will spawn a task in a minimized
window.)
See also: SYS( ) Invoke Operating System Command, p. 415(f)
Format 1: INVOKE command$[, ERR=stmtref]

In EXECUTION mode, you can generate and pass a character string from your program to the Operating
System. In COMMAND mode, entering a line of code that starts with a quotation mark (i.e. "statement"[,
ERR=stmtref]) is the same as using the word INVOKE to start the directive.
The Operating System processes your statement as if it were entered as a command from the terminal. If
an error occurs during the execution of the character string:

you can obtain the error code(s) from the RET and ERR system variables, and
if you use an ERR= option, control transfers to your specified statement reference.
Example in EXECUTION Mode:

0010 INVOKE "COMMAND.COM /K DIR C:\WINDOWS"
Note that some DOS commands (such as COPY and DIR) are built-into COMMAND.COM and can be
called using this type of statement.
Background Tasking in ProvideX:

You can use INVOKE to start a background process in ProvideX.
Under UNIX, output generated by the O/S command may result in strange display behaviour. In particular,
ProvideX will not know where the cursor is, nor be able to restore the screen if a window is pushed /
popped. This is because the output from the O/S command is not intercepted by ProvideX and is therefore
unknown to it.
When you INVOKE another copy of ProvideX under UNIX, we recommend that you also redirect stdin,
stdout, and stderr to null files. For example:
INVOKE ARG(0)+"program >/dev/null >2/dev/null </dev/null"
NOTE: Arg(0) returns the name of the 'pvx' executive as entered in the original command
line. Please make sure that this is an absolute pathname or that pvx can be found in
the system PATH search rules.
Format 2 (In Windows): INVOKE HIDE task$ [, ERR=stmtref]

In WINDOWS modes, you can use the INVOKE HIDE format to have your task minimized when it starts.
Format 3 (In Windows): INVOKE WAIT task$ [, ERR=stmtref]

Also in WINDOWS modes, you can use the INVOKE WAIT format to have your ProvideX session wait until
the application terminates or the user manually reactivates your task.

IOL( ) Get IOLIST Specification
Function IOL( )
Format: Get Value
1 In Composite String IOL(composite$[,ERR=stmtref])

2 In Open File IOL(chan[,ERR=stmtref])
Where =
composite$ Composite string variable whose IOLIST is to be retrieved. String expression.
chan Channel or logical file number whose default IOLIST is to be returned.
Returns: Object value of an IOLIST or composite string variable
Description:
The IOL( ) function returns the object code value of an IOLIST for either an open file or a composite string
variable. If the specified file or string variable does not have an associated IOLIST, ProvideX returns an
Error #81: Invalid IOLIST specification. .
Syntax Returns
IOL(nnn:*) Returns the IOLIST for the file's embedded Data Dictionary
IOL(nnn:KEY) Returns the IOLIST for the file's external key, if any.
IOL(X:^) Returns the alternate IOLIST
NOTE: To convert the object code into a format you can display, pass it to the LST( )
function.
Examples:
0100 DIM CUST$:IOL=0110
0110 IOLIST NAME$,ADR1$,ADR2$,SMAN$
0120 PRINT LST(IOL(CUST$))
-:run
IOLIST NAME$,ADR1$,ADR2$,SMAN$
For cases like the example below, ProvideX returns an Error #84: No DICTIONARY exists on
OPENed file if you havent predefined an associated internal IOLIST for your file.
0130 OPEN (1,IOL=*)"CUSTDB" ! Open with internal IOL
0140 PRINT LST(IOL(1))

IOLIST Specify Variable List
Directive IOLIST
Format:
1 Define List IOLIST {expression[:[format]]...}

2 Define Delimiter IOLIST SEP=char$
Where =
expression Set of parameters to be used in an input/output directive. The parameters can
include variables, expressions, mnemonics, @(...) functions, an IOL=option, and/or
literals.
format Defines how the field is formatted. Options include:
CHR(len) Variable length string (pad output)
CHR(dlm) Variable length string (delimited). As of Ver. 4.20, the default
record limit has increased to 10240 for composite IOLISTs with the CHR
field definition. (Prior versions: limit was 4096.)
LEN(len) Fixed length string
STR(dlm) Quoted String
NUM(len[,scl][SEP=char$]) Fixed length numeric. Optional SEP=clause
(Ver. 4.20) allows for padded numerical fields followed by a field
separator. Note that NUM fields are padded with leading zeroes.
BIN(len[,scl]) Binary numeric
INT(len[,scl]) Unsigned integer numeric
BCD(len[,scl]) Packed decimal numeric
Where:
len is the length of the field in the record
dlm is a string whose first character delimits the field
scl is the optional scaling factor to apply to the number (e.g., 2 indicates that
1.34 is output as 134)
char$ The separator. The SEP= option will change the field separator for your given file. All
subsequent fields will use your newly defined field separator. String expression.
Description:
Use the IOLIST directive to define a common I/O parameter list. ProvideX ignores the IOLIST directive
when it encounters it during program execution until it is used in conjunction with file I/O directives (e.g.
READ, WRITE, etc.) and composite string definitions. For more information, see File Handling.
NOTE: The IOLIST must be the only directive in a statement.
Example:
0010 OPEN (20)"CSTFLE"
0020 READ (20,KEY=C$)IOL=1000
0030 LET J=J+10
0040 WRITE (20,KEY=C$)IOL=1000
0050 WRITE (21)IOL=1010
...
1000 IOLIST C$,C1$,C2$,C3$,J,K,L,M
1010 IOLIST C$:[CHR(10)],C1$:[CHR(40)]

IOR( ) 'OR' Strings
Function IOR( )
Format:
OR Comparison IOR(initial$,compare$[,ERR=stmtref])
Where =
initial$ Initial string value. String expression.
compare String value to compare with the initial string value using 'OR'. Its length must match
that of the initial string. String expression.
Returns: String, result of bit-wise logical OR comparison
Description:
The IOR( ) function performs a bit-wise logical OR comparison of two strings and returns the string
generated as a result. The length of the two strings must be equal or ProvideX returns an Error #26:
Variable type invalid.
Binary Result
0 IOR 0 0
1 IOR 0 1
0 IOR 1 1
1 IOR 1 1
For Instance:
0100 PRINT IOR($41$,$42$)," ",HTA(IOR($41$,$42$))," ",
yields C,$43$ (binary 01000011)
0110 PRINT IOR($41$,$25$)," ",HTA(IOR($41$,$25$))," ",
yields e, $65$ (binary 01100101)
0120 PRINT ASC(IOR($5A$,$DD$))," ",HTA(IOR($5A$,$DD$))
yields 223 (extended character),$DF$ (binary 11011111)
-:run
C 43 e 65 223 DF
Example:
0040 READ (1,END=1000)F$
0050 R$=IOR(F$(1,2),$8080$) ! Turn on high bit
0060 ...

JUL( ) Return Julian Date
Function JUL( )
Format:
1 Julian from Numeric JUL(year,month,day[,ERR=stmtref])

2 Julian from Day Format JUL(date_string$[,ERR=stmtref])
Where =
year Numeric expression of the year. Use 0 (zero) for the current year. If your value is
less than 100, the current century is added to the value.
month Numeric expression of the month. Use 0 (zero) for the current month.
day Numeric expression of the day of the month. Use 0 (zero) for the current day.
date_string$ String in the same DAY_FORMAT as the DAY variable. String expression.
Returns: Julian date (converted from year, month, day)
Description:
The JUL( ) function is used to convert a date from year, month, day to a Julian date. The Julian date is the
an integer: the number of days since the system base-date. By default, in ProvideX this is January 1,
1970. You can use the 'BY' system parameter to change the base date.
Historically the true Julian calendar starts sometime around 4713 BC., but because of errors in early
calendars, dates prior to 1200 are not reliable. If you want the JUL( ) function to return dates based
roughly on the Julian calendar, set the 'BY' system parameter to 0 (zero).
See also: 'BY'=num Base Year, p. 540(p)
Example:
0020 LET M=NUM(X$(1,2))
0030 LET D=NUM(X$(3,2))
0040 LET Y=NUM(X$(5,2))
0060 PRINT "That is ",N-JUL(0,0,0)," days from now"
0070 STOP
0100 PRINT "Invalid date"; GOTO 0010
-:RUN
That is 23 days from now
-:
The JUL( ) function accepts a valid DAY string and returns the corresponding Julian date (Ver. 4.02). For
example:
X$="01/01/A0"
DAY_FORMAT "MM/DD/AA"
PRINT JUL(X$)
10957
PRINT DTE(10957:"%Y %Ml %D")
2000 January 1
See also: DAY_FORMAT Specify DAY Format, p. 68(d),

DAY Return Current System Date, p. 67(v)

KEC( ) Return Key of Current Record
Function KEC( )
Format:
Return Current Key KEC(chan[,fileopt])
Where =
chan Channel or logical file number of your given file.
fileopt File options. Valid options for KEC( ) include:
Returns: Current key or current logical position in file
Description:
The KEC( ) function returns the current records key based on:
the current access key_number or,
your given key_number if you use the KNO= option. (For a non-existent key, the function returns
the key_number to report the current logical position in your given file.)
Example 1:
KEYED "PVX_KEYD",[1:1:6],[2:1:10],,128 has 2 internal alternate keys, 0 [1:1:6] and 1
[2:1:10]. Key 0 (zero) is treated as the primary key (external). The following data is in the file:
Key '123456' 123456,ABC MFG,213 ANY ST ... etc.
Key '123457' 123457,ABC CO,956 NEW AV ... etc.
Key '123458' 123458,VIPCO,1 MAIN ST ... etc.
Key '123459' 123459,NEW CO,8920 WIDE DR ... etc.
Key '123460' 123460,ACME CO,2000 1ST ST ... etc.
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEC( ) values (for current/primary key and alternate keys 0 and 1 re: the record just read):
0100 IOLIST CUST$,NAME$,ADDR$
0210 OPEN (2)"PVX_KEYD"
0220 READ (2)IOL=0100
0280 LET C$=KEC(2); PRINT "KEC=",C$
0290 LET C0$=KEC(2,KNO=0); PRINT "KEC=",C0$
0300 LET C1$=KEC(2,KNO=1); PRINT "KEC=",C1$
-:END
-:RUN
KEC=123456
KEC=123456
KEC=ABC MFG
If you specify a non-existent key in your KNO= option, ProvideX returns that given key to report your
current logical position in the file. (For instance, if the example above included KNO=12, the KEC( )
function would return 12.) You can use the KEC( ) function to validate current position in the file. Typically,
the KEC( ) function is used after you READ a record, to determine the key of the record you just read (i.e.
the key of the current record or current position in the file).

KEF( ) Return First Key of File
Function KEF( )
Format:
Key of First Record KEF(chan[,fileopt])
Where =
fileopt File options. Valid options for KEF( ) include:
END=stmtref Empty file transfer
Returns: Key of first record in file
Description:
The KEF( ) function returns the key of the first record in your given file. It will return the key of the first
record based on:
your given key_number if you use the KNO= option.
The KEF( ) function can also be used in TCP (Transmission Control Protocol) to identify local sockets.
Example:
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEF( ) values (for current/primary key and alternate keys 0 and 1):
0220 READ (2)IOL=0100
0280 LET F$=KEF(2); PRINT "KEF=",F$
0290 LET F0$=KEF(2,KNO=0); PRINT "KEF=",F0$
0300 LET F1$=KEF(2,KNO=1); PRINT "KEF=",F1$
-:begin
-:run
KEF=123456
KEF=123456
KEF=A1 MFG ! (alph. ascending order)

KEL( ) Return Last Key of File
Function KEL( )
Format:
Return Last Key KEL(chan[,fileopt])
Where =
fileopt File options. Valid options for KEL( ) include:
END=stmtref Empty file transfer
Returns: Key of last record in file
Description:
The KEL( ) function returns the key of the last record in your given file. It will return the key of the last
record based on:
the current access key_number, or,
your specified key_number if you use the KNO= option.
NOTE: ProvideX supports the KEL( ) function for ODBC files. See also: File Handling
Example:
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEL( ) values (for current/primary key and alternate keys 0 and 1):
0220 READ (2)IOL=0100
0280 LET L$=KEL(2); PRINT "KEL=",L$
0290 LET L0$=KEL(2,KNO=0); PRINT "KEL=",L0$
0300 LET L1$=KEL(2,KNO=1); PRINT "KEL=",L1$
-:BEGIN
-:RUN
KEL=123461
KEL=123461
KEL=VIPCO ! (alph. ascending order)

KEN( ) Key of Record After Next
Function KEN( )
Format:
Return Key After Next KEN(chan[,fileopt])
Where =
fileopt File options. Valid options for KEN( ) include:
END=stmtref End-of-file transfer
Returns: Key of the record that follows your next record in the file
Description:
The KEN( ) function returns the key of the record which directly follows the next record in your given file. It
will return the key of the record after next based on:
your specified key_number if you use the KNO= option.
If you omit your ERR= option, ProvideX reports an Error #2: END-OF-FILE on read or File
full on write when the end of the file is reached.
For ODBC FILES, the KEN( ) function supports some debugging tools:
KEN (nn) Returns last generated SQL statement passed to the ODBC driver
KEN (nn, IND=1) Returns CURSOR name for Database
KEN (nn, IND=2) Returns ODBC handles
Example 1:
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEN( ) values (for current/primary key and alternate keys 0 and 1):
0220 READ (2,END=0330)IOL=0100
0280 LET N$=KEN(2,ERR=0320); PRINT " KEN=",N$
0290 LET N0$=KEN(2,KNO=0,ERR=0320); PRINT " KEN=",N0$
0300 LET N1$=KEN(2,KNO=1,ERR=0320); PRINT " KEN=",N1$
0320 STOP
-:begin
-:run

KEN=123458
KEN=123458
KEN=NEW CO ! (alph. ascending order: with ABC MFG as current record)
Example 2:
0010 OPEN (13)"INVDET"
0020 K$=KEY(13,END=1000)
0030 REM Last record is total line - different format
0040 KN$=KEN(13,END=0080); IF KN$(1,6)<>K$(1,6) GOTO 0080
0050 READ (13)IOL=8010 ! Get record
0060 GOSUB 7000 ! Process invoice line
0070 GOTO 0020
0080 READ (13)IOL=8010 ! Get total line
0090 GOSUB 7500; GOTO 0020
1000 END
Example 3:
To return the current ODBC SQL statement being passed to the ODBC driver:
OPEN (1) "[odb]Database;customer;key=custid"
READ (1,KEY="MIKE")
PRINT KEN(1)
SELECT * FROM customer WHERE custid = 'MIKE'

KEP( ) Return Key of Prior Record
Function KEP( )
Format:
Return Prior Records Key KEP(chan[,fileopt])
Where =
fileopt File options. Valid options for KEP( ) include:
Returns: Key of the prior record in file
Description:
The KEP( ) function returns the key of the record prior to your current record in your given file. It will return
the key of the prior record based on:
if you use the KNO= option, the key_number you specify.
If the current record is at the start of the file, there is no prior record. ProvideX reports an Error #2:
END-OF-FILE on read or File full on write unless you include an ERR= option.
NOTE: ProvideX supports the KEP ( ) function for ODBC files. See also: File Handling
Example 1:
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEP( ) values (for current/primary key and alternate keys 0 and 1):
0030 LET K$=KEY(2)
0040 REM Start of file: key=123456, no KEP( )
0050 LET K$="123460"; PRINT "SET CURRENT KEY=123460"
0060 READ (2,KEY=K$,END=0100)IOL=0010
0070 LET P$=KEP(2,ERR=0100); PRINT " KEP=",P$
0080 LET P0$=KEP(2,KNO=0,ERR=0100); PRINT " KEP=",P0$
0090 LET P1$=KEP(2,KNO=1,ERR=0100); PRINT " KEP=",P1$
0100 STOP
-:END
-:RUN
SET CURRENT KEY=123460
KEP=123459

KEP=123459
KEP=ABC MFG ! (alph. descending order: with ACME CO as current record key)
Example 2:
0010 OPEN (13)"CUSTNO"
0020 READ (13,KEY="zzz",DOM=30) ! Go to End of file
0030 LET K$=KEP(13,END=1000)
0040 READ (13,KEY=K$)R$
0050 PRINT "Key: ",K$," Data: ",R$
0060 GOTO 0030
1000 PRINT "Back to the start"
1010 END

KEY( ) Return Key of Next Record
Function KEY( )
Format:
Return Key of Next Record KEY(chan[,fileopt])
Where =
fileopt File options. Valid options for KEY( ) include:
ERR=stmtref Error Transfer
IND=num Record index
Returns: Key of next record in file
Description:
The KEY( ) function returns the key of either the next record in your given file or, if you use the IND= or
RNO= options, the key of the record at the index/record number you specify. It will return the key based
on:
if you use the KNO= option, the key_number you specify.
Example 1:
Key '123460' Index=21 123460,ACME CO,2000 1ST ST ... etc.
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KEY( ) values - for current/primary key (at current record and at IND=21) and for alternate
keys 0 and 1:
0030 READ (2,END=0080)IOL=0010
0040 LET Y$=KEY(2,ERR=0080); PRINT " KEY=",Y$
0050 LET Y$=KEY(2,IND=21,ERR=0080); PRINT " KEY=",Y$
0060 LET Y0$=KEY(2,KNO=0,ERR=0080); PRINT " KEY=",Y0$
0070 LET Y1$=KEY(2,KNO=1,ERR=0080); PRINT " KEY=",Y1$
-:run
KEY=123457
KEY=123460
KEY=123457
KEY=ACME

Example 2:
0010 OPEN (13)"CUSTNO"
0020 LET K$=KEY(13,END=1000)
0030 READ (13,KEY=K$)R$
0040 PRINT "Key: ",K$," Data: ",R$
0050 GOTO 0020
1010 END

KEYED Create Single/Multi-Keyed File
Directive KEYED
Format:
Create Keyed File KEYED filename$,[,extkey_len][,key_def$][,max_rec[,max_datasize]]

--> (continued) [,BSZ=key_bsz][,ERR=stmtref][,SEP=char$]
Where =
filename$ Name of the KEYED file to create. String expression.
key_def$ String expression defining the key. Your KEYED file can be single- or multi-keyed. A
key definition is made up of one or more key field definitions (range 0 to 15). Use
integers for specific field numbers, or 0 (zero) for the complete record.
Key Definition Formats:

1 Single key field [field:offset:len[:"attr_char"] ]
2 Composite key fields (using the + operator):
[field:offset:len[:"attr_char"] ]+[field:offset:len[:"attr_char"] ]
3 Multi-keyed alternate key fields are comma-delimited:
[field:offset:len[:"attr_char"] ],[field:offset:len[:"attr_char"] ]
Where:
field = field number (integer, 0 to number of fields)
offset = the starting position within the field (integer, 1 to 2047)
len = length, number of characters in the key field (integer)
attr_char$ = one or more valid Key Definition Attributes, p. 213
: (colon) = the separator for elements in a key segment
Note that the outer square brackets in the formats are real (i.e. part of the syntax); the
inner brackets are not (i.e. the brackets enclosing the optional [:attr_char$] are not
extkey_len Numeric expression. Length of the external key for all records in the file.
max_rec Maximum number of records the file is allowed. Numeric expression. The default is
zero (no limit). (Use a comma with no value to set the default.)
If you supply a positive value for max_rec, ProvideX will create the file and pre-
allocate disk space for the file. If you use a negative value, ProvideX will allocate
sufficient disk space for the file, but will set the max_rec count back to zero
(unlimited).
max_datasize Maximum size of the data portion of the record (excluding the key). If you use a
negative value, ProvideX creates a variable-length record data file with the maximum
record length equal to the positive value of this field. If you don't specify size, the
default is variable-length records with a maximum record size of 256.
key_bsz Size of the Key Block in Kb. Numeric expression 1,2,4,8,16,32.
char$ Character to use as default field SEParator. Optional.
Description:
Use the KEYED directive to create a file with one or more keys.

If the first field in your directive after the filename is a number, ProvideX creates an external file key (i.e. an
index to the file). If the first field in your directive is a key definition enclosed in square brackets [ ], then
ProvideX uses only internal key fields instead.
ProvideX considers the first key you specify for your KEYED file to be the primary key. Every record must
have a unique primary key. You can have duplicate secondary keys from record to record. You can use a
maximum of 16 keys in your given file. Each of these key fields can be composed of up to 96 data
components. There is no limit to the number of fields you can include in a key.
If your given file name already exists, ProvideX returns an Error #12: File does not exist (or
already exists).
You can use the SEP= option to set the default separator to use for your given file. You can use any
character from $00$ to $FF$, or you can use SEP=*. If you use the asterisk as your value, the fields will
not be delimited. ProvideX will write records to the file with field type and length headers. You can use this
feature for better results in overall file performance.
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag, e.g., KEYED
See also: DIRECT Create File with Keyed Access, p. 88(d) and Multi-Keyed Files.
If you see the message Corrected Missing Key when ProvideX attempts to remove or rewrite a
record in a KEYED file where a change to the primary or alternate key table is needed (e.g. for an alternate
key to a customer name when the name changes or for removal of all keys when a record is deleted), the
message indicates that the key entry to be changed was not found. This is not a fatal message, but
usually means that the file has been corrupted in some way. You should check the file using *UFAC or try
to recover it using *UFAR (ProvideX utilities).
Example:
This example defines a KEYED file in a variable. Instead of:
01000 KEYED "workfile",[1:1:3]+[2:1:6],[3:1:30],0,0
it is possible to use:
01010 keydef$="[1:1:3]+[2:1:6],[3:1:30]"
01015 KEYED "workfile",keydef$,0,0
This circumvents using an EXECUTE.
Key Block Size and Performance

ProvideX uses the size of the primary key to determine the optimum key block size. Key blocks are stored
in even Kb increments ranging from 1 to 4 Kb. You can calculate the actual size of the key block by taking
the (size of the primary key + 5 bytes) multiplied by a maximum of 255 entries. The calculation is rounded
up to the nearest Kb to a maximum of 4Kb. You can use a BSZ= option to override the key block size.
Setting BSZ=1 can improve performance on WANs (Wide Area Networks) by reducing the overall network
traffic when accessing KEYED files.
NOTE: As of Ver. 4.20, you no longer have to use ,BSZ= in KEYED file definition if defining
record sizes over 4000 bytes. ProvideX now calculates the minimum block size
necessary.

Attr_char$ Key Definition Attributes
NOTE: Optional. As of Ver. 4.20, if you do include attr_char$, you can use one or a
combination of the valid attributes below to refine your key segment definitions.
Example:
KEYED "MES_FACTURES",[1:1:40:"T"],[2:1:40:"TCD"]
"D" Descending order (default is ascending).
"C" (Ver. 4.20) Force uppercase for individual key segments to create case-insensitive keys.
For example:
KEYED "filename",[1:1:10:"C"],[2:1:40:"L"]+[1:1:10:"C"]
NOTE: The conversion tables for upper- and-lower case conversions are
located in the ProvideX message file *MLFILE.EN. You can set these
tables using the DEF UCS and DEF LCS directives and retrieve values
using the UCS(*) and LCS(*) functions.
"L" (Ver. 4.20) Force lowercase for individual key segments to create case-insensitive keys.
See the example and note in "C", above.
"T" (Ver. 4.20) Force automatic accent translation for individual key segments (i.e. to
translate accented/extended characters to their non-accented counterparts). Youll find
this useful for sorting multilingual characters into a single unified sort sequence.
Example:
KEYED "filename",[1:1:40:"T"],[2:1:40:"TCD"]
NOTE: The conversion tables for accent translations are located in the
ProvideX message file *MLFILE.EN. You can set this table using the
DEF CVS directive and retrieve values using the CVS(*) function.
"U" (Ver. 4.20) If you declare an alternate key segment as unique, then no duplicate keys are
allowed on writing a record. (ProvideX generates an Error #11: Record not found
or Duplicate key on write.) If you designate any segment in a key definition as
unique, then the entire key will be unique.
NOTE: The primary key must always be unique.
See also: DEF CVS / DTE / LCS / UCS Define System Tables, p. 70(d)
Examples:
KEYED A$+"_"+B$,10,100,50,ERR=1090 creates a keyed file with the following structure:

Maximum # records ............: 100
KEYED "CSTFLE1",6,,140 also creates a file with an external primary key (6 bytes)
KEYED "CSTFLE2",6,[1:1:10],,500 creates a file with an external primary key (6 bytes) and a single
internal alternate key.
KEYED "CSTFLE3",[1:1:6],[2:1:10],,500 creates a multi-keyed file with 2 internal alternate keys.
Here, ProvideX treats alternate key 0 (field 1) as the primary external key.
Keyed file: C:\OTHER\MANUALS\PVX\CST\CSTFLE3

Alt. key 0 ...................: [1:1:6]
Alt. key 1 ...................: [2:1:10]
KEYED "CSTFLE4",6,[2:1:10]+[1:1:6] creates a file with an external primary key (field 1, 6 bytes),
and a composite internal alternate key:
Keyed file: C:\OTHER\MANUALS\PVX\CST\CSTFLE4
Maximum Record size ..........: 256 (Variable)
Record Expansion factor ......: 10%
Alt. key 1 ...................: [2:1:10]+[1:1:6]
To use a variable for the key definition:
X$="[1:1:6],[2:1:10]"; KEYED "CSTFLE",X$,,500
X$="6,[1:1:6],[2:1:10]"; KEYED "CSTFLE",X$,,500

KGN( ) Generate Record Key
Function KGN( )
Format:
Generate Record Key KGN([ext_key$],data$,key_def$,key_num[,ERR=stmtref])
Where =
ext_key$ Value of the external key. Optional. String expression.
data$ Contents of the data record. String expression.
key_def$ Key definition structure. String expression. (This can be extracted using the FID( )
function starting at position 85.)
key_num Key number (primary or an alternate key) to extract. Numeric expression.
Returns: Key of record in file, given the records contents
Description:
The KGN( ) function generates the key of the record you identify using a string of its data contents. You
can use this function to obtain the value of an alternate (or primary) key for a record, given the record's
contents (and external key, if present).
ProvideX uses your value in key_num to determine the key number for which you want a record key
generated. If your numeric expression exceeds the existing number of alternate keys in your given file,
ProvideX returns an Error #41: Invalid integer encountered (range error or non-
integer). All fields defined as descending will have all bits inverted if your key_num value is less than
zero (or greater than 256). In this case, the internal value of the corresponding positive key (or key less
256) will be returned.
Example:
Key '123461' 123461,A1 MFG,6 2ND ST ... etc.
Print sample KGN( ) values:
0010 OPEN (13)"pvx_keyd"; LET X$=FIB(13)
0020 LET K$=KEY(13,END=1000)
0030 READ RECORD (13,KEY=K$)R$
0040 PRINT "Key: ",K$," Alt 1: ",KGN(K$,R$,X$(85),1)
0050 GOTO 0020
1010 END
-:end
-:run
Key: 123456 Alt 1: ABC MFG
Key: 123457 Alt 1: ABC CO
Key: 123458 Alt 1: VIPCO
Key: 123459 Alt 1: NEW CO

Key: 123460 Alt 1: ACME
Key: 123461 Alt 1: A1 MFG
End-of-file

LCS( ) Return Lower Case String
Function LCS( )
Format:
Convert to Lowercase LCS(string$[,ERR=stmtref])
Where =
string$ String expression whose lower case ASCII counterpart is to be returned.
Returns: Lowercase counterpart of string
Description:
The LCS( ) function returns the lower case counterpart of your original string (with all upper case
alphabetic characters replaced by their corresponding lower case characters).
See also: UCS( ) Return Upper Case String, p. 443(f)
Example:
0010 INPUT "Enter name: ",NAME$
0020 LET NAME$(2)=LCS(NAME$(2))
0030 LET NAME$(1,1)=UCS(NAME$(1,1))
0040 PRINT "Name is",@(10),": ",NAME$
-:RUN
Enter name: SMITH
Name is : Smith
NOTE: If you use an asterisk "*" instead of a string, i.e. LCS(*), the function returns the 256
byte Lowercase Conversion Table. The printable characters start at position 33, so
PRINT A$(33) will display the results. See the example below.
Example:
A$=LCS(*)
Note that if you try to print the entire LCS table (i.e., in this case, PRINT A$), ProvideX returns an Error
#29: Invalid Mnemonic or position specification, since the first part of the table contains
unprintable keystrokes (e.g. <Esc> key character $1B$, etc.)
-:?HTA(A$)
000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627
28292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F406162636465666768696A6B6C6D6E6F
707172737475767778797A5B5C5D5E5F606162636465666768696A6B6C6D6E6F7071727374757677
A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7
C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
-:?POS($20$=A$) ! $20$=blank (start of printable characters in ASCII string)

33
-:PRINT A$(33)
!"#$%&'()*+,-./0123456789:;<=>?@abcdefghijklmnopqrstuvwxyz[\]^_àbcdefghijklmno
pqrstuvwxyz{|}~-
??

LEN( ) Return String Length
Function LEN( )
Format:
Return Length of String LEN(string$[,ERR=stmtref])
Where =
string$ String expression whose length is to be returned. See the examples, below.
Returns: Integer, length of given string, 0 (zero) if NULL string
Description:
The LEN( ) function returns an integer reporting the length of your given string. If your given string is a
NULL string ("") then the function returns a length of 0 (zero).
Examples:
A=LEN("HELLO") ! yields 5
A=LEN("") ! yields 0
A=LEN("A"+"BC") ! yields 3
A=LEN(DAY) ! yields 8 (DAY variable is in format MM/DD/YY)

LET Assign Value to Variable
Directive LET
Format:
Assign Value [LET] var[$]=expression,[var[$]=expression,...]
Where =
var Numeric or string variable to be set to the value of the expression.
expression Numeric or string expression whose value will be assigned to the variable.
Description:
Use the LET directive to set a variable to the value of an expression. If the variable is numeric, you must
use a numeric expression. If it's a string variable, you must use a string expression. You can use
substrings with string variables. (Specify the starting position and optional length.)
The word "LET" is optional in COMMAND mode. ProvideX assumes the word LET when it encounters a
directive starting with a variable. You can include multiple LET directives in one statement by using
comma delimiters. In this case, if you use the word "LET", it only occurs once, before the first assignment.
You can initialize, copy or manipulate a complete array by specifying {ALL} following the variable name. In
this case, you can also use the word {ALL} on the right side of the equation. The curly brackets { } are
"real" (i.e. part of the syntax).
Example 1:
0080 LET A$="THIS IS AN EXAMPLE"
0100 A$(1,4)="WHAT",A$(19)="!",Z$=""
0110 A$(5,4)=Z$
If Z$ is more than 4 characters, A$(5,4) is set as the first 4 characters of Z$. If Z$ is less than 4 characters,
the A$(5,4) value is Z$ plus space-padding up to a length of 4 characters:
RUN
-:?A$
WHAT AN EXAMPLE!
Other Examples:
-: Z4=A+4.5,Z5=Z4*.85
-: LET D$=DAY,T=TIM*3600
-: DIM A[30]; LET A{ALL}=A{ALL}*4

LFA Last File Number Accessed
Numeric System Variable LFA
Returns: Integer, channel number of last file/device accessed
Description:
This numeric system variable returns an integer reporting the channel number of the last file or device
accessed. It returns 0 (zero) if the last device was the console/users teminal.
Example:
->?LFA
0

LFO Last File Number Opened
Numeric System Variable LFO
Returns: Integer, channel number of last file opened
Description:
This numeric system variable returns an integer reporting the channel number of the last file OPENed.
Example:
0050 OPEN (14) "TESTFILE"
0600 OPEN (30) PRINTER$
->?LFO
30

LINE_SWITCH Redirect Console Input/Output
Directive LINE_SWITCH
Format
1 Switch File (0) LINE_SWITCH [(chan,ERR=stmtref)]

2 Switch File (0) LINE_SWITCH [device$]
Where =
chan Channel or logical file number to which to redirect file 0 (zero) input and output.
device$ Name of the device to which to switch file 0 (zero). String expression.
Description:
You can use the LINE_SWITCH directive to switch all I/O currently sent to channel or logical file number 0
(zero, the terminal) to another device. Its primary purposes are to allow for secondary users on a PC or to
provide remote maintenance capability.
While the LINE_SWITCH is in effect, the original device is disabled. ProvideX will expect to receive all
input from and send all output to the new device designated as file or channel 0 (zero).
Use a LINE_SWITCH directive with no parameters to restore communications with the original device on
channel (logical file number) 0 and CLOSE the alternate file.
Example:
-> LINE_SWITCH "PORT2" ! Defines/opens PORT2 as logical file number (0)
-> LINE_SWITCH ! Closes PORT2, restores terminal/console as logical file #(0)

LIP Input Location: Column, Line
String System Variable LIP
Returns: Numeric string, screen line and column location of statement
Description:
This string system variable returns a numeric string reporting the screen position (i.e. the column and line
numbers at the intersection) where you started to enter your last statement in your program. (This is used
by the Help/Query subsystem.)
Example:
->?LIP
0212

LIST List Program Lines
Directive LIST
Format:
1 List a Range of Lines LIST [EDIT] [(chan,fileopt)][from_stmt][,[to_stmt]]

2 List a Range of Lines / [EDIT] [(chan,fileopt)][from_stmt][,[to_stmt]]
Where =
/ or \ You can use either of the slashes (forward or back) as a substitute for typing the word
"LIST". (ProvideX also accepts LSIT instead of LIST.)
EDIT You can use the optional keyword EDIT with the LIST directive to have ProvideX both
logically break the lines and indent them.
See also: 'LE' SAVE and LIST: Indent Statements, p. 549(p)

chan Channel or logical file number to receive the readable LISTing of the contents of a
program.
fileopt File options. Valid options for LIST include:
END=stmtref END_OF_FILE transfer
IND=num Starting record index
TBL=stmtref Translation table
stmtref is a line number or statement label to which to transfer control.
from_stmt Starting statement to list. Optional. If you omit this, the default is to LIST from the
start of the program.
to_stmt Ending statement to list. Optional. If you omit this, the default is to LIST to the end of
the program.
Description:
The LIST directive converts program statements from the internal (compiled) format to a readable LISTing
which can be sent to a file or to your screen. This directive gives you a LISTing of the contents of your
program's statements as they were entered into the system originally. That is, it will return a series of
directives, variables, and operators, with line numbers.
The LISTing will not necessarily match exactly the way in which a statement was entered in the first place,
but will be syntactically the same. For instance, if you entered 510 A$="Example" and then used the
LIST directive, ProvideX would return 0510 LET A$="Example".
If you use the LIST directive with no file number or options, the output will be displayed on your screen.
You can direct the output of the LIST directive to any SERIAL or INDEXED file or to a device (e.g. a printer
or terminal). For more information see File Handling.
If the output of a list command goes to your terminal, the LISTing stops every 20 lines to allow you to read
the program page by page. To continue the listing, simply hit the <Enter> key. To stop the listing, use the
<F4> key. All other input is discarded.
If the LISTing of a statement exceeds the maximum allowed length of a record for your given file (e.g. 80
for terminals), the statement will be broken into multiple segments (records/lines). The first 'n' characters
(where 'n' is the maximum segment length) will be contained in the first segment with each subsequent 'n'
characters up to the end of the statement sent in subsequent segments. Each continuation segment will
be prefixed by the line number followed by a colon ":" and a space.
If you dont want the lines segmented, use the SAVE directive instead of LISTing your program.
See also: SAVE Write Program to File, p. 370(d)

Examples:
Given a file with twenty character records:
0020 PRINT "The quick brown fox licked the dog"
becomes
0020 PRINT "The quic
0020: k brown fox li
0020: cked the dog"
LIST Directive Result:

LIST 30 Lists line 0030
/ 30 Also lists line 0030
LIST 30,100 Lists lines 0030 to 0100
LIST 30, Lists lines from 0030 to the end of the program
LIST,WRAP_UP Lists lines up to and including the statement with label WRAP_UP
LIST Lists the entire program
LIST (1) Lists the entire program to logical file #(1) which can be a file/device (e.g. a printer).
Coloured Syntax Displays:

If your CS system parameter is ON, your listing will be displayed with a different colour for each syntax
element.
Example:
A Poem ... by Anony Mous:
Errors are red,
Variables are blue,
Directives are black
And tell ProvideX what to do.
See also: 'CS' Coloured Syntax, p. 540(p)
'*H' Control Screen Colours, p. 489(m)

There is a *CMD Command Line Utility called COLOUR (or COLOR) that can be used to display or alter
the current settings. Typing COLOUR or COLOR at a ProvideX prompt will display online help for this
utility.

LIST_BOX Define/Control LIST_BOX
Directive LIST_BOX
Format:
1 Define/Create LIST_BOX ctl_id,@(col,line,width,height)[,fileopt]

2 Define Formatted List Box LIST_BOX ctl_id,@(col,line,width,height),FMT=mask$[,fileopt]
3 Delete LIST_BOX REMOVE ctl_id[,ERR=stmtref]
4 Disable/Enable LIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
5 Set Focus To LIST_BOX GOTO ctl_id[,ERR=stmtref]
6 Load Via Delimited String LIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]
7 Load Via Array LIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]
Note that the curly brackets are "real" (i.e. part of the syntax) for {ALL}, above
8 Load/Delete Index Element LIST_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]
9 Find Element LIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]
10 Read Current Selection LIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]
11 Read Current Index LIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
12 Write Selection LIST_BOX WRITE ctl_id,element$[,ERR=stmtref]
13 Write Index LIST_BOX WRITE ctl_id,index[,ERR=stmtref]
14 Set Focus Notification LIST_BOX SET_FOCUS ctl_id,alt_ctl,[,ERR=stmtref]
15 Report All Changes LIST_BOX AUTO ctl_id[,ERR=stmtref]
16 Hide/Show LIST_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the LIST_BOX. Numeric expression. Integers, range: -
32000 to +32000. Avoid integers that conflict with keyboard definitions (e.g. function
key CTLs like 4).
@(col,line, Position and size of the LIST_BOX region. Numeric expressions. Column and line
coordinates for top left corner, width in number of columns, height in number of lines.
width,height)
fileopt File options. Valid options for LIST_BOX include:
FMT=mask$ For valid masks, see Formatted LIST_BOXes, p. 233 (Ver. 4.10)
KEY=char$ Hot key
OPT=char$ Valid single-character. See OPT=Char$ for LIST_BOXes, p. 229.
TBL=char$ Single-character translation
TIP=text$ Mouse pointer message. See also 'TC'=num TIP Window Colour,
p. 559(p) to change the colour.
array_name$ Name of array to load into the LIST_BOX. String variable followed by {ALL}.
index Position of the element in the LIST_BOX. Numeric expression. Integers: the index of
the 1st element is 1.

Where =
delete an element. For instance, LIST_BOX LOAD 86,4,* will "eighty-six" (remove)
element 4 from LIST_BOX 86.
var[$] Receives the value of the selected element (string variable) or index (numeric variable).
mode$ String variable. ProvideX returns a single-character hex value in this variable to report
the last method / keystroke the user chose to select an item from the LIST_BOX (e.g.
$01$ for a <Mouse-Click> or $0D$ for <Enter>).
alt_ctl CTL value to generate when the LIST_BOX gains focus.
Description:
Use the LIST_BOX directive to create and control LIST_BOXes on the screen. A LIST_BOX is used to
display a preset series of selections or elements from which the user can choose. ProvideX supports the
following LIST_BOX types:
Standard. Note that for Standard LIST_BOXes and all other types,
Format 1 Creates LIST_BOX ctl_id,@(col,line,width,height)[,fileopt], p. 227
Formatted LIST_BOXes, p. 233
Listview LIST_BOXes (List and Report Styles), p. 235
Treeview LIST_BOXes, p. 239
NOTE: A standard WINDOWS LIST_BOX can only use vertical scrollbars. However, you can
use Listview LIST_BOXes or GRIDs (Ver. 4.10) to incorporate horizontal scrollbars in
your applications.
Your user can select any element from a list of items you assign to the LIST_BOX, but variable input is not
allowed. That is, the user can only select - not enter - values. If you need a list box that allows both
variable input and selection from a list, use VARLIST_BOX Define/Control Variable List Box, p. 459(d)
instead.
See also: Dynamic Control Object PROPERTIES, p. 572
Format 1 Creates LIST_BOX ctl_id,@(col,line,width,height)[,fileopt]

You can use this format to define or create your Standard LIST_BOX and specify its unique identifier
(ctl_id). When a user selects an item from a LIST_BOX, the items associated ctl_id is used in generating
a CTL. Use an integer or numeric expression between -32,000 and +32,000 for the ctl_id.
Your file options include (but are not limited to):

The FNT=option to set the font for your LIST_BOX. If you omit your FNT= setting, ProvideX uses
the "System" default font. Use FNT="*" for the standard text mode fixed font.
OPT=Char$ for LIST_BOXes, p. 229 to refine your Standard / Formatted definition and/or to
define a LIST_BOX as a Treeview or Listview LIST_BOX.
The FMT=option to create Formatted LIST_BOXes, p. 233.
You can include other fileopts in any LIST_BOX definition (e.g. ERR=stmtref ... )
Example:
The example below creates a LIST_BOX that generates a CTL=100 when an item is selected from it and
uses FNT=text mode fixed font. The LIST_BOX is LOADed with the items Dog, Cat and Pig. The
programmer (obviously a cat-lover) writes Cat as the initial / highlighted selection and removes Dog from
the top of the list.

0020 LIST_BOX 100,@(2,14,12,6),FNT="*"
0030 LIST_BOX LOAD 100,"Dog/Cat/Pig/"; WAIT 1
0040 LIST_BOX WRITE 100,"Cat"; WAIT 1
0050 LIST_BOX LOAD 100,1,*; WAIT 1
0060 END

OPT=Char$ for LIST_BOXes
LIST_BOXes: OPT=Char$
Description:
Valid LIST_BOX single-character OPT= settings and descriptions are listed in the chart that follows (Ver.
4.10 and higher). Use them to refine your Standard and Formatted LIST_BOX definitions and / or to
designate your LIST_BOX type as:
Listview LIST_BOXes (List and Report Styles), p. 235 using either OPT="r" for Report Style
or OPT="l" for List Style (Ver. 4.10)
Treeview LIST_BOXes, p. 239 (OPT="e"), Ver. 4.10
LIST_BOX Settings
OPT=char$
! For Treeview only. Data has bitmaps (Ver. 4.11) or icons (Ver. 4.20). For example:
(exclamation 0020 LIST_BOX 100,@(10,10,10,10),OPT="e,!"
mark) If your OPT= setting includes "!" (as above), you can use LIST_BOX LOAD
statements to define bitmaps or icons for individual elements of a Treeview. ProvideX
displays your bitmap or icon to the left of the related element. Include the image
filename in your LIST_BOX WRITE statements to select (highlight) a Treeview element
with a bitmap or icon.
Examples:
0030 LIST_BOX LOAD 100,"{Cat.bmp}Cat/{Dog.bmp}Dog/{Hog.ico}Pig/"
0040 LIST_BOX WRITE 100,"{Cat.bmp}Cat"
Bitmaps or icons you define for individual elements using LIST_BOX LOAD statements
will override any default bitmaps or icons (defined using FMT=mask$).
See also: Treeview Bitmaps and Icons: FMT=Mask$, p. 239
Data with Bitmaps or Icons, p. 242
Write Treeview Data with Bitmaps, p. 243

LIST_BOX Settings
OPT=char$
# (pound Users can select more than one entry from the LIST_BOX. (This option is not supported
sign) for Treeview.)
If OPT="#", and your items were loaded in a single string, then when you READ and
WRITE the element(s) the user or program highlights in the LIST_BOX, ProvideX
returns the item(s) in your variable, using either the delimiter from your LIST_BOX
LOAD statement or, as default delimiter, the ProvideX SEP $8A$.
Example:
0010 PRINT 'CS'; BEGIN; LIST
0020 LIST_BOX 100,@(2,16,12,6),OPT="#"
0030 LIST_BOX LOAD 100,"Cat/Dog/Pig/"; WAIT 1
0040 ! If you read the ITEMS$ now, the returned value is NULL:
0050 LIST_BOX READ 100,ITEMS$;WAIT 1; PRINT ITEMS$+"Before Write"
0060 LIST_BOX WRITE 100,"Cat"; WAIT 1
0070 LIST_BOX READ 100,ITEMS$; PRINT ITEMS$
0080 LIST_BOX LOAD 100,2,*; WAIT 1
0090 LIST_BOX WRITE 100,2
0100 LIST_BOX READ 100,ITEMS$; WAIT 1; PRINT ITEMS$
0110 END
-:run
Before Write
Cat/
Cat/Pig/
| (pipe) For Treeview only. Show connecting lines.
LIST_BOX 100,@(10,10,10,10),OPT="e,|"
If OPT="|", the Treeview will display connecting lines between the various nodes of the
tree.
~ (tilde) No height adjustment.
Normally, a LIST_BOX displays an integral number of lines. If OPT="|", the LIST_BOX
will not be forced to show only complete lines. ProvideX will truncate the last line
horizontally (i.e. displaying a partial line to ensure that the height of your LIST_BOX
matches the size you defined).
A Auto signal is ON. ProvideX returns a signal on ALL changes in the LIST_BOX.
b For Listview (Report Style) and Treeview only. Suppress column heading or expansion
and collapse buttons.
In Listview (Report Style) "b" suppresses the column header buttons:
LIST_BOX 100,@(10,10,10,10),OPT="r,b"
When you use "b" for a Treeview, the {+} and {-} buttons (for the expansion and
collapse of the tree) are suppressed:
LIST_BOX 100,@(10,10,10,10),OPT="e,b"
B LIST_BOX has no border or frame.
d LIST_BOX is permanently disabled. (Cannot be enabled.)
D (or 1) LIST_BOX is initially disabled

LIST_BOX Settings
OPT=char$
e Defines your LIST_BOX as a Treeview control object (Ver. 4.10).
By default, a Treeview shows the data as a tree with tree level {+} and {-} buttons (for
the expansion and collapse of the tree). A Treeview displays and maintains the data in
sorted order. When you add elements to a Treeview LIST_BOX, ProvideX
automatically creates and inserts the elements. Bitmaps (or, as of Ver. 4.20, icons) are
optional.
See also: Treeview LIST_BOXes, p. 239.
h LIST_BOX is permanently hidden. (Cannot be shown.)
H LIST_BOX is initially hidden.
l Defines your LIST_BOX as a Listview (List Style) control object (Ver. 4.10).
(lower-case Listview (List Style): A simple multi-column list of the first element of data. Lists a series
el) of data columns as items from which the user can select. (Columns wrap from the
bottom of one to the top of the next column.) You can include an optional bitmap (or, as
of Ver. 4.20, an icon) in the first column (i.e. as the first piece of data in the row / line).
See also: Listview LIST_BOXes (List and Report Styles), p. 235.
L LIST_BOX is initially locked.
p For Listview only. Highlight partial match(es).
If OPT="p", your WRITE directives with strings are interpreted as selecting / highlighting
those items whose leading characters match the data you are writing. For example, if
you write "ABC", then the first item which starts with ABC is highlighted (or all items
that start with "ABC" if OPT="#" (above) is also set to allow users to make multiple
selections).
Examples:
LIST_BOX 100,@(10,10,10,10),OPT="l,p,#"
LIST_BOX 100,@(10,10,10,10),OPT="r,p"
q For Listview (Report Style) and Treeview controls only. Disable sorting.
If OPT="q" in Listview (Report Style), that suppresses the use of the column header
button to sort data:
LIST_BOX 100,@(10,10,10,10),OPT="r,q"
If OPT="q" in Treeview, items added to the list are always added at the end of their
respective trees:
LIST_BOX 100,@(10,10,10,10),OPT="e,q"
r Defines your LIST_BOX as a Listview (Report Style) control object (Ver. 4.10).
Listview (Report Style) LIST_BOX: Has column headings and variable column widths
and alignments. Each column of data has an optional {column-header} button for
sorting data. You can include an optional bitmap (or, as of Ver. 4.20, an icon) for the first
column (i.e. as the first piece of data in the row / line).
See also: Listview LIST_BOXes (List and Report Styles), p. 235
S LIST_BOX will scroll in a Scrollable window
T Strip Trailing spaces when reading or writing data for a LIST_BOX

LIST_BOX Settings
OPT=char$
v For Listview (Report Style) LIST_BOXES only. First Column highlight.
LIST_BOX 100,@(10,10,10,10),OPT="r,v"
You can use OPT=v to control the highlight style for individual LIST_BOXes and
override any system-wide use of the print mnemonic +V. If OPT=v, the user can
only click in the first column to highlight a row in the LIST_BOX.
See also: +V' * and -V Control Row Highlighting (Ver. 4.20), p. 532(m)
V For Listview (Report Style) LIST_BOXES only. Full Row highlight.
LIST_BOX 100,@(10,10,10,10),OPT="r,V"
You can use OPT=V to control the highlight style for individual LIST_BOXes and
override any system-wide use of the print mnemonic -V. If OPT=V, the user can
click in any column to highlight a row in the LIST_BOX.
See also: +V' * and -V Control Row Highlighting (Ver. 4.20), p. 532(m)
X Signal when Focus exits from the LIST_BOX

Formatted LIST_BOXes
Formatted LIST_BOXes
Description:
You can use a LIST_BOX definition with the FMT= option to:
Create a Formatted LIST_BOX and supply the format mask for your LIST_BOX columns.
Create formatted Listview LIST_BOXes by including both the FMT=mask$ and OPT="l" for a
Listview (List Style) or OPT="r" for a Listview (Report Style). See Listview LIST_BOXes
(List and Report Styles), p. 235.
Define bitmaps or icons for Treeview LIST_BOXes, p. 239.
Format 2: Formatted LIST_BOX ctl_id,@(col,line,width,height),FMT=mask$[,fileopt]

The information in the FMT=mask$ string expression for a Formatted LIST_BOX describes each of the
columns and/or rows. Each column is formatted with an alignment code, usually followed by a width in
column units. The list of columns is a space-separated string enclosed in quotation marks. Each new row
is delineated by a /slash.
Standard Formatted LIST_BOX Example

LIST_BOX 10000,@(5,5,35,10),FMT="L15 R5 N12 C3/B5 L25"
The width in the FMT= format mask is the display / window width, not the number of characters in the text.
Load the contents of the columns in your Formatted LIST_BOX from a delimited data string (positional data
for the entries in the LIST_BOX). The default delimiter is SEP $8A$. To change this, use the SEP= option.
Note that the value for the field delimiter (in this case, SEP) and the value signalling the end of row (in this
case, $0A$) must be different. For the example above:
"1123 East Main"+SEP+"Ont"+SEP+" 123.45"+SEP+SEP+"*"+SEP+"North Bay"+SEP+$0A$
Position Width: Contents Alignment

Col. 1, Line 1 15 1123 East Main L=Left
Col. 2, Line 1 5 Ont R=Right
Col. 3, Line 1 12 123.45 N=Numeric/Decimal
Col. 4, Line 1 3 * C=Centered
Col. 1, Line 2 5 B=Insert Blanks, 5=Length
Col. 2, Line 2 25 North Bay L=Left
For data you want hidden, you can use S (with no length) as your alignment character to indicate that a
column is to be skipped. (The data is present, but not displayed. The user cant see or gain access to the
column.)
NOTE: The maximum length of an element in a formatted LIST_BOX is 256 bytes.

See also: Example: Listview (Report Style), p. 237
Treeview Bitmaps and Icons: FMT=Mask$, p. 239

Colour in a Formatted LIST_BOX
To change the colour of any field in a Formatted LIST_BOX, simply prefix the data with one of the
mnemonics in the following chart.
Colour Foreground Mnemonic Background Mnemonic

Black 'BLACK' '_BLACK'
Red 'RED' '_RED'
Green 'GREEN' '_GREEN'
Yellow 'YELLOW' '_YELLOW'
Blue 'BLUE' '_BLUE'
Magenta 'MAGENTA' '_MAGENTA'
Cyan 'CYAN' '_CYAN'
White 'WHITE' '_WHITE'
Light Gray 'SF'+'_WHITE'
Normally background colours are dimmer than their respective foreground colours. If you want to use the
background (dimmer) colour for foreground text, prefix the colour with the 'SB' (Set Background)
mnemonic. If you want to use foreground colour brightness for the background, prefix the colour with the
'SF' (Set Foreground) mnemonic.
NOTE: This is not standard text plane colour handling. To get light gray background use
'SF'+'_WHITE' since '_WHITE' yields bright white.
All colours are reset to LIST_BOX default standards at the end of each column.
Example:
0010 OPEN (1)"INVOICE",(2)"CUST"
0020 LIST_BOX 10,@(10,10,60,10),FMT="L8 B2 L20 C10 N15 C3"
0030 READ (1,END=1000)INV_ID$,INV_CUST$,INV_DATE$,INV_AMT,INV_STS$
0040 READ (2,KEY=INV_CUST$)CST_NAME$
0050 LET L$=INV_ID$ ! 1st column
0060 LET L$+=SEP+CST_NAME$ ! 2nd column
0070 LET L$+=SEP+INV_DATE$ ! 3rd column
0080 LET X$=STR(INV_AMT:"$###,##0.00-")
0090 IF INV_AMT<0 THEN LET X$='RED'+X$ ! Column is red if negative
0100 LET L$+=SEP+X$
0120 LET X$='SF'+TBL(POS(INV_STS$="ISP"),"",'_GREEN','_BLUE','_RED')+INV_STS$
0130 LET L$+=SEP+X$
0140 LIST_BOX LOAD 10,0,L$
0150 GOTO 0030
1000 CLOSE (1),(2)
1010 INPUT *; IF CTL<>4 THEN GOTO *SAME

Listview LIST_BOXes (List and Report Styles)
Listview LIST_BOXes
Description:
Providex supports two styles of Listview LIST_BOXes:
List Style. Use the file option OPT="l" (lower case el) to define a simple multi-column list of
the first element of data. List Style lists a series of data columns as elements from which the
user can select. (Columns wrap from the bottom of one to the top of the next column.) When
you LOAD the Listview (List Style) LIST_BOX, you can include an optional bitmap (or, as of
Ver. 4.20, an icon) to be displayed as the first piece of data in the row / line.
Report Style. Use OPT="r" to define a list with column headings and variable column widths
and alignments. Each column of data has an optional {column-header} button for sorting
data. When you LOAD the Listview (Report Style) LIST_BOX, you can include optional
bitmaps (or, as of Ver. 4.20, icons) in the first column, as the first piece of data in the row or
line.
See also: OPT=Char$ for LIST_BOXes, p. 229
Examples:
0200 LIST_BOX 100,@(2,14,12,6),FNT="*",OPT="l"
...
0500 LIST_BOX 15000,@(10,10,20,10),OPT="r",ERR=2000
Listview FMT= Options

You can use the FMT= option to define Listview column widths, titles and the placement of an optional
bitmap or icon. Include a series of space-separated column definitions with an optional column header [in
square brackets], alignment code and width specification. As of Ver. 4.20, you can include icons and
specialized sorting features in the format.
Example:
LIST_BOX 10000,@(5,5,35,10),FMT="[Company]L10 [Vendor]C6 [Amount]#R12"
FMT=Settings Listview Description

Column Title Enclose your Column Title in square brackets ahead of the column alignment and
width, as in [Company]L10
Bitmaps or Icons If you want to include a bitmap or icon to the left of a line, place the bitmap or icon
filename in the format to identify the column.
Enclose bitmap or icon path and filenames in curly braces. Your icon filenames
must have .ico as an extension. You can use a leading exclamation point to
designate that the image is internal, but when you do that for icons, ProvideX only
searches in the *BMP directory. There are no icons in the ProvideX executable
and ProvideX does not support retrieving icons from either resource libraries or
other system DLLs /executables.
NOTE: Icon files often contain extra images for different sizes and
color depths. If you use an icon file in ProvideX, the file can
only contain one image.

FMT=Settings Listview Description
Column Alignment The Listview FMT= option supports Left, Right and Centre alignment. Use L or R
and Width or C as your alignment code, as a prefix to the width (in columns). For example,
LIST_BOX 10000,@(5,5,35,10),FMT="[Company]L10 ..." indicates
that column 1 is left justified and 10 columns wide. See also Formatted
LIST_BOXes, p. 233.
Numerical Column Specialized codes for a Listview column of numeric data notify ProvideX about the
Sorting Code nature of the data for sorting (Ver. 4.20):
# indicates that the data has been formatted using the STR( ) function and
contains a consistent number of decimal places as applied by a
format mask. Since the data is formatted, ProvideX will recognize
the character you assign in the DP System Parameter as the
decimal point for sorting. Default: DP=46 or DP=ASC("."). For
example, the [Amount] column, below, contains formatted data, right
justified, with a column width of 12:
LIST_BOX 100,@(5,5,35,10),FMT="[Amount]#R12"
N indicates that the numeric data is unformatted (may contain the default
ASC(".") decimal point followed by varying numbers of digits). For
example, [Amount], below, is unformatted numeric data, centered,
with a column width of 10:
LIST_BOX 100,@(5,5,35,10),FMT="[Amount]NC6"
Support for Date Y, M and D:
Column Sorting
Specialized codes for a Listview column of dates to notify ProvideX about the
order of the date components for use in sorting (Ver. 4.20).
To indicate that a column contains data that is to be treated as a date for sorting
purposes, include up to three Y, M, and D characters showing the order of the date
as it appears in the data (MD, DMY, MDY, YMD ...).
ProvideX doesnt translate or format the data, but recognizes and sorts it as date
values. The data must contain some sort of alpha separator (dashes or slashes,
etc.) between the individual values. In the example below, DMY will support
sorting of dates where the data is in day-month-year order (15-11-99,
01\JUL\2000, etc.):
LIST_BOX 100,@(5,5,35,10),FMT="[Sent]DMYL11"
ProvideX will parse the data into up to three fields and treat any alpha field it
encounters as a month name. Month names must match those currently in use by
the DTE( ) function.
LOAD Listview data into the columns from SEP-delimited data strings.
See also:
Standard Formatted LIST_BOX Example, p. 233
Format 6 Loads Delimited String: LIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref], p. 241
Listview FMT= Example

Note that ProvideX automatically supplies a horizontal scrollbar in the example below, where the total
width of the data columns is greater than the LIST_BOX display width:
0100 LET X$="[Custno]L10 [Name]L20 [Address]L20 [Category]C10 [Amount]R10"

0110 LIST_BOX 10000,@(10,10,50,10),OPT="r",FMT=X$,FNT="Arial,1"
0120 PRINT "Scroll to see columns"; WAIT 5
0130 LIST_BOX REMOVE 10000; END

The chart that follows describes the FMT= settings for line 0100 above. That is, for:
"[Custno]L10 [Name]L20 [Address]L20 [Category]C10 [Amount]R10"
Header Title Position Width Alignment

Custno Col. 1, Line 1 10 Left
Name Col. 2, Line 1 20 Left
Address Col. 3, Line 1 20 Left
Category Col. 4, Line 1 10 Centered
Amount Col. 5, Line 1 10 Right
Colour in Listview Report Style

(Ver. 4.20) The Listview (Report Style) LIST_BOX supports colours on a per column basis. Your colour
mnemonics can precede the data in the column or be intermixed with the data itself so that you can set up
more than one foreground / background colour per column. If your background colour mnemonic
precedes all the data in a column then the entire background of the column will be set to that colour.
See also: Colour in a Formatted LIST_BOX, p. 234.
Sort Arrows in Listview Report Style

(Ver. 4.20) The Listview (Report Style) LIST_BOX displays directional sort arrows (ascending /
descending) in the column title when a the user initiates sorting by clicking on the column title, or when
your logic forces sorting via the sort property.
See also: Dynamic Control Object PROPERTIES, p. 572.
Row Highlighting in Listview Report Style

(Ver. 4.20) The Listview (Report Style) LIST_BOX supports first column highlight (where the user must
click on the first column to highlight the row) and full-line highlight (where the user can click on any column
to highlight the row). You can set highlighting style for individual LIST_BOXes by using OPT= either "v"
or "V" when you create the control object or you can control the highlighting style system-wide by setting
the print Mnemomics -V and +V.
+V' * and -V Control Row Highlighting (Ver. 4.20), p. 532(m)
Example: Listview (Report Style)

0010 OPEN (1)"."
0020 SET_PARAM 'SD'

0030 LIST_BOX 10,@(5,5,25,10),OPT="r",FMT="[Name]L15 {} [Size]R7"
0040 LOOP:
0050 READ (1,END=0150)F$
0060 IF MID(F$,-1)=DLM
0060: THEN LET B$="!File",SZ$="<dir>";
0060: GOTO LOADIT
0070 LET B$=""
0080 OPEN INPUT (2,ISZ=-1)F$
0090 LET X$=FIN(2)
0100 CLOSE (2)

0110 LET SZ$=STR(DEC(X$(1,4)))
0120 LOADIT:
0130 LIST_BOX LOAD 10,0,F$+SEP+B$+SEP+SZ$+SEP
0140 GOTO LOOP
0150 CLOSE (1)
0160 ESCAPE

Treeview LIST_BOXes
Treeview LIST_BOXes
Description:
A Treeview LIST_BOX control object provides a hierarchical view of data, using a collapsible tree
structure. The Treeview works much like a standard LIST_BOX. As items are loaded into the Treeview,
ProvideX automatically parses the entries based on your given delimiter and creates all intervening tree
levels required. For instance, if you use a slash as your delimiter and load the single entry aaa/bbb/ccc,
ProvideX will generate three entries in the Treeview:
aaa
aaa/bbb
aaa/bbb/ccc
If you then load aaa/bbb/ddd, ProvideX only creates one new entry for aaa/bbb/ddd (since aaa and aaa/
bbb already exist). If you add aaa/xxx/iiid, ProvideX creates two new entries: one for aaa/xxx and
one for aaa/xxx/iii.
When an item from a branch is selected, the LIST_BOX READ returns the item, including its parent
branches. In the example above, selecting ccc would return "aaa/bbb/ccc/".
Treeview Bitmaps and Icons: FMT=Mask$

When you create your Treeview, you can use FMT=mask$ settings to define default bitmaps to be
displayed in the tree (optional). As of Ver. 4.20, ProvideX also supports {icon.ico} images for use in
LIST_BOXES. Your icon filename must have .ico as an extension.
Enclose image path and filenames in curly braces. You can use a leading exclamation point to designate
that the image is internal, but when you do that for icons, ProvideX only searches in the *BMP directory.
There are no icons in the ProvideX executable and ProvideX does not support retrieving icons from either
resource libraries or other system DLLs /executables.
Example:
LIST_BOX A,@(x,y,10,10),OPT="e",FMT={Cat.ico|Dog.bmp|Pig.bmp}
Note that filenames are mandatory in FMT= {images$} clauses. Place them inside curly braces in a pipe-
separated list. (NULL values in FMT= {images$} are not allowed. For instance, FMT={||Pig.bmp}
generates an Error #23: Missing/Invalid variable.)
Default Bitmaps:
You can define up to six default bitmaps (or icons as of Ver. 4.20) in Treeviews. The order of the images
determines when they are used:
1. Default overall bitmap or icon: always used with any listed entries that do not have subordinates.
2. Default bitmap or icon for items with subordinates.
3. Default bitmap or icon for items with subordinates if the tree level is expanded (i.e. shown) in Treeview.
4. Bitmap or icon for entries that do not have any subordinates when the item is selected.
5. Bitmap or icon for entries that have subordinates when selected.
6. Bitmap or icon for entries that have subordinates when selected and level is expanded.
NOTE: When OPT="e,!" (Treeview data has bitmaps or icons), any images you set up for
individual elements in Treeview LIST_BOX LOAD and WRITE statements will override
the default FMT= bitmap or icon for the individual element. See OPT=Char$ for
LIST_BOXes, p. 229.

Example: Treeview
0010 LIST_BOX 10,@(5,5,25,10),OPT="e|",
0020 LET F=1,D$="."
0030 NXTDIR:
0040 OPEN (F)D$
0050 NXTFILE:
0060 IF F$(1,1)="."
0070 IF MID(F$,-1)<>DLM
0070:GOTO NXTFILE
0090 F++
0100 GOTO NXTDIR
0110 ENDDIR:
0110:CLOSE (F)
0120 F--
0130 IF F>0
0140 ESCAPE

For All LIST_BOX Types
Formats for All LIST_BOXes
Description:
The remaining formats for LIST_BOXes, described below, apply to all types (Standard, Formatted, Listview
and Treeview).
NOTE: Make sure all bitmaps or icons in the same LIST_BOX control are the same size
(mandatory). If you include different sizes, ProvideX treats the size of the first bitmap
or icon as the size of all images for your given LIST_BOX.
ALSO: If you use Best Software Canada Ltd.s internal bitmaps (those starting with a !
found in PVX, in your resourcelib, or the *bmp directory) ProvideX converts the
background light gray to match the background colour of the LIST_BOX entries.
TIP: You can use SEP=DLM when READing directories to have ProvideX append the
operating system delimiter to subdirectory names.
Format 3 Deletes: LIST_BOX REMOVE ctl_id[,ERR=stmtref]

Use the LIST_BOX REMOVE format to delete a LIST_BOX. (To delete an individual element, use the
LIST_BOX LOAD directive instead.)
Format 4: LIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

When you disable a LIST_BOX, its grayed out. Users can see it, but the users and your program cant
gain access to it. Use the LIST_BOX ENABLE format to restore the display and access to a disabled
LIST_BOX.
Format 5 Sets Focus: LIST_BOX GOTO ctl_id[,ERR=stmtref]

Use the LIST_BOX GOTO format to set the Focus on a LIST_BOX, ready for the next user action.
LOAD Formats 6, 7 and 8

Use the LOAD formats below to add or delete the elements in a LIST_BOX. The formats set up the
elements using a delimited string, an array of string elements or individually.
Format 6 Loads Delimited String: LIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

When you LOAD elements into your LIST_BOX from a delimited string, the last character in the string must
be your delimiter. That ending delimiter must be identical to the separator between the elements in the
string.
Examples:
LIST_BOX LOAD 11000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
LIST_BOX LOAD 15000,"Fox"+SEP+"Cat"+SEP+"Dog"+SEP

Data with Bitmaps or Icons
Listview
When you LOAD a Listview LIST_BOX, you can include an optional bitmap (or, as of Ver. 4.20, an icon) to
be displayed to the left of the row / line. Enclose the bitmap or icon path and filename in curly braces as
the first piece of data in the row.
Treeview
If you create a Treeview with OPT="!" (as in LIST_BOX 100,@(10,10,10,10),OPT="e,!"), then you
can use LIST_BOX LOAD statements to define optional bitmaps (or, as of Ver. 4.20, icons) for individual
elements of a Treeview.
Place the bitmap or icon filename in the data, enclosing the path and filename in curly braces.
Example:
0030 LIST_BOX LOAD 100,"{cat.ico}Cat/{dog.bmp}Dog/{hog.bmp}Pig/"
ProvideX displays these images to the left of the related elements in the Treeview. Bitmaps or icons you
define for the individual elements in LIST_BOX LOAD statements will override any default FMT= images in
your LIST_BOX definition.
About Icons:
Your icon filenames must have .ico as an extension. You can use a leading exclamation point to
designate that the image is internal, but when you do that for icons, ProvideX only searches in the *BMP
directory. There are no icons in the ProvideX executable and ProvideX does not support retrieving icons
from either resource libraries or other system DLLs /executables.
Format 7 Loads Array: LIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

When you LOAD an array into your LIST_BOX, note that the curly brackets in {ALL} are "real" (i.e. part of
the syntax).
Format 8 Loads/Deletes Element: LIST_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]

IWhen you LOAD a LIST_BOX one element at a time, your index value refers to the index before which the
element is to be inserted. (Use a value of 1 to insert an element at the start of the list. If the value of your
index is 0 (zero), the element will be appended to the end of the list.)
If you have more elements on your data list than the physical screen size of the LIST_BOX can display at
one time, ProvideX automatically supplies vertical scrollbars.
To remove or delete individual elements from the box, use LIST_BOX LOAD with an asterisk instead of
the element string. For example:
LIST_BOX LOAD 86,4,* ! * deletes element 4 from list_box 86

Format 9 Retrieves Element: LIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]
Use a string variable in the FIND format to return a specific element from a LIST_BOX.
READ Formats 10 and 11:

Use the LIST_BOX READ formats (below) to read which element in the LIST_BOX has been selected.
Your string variable (mode$) will return a hex value showing how the element was selected. Some
possible values are:
$01$ for <Mouse-click>

$02$ for <Double-Mouse-click>
$0D$ for <Enter>.
Once this value is read its reset to $00$.
ProvideX returns an EOM value and event when the user hits the <Insert> or <Delete> keys. <Insert>
returns $2D$, <Delete> returns $2E$ (Ver. 4.10).
Format 10 READs Element: LIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

When you use LIST_BOX READ with a string variable, you can return the value of the currently selected
element and the method used to make the selection (mode$).
Format 11 READs Index: LIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref]

If you use LIST_BOX READ with a numeric variable, you can return the element by index and your users
method of selection (mode$) from the LIST_BOX.
WRITE Formats 12 and 13

Use the LIST_BOX WRITE formats (below) to make the element the current selection, highlighted in the
LIST_BOX.
Format 12 Updates Element: LIST_BOX WRITE ctl_id,element$[,ERR=stmtref]

Your string expression to write an element to a LIST_BOX as the current selection must exactly match the
value of one of the elements in the list box. Otherwise ProvideX returns an Error #11: Record not
found or Duplicate key on write.
Write Treeview Data with Bitmaps

If you create a Treeview with OPT="!" (as in LIST_BOX 100,@(10,10,10,10),OPT="e,!"), then you
can use LIST_BOX LOAD statements to define optional bitmaps (or, as of Ver. 4.20, icons) for individual
elements of a Treeview (Ver. 4.11). ProvideX displays your image to the left of the element. When you
WRITE the current selection, enclose the image filename in curly braces, preceding the individual data
element. For example:
0030 LIST_BOX WRITE 100,"{Cat.ico}Cat"

Bitmaps and icons you define for individual elements in LIST_BOX LOAD statements will override any
FMT= images.

Format 13 Updates Using Index: LIST_BOX WRITE ctl_id,index[,ERR=stmtref]

You can WRITE the current selection to a LIST_BOX by using its index.
NOTE: A WRITE to the LIST_BOX using an index of 0 (zero) will reset all highlighted lines.
Format 14 for Focus Notification: LIST_BOX SET_FOCUS ctl_id,alt_ctl,[,ERR=stmtref]

Use the SET_FOCUS format to set an alternate CTL value to be generated whenever Focus shifts to the
LIST_BOX.
Format 15 Reports Changes: LIST_BOX AUTO ctl_id[,ERR=stmtref]

Use the LIST_BOX AUTO format to have ProvideX generate a CTL automatically whenever the current
selection is changed. You can use this to track changes to the highlighted selection in a LIST_BOX.
Format 16: LIST_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]

Use the LIST_BOX HIDE format to keep your LIST_BOX from being displayed. (The user can't see the
LIST_BOX or gain access to it.) Use the LIST_BOX SHOW format to restore the display.

LOAD Read Program into Memory
Directive LOAD
Format:
Load Program in Memory LOAD [prog_name$]
Where =
prog_name$ Name of the program to LOAD. String expression.
Description:
Use the LOAD directive to read a program into memory (i.e. to open or retrieve a program) for execution,
listing, or modification . The program you LOAD into memory replaces the current program, if any.
On a LOAD directive, ProvideX resets the FOR/NEXT, GOSUB/RETURN, and WHILE/WEND stack. Any
addresses set in SETERR or SETESC directives are cleared and the current PRECISION is reset to two.
The current DATA pointer is also reset to the start of the program. No user data areas or files are affected
by the LOAD directive.
You can only use the LOAD directive in COMMAND mode or with the EXECUTE directive. Misuse of the
LOAD directive in EXECUTION mode (i.e. without the EXECUTE directive) generates an Error #45:
Referenced statement invalid.
If you omit the program filename, ProvideX LOADs the last file for which there was a LOAD, RUN, or
SAVE. If there is no prior file in the stack, ProvideX returns an Error #10: Illegal pathname
specified.
See also: RUN Transfer and Execute a Program, p. 368(d)
SAVE Write Program to File, p. 370(d)
NOTE: ProvideX accepts certain typographical errors. For instance, it accepts "LAOD" as a
substitute for "LOAD".
Examples:
LOAD "MYPROG" ! Loads "MYPROG"
LOAD ! Loads last program specified, if any (in this case, "MYPROG")
->DELETE
->LOAD
Error #10: Illegal pathname specified

LOCAL Designation of Local Variable
Directive LOCAL
Format:
Define Variable as Local LOCAL [varlist]
Where =
varlist List of variables for temporary use in the execution of a subroutine, subprogram,
FOR/NEXT loop or user-defined function.
Description:
Use the LOCAL directive to reassign a variable name temporarily, without affecting the original contents.
Then, if the variable name you supply in the LOCAL directive is in current use, ProvideX will preserve its
value/contents. Once the current FOR/GOSUB stack has been cleared or the program is exited, ProvideX
restores variables you have designated as LOCAL to their original values. (LOCAL variables are only
active until the current stack is cleared.)
Examples:
In the example below, X is designated as LOCAL for both subroutines (CHK_IT and LOOP), so the value
of X is restored to its original value "1234" after the GOSUB stack is cleared for each subroutine. Since
X$ was not designated as LOCAL in the LOOP subroutine, its value has changed from "START TEST,
X=" to "LOOP" after the GOSUB stack for the LOOP has been cleared.
1030 LET X=1234,X$="START TEST, X="; PRINT X$,X
1040 GOSUB CHK_IT
1060 GOSUB LOOP
1070 PRINT X$,X," DONE"; STOP
6000 CHK_IT:
6010 LOCAL X$,X; LET X$="CHECK X:"; PRINT X$,X
6020 LET X=X+10
6030 PRINT X$,X
6040 RETURN
7000 LOOP:
7010 PRINT "START LOOP, X=",X
7020 LET X$="LOOP" ! Not designated as LOCAL
7030 FOR LOCAL X=1 TO 4
7040 PRINT X$,X
7050 NEXT X
7060 RETURN
-:run
START TEST, X= 1234
CHECK X: 0
CHECK X: 10
TEST DONE
START LOOP, X= 1234
LOOP 1
LOOP 2
LOOP 3
LOOP 4
LOOP 1234 DONE
Variables in function definitions can be designated as LOCAL to prevent changes in program variables:
0010 DEF FNXY(LOCAL X,LOCAL Y,LOCAL Z)=X+Y+Z
See also: DEF FN Define Function, p. 72(d)

LOCK Reserve File for Exclusive Use
Directive LOCK
Format:
Exclusive File Use LOCK (chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file to be locked.
Description:
Use the LOCK directive to reserve your given file for exclusive processing by the user/program. Once a
file is locked, no other user or program can gain access to it. However, if another user already has the
given file OPEN, the OPEN and LOCK directives fail and ProvideX returns an Error #0: Record/file
busy.
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag. (If you are
running an earlier version of ProvideX on a WindX PC, you still need to encapsulate
your command in an EXECUTE "[WDX]..." directive.) See [WDX] Tag: Directs Action
to Client Machine, p. 626.
See also: UNLOCK Remove Exclusive Use from File, p. 445(d)
Example:
0010 OPEN (30,ERR=0100)"GLFILE"
0020 LOCK (30,ERR=0120)
...
0100 PRINT "Cannot open GLFILE"
0110 STOP
0120 PRINT "GL still in usetry later"
0130 STOP

LOG( ) Return Base 10 Logarithm
Function LOG( )
Format:
Return Base 10 Log LOG(num[,ERR=stmtref])
Where =
num Numeric expression whose base ten logarithm is to be returned.
Returns: Numeric, base ten logarithm
Description:
The LOG( ) function returns the numeric base ten logarithm of your given number, rounded to current
PRECISION. This is the inverse of the EXP( ) function.
ProvideX returns an Error #40: Divide check or numeric overflow if your numeric value is
negative.
Example:
0010 PRINT EXP(LOG(90)/3) ! yields 4.47

LONG_FORM Use Long Variable Names
Directive LONG_FORM
Format:
Use Long Variable Names LONG_FORM
Description:
Use the LONG_FORM directive to have the ProvideX compilers input-parsing routine accept long
variable names (default mode). The complementary directive is SHORT_FORM, which allows only short
variable names.
You can write programs in either SHORT_FORM or LONG_FORM or a combination of both. You can also
RUN programs in either mode.
See also: LF Long_Form Variables, p. 549(p)
SHORT_FORM Use Short Variable Names, p. 395(d)
Example:
-:LONG_FORM
-:LONG_NAME$="OK"
-:SHORT_FORM
-:LONG_NAME$="NOT OK IN SHORT_FORM"
Error #20: Syntax error ...ONGNAME$="L... (Long variable name not accepted)
-:L$="OKAY IN SHORT_FORM"

LPG Lead Program Name
String System Variable LPG
Returns: String, lead program name
Description:
This string system variable returns a string reporting the lead program name. This is the program that
started the current ProvideX session or the last program specified in the START directive.
See also: Command Line, Launching ProvideX, p. 569
Example:
->?LPG
start.win

LRC( ) Longitudinal-Redundancy Check
Function LRC( )
Format:
Return Checksum LRC(string$[,ERR=stmtref])
Where =
string$ Character string whose longitudinal redundancy checksum is to be calculated. String
expression.
Returns: One-byte string, longitudinal checksum
Description:
NOTE: The LRC( ) function is used primarily in conjunction with synchronous

communications.
The LRC( ) function returns the longitudinal redundancy checksum of a character string. The longitudinal
redundancy check of a character string is a one byte string resulting from a logical XOR( ) comparison of
all the characters in the string.
Example:
A$=HTA(LRC($0102$)) ! yields hex 03
A$=HTA(LRC($0305$)) ! yields hex 06

LST( ) Return 'List' Form of Statement
Function LST( )
Format:
Returns LIST Format LST(internal$[,ERR=stmtref])

Returns Colourized LIST LST(*internal$[,ERR=stmtref])
Where =
internal$ Character string containing the internal (compiled) form of a ProvideX statement.
String expression. For example: X$=LST(PGM(10))
* (asterisk) To return the listing in colourized syntax.
Returns: LIST format of statement (converted from compiled statement)
Description:
The LST( ) function converts a ProvideX statement from internal form to normal LIST format. It is your
responsibility to ensure that the string processed by the LST( ) function is a statement in valid internal form.
If the statement isn't valid, ProvideX returns either an Error #30: Statement too complex --
cannot compile or an Error #49: <*> Internal program format error <*>.
Coloured Syntax Displays:

The LST( ) function displays statements with coloured syntax (Ver. 4.02), for instance using statements like
X$=LST(* PGM(10)) and X$=LST(EDIT * PGM(10)) when the CS parameter is ON.
'*H' Control Screen Colours, p. 489(m)

There is a *CMD Command Line Utility called COLOUR (or COLOR) that can be used to display or alter
the current settings. Typing COLOUR or COLOR at a ProvideX prompt will display online help for this
utility.
Example:
0030 INPUT "Enter statement to display:",A
0035 IF A=0 THEN GOTO 2000
0040 LET X$=PGM(A,ERR=1000)
0050 PRINT LST(X$)
0060 GOTO 0030
1000 PRINT "Cannot find statement"
1010 GOTO 0030
-:run
Enter statement to display:50
0050 PRINT LST(X$)
Enter statement to display:
DONE

LWD Current Working Directory
String System Variable LWD
Returns: String, pathname of current working directory
Description:
This string system variable returns a string reporting the full pathname of your current working directory.
Example:
->?LWD
C:\MANUALS\PVX
->

MAX( ) Return Maximum Value
Function MAX( )
Format:
Returns Maximum Value MAX (compare1,compare2,...n[,ERR=stmtref])
Where =
compare1 n Numeric values and/or expressions to be compared.
Returns: Numeric, largest value, given list of numerics
Description:
The MAX( ) function evaluates and returns the maximum (largest) value of the numeric values or
expressions you specify. There is no limit to the number of values or expressions you can pass to the
MAX( ) function.
NOTE: You can also use the ProvideX MAX( ) function to obtain statistical information on
ODBC data fields. See also File Handling.
Example:
In this example, the MAX( ) function evaluates an expression(12*3.7=44.4), a literal (44.8) and a
variable (evaluated, A=43.2):
0050 LET A=13.21*3.27
0060 LET B=MAX(12*3.7,44.8,A)
0070 PRINT B
->run
44.8

MEM( ) Return Memory Value
Function MEM( )
Format:
1 Get Address of String MEM(var$[,ERR=stmtref])

2 Read Memory, 2 Bytes MEM(address[,ERR=stmtref])
3 Read Memory, 'n' Bytes MEM(address,bytes[,ERR=stmtref])
4 Change Memory MEM(address,val$[,ERR=stmtref])
Where =
var$ Name of string variable whose address you wish to obtain.
address Memory address being referenced. Numeric expression.
bytes Number of bytes to return. Numeric expression.
val$ Value you wish to write. String expression.
Returns: Memory location and information
Description:
NOTE: This function is mainly for use with external functions, i.e. using the functions DLL( )
and DLX( ) Call Windows DLL/DLX, p. 92(f).
The MEM( ) function gives you direct access to memory location through the use of pointers. ProvideX
performs address validation and returns an Error #41: Invalid integer encountered (range
error or non-integer) for an invalid memory location.
Format 1 returns the address of your string variable.
Format 2 returns the contents of a word (16 bits) of memory. The value returned is a binary value (integer
in twos complement format).
Format 3 returns a string consisting of the data at the address specified for the specified number of bytes.
Format 4 copies your character string value to the address given.

MENU_BAR Define/Control MENU_BAR
Directive MENU_BAR
Format:
1 Define/Create MENU_BAR ctl_id,list$[,ERR=stmtref]

2 Read Selected Item MENU_BAR READ var$[,ERR=stmtref]
3 Clear Menu_Bar MENU_BAR CLEAR[,ERR=stmtref]
4 Restore Default Help MENU_BAR RESET[,ERR=stmtref]
5 Set Focus To MENU_BAR GOTO[,ERR=stmtref]
6 'Tick'/'Untick' Item MENU_BAR {ON | OFF} element$[,ERR=stmtref]
7 Disable/Enable Item MENU_BAR {DISABLE | ENABLE} element$[,ERR=stmtref]
8 Remove Menu_Bar MENU_BAR REMOVE[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the MENU_BAR control object. Numeric expression.
Integers, range: -32000 to +32000. Avoid integers that conflict with keyboard
definitions (e.g. function key CTLs like 4).
list$ Your menu structure and elements. String expressions. Maximum 2047 elements.
Tip: To determine how many elements you already have, count the
ampersands (&).
var$ String variable to receive the last selected menu item.
element$ Individual menu selection. String expression.
Description:
Use the MENU_BAR directive to define and control the menu across the top of a window.
Format 1 Creates: MENU_BAR ctl_id,list$[,ERR=stmtref]

Use this format to create your MENU_BAR control object. If your MENU_BAR is not properly defined,
ProvideX returns an Error #87: MENUBAR definition invalid.
Define a list of menu groups and elements and identify each item uniquely (e.g., F and O would identify
File/Open) by marking the character your user can hit in conjunction with the <Alt> key (e.g. <Alt-F>) to
select the particular item. Use the following format for your string expression:
Enclose each menu group in square brackets.
Delimit each item in a group with a comma
Prefix each item's selection character (hot key) with & (an ampersand)
Prefix each sub-menu group with its item_id
The example below shows a menu string containing File and Edit, each with a submenu (for File: Open,
Save and Quit, and for Edit: Add and Delete). Each item has a shortcut key. The Quit selection has both
the shortcut key, Q, and a control ID value, 4.
MENU_BAR 100,"-[&File,&Edit],F:[&Open,&Save,&Quit=4],E:[&Add,&Delete]"
ProvideX includes the HELP selection on all MENU_BARs by default. You can suppress the HELP
selection by inserting a minus sign (-) as the first character in your menu definition string, as in the

example above.
You can right-justify a description of the menu entry (e.g. to tell users what function key will give them quick
access to the selection). Use the <Tab> character $09$ to separate the text to be right-justified, as in the
following example:
MENU_BAR 99,"[&File,&Edit...],E:[&Cut"+$09$+"Shft-DEL,&Paste"+$09$+"Ins]"
Normally, any selection from the MENU_BAR will generate its ctl_id. You can also have individual menu
items generate a unique CTL value. To do this, append an equals sign "=" and a control value to the
item(s) in your menu selection list (&Quit=4, in the example above).
You should use unique shortcut keys for selections from a given sub-menu in a group. You can use
duplicates, but if you do, you'll have difficulty determining which selection a user makes unless you also
have unique control values for menu items. If you omit a shortcut key, ProvideX assigns a value equivalent
to the item's placement in the definition string.
Example:
To insert a line to separate options, insert an additional comma , as a place holder in the definition string
(e.g. between &Open &Save, below).
MENU_BAR 120,"[&File],F:[&Open,,&Save,&Quit=4]"
NOTE: The MENU_BAR has a limitation of 2047 entries. If you exceed this number, an error
message is generated.
Example
0100 ! 100 - Menu Bar Example
0110 LET MNU_DEF$="[&Buttons,&Scrollbars,&Graphics,&Misc,&Quit=4]"

0120 LET MNU_DEF$=MNU_DEF$+",B:[&Standard,&Check box,&Tri-state]"
0130 LET MNU_DEF$=MNU_DEF$+",S:[&Vertical,&Horizontal]"
0140 LET MNU_DEF$=MNU_DEF$+",G:[&Standard Bitmaps,&Lines and
Shapes,&Pictures]"
0150 LET MNU_DEF$=MNU_DEF$+",M:[&Message Box,&Multi-&Line input,Menu &Bar]"
0160 MENU_BAR 999,MNU_DEF$,ERR=1000
1000 ! 1000
1010 OBTAIN (0,TIM=1,ERR=1020)@(0,0),SEL$,
1020 IF CTL=999 THEN MENU_BAR READ SEL$
1030 IF CTL>0 THEN STOP
1040 IF SEL$="" THEN LET SEL$="None"
1050 PRINT @(0,1),"Selection: ",SEL$,'CL',; GOTO 1000
Format 2 READs Selected Item: MENU_BAR READ var$[,ERR=stmtref]

When a user selects any of the items from a MENU_BAR, ProvideX generates the ctl_id you assigned to
the MENU_BAR. You can return the selected ctl value in a string variable by using the MENU_BAR READ
directive.
NOTE: Your program does not receive the CTL value for the menu item the user has chosen
until you READ it.

Format 3: MENU_BAR CLEAR[,ERR=stmtref]
Use the MENU_BAR CLEAR format to remove the MENU_BAR from the current window until a BEGIN or
END is executed.
NOTE: Use a MENU_BAR RESET or MENU_BAR CLEAR directive before you alter your
MENU_BAR.
Format 4 Restores Standard Help: MENU_BAR RESET[,ERR=stmtref]

Use the MENU_BAR RESET format to reset the current MENU_BAR to the default Help setting.
Format 5 Sets Focus: MENU_BAR GOTO[,ERR=stmtref]

Use the MENU_BAR GOTO format to set the Focus on your MENU_BAR.
Format 6 'Ticks'/'Unticks' Item: MENU_BAR {ON | OFF} element$[,ERR=stmtref]

Use the MENU_BAR ON option of this format to display a tick mark in front of the specified MENU_BAR
item, making it appear that it was selected. Use the MENU_BAR OFF option to remove the tick mark.
Format 7 Disables/Enables Item: MENU_BAR {DISABLE | ENABLE} element$[,ERR=stmtref]

Use the MENU_BAR DISABLE format to gray out the display of a specified MENU_BAR item and prevent
its selection. Use MENU_BAR ENABLE to reactivate it so that your program and users can gain access to
it.
Format 8 Deletes: MENU_BAR REMOVE[,ERR=stmtref]

Use the MENU_BAR REMOVE format to delete the MENU_BAR completely from the current session.
Then it can't be redisplayed until it is redefined.

MERGE Read/Append Lines from File
Directive MERGE
Format:
1 From File Number MERGE (chan,fileopt)

2 From SERIAL File Name MERGE filename$
Where =
chan Channel or logical file number from which to read program statements.
fileopt File options. Valid options for MERGE include:
IND=num Starting record index (numeric expression)
filename$ Name of the SERIAL file to be used as the source file for your MERGE.
Description:
Use the MERGE directive to add program statements from a source file to your current (target) program.
You can use a MERGE directive for SERIAL or INDEXED files. You can also use it with *MEMORY* files
(Ver. 4.10).
See also: INDEXED Create File Access by Record Number, p. 191(d)

SERIAL Create a Sequential File, p. 375(d)
Format 1 Specifies Source File by Channel #: MERGE (chan,fileopt)

OPEN the source file and use its current channel / logical file number to identify it. You can use this format
with a memory-resident file (i.e. *MEMORY*).
Format 2 Specifies Source File by Filename: MERGE filename$

You can use a SERIAL filename to identify it as the source for the MERGE (instead of opening it and
referring to the channel number).
Notes for Both Formats

The source file must contain records which are statements in valid LIST format (i.e. with correct syntax, line
numbers, etc.).
Warning: During the MERGE process, if a statement from the source file has a line number
matching a line number in the target program, the statement from the source file will
overwrite the corresponding statement in the target program.
You have to include line numbers in the source file, but you don't have to put them in numeric order.
ProvideX reads them into the target program in ascending sequence as if they were entered in COMMAND
mode, but will place them in the correct numeric sequence, using the source file's numbering.
If your source file contains a statement without a statement number, or with an invalid statement number

(outside of the allowed range), ProvideX generates an Error #21: Statement number is invalid
and halts the MERGE process.
ProvideX terminates the MERGE process when it encounters an END-OF-FILE status in the source file.
Example:
The following is a sample terminal session using the MERGE directive to combine two programs:
->LOAD "TIME.PRT"
->LIST
1000 REM Time output routine
1010 T$=STR(INT(TIM)*100+FPT(TIM)*60:"00:00")
1020 RETURN
->SERIAL "WORKFILE"
->OPEN (1)"WORKFILE"; LOCK(1)
->LIST (1)
->CLOSE (1) ! WORKFILE has list of program
->LOAD "PASS.CTRL"
->LIST
0010 GOSUB 1000; PRINT "1st pass: ",T$
0020 CALL "PASS1"
0030 GOSUB 1000; PRINT "2nd pass: ",T$
0040 CALL "PASS2"
0050 GOSUB 1000; PRINT "End both: ",T$
0060 STOP
->OPEN (1)"WORKFILE"
->MERGE (1)
->CLOSE (1)
->LIST
0010 GOSUB 1000; PRINT "1st pass: ",T$
0020 CALL "PASS1"
0030 GOSUB 1000; PRINT "2nd pass: ",T$
0040 CALL "PASS2"
0050 GOSUB 1000; PRINT "End both: ",T$
0060 STOP
1000 REM Time output routine
1010 T$=STR(INT(TIM)*100+FPT(TIM)*60:"00:00")
1020 RETURN

MESSAGE_LIB Establish Message Library
Directive MESSAGE_LIB
Format:
1 Designate Message Library MESSAGE_LIB filename$[,NBF=num][,ERR=stmtref]
NOTE: As of Ver. 4.20, you can also use the following additional Formats:
2 Add Library to Top of List MESSAGE_LIB ADD filename$[,NBF=num][,ERR=stmtref]
3 Remove Library from List MESSAGE_LIB DROP filename$[,ERR=stmtref]
4 Remove Top Lib. from List MESSAGE_LIB POP [,ERR=stmtref]
Where =
filename$ Name of the variable length DIRECT / KEYED file to be used as a Message Library.
String expression which may or may not include the pathname.
num Number of buffers to allocate
stmtref A statement number or line reference to which to transfer control.
Description:
Use the MESSAGE_LIB directive to designate files as containing messages to be returned by the MSG( )
function. A MESSAGE_LIBrary must be a variable length DIRECT / KEYED file with the message
identifier as the key. The record contains the message. As of Ver. 4.12 there is an alternate key to the
*msglib.en (and any newly created MESSAGE_LIB files) on the first 50 characters of the message field.
See also: MSG( ) Return Message Text, p. 271(f)
KEYED Create Single/Multi-Keyed File, p. 211(d)
DIRECT Create File with Keyed Access, p. 88(d)
Format 1 Designates Message Library: MESSAGE_LIB filename$[,NBF=nnn][,ERR=lineref]

Use this format to designate and add your filename(s) to the MESSAGE_LIB list.
Prior to Ver. 4.20, only one MESSAGE_LIB could be active at a time. (In ProvideX versions before Ver.
4.20, when you use a MESSAGE_LIB directive, ProvideX closes any other currently active message
library and designates your given file as the new one.)
As of Ver. 4.20, you can have more than one MESSAGE_LIB active at a time. When you use the MSG( )
function, the MESSAGE_LIBraries are searched in order until a match is found.
An error is generated if the file cannot be properly opened. You can use NBF to specify the number of
buffers to allocate. Your filename$ expression can contain one or more MESSAGE_LIB filenames, each
SEP separated, so that you can reset the entire list in one command.
Example 1:
KEYED "MESSAGE.LIB",10,0,-256
OPEN (1)"MESSAGE.LIB"
WRITE RECORD (1,KEY="NOCUST")"Sorry but Customer %1 is not valid"
CLOSE (1)
MESSAGE_LIB "MESSAGE.LIB"
PRINT MSG("NOCUST","0001")
Sorry but Customer 0001 is not valid

Example 2:
0010 MESSAGE_LIB "MSGLIB."+ENV("LANG"),ERR=0020;GOTO 0100
0020 MESSAGE_LIB "MSGLIB.EN"
0100 REM...
0110 ! ...
1000 READ (CST_FN,KEY=K$,DOM=1900)...
1010 ! ...
1900 PRINT MSG("MSG2",K$)
Format 2 Adds Library to Top of List: MESSAGE_LIB ADD filename$[,NBF=num][,ERR=stmtref]

You can use this format to add your filename$ to the top of the list of MESSAGE_LIBraries to search. An
error is generated if the MESSAGE_LIB file cannot be properly opened. You can use the NBF option to
specify the number of buffers to allocate.
Format 3 Removes Library from List MESSAGE_LIB DROP filename$[,ERR=stmtref]

You can use this format to remove the specified filename$ from the list of MESSAGE_LIBs to search. An
Error #12: File does not exist (or already exists) is generated if the filename$ is not on
the list.
Format 4 Removes Top Library from List MESSAGE_LIB POP [,ERR=stmtref]

You can use this format to remove the top filename$ from the list of MESSAGE_LIBs to search. An Error
#13: File access mode invalid is generated if the filename$ is empty.

MID( ) Return Substring
Function MID( )
Format:
Return Part of String MID(string$,offset[,len][,ERR=stmtref])
Where =
string$ String expression from which the substring is to be derived.
offset Starting position of the substring. Numeric expression, integer. If the integer is
negative, the offset is taken from the end of the string.
len Length of the substring.
Exception: The error branch is not taken if your offset is 0 (zero). Then, ProvideX
returns an error instead.
Returns: Extracted portion of string (similar to substring)
Description:
Use the MID( ) function to extract a portion of a string. Using this function is similar to using a substring,
except that you can use this function directly with the return value of a function, variable or expression. For
example:
->IF MID(MSE,22,1)>$00$ AND MID(MSE,22,1)<$FF$ THEN %WDX$="[WDX]"
In addition, if your offset is negative, ProvideX uses it as an offset from the end of the string. For example,
MID(X$,-1) is the last character of X$. If the length is negative, then ProvideX uses it as the number of
characters preceding the offset. That is, MID("ABCD",-1,-1) returns "C" (the first character preceding
the last character) and MID("abcde",-2,-4) yields "abc".
By default, if this function is passed an invalid offset, it returns a NULL string. If passed an invalid length,
then it returns the rest of the string.
Example:
F_KSZ=DEC($00$+MID(FID(0),11,1))

MIN( ) Return Minimum Value
Function MIN( )
Format:
Return Minimum Value MIN(compare_1,compare_2,..._n[,ERR=stmtref])
Where =
compare_1 ... n Numeric values and/or expressions to be compared.
Returns: Numeric, smallest value, given list of numerics
Description:
The MIN( ) function returns the minimum (smallest) value of your given numeric values or expressions.
There is no limit to the number of values or expressions you can pass to the MIN( ) function.
NOTE: You can also use the ProvideX MIN( ) function to obtain statistical information on
ODBC data fields. See also File Handling.
Example:
In this example, the MIN( ) function evaluates an expression (13/2.96=4.39), a literal (4.5) and a variable
(evaluated, A=5.69):
0010 A=12.345/2.71
0020 B=MIN(13/2.96,4.5,A); PRINT B
-:run
4.39

MNEMONIC Define File Command Sequence
Directive MNEMONIC
Format:
Define MNEMONIC [(chan)]mnm_name$=esc_sequ$
Where =
chan Channel or logical file number for which the mnemonic is defined.
mnm_name$ Valid mnemonic name, enclosed in apostrophes. String expression.
esc_sequ$ Escape or command sequence required by the file/device in order to process your
mnemonic. String expression.
Description:
Use the MNEMONIC directive to define additional mnemonics for files and/or devices. Once you define a
mnemomic for a given logical file number, it stays active until the channel is closed. When ProvideX
encounters a user-defined mnemonic in a PRINT or INPUT statement, it converts the mnemonic to the
character string in the escape sequence.
See also: Mnemonics, p. 486
In WindX
NOTE: As of Ver. 4.20, WindX supports the use of the MNEMONIC directive via the [WDX]
tag. If you are running in an earlier version of ProvideX on a WindX PC, you still
need to encapsulate your command in an EXECUTE "[WDX]..." directive. See [WDX]
Tag: Directs Action to Client Machine, p. 626.
As an example of the EXECUTE command under WindX (for earlier versions):

IF WDX%<>$00$ THEN EXECUTE "[WDX]MNEMONIC(LFO)5X=$1B+hex$" ELSE GOTO MY_LABEL
As of Ver. 4.20:
After you OPEN a channel across a WindX connection, all mnemonics you declare (except *R and *X)
are sent automatically to the WindX workstation. ProvideX considers the *R and *X mnemonics to be
local to the server unless you use the [WDX] tag in declaring them. (*R declares an operating system
command to execute on channel close, and *X declares a program to CALL on channel close.)
WindX Examples:
OPEN(chan)"[WDX]\\mach\printer_share"
MNEMONIC(chan)FF=$0C$ ! automatically goes to WindX workstation
MNEMONIC(chan)*R="erase "+filename$ ! local to server, not workstation
MNEMONIC(chan)*R="[WDX]erase "+filename$ ! on workstation, not server
ProvideX Examples
To define and use a mnemonic:
0010 OPEN(1) "/dev/printerxx"

0020 MNEMONIC 'US'=ESC+"_" ! Define mnemonic
....
0030 PRINT(1)'US',"Title line...", ! Underscored
The example below illustrates how the MNEMONIC directive can be used for flexible text fonts on a screen

in WINDOWS. Define the font and the logical screen size in your statement. For example, to assign
settings for the ProvideX standard mnemonics CP and SP:
MNEMONIC(0)CP="Courier New,-8":120,40
MNEMONIC(0)SP="*":80,25
Then, a subsequent PRINT CP directive will change the screen font to Courier New with a size of 8
points. PRINT SP will restore the screen font to standard print.
NOTE: The TEXT plane font must always be a fixed font.

MNM( ) Return Mnemonic Value
Function MNM( )
Format:
Return Sequence MNM(mnemonic$[,chan][,ERR=stmtref])
Where =
mnemonic$ Name of defined mnemonic to look up, or the string value of the mnemonic. String
expression.
chan Channel or logical file number of your given file. If you omit this, the default is file 0
(zero).
Returns: String, command sequence for mnemonic
Description:
The MNM( ) function returns the defined command sequence for the specified mnemonic for your given
file. The command sequence is typically the exact transmission string to handle the mnemonic for the file.
If this isnt a standard ProvideX mnemonic and you haven't predefined this string using the MNEMONIC
directive, the MNM( ) function returns a NULL string.

Mnemonics, p. 486
Example:
See if the terminal supports condensed print. If so, create window 1 (overlaying the program on window 0)
with compressed print text font:
0010 LET X$=MNM('CP')
0020 IF X$="" THEN GOTO 0050
0030 PRINT 'WINDOW'(0,0,132,25),'CP','CS', ! Create window 1, compressed print
0040 INPUT "Type something: ",A$
0050 REM
0060 PRINT 'SP', ! Use standard print
0070 INPUT "DONE! Type something else: ",B$
0080 END
-:run
Type something: HELLO, WHOVILLE
Type something: HELLO, WHOVILLE ! Redisplayed, refreshed, with standard print
DONE! Type something else: THIS IS GULLIVER
Next, your program listing is redisplayed in window 0 (zero), standard print.

MOD( ) Return Modulus
Function MOD( )
Format:
1. Return Modulus MOD(num,base[,ERR=stmtref])

2. Using Pipe (|) num|base,ERR=stmtref
Where =
num Value for which to calculate the modulus. Numeric expression.
base Modulus base value. Numeric expression.
| (pipe) ProvideX treats the pipe | vertical bar in Format 2 as an instruction to evaluate the
modulus.
Returns: Numeric, modulus / remainder
Description:
The MOD( ) function returns the modulus / remainder from a division of the first expression by the second.
Example 1:
Conditions to deal with leap year dates:
1040 IF Y|4=0 THEN LET N.MAX=366,M.TBL$(3,2)="29" ELSE LET N.MAX=365,
1040:M.TBL$(3,2)="28"
Line 1040, using the pipe "|" above, is the equivalent of the syntax in line 1040 below:
1040 IF MOD(Y,4)=0 THEN LET N.MAX=366,M.TBL$(3,2)="29" ELSE LET N.MAX=365,
1040:M.TBL$(3,2)="28"
Other Examples:
A=MOD(10,3) ! yields A=1
A=MOD(10,5) ! yields A=0
A=MOD(9,3.5) ! yields A=2

MSE Mouse State
String System Variable MSE
Returns: String, current state of mouse
Description:
This string system variable returns the current state of the mouse. Use the HTA( ) function to obtain the
your hex values and use the chart below to interpret them:
->?MSE
O_x O____
->?HTA(MSE)
004F15027800A84F150101010100000000000000000000000000000000000000
MSE String Returns:

(1,1) = Current state:
$FF$ - Mouse inactive/unavailable
$00$ - (Above sample, in DOS environment, no mouse)
$01$ - Left button down
$02$ - Right button down
$03$ - Both buttons down
(2,1) = Current mouse column in binary
(3,1) = Current mouse line in binary
(4,2) = Current mouse X (column) position in binary
(6,2) = Current mouse Y (line) position in binary
(8,1) = Absolute column #
(9,1) = Absolute row #
(10,1) = Standard character width
(11,1) = Standard character height
(12,1) = Width of Scroll box on standard scroll bar
(13,1) = Height of Scroll box on standard scrollbar
(14,2) = Mouse X (column) position relative to current window in binary
(16,2) = Mouse Y (line) position relative to current window in binary
(18,2) = Current control object with focus
(20,2) = Last control object with focus
(22,1) = WindX revision level. Range $00$ to $FF$. ($FF$ for non-WindX)
(23,2) = CTL value for context-sensitive help
(25,2) = Last control object to lose Focus
(27,2) = Maximum X (column) coordinates of the screen
(29,2) = Maximum Y (line) coordinates of the screen

MSE String Returns:
(31,1) Returns current window state (Ver. 4). Values correspond to SHOW( )
mnemonic, i.e., dec(mid(mse,31,1))=
-1 for hidden
0 for minimized
1 for normal
2 for maximized
WindX Example:
You can create a global variable using MSE values in your WindX setup, and use it to determine whether
or not youre running under WindX. The variable %WDX below is only set when WindX is running,
otherwise its value is NULL.
IF MID(MSE,22,1)>$00$ AND MID(MSE,22,1)<$FF$ THEN %WDX$="[WDX]"
Then you can use this global variable, for example, in OPEN (30)%WDX$+"WINPRT" to bypass Error
#12: File does not exist (or already exists).
Screen Size Example:

You can use the MSE variable to return screen dimensions in pixels so that you can determine screen size
in lines and columns:
MSE Characters Returned Value

27,2 Number of pixels across the screen
29,2 Number of pixels top to bottom
10,1 Standard character width in pixels
11,1 Standard character height in pixels
To get the maximum screen size in lines and columns:

0010 LET X$=MSE
0020 XCHAR=DEC($00$+X$(10,1))
0030 YCHAR=DEC($00$+X$(11,1))
0040 MAX_WIDE=INT(DEC(X$(27,2))/XCHAR)
0050 MAX_HIGH=INT(DEC(X$(29,2))/YCHAR)

MSG( ) Return Message Text
Function MSG( )
Format:
1 By Message # MSG(err_msg,[,ERR=stmtref])
2 By Message Key MSG(msg_key$,[param1,...n][,ERR=stmtref])
3 MESSAGE_LIB Setting MSG(*)
Where =
err_msg Number of the ERRor message to return. Numeric expression. PRINT MSG(-1)
will return the last reported ODBC error.
msg_key$ Message key to the Message Library file. String expression.
param1...n Optional parameters. You can use a list of values to replace the parameters stored in
the message.
* As of Ver. 4.20, MSG(*) returns the current MESSAGE_LIB settings. If more than
one MESSAGE_LIB is open, the function returns all the open filenames in search
order, each separated by the default field separator, SEP ($8A$).
Returns: Text associated with given message number or key
Description:
The MSG( ) function returns the text of the message whose number or key you specify. You can use this
function to obtain more information about errors generated in ProvideX by a program and to return
information from your own MESSAGE_LIBraries.
See also: MESSAGE_LIB Establish Message Library, p. 261(d)

Example 1:
0010 OPEN (1,ERR=1000)"PRINTR"
0020 OPEN (2,ERR=1000)"CUSTOM"
0030 READ (2,KEY="",ERR=1000)R$
0040 ...
1000 PRINT "Could not open PRINTR",'LF',MSG(RET)
1010 STOP
Example 2:
KEYED "MESSAGE.LIB",20,0,-256
OPEN (1)"MESSAGE.LIB"
WRITE RECORD (1,KEY="NOCUST")"Sorry but Customer %1 is not valid"
CLOSE (1)
MESSAGE_LIB "MESSAGE.LIB"
PRINT MSG("NOCUST","0001")
Sorry but Customer 0001 is not valid
Example 3:
0010 ! Returns the current message library name, if any is in effect
0020 PRINT MSG(*)

Example 4:
You can use this function to obtain the ProvideX error message associated with an error number:
-:?msg(14)

MSGBOX Display PopUp Message Box
Directive MSGBOX
Format:
Define Message Box MSGBOX text$[,title$[,options$[,selection$]]]
Where =
text$ Text to appear in the message box. String expression.
title$ Title of the message box. String expression. (If you omit this field, the title will be
"Error".)
options$ Customized message box options. Optional string expressions, separated by
commas if you include a list.
Valid options for MSGBOX buttons include:
OK Ok only
CANCEL Ok , Cancel
RETRYCANCEL Retry, Cancel
ABORT Abort, Retry, and Ignore.
YESNO Yes, No
YESNOCANCEL Yes, No, Cancel
1 (or 2 or 3 ) Default button number
Valid icons (in graphics mode only) include:
STOP Stop sign
INFO Lowercase 'i' in a circle
QUESTION or ? Question mark
EXCLAMATION or ! Exclamation Mark
You can also include:
BEEP Send associated sound
selection$ String variable to return the button selected by the user. Possible values are
"ABORT", "CANCEL", "IGNORE", "NO", "OK", "RETRY", "YES".
Description:
Use the MSGBOX directive to display a window with a message in the middle of the screen. The text will
be split into segments (lines) based on the system settings for screen width and centering characteristics.
You can define multiple lines of text by using a SEP between lines.
You can use the options string to identify the buttons and/or icons you want to include in the MSGBOX.
The users MSGBOX button selection is returned in a string variable.
Example:
1000 MSGBOX "Remove the customer record",
1000: "Confirmation Please","?,YESNO",X$
1010 IF X$<>"YES" THEN RETURN
1020 REMOVE (1,KEY=K$)

MSK( ) Scan String for Mask
Function MSK( )
Format:
Return Mask MSK(string$,mask$[,ERR=stmtref])
Where =
string$ String to search. String expression.
mask$ String containing the pattern / mask definition. If this value is NULL, then the last-
used pattern is reused. String expression.
Returns: Integer reporting starting offset
Description:
Use the MSK( ) function to scan a string looking for a specific pattern of characters. The value returned is
an integer reporting the starting offset of the longest string matching the given mask or pattern. Your
pattern defines the mask as a regular expression or series of characters, some of which have a special
meaning. The following table lists those characters and their meanings. Combinations are allowed.
MSK Char. Format in pattern$ Search

^Caret At start of regular expression To find a match with the start of the string being
searched.
Dollar Sign$ At end of regular expression To find a match with the end of the string being
searched.
. Period To find a match with any character
( string ) String of characters (or other To define a sub-expression to match.
codes) enclosed in parentheses
[ string ] String enclosed in square brackets To find a match with any character in that string.
[^string] Square bracketing combined with a To find a match with any character except the
caret (^) as the first character of the characters in the string. For example [xyz]
string matches x, y, or z, while [^xyz] matches a, b, c,
but not x, y, or z.
a-Dash 2 characters separated by a dash To specify a range.
(-)
[str-ing] In combination: dash within string To form expressions: e.g. [a-bd-z] to search for
in square brackets a match with any lower case letter except c.
* Asterisk At the end of a character (or To search for zero or more occurrences of the
subexpression) character (or subexpression). For example: in
fo*, the * operates on the o; it matches f, fo, foo
etc.. but doesn't match fa. The expression f(at)*
matches f, fat, fatat, fatatat, etc..
a+ Plus Sign At the end of a character (or To find a match with 1 or more occurrences of
subexpression) that character (or sub-expression). For example
fa+ will match fa, faa, faaa, etc. but not f.

MSK Char. Format in pattern$ Search
Question? At the end of a character (or To indicate that it is optional. For example
Mark subexpression) colou?r will match color or colour. The
expression sea(horse)? will match sea or
seahorse.
Vertical Bar | Separating two characters (or To find a match for either of the two characters
(Pipe) subexpressions) (or subexpressions). For example: c(at)|(ow) will
match cat or cow and at|(nd) will match at or and.
\Backslash Preceding a MSK character to indicate that the character which follows, is to
be taken literally. For example, to search for
multiple asterisks use \**.
The MSK( ) function returns the starting offset in your string$ expression (where it matches the pattern
specified). The MSL system variable and TCB(16) return the length of the string found.
NOTES: When the TL (Thoroughbred Like) system parameter is OFF, the LIKE operator will
use the same pattern matching that MSK( ) does. With the OM (Old Mask) System
Parameter ON, MSK( ) behaviour is compatible with the UNIX GREP command.
See also: MSL Length of String Matching Last MSK, p. 276(v)
TCB( ) Return Task Information, p. 424(f)
TL LIKE Emulates Thoroughbred, p. 559(p)
'OM' Old-Style Mask, p. 552(p)

Operators Supported in ProvideX, p. 587 re: the LIKE operator.
Example:
->PRINT MSK("my name is Foxxy","[A-Z][a-z]*"),MSL
12 5
Here, MSK( ) reports the starting offset. ("F", the 12th character, is the first uppercase character.) MSL( )
reports the length of the string. ("Foxxy" is 5 characters long.)

MSL Length of String Matching Last MSK
Numeric System Variable MSL
Returns: Integer, length of string matching last MSK( ) function
Description:
This numeric system variable returns an integer reporting the length of the string that matched the last
MSK( ) function. TCB(16) also reports the length of the string.
See also: MSK( ) Scan String for Mask, p. 274(f)
Example:
->PRINT MSK("my name is Foxxy","[A-Z][a-z]*"),MSL
12 5
Here, MSK( ) reports the starting offset. ("F", the 12th character, is the first uppercase character.) MSL( )
reports the length of the string. ("Foxxy" is 5 characters long.)

MULTI_LINE Define/Control MULTI_LINE Input
Directive MULTI_LINE
Format:
1 Define/Create MULTI_LINE ctl_id, @(col,line,width,height)[,fileopt]

2 Delete MULTI_LINE REMOVE ctl_id[,ERR=stmtref ]
3 Disable/Enable MULTI_LINE {DISABLE | ENABLE} ctl_id [,ERR=stmtref]
4 Set Focus To MULTI_LINE GOTO ctl_id[,ERR=stmtref ]
5 Read Current Value MULTI_LINE READ ctl_id,var$[,mode$][,ERR=stmtref]
6 Load Value MULTI_LINE WRITE ctl_id,contents$[,ERR=stmtref]
7 Notify Re: Focus MULTI_LINE SET_FOCUS ctl_id,CTL_val[,ERR=stmtref]
8 Report All Changes MULTI_LINE AUTO ctl_id[,ERR=stmtref]
9 Prevent/Allow Changes MULTI_LINE{ LOCK | UNLOCK} ctl_id[,ERR=stmtref]
10 Hide/Show MULTI_LINE {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the MULTI_LINE input field / control object. Numeric
expression. Integers, range: -32000 to +32000. Avoid integers that conflict with
keyboard definitions (e.g. function key CTLs like 4).
@(col,line, Position and size of the MULTI_LINE input region. Numeric expressions. Column
and line coordinates for top left corner, width in number of columns, height in number
width,height)
of lines.
If you are creating more than one MULTI_LINE for a screen, note that, depending on
the way WINDOWS redraws MULTI_LINES, they can lose their surrounding boxes.
To circumvent this, we recommend a minimum distance of 1.6 lines between
MULTILINES.
fileopt File options. Valid options for MULTI_LINE input fields include:
FMT=mask$ Format mask
As of Ver. 4.20, you can use FMT="!" for numeric MULTI_LINE input
fields to indicate that the field should be displayed as blank if the value
is 0 (zero). Note that you should not use this option if your field values
could ever be zeroes but less than 1. That is, if you use FMT="!" with a
decimal value only, (e.g. field value 0.00), ProvideX blanks out the
value.
KEY=char$ Hot key
LEN=num Maximum input characters (maximum: increased from 255 to
32000 as of Ver. 4.20). You can use the LEN= option in conjunction with
the FMT= option to limit the number of characters allowed for a
MULTI_LINE WRITE that violates the format mask.
NUL=string$ Empty value
OPT=char$ Single char. parameter. (See MULTI_LINE OPT=char$, p. 278.)
SEP=char$ Delimiter

Where =
var$ String variable to receive the text / contents of the MULTI_LINE input field.
report the last method / keystroke the user chose to terminate the MULTI_LINE input
field, e.g. $0D$ for <Enter> as the EOM character (for a 1-line MULTI_LINE input
field) or $09$ for <Tab> to exit a MULTI_LINE input field.
contents$ Text / contents of the MULTI_LINE input field. String expression.
CTL_val CTL value to generate when Focus goes to the MULTI_LINE input field.
Description:
Use the MULTI_LINE directive to create and control a MULTI_LINE input region on the screen. Multi-line
input is used to enter or display text. When the input is complete, your user presses <Tab>, a <function_
key>, or <Enter> for a single-line-high MULTI_LINE input field. ProvideX then generates a CTL using the
MULTI_LINE input region's associated ctl_id.
See also: Dynamic Control Object PROPERTIES, p. 572 .
Format 1 Creates: MULTI_LINE ctl_id,@(col,line,width,height)[,fileopt]

Use this format to define or create your MULTI-LINE input field. You can use the FNT= option to establish
the font for MULTI_LINE input. If you omit this option, ProvideX uses the "System" default font. If you
specify FNT=*, standard text mode fixed font is used.
If you define a MULTI_LINE input field as occupying more than one line, ProvideX adds scrollbars and
automatic word wrapping. If you define the input area as only one line high, the MULTI_LINE input region
will not have a vertical scrollbar, but will scroll horizontally as required.
MULTI_LINE Description
OPT=char$
$ Password entry displays $ (dollar sign) as substitute for each character entered
> Include a horizontal scrollbar
# Implied decimal point
! Support for Arabic characters (right to left entry)
A Auto: generates a CTL signal for every character entered
B No border: the MULTI_LINE input region will not have a border
C Centre the input
d Permanently disabled
D Disabled: user cannot gain access to the MULTI_LINE input region
E Edit Mode: append to end of existing text (default=Insert)
h Permanently hidden
H Hide: do not display the MULTI_LINE input region
i Suppress the +I mnemonic (implied decimal points) for a single MULTI_LINE input
region
I (upper case i) Activate the +I mnemonic for implied decimal points for a single MULTI_LINE input
region
L Lock: user can set Focus, but cannot change the MULTI_LINE input region
R Right justify

MULTI_LINE Description
OPT=char$
s Scroll: allows the MULTI_LINE input region to scroll in a resizable/scrollable
dialogue box
t Supports the use of the <Tab> key in the MULTI_LINE input region
T Strips trailing spaces
U Upper case: converts lower case to upper case automatically
X Signal on exit: generates a CTL when focus leaves the MULTI_LINE input region
Example:
0010 MULTI_LINE 100,@(2,14,12,6)
0020 MULTI_LINE WRITE 100,"Now is the time for all"
0030 OBTAIN *
0040 IF CTL=100 THEN MULTI_LINE READ 100,X$
This creates a MULTI_LINE input field that generates a CTL 100 when its value changes and the user
exits the MULTI_LINE input region.
Format 2 Deletes: MULTI_LINE REMOVE ctl_id[,ERR=stmtref]

Use the MULTI-LINE REMOVE format to delete a MULTI_LINE input field.
Format 3: MULTI_LINE {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use the MULTI_LINE DISABLE format to disable or gray out a MULTI_LINE input region or MULTI_LINE
ENABLE to reactivate it so that users and your programs have access to it.
Format 4 Sets Focus: MULTI_LINE GOTO ctl_id[,ERR=stmtref]

Use the MULTI_LINE GOTO format to set the Focus on the MULTI_LINE input field, ready for the user's
next action.
Format 5 READs Current Value: MULTI_LINE READ ctl_id,var$[,mode$][,ERR=stmtref]

Use the MULTI-LINE READ format to read the contents of the MULTI_LINE input field.
If your user enters more than one line of text, ProvideX will delimit each line, either using the system SEP
character or the character you specify in the SEP= option of your directive. By default, MULTI_LINE input
fields auto-wrap text, so the SEP character will only be returned on the READ if the user inserts a carriage
return.
On the READ, the mode$ variable will identify the method use to end MULTI_LINE input. It will contain:
$09$ for <Tab> used to exit or
$0D$ for <Enter> used to end a 1-line MULTI_LINE input field.
Once this value is read, it is reset to $00$.
Format 6 Loads Value: MULTI_LINE WRITE ctl_id,contents$[,ERR=stmtref)

When you WRITE string expressions into the MULTI_LINE input, you must use a delimiter set by either the
SEP= or the DLM= option.

Format 7 Notifies re: Focus: MULTI_LINE SET_FOCUS ctl_id,CTL_val[,ERR=stmtref]
Use the MULTI_LINE SET_FOCUS format to generate a CTL value whenever Focus shifts to the
MULTI_LINE input region.
Format 8 Reports All Changes: MULTI_LINE AUTO ctl_id[,ERR=stmtref]

Use the MULTI_LINE AUTO format to generate a CTL automatically whenever there is a change.
Format 9 Prevents/Allows Updates: MULTI_LINE{ LOCK | UNLOCK} ctl_id[,ERR=stmtref]

Use the MULTI_LINE LOCK or UNLOCK formats to prevent or allow access to the MULTI_LINE input field.
You can use a LOCK to limit the user's permissions to "view only" for data such as notes and instructions.
Format 10: MULTI_LINE {HIDE | SHOW} ctl_id [ , ERR=stmtref ]

Use the MULTI_LINE HIDE format to hide the MULTI_LINE input region. (The user can't see or gain
access to it, even though it's still active and accessible through your program.) Use the SHOW format to
restore the display and access.

MULTI_MEDIA Control MULTI_MEDIA Interface
Directive MULTI_MEDIA
Format:
Multimedia Command MULTI_MEDIA command$[,var$[,CTL_val]]
Where =
command$ String containing the multi-media command to execute. String expression.
var$ String variable to receive any response or error message.
CTL_val Optional CTL code to be generated when a NOTIFY signal is returned by the Multi-
Media system. Numeric expression.
Description:
NOTE: For use in WindX or WINDOWS only.

Use the MULTI_MEDIA directive to pass commands to the WINDOWS Multi-Media Control Interface
(MCI). These strings can contain commands that will play WAV files, MID files, AVI files or control various
multi-media devices.
Some typical commands are:
Command Function/Purpose
open filename Opens the specified file and loads the required drivers. You can append an optional
'alias name' to an open command to change the name of the file (to make
controlling the file easier).
close filename Closes the specified files and releases the drivers.
close all Stops and closes all files.
play filename Plays the specified file. If the file is not already opened, it will be opened, played,
and closed automatically.
rewind filename Rewinds the file.
stop filename Stops the playback.
NOTE: This directive only functions in WINDOWS or when using the WindX terminal
driver.
Example 1:
open c:\video\files\demo.avi alias video
Example 2:
0010 ! Close all previous Multi_media commands for this session
0020 MULTI_MEDIA "close all"
0030 !
0040 ! Assign an Alias to the Wave file for use in the Play command
0050 MULTI_MEDIA "open c:\windows\media\tada.wav alias wavefile"
0060 !
0070 ! Issue the Play command requesting notification of a CTL=100
0080 ! after the wave file has finished
0090 MULTI_MEDIA "play wavefile notify",100
0100 !
0110 ! Wait for the CTL=100

0120 OBTAIN X$
0130 IF CTL=4 THEN STOP
0150 PRINT "Multi_media command finished"
Future references to the file could simply use the alias.
Two options can be appended to the play command:
notify (send the CTL value when completed)
wait (wait for the playback to complete)
If an error occurs during processing, it will be returned in your return$ variable.
NOTE: Full documentation of all of the available MCI commands is beyond the scope of this
manual. We suggest that you refer to other sources for complete documentation on
the Microsoft MCI system.

MXC( ) / MXL( ) Return Maximum Column/Line
Functions MXC( ) / MXL( )
Format:
Return Maximum Columns MXC(chan[,ERR=stmtref])

Return Maximum Lines MXL(chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file to reference, typically 0 (zero, for the
terminal). Use an integer for a device channel (e.g. a printer). Numeric expression.
Returns: Integer, zero-based, maximum columns/lines allowed for file/device
Description:
The MXC( ) function returns an integer reporting the zero-based maximum number of columns allowed for
a file or device. The MXL( ) function returns an integer reporting the zero-based maximum number of
lines allowed for your given file or device. You can use these functions as a quick means to determine the
size of the current display window on a screen.
Note that the functions MXC( ) and MXL( ) return maximum available column and line for the channel
based on the current default settings for paper size, printable area, offset, margin, font and pitch.
Examples:
On a terminal where MXC(0)=79 and MXL(0)=24 with LEN(X$)=15:
0100 X$="THIS IS A TITLE"
0110 PRINT @(MXC(0)-LEN(X$)+1,0),X$ ! Right-justified on line 1
0200 PRINT @(0,MXL(0)),"F1-Help F4-Quit", ! Left-justified on bottom line
The next example returns the maximum column and line values for a given printer (ASIS=the last printer
OPENed on channel 30). The values are zero-based. That is, the MXC( ) value returned is 79 for 0-79 =
80 columns:
OPEN INPUT (30)"*WINPRT*;ASIS"
C=MXC(30)+1 ! For this printer MXC(30) returns 79, C=80 (0-79)
L=MXL(30)+1 ! For this printer MXL(30) returns 55, L=56 (0-55)
CLOSE (30)

NAR Number of Arguments, Start Providex
Numeric System Variable NAR
Returns: Integer, number of arguments in ProvideX start up
Description:
This numeric system variable returns an integer reporting the number of arguments in the ProvideX
command that launches ProvideX (e.g. in using a batch file or from a command statement).
See also: ARG( ) Command-Line Argument, p. 17(f)

Example:
-> PVX -SZ=20 -ARG TOM JONES
->?NAR
2

NEXT End of Loop
Directive NEXT
Format:
Marker, End of Loop NEXT [var]
Where =
var Current FOR variable to be incremented or decremented.
Description:
Use the NEXT directive to terminate a FOR/NEXT loop. When ProvideX encounters the NEXT directive,
the current FOR/NEXT variable is incremented or decremented by the STEP value and, if the current value
does not exceed the ending value, control is returned to the directive following the FOR.
The variable you use in the NEXT directive must match that of the currently active FOR. If no FOR is
active or the variables do not match, ProvideX returns an Error #28: No corresponding FOR for
NEXT. If you omit the NEXT variable, then the variable in the current FOR directive is incremented or
decremented.
See also: FOR ... NEXT Loop While Incrementing, p. 155(d)
Example:
0010 FOR I=1 TO 10
0020 PRINT I,
0030 NEXT ! NEXT I, since I is current
-:RUN
1 2 3 4 5 6 7 8 9 10

NEXT RECORD End of SELECT
Directive NEXT RECORD
Format:
End of SELECT NEXT RECORD
Description:
Use your NEXT RECORD directive to end a SELECT directive. As each record is read, ProvideX
processes any logic you include following the SELECT directive up to the NEXT RECORD. When
ProvideX encounters a NEXT RECORD statement with no records found for a nested SELECT, it will
locate the corresponding SELECT statement.
See also: SELECT Select/Query From ... Where, p. 371(d)
NOTE: In versions prior to Ver. 4.20, the CONTINUE and BREAK directives (and
corresponding *CONTINUE and *BREAK labels) are not supported for use with
SELECT / NEXT RECORD directives. As of Ver. 4.20, you can use BREAK commands
in SELECT structures.
Example:
0010 SELECT IOL=0100 FROM "CUST_FILE",KNO=1 BEGIN "ABC CO" END "NEW CO" WHERE
0010:CITY$="CLARENDON"
0020 PRINT REC(IOL=0100)
0030 NEXT RECORD
0100 IOLIST CUST$,NAME$,ADDR1$,ADDR2$,CITY$,PROV$,POSTAL$,INV_DT$,AMT,TERMS,
0100:DUE_DT$
-:run
123460
ACME LTD.
SUITE 1900
2000 1ST ST.
CLARENDON
ON
K0K0K0

NID Network or Network Node ID
String System Variable NID
Returns: String, network identifier
Description:
This string system variable returns a string reporting the network identifier under MS-DOS. Under UNIX
this variable returns the network node name.
Examples:
PRINT NID on an MS-DOS system yields system-specific string values like:
a users surname and initial, e.g. SMITHJ
a department identifier, e.g. ACCT_SYS
a users first name, e.g. WENDY
...

NOT( ) Invert String Bits/Logical Condition
Function NOT( )
Format:
1 Invert String NOT(data$[,ERR=stmtref])

2 Invert Logical Condition NOT(num[,ERR=stmtref])
Where =
data$ Data whose bits are to be inverted. String expression.
num Value for inverting a logical condition. Numeric expression.
Returns: Inverted value, string or numeric (ON bits turned OFF and vice versa)
Description:
This function returns the inverted value of a string or numeric (i.e. with all ON bits turned OFF and vice
versa).
Format 1 Inverts String: NOT(data$[,ERR=stmtref])

The NOT( ) function inverts the value of the bits in the character string you specify. The string returned by
the NOT( ) function will be the same length as your given data string. All OFF bits in the string will be
returned ON, while all ON bits will be returned OFF.
Your string expression can be a literal like "abc" or $8A$, a variable such as A$, or an expression
using operators, such as A$="1234".
Examples:
A$=HTA(NOT($FF00FF$)) ! Print A$ yields 00FF00
D$=NOT("ABC") ! yields , HTA(D$)=BEBDBC
IF NOT(CST_ID$="123456") THEN PRINT "Not matched..."
Format 2 Inverts Logical Condition: NOT(num[,ERR=stmtref])

You can use this format of the NOT( ) function to invert a logical condition (Ver. 4.). If your numeric is 0
(FALSE), this function returns 1 (TRUE). Otherwise this function returns 0 (FALSE).
Example:
0710 IF NOT(INV_AMT<=0) THEN PRINT "Valid amount : ", ELSE PRINT "Invalid amou
0710:nt: ",
0720 PRINT "$",INV_AMT:"###0.00"
0730 PRINT "Value of NOT :",NOT(INV_AMT<=0) ! 0 (false) for <=0
-:end
-:run
Invalid amount: $ 0.00
Value of NOT : 0
-:inv_amt=12.50
-:run
Valid amount : $ 12.50
Value of NOT : 1

NUL( ) Return Test for Null
Function NUL( )
Format:
Return NULL Status Code NUL(string$,ERR=stmtref)
Where =
string$ String to be tested for NULL value. String expression.
Returns: Numeric true/false code, 1 or 0 (zero)
Description:
The NUL( ) function returns a numeric status code. The value returned is 1 (TRUE) if the string expression
is NULL or contains nothing but spaces. If the string contains data other than spaces, then this function
returns 0 (FALSE).
Example:
In this example, the NUL( ) conditions force the user back to the prompts to put data in mandatory fields:
0010 BEGIN
0020 INPUT EDIT "Enter your Name: ",N$
0030 IF NUL(N$) THEN PRINT "Your name is required. ",; GOTO 0020
0040 INPUT EDIT "Address: ",A$
0050 IF NOT(NUL(A$)) THEN GOTO 1000 ELSE GOTO 0040
-:RUN
Enter your Name:
Your name is required. Enter your Name: IDA WANNA
Address:
Address:
Address: 123 ANY ST.
DONE
-:?nul(a$),nul(n$)
0 0

NUM( ) Convert String to Value
Function NUM( )
Format:
Return Numeric Value NUM(string$[,ERR=stmtref])
Where =
string$ Character string whose value is to be converted to a numeric value. Numeric in
string expression (e.g. "19990317").
Returns: Numeric value from string
Description:
The NUM( ) function returns the numeric value (e.g. 19990317) of a numeric expression in a string (e.g.
"19990317"). The contents of your string expression are evaluated and converted to a numeric.
If your given string does not contain a valid numeric value, ProvideX returns an Error #26: Variable
type invalid. Your string expression can include any number of the following valid characters: 0-9, a
space, a comma, an equals sign, or a dollar sign. You can also include one decimal point along with one
sign character (either '-' or '+').
The NUM( ) function always ignores the decimal point and thousands separator settings in the 'DP' and
'TH System Parameters, p. 537.
Example:
A=NUM("1.34") ! Yields 1.34
A=NUM("-1,005.") ! Yields -1005
A=NUM("A",ERR=50) ! On error, transfers to 0050 and sets ERR=26

OBJ( ) Return Object Information
Function OBJ( )
Format:
Return Object Information OBJ(ctl_id,ERR=stmtref)
Where =
ctl_id Control ID number that is assigned to each control when created. Numeric
expression.
Returns: String, 64 characters, information about custom control object
Description:
The OBJ( ) function returns a string containing information about your given custom control object (i.e.,
BUTTON, LIST_BOX, etc.). If your given control doesnt exist, ProvideX returns an Error #65: Window
element does not exist or already exists. The example below shows what is returned for
existing LIST_BOX 10. The string returned by the OBJ( ) function contains 64 characters:
0020 LIST_BOX 10,@(10,10,60,10),FMT="L8 B2 L20 C10 N15 C3"
->?hta(obj(10))
00040000000A000A003C000A0000000000000978004E00CE01E40092004F009501E2009000000000
000000000000000000000000000000000000000000000000
Characters Information Returned by OBJ( )

1,2 Object Type:
$0001$ Push Button
$0002$ Check Box
$0003$ Tri_State Check Box
$0004$ Standard List Box
$0005$ Variable List Box
$0006$ Drop Box
$0007$ Variable Drop Box
$0008$ Multiline Edit box
$0009$ Radio Buttons
$000A$ External VBX
$000B$ Listview
$000C$ Tree View
$000D$ Grid
$0010$ Vertical Scroll Bar
$0020$ Horizontal Scroll Bar

Characters Information Returned by OBJ( )
3,2 State:
$0000$ Additive bit state: nothing listed below is happening
$0001$ Drop box open
$0002$ Control changed: issue CTL on closure
$0004$ Control has focus
$0008$ Control is dropped
$0010$ Insert mode for typing
$0020$ Temporary font in effect
$0040$ Ignore format
$0080$ Temporarily non-paint
$0100$ Notification pending "signal" button
$0200$ Focus changed due to signal
$0400$ Hide until input
$0800$ Button is down
$1000$ Focus interrupt is deferred
$2000$ Input must have implied decimal point
$8000$ Disabled object
Example:
To detect enabled / disabled NOMADS control:
X$=OBJ(OBJECT_NAME.CTL)
IF AND(X$(3,2),$8000$)=$8000$ THEN PRINT "Object is disabled"
5,2 Column
7,2 Line
9,2 Width
11,2 Height
13,4 Visual screen attributes at time of creation
17,4 Operating system handle
21,2 Left Pixel } Includes Border
23,2 Top Pixel } Includes Border
25,2 Right Pixel } Includes Border
27,2 Bottom Pixel } Includes Border
29,2 Left Viewable Column
31,2 Top Viewable Row
33,2 Viewable # of Columns
35,2 Viewable # of Rows

OBTAIN Get Hidden Terminal Input
Directive OBTAIN
Format:
Obtain Input OBTAIN (chan[,fileopt])varlist
Where =
chan Channel or logical file number of a terminal or INDEXED file from which to obtain
input.
fileopt File option(s). Valid options for OBTAIN include:
HLP=string$ Help message identifier
IND= num Record index value
LEN=num Limit of input size
SIZ=num Maximum characters to read
TIM=num Maximum time-out value
'@(...)'. The listed items must be comma-separated.
Description:
Use the OBTAIN directive to issue prompts to terminal devices and to process responses (your users
input). Your file reference should be to a terminal, but you can use an INDEXED file. If you include literals
or expressions in your directive, ProvideX treats them as prompts for your user.
You can include format masks, as in A$=STR(.01:"0.00"). If you omit the format mask for a numeric in
your OBTAIN statement, the DP and TH system parameters for European decimal settings are ignored.
NOTE: OBTAIN performs in the same way as the INPUT directive except that the users input
is not echoed on the screen. This can be useful for such applications as passwords.
'ME' Begin Edit_Mode, p. 518(m)
'BI' Begin Input_Transparency, p. 494(m)
Example:
0010 OBTAIN 'CS',@(5,5),"Enter your password:",C$
RUN
Enter your password:
!The password, "TEST" in this example, is not echoed, but C$ will return the value.
-:?C$
TEST

OCX Interface Define Windows Object
Directive OCX
Format:
1 Define Invisible OCX DEF OBJECT ocx_id,obj_name$[,ERR=stmtref]

2 Define with Visible Location DEF OBJECT ocx_id,@(col,line,w,h){, | =}obj_name$[,ERR=stmtref]
3 Query / Read Property var[$]=ocx_idproperty[$][,ERR=stmtref]
4 Set / Write Property ocx_id[sub_id]property[$]=val[$][,ERR=stmtref]
5 Invoke Method, Pass Args. var[$]=ocx_idproperty[$]([args])[,ERR=stmtref]
6 Remove/Disconnect OCX DELETE OBJECT ocx_id[,ERR=stmtref]
Where =
ocx_id Numeric variable to receive a handle (memory pointer to the OCX).
obj_name The name by which the OCX object is registered in the WINDOWS system
registry subkey HKEY_CLASSES_ROOT. String.
var[$] String or numeric variable to receive the property value.
property[$]= Property name and format to assign properties or attributes to your given object.
Numeric or string expressions.
There are two properties to help with error handling:
pvxerror$ gives the text of the error message from the object
pvxerror gives the numerical error code from the object
sub_id To identify an object within an object. (Your statement can be compound, e.g.
numvarobjectproperty=value.)
args Variable(s) you use as arguments to pass to the OCX.
The format used for variables is the same as is used in DLL( ) functions. If an
argument variables name is prefixed by an asterisk, e.g., *arg_variable
ProvideX passes the argument by reference (i.e. memory pointer to address of
variable). Otherwise, it passes the argument variable by value (i.e. using data).
Description:
NOTE: The OCX / COM / ActiveX interface (Ver. 4.20) is for use in WindX or WINDOWS only,
but is not fully supported across a WindX connection.
ALSO: ProvideX reserves CTL values -32001 through -32767 and 32001 through 32767
internally for use in OCX handling (Ver. 4.20).
WARNING: Best Software Canada Ltd. does not provide support for any OCX / COM / ActiveX
objects, their use nor for their errors / problems / GPFs. We will, however provide
support for problems relating to the ProvideX interface itself (i.e. the
communications tunnel between ProvideX and the OCX / COM / ActiveX object). Use
of this interface is at your own risk. Contact your OCX / COM / ActiveX object
proprietor or supplier for documentation on the proprietary properties, usage,
arguments for methods, etc.. (Best Software Canada Ltd. does not provide these
items.)
An OCX (Object Component eXtension) is used primarily in Visual Basic and is similar to a DLL. Its a

separately compiled utility that provides a service, function or control and uses the Microsoft COM
(Common Object Module) interface. Each OCX must be registered in the system Registry under the
subkey HKEY_CLASSES_ROOT (done by the OCX / COM / ActiveX object itself).
Features ProvideX currently supports for OCX / COM / ActiveX objects are described below (Ver. 4.10).
As of Ver. 4.20 this interface supports a very wide range of objects. Methods and Properties are supported
as if they were dynamic properties. Events and Event Handling are not yet supported.
Format 1 Defines Invisible OCX: DEF OBJECT ocx_id,obj_name$[,ERR=stmtref]

Use this format to create a link to an invisible OCX / COM / ActiveX object. This format associates the
object with the current window, yet hidden from view.
Once the definition is complete, ocx_id will contain a handle to the object. You can use this handle to
query and set properties and methods. Note that since the value returned in ocx_id is a handle (memory
pointer) to the object, you should not change this in your application.
Example:
0010 DEF OBJECT this_ocx_id,"Mabry.SoundX"
2 Define OCX+Visible Location: DEF OBJECT ocx_id,@(col,line,w,h){,|=}obj_name$[,ERR=stmtref]

Either of the two syntax statements below will define a visible object and associate it with a location in the
current window. (The object will be visible at the coordinates specified.)
DEF OBJECT numvar,@(col,row,wide,high),"object_name",err=2000

DEF OBJECT numvar,@(col,row,wide,high)="object_name",err=2000
Format 3 Reads Property var[$]=ocx_idproperty[$][,ERR=stmtref]

When you query or read property values for the object, use your given ocx_id variable (containing the
handle to the OCX / COM / ActiveX object) as your object ID.
Examples:
PRINT this_ocx_idSoundex$
my_return_var$=this_ocx_idSoundex$
Format 4 Writes Property: ocx_id[sub_id]property[$]=val[$],ERR=stmtref

Use this format to set or write the property value. Your statement can be compound (i.e. you can write a
property to an object within an object).
y=this_ocx_idWord$="Hello"
y=this_ocx_idWord$Subtext$="World"
Format 5 Invokes Method, Passes Arguments: var[$]=ocx_idproperty[$]([args]),ERR=stmtref

Methods are also invoked using the property operator. Optional arguments are enclosed in the
parentheses appended to the property name. Arguments are converted using the following rules:
Strings Copied and converted to OCX BSTR
Numerics Sent as LONG, except for integers, which are sent as SHORT

Examples:
x=ocx_idMethod(arg1,arg2)
x=ocx_idMethod()
You can only pass variables to an OCX / COM / ActiveX object, either by reference or by value. (Passing
by reference means that ProvideX will pass a memory pointer. Passing by value means that ProvideX will
pass the data. To pass a variable by reference, prefix the variable name with an asterisk.
y=xDoSomething(X$) ! Passes X$ address (memory pointer)
y=xDoSomethingElse(Y) ! Converts Y to LONG and passes the value of Y
Format 6 Removes / Disconnects OCX: DELETE OBJECT ocx_id

Use Format 3 to remove or disconnect an associated OCX / COM / ActiveX object from the screen.
NOTE: An OCX / COM / ActiveX object is automatically destroyed when the window it was
defined in is dropped.
Example:
0010 DEF OBJECT handle,@(2,2,70,16)="Shell.Explorer"
0020 errcode=handleNavigate2("www.pvx.com")
0030 input *
0040 DELETE OBJECT handle

ON ... GOSUB Conditional Subroutine Execution
Directive ON ... GOSUB
Format:
ON Case, Do Subroutine ON num GOSUB stmtref,stmtref,...
Where =
num Value determines the location to which to transfer. Numeric expression. Integer
range: -32768 to +32767.
stmtref, Program line number or statement label to which to transfer control.
Description:
Use the ON...GOSUB directive to transfer control to a subroutine at one of the statement references in
your list, based on the numeric value you supply:
if value <=0 control is transferred to the first statement specified
if value =1 control is passed to the second statement number specified
if value =2 control is passed to the third, and
for 3 nnn control is passed sequentially.
Control is passed to the final statement in your list if your numeric value exceeds the number of entries in
the list minus one.
As in the GOSUB directive, if your statement number doesn't exist, control transfers to the statement with
the next higher sequence number.
See also: GOSUB ... RETURN Execute Subroutine, p. 165(d)
Example:
0020 ON X GOSUB 0100, 0200, 0300, 0400, 0500
ON... GOSUB
X < or = 0 Transfers to 0100
X=1 Transfers to 0200
X > or = 4 Transfers to 0500

ON ... GOTO Conditional Transfer of Control
Directive ON ... GOTO
Format:
ON Case, Transfer Control ON num GOTO stmtref,stmtref,...
Where =
num Value determines the location to which to transfer. Numeric expression. Integer
range: -32768 to +32767.
stmtref, List of statement references. Use program line numbers or statement labels to which
to transfer control conditionally.
Description:
Use the ON...GOTO directive to transfer control to one of the statements listed based on the value you
provide:
ON... GOTO
Val <=0 Control is transferred to the first statement specified
Val =1 Control is passed to the second statement number specified
Val =2 Control is passed to the third, and
Val up to nth Control is passed sequentially.
Control is passed to the final statement in your list if your numeric value exceeds the number of entries in
the list minus one.
As in the GOTO directive, if your statement number doesn't exist, control transfers to the statement with
the next higher sequence number.
When you use the ON ... GOTO directive in a compound statement, it must be the final directive.
See also: GOTO Transfer within Program, p. 166(d)
Example:
0020 ON X GOTO 0100, 0200, 0300, 0400, 0500
ON... GOTO
X < or = 0 Transfers to 0100
X > or = 4 Transfers to 0500

OPEN Open a File for Processing
Directive OPEN
Format:
1 OPEN File/Device Channel OPEN (chan[,fileopt])string$

2 OPEN INPUT OPEN INPUT (chan[,fileopt])string$
3 OPEN LOCK OPEN LOCK (chan[,fileopt])string$
4 OPEN OPEN PURGE (chan[,fileopt])string$
5 OPEN LOAD OPEN LOAD (chan[,fileopt])string$
Where =
chan Channel or logical file number to assign to the file.
fileopt File option(s). Valid options for OPEN include:
BSZ=num Block size
IOL=iolref Default IOLIST
ISZ=num Open file in binary mode
NBF=num Dedicated number of buffers
OPT=char$ File OPEN options
For more information, see About File OPEN Options, p. 300.
string$ Name of the file or device to open. Your string expression can include a specialty
filename or file tag (e.g. *MEMORY*, [RPC], etc .).
Description:
Use the OPEN directive to open your file or device and assign a logical file number to it.
NOTE: When you use named pipes in your OPEN statement, you must indicate whether you
will READ from or WRITE to the pipe. Use OPEN INPUT with a named pipe to notify
ProvideX that you will be READing from the named pipe. Use a standard OPEN with
a named pipe if you will be issuing WRITEs to the pipe.
See also: CLOSE Close File, p. 47(d)
OPT( ) Return File OPEN Options, p. 303(f)
Format 1 for File / Device: OPEN (chan[,fileopt])string$...

Your given file or device must be OPENed before your program can gain access to it. You can normally
have a maximum of 127 files open at any time in a ProvideX session (less under some Operating
Systems). In the extended file access mode 'XF' you can OPEN up to 65000 files.
As of Ver. 4.20, you can use a colon (:) at the end of a filename when opening an LPTn port number
directly. For instance, LPT1 and LPT1: are now considered to be the same device.
NOTE: The actual number of files you can OPEN at any one time depends on Operating
System parameters. Consult your system configuration information for details on
how to increase the number of files you can open.

Example:
0010 OPEN (2,ERR=1000)"CSTMER"
0020 INPUT "Enter customer number: ",C$
0030 READ (2,KEY=C$)C1$,C2$,C3$,C4$,A,B,C
1000 PRINT "No customer file exists or file is busy"
1010 STOP
Error Messages on OPEN

If you use a channel that is already OPEN, ProvideX returns an Error #14. If you try to OPEN a file that
doesnt exist, it returns an Error #12: File does not exist (or already exists). In some
circumstances (e.g. in trying to OPEN a printer twice), an Error #0 is generated. For example:
-:KEYED "TEST",[1:1:6],,128
-:OPEN (5)"TEST"
-:OPEN (5)"TEST" ! Not okay: channel 5 is already in use
-:OPEN (4)"TEST" ! Okay - "TEST" file can be OPEN on two channels
-:OPEN (30)PRINTER$
-:OPEN (10)PRINTER$ ! Not okay: PRINTER$ device cant be OPEN on two channels
Error #0: Record/file busy
About File OPEN Options

Use the OPT= parameter to define options for WINDOWS COM ports. That is, in the WINDOWS
environment you can specify communications port settings for COM ports by adding, for example,
OPT="9600,n,8,1,x" where the values represent baud rate, parity, data bits, stop bits and xon/xoff
flow control. See also COM Ports and Serial Devices, p. 567.
NOTE: If you don't use the OPT= option for communications settings, ProvideX will
default to the setup in the WINDOWS Control Panel.
Use the IOL= option to define a standard IOLIST to be used while the file is open. ProvideX will use this
IOLIST for all subsequent file READ, WRITE, EXTRACT, or FIND statements where you don't explicitly
supply variable lists. You can also use the REC= option to supply a prefix to be added to all the
variables in the IOL= specification.
If you use the ISZ= option, ProvideX opens the file in binary mode. That is, ProvideX makes no attempt
to analyze the file structure or contents. All subsequent access to the file / channel is done as if the file
is an INDEXED file with a record size equal to the value set in your ISZ= option.
If you use ISZ=1, a READ RECORD directive will return 1 byte at a time (each logical record is 1 byte).
For ISZ=1024, the data is returned 1024 bytes at a time, with the first 1024 bytes in IND=0, the next
1024 bytes in IND=1 and so on. You can gain access to the file sequentially or by using the INDex. A
negative value notifies ProvideX to return up to the given number of bytes.
If you use ISZ=-1, ProvideX will not append record terminators to output lines PRINTed to a file
without a hanging comma. (Normally ProvideX appends a Line Feed to the end of such output lines in
UNIX, or a Carriage Return and Line Feed in WINDOWS and to the end of every record written to a
SERIAL file.)
If you use the BSZ= option, file access will be buffered in a buffer equal to the size you set for the option.

OPEN with PREFIX FILE Definition
You can have two fields in a PREFIX FILE data record. The first is the path/filename of the real file to open.
The second is an options field. ProvideX uses any options in this field as the OPT=value(s) when
OPENing the real path/filename. As of Ver. 4.20, if you OPEN a filename assigned in a PREFIX FILE
directive, you can include additional OPT=values$ in the OPEN directive to have ProvideX append these
as additional options for the true file being opened (i.e. the filename in the PREFIX FILE record).
Example:
Given a PREFIX FILE record containing the following:
Key="GLMAST", DATA RECORD="[ODB]DSN;TABLE"+sep+"KEY=field1"
If you OPEN(chan)"GLMAST" internally ProvideX will:
OPEN(chan,OPT="KEY=field1")"[ODB]DSN;TABLE"
If you OPEN(chan,OPT="REC=somedata")"GLMAST" then internally ProvideX will:
OPEN(chan,OPT="KEY=field1;REC=somedata")"[ODB]DSN;TABLE"
Format 2 for Read-Only Mode: OPEN INPUT (chan[,fileopt])string$...

If you use the OPEN INPUT format, the program cant update the file (opened as READ-only). You should
use this format when opening a disk directory. The OPEN INPUT directive under UNIX will not lock a
character mode device.
Format 3: OPEN LOCK (chan[,fileopt])string$..

If you use the OPEN LOCK format, the file is reserved for exclusive use prior to the OPEN. However, if
another user already has the file OPEN, the LOCK format of the directive fails and ProvideX returns an
Error #0: Record/file busy.
NOTE: Under UNIX, /dev/null and /dev/console files are not locked when OPENed. However,
all other files are.
WindX Example
0010 BEGIN
0020 PRINT CS
0030 !
0040 LET IN_FILE$=%WDX$+"D:\DATA\BATCH\R0000188"

0050 LET O_FILE$="D:\JUNK\TEST\TST_OUT"
0060 EXECUTE "[WDX]ERASE "+O_FILE$+",ERR=*NEXT"
0070 EXECUTE "[WDX]SERIAL ""D:\JUNK\TEST\TST_OUT"""
NOTE: As of Ver. 4.20, WindX now supports the use of SERIAL and ERASE commands via
the [WDX] tag. It is no longer necessary to embed these commands in an EXECUTE
directive. (If you are running an earlier version of ProvideX on a WindX PC, you still
need to encapsulate these commands in an EXECUTE "[WDX]..." directive, as in lines
0060 and 0070 above.) See also [WDX] Tag: Directs Action to Client Machine, p. 626.
0130 LET NO_FILE$="Y"
0140 LET IN_FILE=HFN; OPEN (IN_FILE)IN_FILE$
0150 LET F$=FIN(IN_FILE)
0160 CLOSE (IN_FILE)
0165 LET PD=POS(DLM=IN_FILE$,-1); IF PD<>0 THEN LET INN_FILE$=IN_FILE$(PD+1)

0165:ELSE LET INN_FILE$=IN_FILE$
0170 LET CHARS=DEC(F$(1,4))
0180 !
0190 LET BLK_SIZE=1024,DONE$="N",C=0
0200 IF CHARS<BLK_SIZE THEN LET BLK_SIZE=CHARS
0210 !
0220 OPEN (IN_FILE,ISZ=BLK_SIZE)IN_FILE$
0230 LET O_FILE=HFN; OPEN LOCK (O_FILE,ISZ=BLK_SIZE)%WDX$+O_FILE$
0250 LET CUR_BYTE=0,ST_BYTE=0,SE_BYTE=0
0260 LET R_C=BLK_SIZE
0500 ! 500
0510 ! Get Pos Of First ISA
0520 !
0530 READ RECORD (IN_FILE,END=0700)IN_REC$
0540 LET L=L+1; PRINT @(0,5),L
0550 WRITE RECORD (O_FILE)IN_REC$
0555 LET BY=BY+LEN(IN_REC$)
0556 LET TST=CHARS-BY; IF TST<BLK_SIZE THEN LET R_C=TST
0590 GOTO 0530
Format 4: OPEN PURGE (chan[,fileopt])string$

If you use the OPEN PURGE format, the file will be locked and pre-cleared (PURGEd) prior to the
completion of the OPEN statement.
Format 5: OPEN LOAD (chan[,fileopt])string$

If you use the OPEN LOAD format, ProvideX assumes that the file is a static keyed file and OPENs it for
READ access only. ProvideX assumes that the file is a static keyed file. That is, no other task on the
system will update this file. Whenever a portion of the file's key structure is read into memory, ProvideX
keeps it in memory until you CLOSE the file. ProvideX gives you extremely fast access to static files by
reducing the disk I/O and effectively caches the file in memory.

OPT( ) Return File OPEN Options
Function OPT( )
Format:
Return OPT=Value OPT(chan[,ERR=stmtref])
Where =
Returns: Value you used in OPT= option
Description:
The OPT( ) function returns the value you used in the OPT= option of your OPEN directive for the given
file. If the file you refer to in your OPT( ) function is not OPEN, ProvideX returns an Error #13: File
access mode invalid. If you omitted the OPT= option for an OPEN file, the OPT( ) function returns a
NULL string.
Use this function primarily with device drivers to deal with such processes as generating banners and
multiple copies.
Example:
0040 ! Report OPT( ) value for open COM port:
0050 LET SETTINGS$="9600,n,8,1,x"
0060 LET PORT$="COM2"
0070 OPEN (1,ISZ=1,OPT=SETTINGS$)PORT$
0080 PRINT OPT(1)
0090 END
-:run
9600,n,8,1,x

PAD( ) Pad/Truncate String
Function PAD( )
Format:
Pad/Truncate String PAD(string$,len[,pad_code][,char$][,ERR=stmtref])
Where =
string$ String expression to be processed.
len Desired length of string. Numeric expression.
pad_code Optional numeric parameter defining how to pad the string:
0 = Pad on left (right justify)
1 = Pad on right (left justify)
2 = Center in string
char$ Optional string: its first character is used to pad the string$. If you omit this, the
default is to pad with blanks. String expression.
Returns: String converted to given length
Description:
The PAD( ) function converts your given character string to the length you specify. It makes the string the
desired length either by truncating the string$ or by appending the defined pad character. The default is to
pad with spaces.
The PAD( ) function can return a string to a maximum length of 32767 characters. If the length you specify
is less than zero or greater than 32767, ProvideX returns an Error #41: Invalid integer
Example:
0180 LET CHQ_AMT=1.98,CUST_NAME$="ACME INC."
0190 LET CHQ_AMT$="*****"+PAD(STR(CHQ_AMT),30,"*")
0200 PRINT 'CS',@(0,5),"Customer name :",PAD(CUST_NAME$,20),"| ",
0210 PRINT @(0,6),CHQ_AMT$
-:run
Customer name :ACME INC. |
*****1.98**************************

PASSWORD Password Protect Program Code
Directive PASSWORD
Format:
1 Define/Create PASSWORD prog_password$

2 Common Password PASSWORD *[,prog_password$]
Where =
prog_password$ Password you choose for program protection. String expression.
* The asterisk defines a password as common to all your programs.
Description:
Use the PASSWORD directive to assign and remove your programs passwords. Passworded programs
cannot be listed or edited in ProvideX in any way unless the correct password is used.
See also: 'EL' Encryption Level, p. 543(p)
Format 1 Creates Password: PASSWORD prog_password$

To assign a password, load the program, enter the PASSWORD directive followed by your choice of
password and then SAVE the program.
To remove a password temporarily (so that you can edit and list your program) reload the program, enter a
PASSWORD directive followed by the previously assigned password. Then you can either renew the
same password or:
change the password, using a different string as the new password, or
remove password protection from a program by using a NULL string instead of a password.
Format 2 Creates a Common Password: PASSWORD *[,prog_password$]

Use the asterisk to denote a common password. ProvideX will apply a common password automatically to
all previously passworded programs when they are LOADed and to all new programs.
Example:
->LOAD "MYPROG"
->PASSWORD "CAT"
->SAVE "MYPROG"
->LOAD "MYPROG"
->LIST
Error #52 -- Program password protected
->DELETE 10
Error #52 -- Program password protected
->PASSWORD "CAT"
->LIST
0010 REM...
0020 ... etc.

PCK( ) Pack Numeric Data
Function PCK( )
Description:

Use this function to pack numeric data in a format compatible with use in older Business Basics. ProvideX
supports this function only for conversion from other Business Basics. See other Business Basic manuals
for information on the use of this function.

PERFORM Call Subprogram, Pass All Variables
Directive PERFORM
Format:
Execute Subprogram PERFORM subprog$[;entry$][,ERR=stmtref]
Where =
subprog$ Name of the subprogram to execute. String expression.
;entry$ Name of starting statement label to use as entrypoint in the subprogram. Optional.
If included, add to the subprogram string expression (e.g. PERFORM
"MY_SUBPROG;STARTING_LABEL").
Description:
Use the PERFORM directive to load and execute a subprogram. During execution, ProvideX SAVEs the
calling program when it encounters the PERFORM directive. When the subprogram terminates (on an
EXIT, END, or STOP directive), control returns to the calling program at the directive following the
PERFORM directive.
Warning: All variables are made common to both the calling program and the subprogram (i.e.
variables changed or created in the PERFORMed subprogram will be returned to the
CALLing program).
You can specify an optional statement label in the calling program as an entrypoint for the subprogram. To
do this, append a semicolon and the starting label name to the subprogram name in your PERFORM
directive (e.g. PERFORM "SUBPROG;STARTING_LABEL"). After the subprogram is loaded, ProvideX
internally issues a GOTO directive using the label as a statement reference and starts execution there.
You can use this feature to create subprograms to act as "libraries" (i.e. multiple stand-alone routines, each
starting at its own entrypoint).
RUN Transfer and Execute a Program, p. 368(d)
Example:
This is the calling program:
0180 LET Z=1,X=2,A$="Cat",B$="Pig*****Dog",V=9
0190 PRINT "Values before PERFORM:",@(26),Z,X,A$,B$,@(45),V
0200 PERFORM "ABCDEF;TEST",ERR=9000
0210 PRINT "Values after PERFORM: ",@(26),Z,X,A$,B$,@(45),V,ZZ$
0220 STOP
->RUN
Values before PERFORM: 1 2CatPig*****Dog 9
TEST in subprogram ABCDEF
In PERFORM 1 2CatPig*****Dog 9
Change : 6 7Pig****Cat**** 4 I'm new, from ABCDEF
Values after PERFORM: 6 7Pig****Cat**** 4 I'm new, from ABCDEF
This is the subprogram:
0040 TEST: PRINT "TEST in subprogram ABCDEF"
0060 PRINT @(8),"In PERFORM",@(26),Z,X,A$,B$,@(45),V
0070 LET Z=6,X=7,A$="Pig",B$="****Cat****",V=4,ZZ$=" I'm new, from ABCDEF"
0080 PRINT @(8),"Change : ",@(26),Z,X,A$,B$,@(45),V,ZZ$
0090 EXIT

PFX Current Prefix Setting
String System Variable PFX
Returns: String, current PREFIX entry 0 (zero)
Description:
This string system variable returns a string reporting the current setting of your ProvideX PREFIX directive
(PREFIX entry 0 only).
See also: PREFIX Set File Search Rules, p. 318(d)
Example:
->?PFX
\PGMS\===\ \PGMS\====\ \PGMS\CUST\CASHRCPT\ \PGMS\CUST\MSC\ \PGMS\CUST\SALES\

PFX( ) Return Prefix Value
Function PFX( )
Format:
1 Return Specific Prefix PFX(num)[,ERR=stmtref ])

2 Return Prefix for PGN PFX(PGN[,ERR=stmtref])
Where =
num PREFIX number to use. Numeric expression.
Returns: String, current value of given PREFIX
Description:
The PFX( ) function returns the current value of your given PREFIX number. If no PREFIX has been
defined, the function will return a NULL string. If your specific PREFIX has been DISABLED, ProvideX
returns an Error #14: Invalid I/O request for file state. (Use an ERR=option to transfer
control on the error.)
You can obtain the PREFIX FILE value by using PFX(-1). The PFX system variable contains the current
PREFIX(0) (i.e. zero) value.
PFX Current Prefix Setting, p. 308(v)
Example:
4000 REM
4010 LET I=-1
4020 LET X$=PFX(I,ERR=4050)
4030 PRINT "PREFIX("+STR(I)+")=",X$
4040 IF I<=8 THEN LET I=I+1; GOTO 4020 ELSE GOTO 4060
4050 PRINT "PREFIX("+STR(I)+")=DISABLED"; GOTO 4040
4060 PRINT "PREFIX PGN=",PFX(PGN);STOP
->GOTO 4000
->RUN
PREFIX(-1)=
PREFIX(0)=\OTHER\===\ \OTHER\CUST\CASHRCPT\ \OTHER\CUST\MSC\ \OTHER\CUST\SALES\
PREFIX(1)=DISABLED
PREFIX(2)=\MANUALS\===\ \PVX\TESTS\
PREFIX(3)=
PREFIX(4)=
PREFIX(5)=
PREFIX(6)=
PREFIX(7)=
PREFIX(8)=
PREFIX(9)=
PREFIX PGN=\OTHER\PGMS\===\ \OTHER\PGMS\PVX\ \OTHER\PGMS\CUST\

PGM( ) Return Program Line
Function PGM( )
Format:
Return Compiled Format PGM(lineno[,prog_level][,ERR=stmtref])
Where =
lineno Statement line number. Numeric expression. Use an integer from 1 to 64999. (You
can use -1 or -2 instead, to return program names. See below.)
prog_level Optional numeric value indicating which program level to return. Numeric
expression.
Returns: String, compiled format of statement
Description:
The PGM( ) function returns a string containing the internal (ProvideX) format of your given program
statement number. If you use -1 as your line number instead, your main (level 1) program name is
returned. If you use -2, the current program name is returned.
1030 SWAPTST:
2:
2:A$=PGM(-1)
2:B$=PGM(-2)
2:PRINT A$," | ",B$
C:\OTHER\PGM\PVX_MAINPR | C:\OTHER\PGM\PVX_SUBPR
If you use the ERR= option and your given statement number does not exist, ProvideX returns an Error
#21: Statement number is invalid and control is transferred to your ERR= statement reference.
If you omit the ERR= option and the statement number does not exist, ProvideX returns the next higher
statement.
Example:
0380 REM
0390 INPUT "Enter statement to display OR <F4> to Stop: ",A
0400 IF CTL<>4 THEN LET X$=PGM(A,ERR=0440) ELSE GOTO 0430
0410 PRINT LST(X$)
0420 GOTO 0390
0440 PRINT "Error Transfer Works"; STOP
64999 PRINT "Cannot find statement"; END
-:run
Enter statement to display OR <F4> to Stop: 400
0400 IF CTL<>4 THEN LET X$=PGM(A,ERR=0440) ELSE GOTO 0430
64999 PRINT "Cannot find statement"; END
Enter statement to display OR <F4> to Stop: <F4> (not printable)
DONE
-:run
Error Transfer Works

PGN Current Program Path Name
String System Variable PGN
Returns: String, name of currently LOADed program
Description:
This string system variable returns a string reporting the name of the currently LOADed program, complete
with its full operating system pathname.
Exception:
If you have the 'OP' (original program) system parameter set to ON, PGN returns only the program name
(i.e. without the expanded pathname).
See also: 'OP' Return Original Program Name, p. 552(p)
Examples:
0100 PRINT PGN
0110 SET_PARAM 'OP'
0120 PRINT PGN
-:run
C:\PVX\MANUAL\TST\TST_EGS
TST_EGS

POP Premature Exit from Stack
Directive POP
Format:
Premature Exit from Stack POP
Description:
Use this directive to POP or clear the top entry on the stack. The POP directive performs the same
operation as an EXITTO stmtref directive for terminating a FOR/NEXT or GOSUB operation except that
it continues with the next statement.
See also: EXITTO Premature Exit of FOR/NEXT, GOSUB, p. 134(d)

Use the POP mnemonic (not the POP directive) if you want to pop a child window superimposed on a
parent window.
Example:
Note that ProvideX will generate an Error #28: No corresponding FOR for NEXT if it encounters
a NEXT directive after you POP a FOR loop. In this example, the POP directive is used to terminate a
FOR loop, leaving the GOSUBs RETURN entry on the stack. (No Error #28 is generated.)
0100 GOSUB SCAN_FOR_IT
...
1000 SCAN_FOR_IT
1010 FOR I=1 TO 1000
1020 IF X$=[I]="MOOCOW" THEN POP; RETURN
1030 NEXT
1040 PRINT "NOT FOUND"; RETURN

POS( ) Scan String
Function POS( )
Format:
Scan String POS(pattern${:^=...}string$[,step[,instance]][,ERR=stmtref])
Where =
pattern String value or expression to scan for.
: ^ = ... Relationship operators. Define the relationship for the string comparison:
: colon to search for any of the pattern characters in the string$
^ caret to search for first instance of a character in string$ not in pattern$.
= equals sign to search for exact match
<> greater and/or less than symbols, etc.
string$ String value or expression to be scanned
step Increment value of the intervals. Optional. Numeric expression.
instance Numeric expression tells ProvideX which occurrence(s) to report when the pattern is
found in the string.
Returns: Integer, starting position where relationship is satisfied (0 if none)
Description:
The POS( ) function scans your string$ to determine where a portion of it will satisfy the relationship with
the pattern string. The function returns an integer reporting the starting position in the string$ where the
relationship is satisfied, or 0 (zero) if no position satisfies the relationship.
Use your step value to set the logical increment for the next position to be checked. The default is to move
one (1) position at a time. If the value of your increment is negative, then the string is scanned from back
to front.
Indicate the instance or occurrence for which you want to obtain the POS( ) value. If you omit this value,
the default is 1 (the first instance found). If the value you use for the instance is 0 (zero), the POS( )
function returns the total number of matches found.
Example:
0010 ! To find the POS( ) of $20$ (the blank) in the ASCII LCS string
0020 A$=LCS(*)
0030 B=POS($20$=A$) ! Returns B=33, start of printable characters in LCS string
0040 PRINT B,'LF',A$(B)
-:run
33 !"#$%&'()*+,-./0123456789:;<=>?@abcdefghijklmnopqrstuvwxyz[\]^_àbc ...
Other Examples:
Given A$="The quick brown fox"
POS("q"=A$) ! yields 5
POS("z"=A$) ! yields 0
POS("o"=A$) ! yields 13
POS("o"=A$,-1) ! yields 18 - Scan from end (fox)
POS("o"=A$,1,2) ! yields 18 - Second occurrence (fox)
POS("o"=A$,2) ! yields 13 - Checks every 2nd position
POS("r"<A$) ! yields 6 - "u" is first char. > "r"

POS(" b"=A$) ! yields 10
POS("kw":A$) ! yields 9
POS("o"=A$,1,0) ! yields 2 - there are two 'o's
POS("a"<=A$,1,0) ! yields 15 - there are 15 lowercase letters in the string
POS("hq eT"Â$) ! yields 6

PRC Precision Currently In Effect
Numeric System Variable PRC
Returns: Integer, range 0 to 14, current PRECISION
Description:
Except in scientific notation, this numeric system variable returns an integer reporting the current
PRECISION in effect, with a value in a range from 0 to 14. The default is 2 (two digits to the right of the
decimal point). If the mode is FLOATINGPOINT, then the value returned is in scientific notation. Either a
PRECISION -1 statement or a FLOATINGPOINT directive will activate scientific notation. A PRECISION
directive will cancel it.
Examples:
0010 PRECISION 14; FLOATING POINT ; LET A=7.1234
0020 PRINT PRC,@(10),A
0030 BEGIN ! Resets A=0, precision=2 (doesnt cancel scientific notation)
0050 LET A=6.1234
0070 PRECISION 2 ! Cancels scientific notation
0080 PRINT " ",PRC,@(11),A
-:run
.14E+02 .71234E+01
.2E+01 .0E+00
.2E+01 .612E+01
2 6.12

PRC( ) Round Number to Precision
Function PRC( )
Format:
Round to PRECISION PRC(num[,precision][,ERR=stmtref])
Where =
num Value to be rounded. Numeric expression
precision Precision to which to round. Optional. Numeric expression. Integer from 0 to 14. If
you omit this, rounding is done to the current precision in effect.
Returns: Your numeric value, rounded to a set precision
Description:
The PRC( ) function returns your given numeric value rounded to the set precision. If you only supply one
parameter, then the value is rounded to the current PRECISION in effect. If you use two parameters,
ProvideX takes the second parameter as the precision the PRC( ) function is to use in rounding your value.
Exception: A ROUND ON directive will truncate longer values to the current PRECISION in effect.
If you use an invalid value (e.g. >14), ProvideX returns an Error #41: Invalid integer
Example:
0010 LET A=PRC(1.3456); PRINT A,
0020 LET A=PRC(1.3456,0); PRINT @(15),A,
0030 LET A=PRC(1.3456,3); PRINT @(25),A,
0040 LET A=PRC(1.3456,2); PRINT @(40),A,
-:run
The results will vary, depending on current precision and rounding:
1.35 1 1.346 1.35-: ! PRECISION 2, ROUND OFF
1.35 1 1.35 1.35-: ! PRECISION 2, ROUND ON
.13456E+01 .1E+01 .1346E+01 .135E+01-: ! PRECISION -1

PRECISION Change Current Precision
Directive PRECISION
Format:
Set Numeric Precision PRECISION num
Where =
num Precision to which to round. Numeric expression. Integer range: 0 to 14, or use -1 to
switch to scientific notation.
Description:
Use the PRECISION directive to change the number of digits ProvideX maintains for you to the right of the
decimal point. (Internally, ProvideX makes all calculations using 14 digits of accuracy but when numeric
data is output the value is rounded and returned using the number of digits you set in your PRECISION
directive.)
ProvideX also uses your PRECISION setting with the ROUND directive. If rounding is enabled (default
mode), values assigned to variables in your LET directives will be rounded to the setting of your
PRECISION directive.
NOTE: Precision is automatically reset to two (2) by the following directives: BEGIN,
CLEAR, END, LOAD, RESET, STOP, RUN.
The FLOATINGPOINT directive overrides the PRECISION directive. You can use PRECISION -1 to have
ProvideX switch to FLOATINGPOINT (scientific notation). Use another numeric value in your PRECISION
directive (e.g. PRECISION 2) to cancel scientific notation.
Examples:
0010 FOR A=0 TO 6
0020 PRECISION A
0030 PRINT 1/3,
0040 NEXT A
-:RUN
0 0.3 0.33 0.333 0.3333 0.33333 0.333333 DONE
0060 PRECISION 7
0070 PRINT 1/3
0080 BEGIN ! Resets precision to 2
0090 PRINT 1/3; END
run
0.3333333
0.33

PREFIX Set File Search Rules
Directive PREFIX
Format:
1 Set Prefix 0 (zero) PREFIX [search_string$]

2 Set Any Prefix Number PREFIX (num)[search_string$]
3 Search Rules for Programs PREFIX PROGRAM [search_string$]
4 Search Rules in Keyed File PREFIX FILE [filename$]
Where =
num Numeric value between 0 (zero) and 9 which defines the PREFIX entry to use. If you
omit this value, the default is zero. Numeric expression.
search_string$ One or more pathname prefixes (search locations) you want ProvideX to search
when attempting to find files / programs. Optional string expression.
NOTES:
You can use a NULL string (i.e. PREFIX [(num)]"") or omit the string (i.e. PREFIX
[(num)]) to have ProvideX reset your PREFIX to NULL.
When you have more than one search location in your PREFIX directive, the different
locations must be space-separated. If you need to include a space within a directory
name, then that directory location must be enclosed in double quotation marks. For
example:
PREFIX "C:\Tmp\ C:\Usr\ ""C:\Program Files\"""
filename$ Name of a variable-length KEYED file containing data records which define the
locations of specific files (in effect, a lookup or translation table).
Description:
Use the PREFIX directive to define a series of search paths to be inserted in front of all relative file
references used in OPEN / LOAD / RUN / CALL / PERFORM directives. (ProvideX OPENs files with
absolute paths directly, without performing a search.)
Each PREFIX can contain 0 (zero) or more search locations. (A search location is either a directory or a
disk/directory pair.) You can specify up to 10 differently-numbered PREFIXes, i.e. PREFIX (0) through
PREFIX (9), as well as a PREFIX PROGRAM and a PREFIX FILE. See the descriptions of the various
formats, below.
See also: PREFIX Search Rules, p. 319
Equals Signs for Matching, p. 320
Asterisks as PREFIX Wild Cards, p. 320
Using the PREFIX Directive
Format 1 Sets Prefix 0 (Zero): PREFIX [search_string$]

If no numbered PREFIX is specified, then your PREFIX command affects PREFIX (0) by default. For
example, PREFIX "C:\TMP" would apply to PREFIX (0).

Format 2 Sets Any Prefix Number: PREFIX (num)[search_string$]
You can use this format to define a maximum of 10 numbered PREFIXes (range 0 to 9) to set file search
rules. The example below defines PREFIX (4):
PREFIX (4)"PGMS\CST\CASHRCPT\ \PGMS\MGMT\MISC\ \PGMS\SALES\"
Format 3 Sets Program Retrieval Rules: PREFIX PROGRAM [prefix$]

Use the PREFIX PROGRAM format to define the search location(s) ProvideX will search first when it
attempts to LOAD / RUN, CALL / PERFORM / or SAVE programs. For example:
PREFIX PROGRAM "\other\pgm\tst\"

If you omit the prefix string or use a NULL string (i.e. PREFIX PROGRAM ""), ProvideX will reset your
program prefix to NULL.
Format 3 Using Paths in Keyed File: PREFIX FILE [filename$]

Use the PREFIX FILE format to do dynamic translations of filenames in your applications by defining a
KEYED file as a lookup table. Any file you define as a PREFIX FILE must be a variable-length KEYED file
or ProvideX returns an Error #17: Invalid file type or contents.
If you define a PREFIX FILE, then ProvideX searches this special KEYED file for a search location
whenever it encounters an OPEN command with a relative filename, using the filename in your OPEN
directive as the key to the PREFIX FILE. (Reminder: ProvideX OPENs filenames with absolute paths
directly, without performing a search.) The normal PREFIX search rules still apply after a filename has
been located in the PREFIX FILE.
When you write to this special KEYED file, treat the filename from your programs OPEN command as the
KEY. The data record for each key contains the true filename you want opened instead. (ProvideX
retrieves the data record internally with a READ RECORD.)
Example:
KEYED "someloc.dat",25
OPEN(chan)"someloc.dat"
WRITE RECORD(chan,key="myfile")"c:\tmp\myfile"
CLOSE(chan)
PREFIX FILE "someloc.dat"

OPEN(chan)"myfile ! Internally this becomes OPEN(chan)"c:\tmp\myfile" instead
PREFIX Search Rules

The ProvideX default is to search all prefixes, in the following order:
For OPEN Directives For LOAD / RUN / CALL / PERFORM / SAVE

1) PREFIX FILE, if set. (Replaces pathname then 1) PREFIX FILE if set (Replaces pathname then
continues sequence) continues sequence)
2) Current Directory (if CD System Parameter is 2) Program Cache
set) 3) Current Directory (If CD System Parameter is
3) PREFIX 0 to 9 set)
4) PROGRAM PREFIX, if set 4) PREFIX PROGRAM if set
5) Current Directory (if CD System Parameter not 5) PREFIX 0 to 9
set) 6) Current Directory (if CD System Parameter
not set)

The PREFIX search rules apply not only to files being found, but also to files being created. ProvideX
creates files in the first location that is permitted by the PREFIX rules. If CD (Search Current Directory) is
on, then all files are created in the current directory (the first permitted location). If the CD system
parameter is off, then ProvideX creates your file in the first location permitted by the search rules above.
WINDOWS search rules are used to find DLLs (not PREFIX search rules or current directory).
You can use the ENABLE and DISABLE directives to control which of the numbered prefixes ProvideX will
use in the search. (While scanning PREFIXes 0 to 9, ProvideX ignores any PREFIX that is DISABLEd.)
Note that the initial check for PROGRAM cache checks for a match against the original file names. Thus,
if you used CALL "ABCD" and you had previously loaded a program with the same name, ProvideX would
use the one in cache. This eliminates the directory searches involved, but if you have duplicate program
names in your system, it is possible to get the wrong one, for instance, if you CALL "ABCD" and then
change your directory / prefix and re-CALL "ABCD". If this happens for duplicate program names in your
system, either clear the CACHE or dont use it.
See also: DISABLE Disable Use of Prefix Table Entry, p. 90(d)
ENABLE Re-Enable Use of Prefix Table Entry, p. 110(d)
'CD' Check Current Directory, p. 540(p)
Equals Signs for Matching

Equals signs in your PREFIX search_string$ have special meaning. Each character of the filename that
corresponds by position to an equals sign will be used to form a subdirectory name to be used in the
search. For instance, if you include 1 equals sign, ProvideX will interpret that to mean that the first
character of your filename is also the subdirectory name. If you include 2 equals signs, it will take the first
2 characters as matching the subdirectory name, and so on.
ProvideX automatically finds the location to retrieve or create files by looking first for a subdirectory with a
name matching, character-by-character, in sequence, the portion of your filename that corresponds to the
equals signs. This allows you to sort files into subdirectories based on automated substitution of the first
few characters of your filename and accelerates the search for and / or creation and saving of files in
subdirectories.
Example:
PREFIX (4)"C:\MYAPP\==\" ...
If a directory entry in a PREFIX contains equals signs as shown in the example above, ProvideX evaluates
the initial two characters as matching characters and uses them as the name of the subdirectory where the
search will commence for relative file references. For example:
PREFIX "C:\MYAPP\==\"
OPEN (1)"ARHIST"
ProvideX evaluates the filename ARHIST as C:\MYAPP\AR\ARHIST for purposes of the initial search.
Asterisks as PREFIX Wild Cards

(Ver. 4.20) You can also use * and ** as wild-card characters to support the use of filename extensions
without modifying your code. This feature was added to the ProvideX language as of Ver. 4.20 primarily for
WINDOWS 2000 users, since the Microsoft Certification rules for WINDOWS 2000 require that all files
have file extensions. With the wild-card characters, you can rename your files on disk with a common file
extension without modifying your program code.
Using a Single Star (*):

If your PREFIX directive includes an asterisk plus a specified extension as a filename, ProvideX inserts the
filename from your OPEN command in place of the asterisk and searches first for your filename with the

extension you specify in the PREFIX.
For example, with:
PREFIX "c:\somedir\*.PRG"
OPEN(chan)"FOOFOO"
ProvideX will scan the disk for "c:\somedir\FOOFOO.PRG" and OPEN that file if found. If FOOFOO.PRG
is not found, ProvideX will attempt to find and OPEN a file named "FOOFOO".
Using Two Stars (**):

If your PREFIX directive includes two asterisks plus a specified extension as a filename, the substitution
described above for a single star will occur only if your OPEN directive includes a simple filename (i.e., a
filename without an extension). If your filename is complex (e.g. MY_FILE.DAT), no substitution occurs.
For example, with:
PREFIX "c:\somedir\**.PRG"
OPEN(chan)"FOOFOO"
OPEN(nahc)"MyFile.Dat"
since OPEN (chan)"FOOFOO" contains a simple filename, ProvideX will look first for
"c:\somedir\FOOFOO.PRG", then, if not found, for "FOOFOO". Since MyFile.Dat is a complex
filename and two stars are used in the PREFIX filename, ProvideX doesnt add a .PRG extension to
MyFile.Dat when it executes the search to find and OPEN the file.

PREINPUT Place Data in Input Queue
Directive PREINPUT
Format:
1 Preinput Value + CTL PREINPUT string$[,ctl_val]

2 Preinput CTL Only PREINPUT ctl_val
3 Jumping the Queue PREINPUT NEXT
Where =
string$ String expression. Placed in the input queue for the users terminal.
ctl_val Value to be placed in CTL when the input is processed. Numeric expression.
Description:
Use the PREINPUT directive to have your program prime the input buffer for the users terminal with a
value. You can issue more than one PREINPUT directive, with the messages queued. You can also use
this directive to have subprograms respond to INPUT statements in the calling or subsequent programs.
Format 1 Preinput Value, CTL: PREINPUT string$[,ctl_val]

You can preinput your string$ value and set the optional CTL value to be returned. In this format, the first
PREINPUT data will be processed first (FIFO).
Format 2 Preinput CTL Only: CTL PREINPUT ctl_value

You can add your PREINPUT CTL value alone to the queue.
Format 3 Jumps the Queue: PREINPUT NEXT

When you use this format your PREINPUT entry goes to the front of the queue (LIFO).

PRINT Display Information
Directive PRINT
Format:
1 Print PRINT [(chan,fileopt)]varlist

2 ? = PRINT ? [(chan,fileopt)]varlist
Where =
? ProvideX accepts the question mark "?" as a substitute for the word "PRINT"
chan Channel or logical file number of the target device (terminal or printer) or SERIAL file
for a display or print job. The users terminal is always defined as 0 (zero).
fileopt File options. Valid options for PRINT include:
varlist List of variables, literals, expressions, mnemonics, IOL= options, and/or location
functions'@(...)'. Items in the list must be comma-separated.
Description:
Use the PRINT directive to format and send printable data to a terminal, printer or file. If the print
statement ends with a trailing comma, the output from a subsequent PRINT directive will continue on the
same line. Otherwise, it will start at the first column of the next line. If you omit a format mask for a
numeric in your PRINT statement, the DP and TH System Parameters, p. 537 European decimal
settings are ignored.
ProvideX accepts the question mark ? as a substitute for typing the word PRINT.
NOTE: Because of the potential conflict between the function AND( ) and the logical operator
AND, there is a problem when the syntax processor tries to parse the statement
PRINT AND($41$,$42$). You can work around this either by assigning the result of
a logical AND to a temporary variable or by changing the statement to PRINT
""+AND($41$,$42$).
Examples:
PRINT 'CS',"Date:",DAY," Time:",TIM is the same as ? 'CS',"Date:",DAY," Time:",TIM.
Both result in the same date and time display on a clear screen (Date:02/22/00 Time: 8.398397).
You can assign a page or screen position for your PRINT data:
1010 PRINT @(5,5),"CUSTOMER LISTING",! prints to screen at column 5, line 5
You can PRINT data overlaying a graphic in ProvideX, but only if all text output is sent using FONT and
TEXT mnemonics (rather than as standard PRINT statements). In the example below, "Hello" will overlay
the embedded bitmap.
0010 PRINT 'CS'
0020 PRINT 'PICTURE'(220,210,600,500,"!Binoculars",2),
0030 PRINT 'FONT'("MS Serif",-20); PRINT 'GREEN','TEXT'(220,210,"Hello")

PRM Current ProvideX Parameter Settings
String System Variable PRM
Returns: String, comma-delimited list of system parameter settings
Description:
This string system variable returns a comma-delimited string listing the current settings of O/S parameters
for ProvideX use. See also System Parameters, p. 537. Some parameters only appear in the list if set
and some are O/S specific.
Examples:
PRINT PRM ! Version 4.20 WINDOWS settings
-'3D',-'AD',-'AH','AI'=10,-'B0','BF'=10,-'BT',-'BX','BY'=1970,-'CD','CS','CT'=0,
'CU'=36,-'D0','DC','DF'=0,'DL'=0,'DP'=46,'DT'=0,'DW'=0,-'EG','EL'=0,-'EO',-'ES',
-'EX',-'F4','FB'=5,-'FC','FF'=0,-'FI','FO'=0,-'FU',-'FL','FP','FS'=138,-'FT',-'F
X',-'F,',-'I0',-'I2','IC',-'IM','IR','IS'=5,-'IZ',-'KR','LB'=4,-'LC',-'LD',-'LE'
,'LS'=1,-'LU',-'LZ','MB'=0,'MF'=50,-'MP','NE',-'NI',-'NK',-'NL',-'NN',-'NR',-'OC
','OL'=25,'OM',-'OP','OR','OW'=0,'PC'=10,'PD'=2,-'PO',-'PU','PW'=36,-'PZ','QF'=1
,'Q_'=2,'Q^'=2,-'QS',-'QT',-'RI','RN'=1,'RP',-'RR',-'RS',-'SC',-'SD',-'SF',-'SK'
,'SL'=32,-'SP',-'SR','SV'=1,'SZ'=32000,-'TB','TC'=0,'TH'=44,-'TL',-'TN',-'TT',-'
TU',-'TX','VP'=48,'VR'=0,'VW'=0,'WB','WD'=10000,-'WF','WH'=0,'WI'=1000,-'WK','WT
'=2,-'XC',-'XF',-'XI',-'XT',-'ZP',-'DD','!B'=3,'!U'=0,-'1U'
You can have the PRM( ) function return a specific parameters current setting (or the Boolean value,
1=ON / 0=OFF, for a switch), even when its hidden from the PRM listing.
->?prm('!i') ! hidden unless ON
0

PRM( ) Return Parameter Value
Function PRM( )
Format:
Return Parameter Value PRM(param[,ERR=stmtref])
Where =
param Two-character valid System Parameter code, enclosed in single quotes. See the
section on accepted System Parameters, p. 537. String expression.
Returns: Current value of system parameter, or status code if switch
Description:
The PRM( ) function returns the current value of the specified System Parameter unless the parameter is a
switch. These are the numeric status codes returned for a switch:
Value Description
0 (zero) if the switch is OFF,
1 if the switch is is ON, and
-1 if the specified parameter does not exist.
If the value is not a switch, this function returns the setting of the parameter.
The results returned by this function can be used to reset the parameters using the SET_PARAM directive.
Example:
Temporarily change the 'BY' parameter to obtain a new date.
0100 PRINT "Valentine days.."
0110 LET SV_BY=PRM('BY')
0120 FOR Y=1999 TO 2009
0130 SET_PARAM 'BY'=Y
0140 PRINT DTE(31+14-1:"%Dl %Ml %D/%Y")
0150 NEXT Y
0160 SET_PARAM 'BY'=SV_BY
-:run
Valentine days..
Sunday February 14/1999
Monday February 14/2000
Wednesday February 14/2001
Thursday February 14/2002
Friday February 14/2003
Saturday February 14/2004
Monday February 14/2005
Tuesday February 14/2006
Wednesday February 14/2007
Thursday February 14/2008
Saturday February 14/2009
You can have the PRM( ) function return a specific parameters current setting (or the Boolean value,
1=ON / 0=OFF, for a switch), even when its hidden from the PRM variables contents listing.
->?prm('!i') ! hidden unless ON

0
->?prm('by')
1970
->?prm('ah')
0
->set_param 'ah'
->?prm('ah')
1

PROCESS Call a NOMADS Panel
Directive PROCESS
Format:
1 Invoke a NOMADS Panel PROCESS "panel","[lib]",arg_1$,arg_2$, ... arg_20$

2 Invoke a NOMADS Query PROCESS "panel","[lib]",val$
3 Invoking File Maintenance PROCESS "panel","[lib]",arg_1$
Where =
panel Name of your NOMADS Panel, Query or File Maintenance object. String expression.
lib Optional. Name of the NOMADS library containing your panel_name. String expression.
If you use NULL (""), NOMADS uses your currently active Library.
arg_1$ ... to List of valid arguments for a Panel Object. Optional string expressions. You can use up
arg_20$ to 20 arguments. These arguments are accessible in the invoked Panel as values in the
reserved NOMADS variables ARG_1$ through ARG_20$.
For Query or File Maintenance objects, youre limited to one argument, the value of which
is accessible in the reserved variable ARG_1$. The others are reserved.
val$ Starting / return value for a Query. See the examples, below.
Description:
Use the PROCESS directive to call a NOMADS panel from your program. NOMADS returns you to your
program when the panel is exited. You can pass optional arguments to and from the NOMADS panel.
NOTE: When you use the PROCESS directive in ProvideX, ProvideX converts the statement
internally into a CALL to *winproc (the NOMADS engine) to process your panel.
See also: The ProvideX NOMADS Reference Guide (Ver. 4.20)
Panel Example:
In the example below, the ProvideX PROCESS statement invokes the SALES panel through your program
and passes two arguments (SALES_ID$ and STR(SALES_AMT) to the SALES panel to get the values:
PROCESS "SALES","LIBRARY.EN",SALES_ID$,STR(SALES_AMT)
In the NOMADS Panel Header Pre-Display Logic, you would Execute the following assignments:
SALES_ID$=ARG_1$;SALES_AMT=NUM(ARG_2$)
Query Example 1:
For queries that are not attached to a NOMADS control object:
0110 PROCESS "MY_QUERY","",X$
When MY_QUERY runs, the value of X$ is used to set the starting position in the file. When MY_QUERY is
exited, NOMADS passes the return value to the calling program in X$.
Query Example 2:
For attached queries. The argument is the starting / current value of the Control.
If a user presses a {query} button or <Shift-F2> to invoke your program PROCESSing the Query,
NOMADS uses the reserved variable QRY_VAL$ to pass the value of the Control to the program and back.
You can make use of this in a statement like PROCESS "MY_QUERY","MYLIB.EN",QRY_VAL$ or in
other statements in your program. For example:

0100 LET WHATEVER$=QRY_VAL$ ! Get the current value of the control
0110 ! Manipulate WHATEVER$ value if you want
0200 PROCESS "MY_QUERY","MYLIB.EN",WHATEVER$ ! WHATEVER$ Start & Return value
0210 ! Manipulate WHATEVER$ return value if you want
0300 LET QRY_VAL$=WHATEVER$ ! NOMADS loads this value back into the control
Query Example 3:
When you invoke a Query in a program, it's possible to pass more than one argument to the Query panel.
These arguments can be used further in the setup of the Query (query title, column headers, key prefix or
key range).
The only way to use these additional arguments in the "Select Logic" setup is to embed them in an EVS( )
function. For instance, to select only the records where a particular field has a required value, you would
do the following :
0100 PROCESS "qry","qrylib",qry_val$,required_value$
In the Select Logic of the Query, choose Test and make the following assignment (where n=field number to
test):
FLD#n$=EVS("arg_2$")
If you chose Call instead, you would have to use the following construct :
"program",FIELD$[n],EVS("arg_2$")

PROGRAM Create a Program File
Directive PROGRAM
Format:
Create Program File PROGRAM filename$[,prog_size][,ERR=stmtref]
Where =
filename$ Name of the PROGRAM file to create. String expression.
prog_size Ignored. Size of a program which can be contained in the file. Numeric expression.
Description:
Use the PROGRAM directive to create a ProvideX program file. The file size is for documentation
purposes only and is ignored by the system.
Program files have a special header format indicating that the file contains ProvideX object code. Program
files should only be used with the SAVE or LOAD commands. Any attempt to use READ or WRITE
directives with this type of file can yield unpredictable results when the program file is subsequently
LOADed.
If your given filename already exists, ProvideX returns an Error #12: File does not exist (or
already exists).
PROGRAM "[WDX]somefile.ext"... (If you are running an earlier version of
626.
Example:
0010 PROGRAM "PROG01"
0010 PROGRAM "CSTUPD",1024,ERR=1200

PSZ Current Program Size
Numeric System Variable PSZ
Returns: Integer, program size
Description:
This numeric system variable returns an integer reporting the current program size in bytes.
Example:
->?PSZ
2605

PTH( ) Return Pathname
Function PTH( )
Format:
Return Pathname PTH(chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file whose pathname is to be returned.
Returns: Pathname of OPEN file, given channel number
Description:
The PTH( ) function will return the Operating System path of the file you identify by logical file number.
(The value returned is an ASCII string reporting the full pathname, including directories and the file name.)
Your file must be OPEN for the PTH( ) function to operate.
Example:
With "C:\usr\ar" as current directory:
0010 OPEN (26)"PRODFL"
0020 PRINT "Just opened file: ",PTH(26)
0030 ....
RUN
Just opened file: C:\usr\ar\PRODFL
If your file is a device (e.g. a printer) the PTH( ) function returns the name of the device:
-:OPEN (30)PRINTER$
-:?PTH(30)
LPT1

PUB( ) Return Public Programs
Function PUB( )
Format:
Return ADDRessed Pgms. PUB(index[,ERR=stmtref])
Where =
index Index in the ADDR table for the entry to be returned. Numeric expression.
Returns: String, ADDressed program information
Description:
The PUB( ) function returns a string reporting the names, starting addresses and sizes of all programs for
which the ADDR directive is active. The information is returned as a character string containing the name
and description of each program ADDRessed.
The index indicates the relative program number in the ADDR table. ProvideX updates the table to
account for your subsequent ADDR and DROP directives and changes index numbers accordingly
(They're not static.) ProvideX returns an Error #41: Invalid integer encountered (range
error or non-integer) if no entry in the ADDR table exists for your given index.
The table below lists the contents of the 136 bytes in the string returned by the PUB( ) function:
Byte Contents
1 to 2 Program size in bytes
3 $01$
4 to 13 Reserved for ProvideX use
17 to 76 Name of program as given in ADDR
77 to 136 Path name to program
See also: ADDR Load and Lock Program in Memory, p. 15(d)
DROP Removes Program from Memory, p. 98(d)
Sample Returns:
0010 LET A$=PUB(1)
0020 PRINT A$(17) ! C:=$433A$, starts at position 17 (see below)
0030 PRINT HTA(A$)
-: run
C:\MANUALS\PVX\TEST
03BD0000000080C51000000000000000433A5C4D414E55414C535C5056585C54455354

PURGE Clear Data from a File
Directive PURGE
Format:
Clear Data from File PURGE (chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file to be purged.
Description:
Use the PURGE directive to erase all data from your given file number. Before you can execute the
PURGE directive, the file must be OPENed and LOCKed. A file erased using a PURGE directive still
exists in the system but contains no data. (ProvideX returns disk space to the system while preserving the
lock.) Any READ directives for a purged file return an End-of-File status.
Using the PURGE (or REFILE) directive is faster than deleting the file and recreating it.
NOTE: This directive is not supported by WindX. When you need to use it on a WindX PC,
encapsulate your command in an EXECUTE "[WDX]..." directive. See [WDX] Tag:
Directs Action to Client Machine, p. 626.
See also: REFILE Clear Data from File, p. 352(d)
LOCK Reserve File for Exclusive Use, p. 247(d)
Example:
0020 LOCK (2)
0030 PURGE (2)
0040 WRITE (2)TIM,DAY
...

QUIT Terminate ProvideX
Directive QUIT
Format:
End ProvideX Session QUIT
Description:
Use the QUIT directive to terminate your ProvideX session and return to the Operating System. If the ERR
variable's value is not zero (i.e. an error has occurred) then the Operating System is informed that an error
has occurred within ProvideX. This allows you to do external testing of error conditions.
When you use QUIT in a compound statement, it must be the final directive.
See also: BYE Terminate ProvideX, p. 32(d)
Examples:
8050 IF CTL=4 THEN QUIT
8060 REM
9900 END
-:SAVE
->QUIT

QUO The ASCII Quote(") Character
String System Variable QUO
Returns: ASCII quote (") character
Description:
This string system variable returns the ASCII quote character (").
Example:
0010 LET A=118
0020 LET B$="Oops! ... That didnt work."
0030 PRINT "Error message #",A," is not "+QUO+B$+QUO
-:run
Error message # 118 is not "Oops! ... That didnt work."

RADIO_BUTTON Define/Control RADIO_BUTTON
Directive RADIO_BUTTON
Format:
1 Define/Create RADIO_BUTTON [*]ctl_id:sub_id,@(col,line,wide,high)=contents$[,fileopt]

2 Delete RADIO_BUTTON REMOVE [*]ctl_id:sub_id[,ERR=stmtref]
3 Disable RADIO_BUTTON {DISABLE} [*]ctl_id:sub_id[,ERR=stmtref]
4 Enable RADIO_BUTTON {ENABLE} [*]ctl_id:sub_id[,ERR=stmtref]
5 Set Focus To RADIO_BUTTON GOTO [*]ctl_id:sub_id[,ERR=stmtref]
6 Logical Push/Release RADIO_BUTTON {ON | OFF} [*]ctl_id:sub_id[,ERR=stmtref]
7 READ Activation Mode RADIO_BUTTON READ [*]ctl_id,var,mode$[,ERR=stmtref]
8 Hide/Show RADIO_BUTTON {HIDE | SHOW} [*]ctl_id:sub_id[,ERR=stmtref]
Where =
* (asterisk) Optional. Use a leading asterisk to denote a global RADIO_BUTTON.
ctl_id Unique logical identifier for the group of related RADIO_BUTTONs. Numeric
expression. Integers, range: -32000 to +32000. Avoid integers that conflict with
keyboard definitions (e.g. function key CTLs like 4).
sub_id Unique individual RADIO_BUTTON sub_id. Use an integer, range: from 1 to 255.
(You can use this in your applications to identify which RADIO_BUTTON the user
selects.)
@(col,line, Position and size of the individual RADIO_BUTTON. Numeric expressions. Column
and line coordinates for top left corner, width in number of columns, height in number
wide,high)
of lines. Note that width and height are for the total area (box plus text/description).
Use line value -1 to display the RADIO_BUTTON on the toolbar.
contents$ Text/pictures to appear on the RADIO_BUTTON. As of Ver. 4.20, ProvideX supports
both {bitmaps} and {icons}. See RADIO_BUTTON Contents$, p. 337.
fileopt File options. Valid options for RADIO_BUTTON include:
OPT=char$ Single character parameters. See RADIO_BUTTON
OPT=char$, p. 337.
var Numeric variable. Receives the sub_id of the currently activated RADIO_BUTTON.
report the last method / keystroke the user chose to activate the RADIO_BUTTON
(e.g. $01$ for a <Mouse-Click> or $0D$ for <Enter>).
Description:
Use the RADIO_BUTTON directive to create and control a group of RADIO_BUTTON control objects on
the screen. A RADIO_BUTTON group is a series of related circular/radio-knob buttons (akin to check
boxes) of which only one button can be active at a time. When your user selects one of the
RADIO_BUTTONs, that selection is activated (ON) and all other related RADIO_BUTTONs are

automatically reset to OFF.
See also: BUTTON Define/Control BUTTON, p. 28(d)

RADIO_BUTTON Description
OPT=char$
B (Ver. 4.20) Bitmap Button: A bitmap button has a bitmap whose width is divided
into four images. You can use this attribute to custom design RADIO_BUTTONs of
any colour, style or shape by controlling the bitmap image that appears. Each of
the four divisions represents what your RADIO_BUTTON will look like in a
particular state:
1st quarter: Bitmap image when RADIO_BUTTON is disabled.
2nd quarter: Bitmap image when RADIO_BUTTON is in its normal
(released) state.
3rd quarter: Bitmap image when the mouse is over the RADIO_BUTTON.
4th quarter: Bitmap image when the RADIO_BUTTON is pressed.

broken into quarters (yielding, for instance, 12 bitmap images
for a group of three RADIO_BUTTONs).
D Disabled: User cannot access the RADIO_BUTTON.
F (Ver. 4.20) Flat Button: RADIO_BUTTON shows no raised outline unless the
mouse is over the RADIO_BUTTON or the RADIO_BUTTON is pushed.

For example: RADIO_BUTTON 1000,@(10,10,10,2)="&OK",OPT="F"
H Hide: Do not display the RADIO_BUTTON.
S Signal: Generates CTL value but does not alter focus.
Format 1 Creates: RADIO_BUTTON [*]ctl_id:sub_id,@(col,line,width,height)=contents$[,fileopt]

Use this format to create a RADIO_BUTTON. Unlike most other controls, related RADIO_BUTTONs share
the same ctl_id. That is, to group common RADIO_BUTTONs together, you define each member of the
group using the same ctl_id and a different sub_id (index). When your user makes a selection, other
RADIO_BUTTON sub_ids in the same ctl_id group are turned OFF or lose focus.
The group ctl_id value generates a CTL whenever any RADIO_BUTTON in the group is pressed and must
be unique. Use an asterisk [*] as a prefix for your ctl_id to identify the group of RADIO_BUTTONs as
global (not tied to a specific window).
RADIO_BUTTON Contents$
Your contents$ string expression defines the text/picture (bitmap or icon) to appear on the
RADIO_BUTTON. In the text, you can use an ampersand "&" preceding a character to identify it as a hot
key the user can press in conjunction with the <Alt> key to activate a RADIO_BUTTON from the keyboard.

Example:
0010 RADIO_BUTTON 100:1,@(2,14,12,2)="&Daily"
0020 RADIO_BUTTON 100:2,@(2,16,12,2)="&Weekly"
0030 RADIO_BUTTON 100:3,@(2,18,12,2)="&Monthly"
This would create a group of three RADIO_BUTTONs that will each generate a CTL=100 when pressed.
Their individual sub_ids are 1, 2 and 3. Their respective hot keys are D, W and M.
Bitmaps and Icons:

To add a bitmap to a RADIO_BUTTON, you can include the absolute path to the .bmp file in the contents$
or use the name of one of Best Software Canada Ltd.s embedded bitmaps. As of Ver. 4.20, ProvideX
supports {icon} images for use on RADIO_BUTTONs. Your icon filename must have .ico as an
extension. When you use both text and an image filename, the relative positions of the image and the text
set their relative placement on the RADIO_BUTTON.
Canada Ltd.s embedded bitmaps. For instance, "{!Stop}Quit" displays the {!Stop} bitmap in front of
the text "Quit" You can use a leading exclamation point to designate that an icon is internal, but in that
case ProvideX only searches in the *BMP directory. There are no icons in the ProvideX executable and
ProvideX does not support retrieving icons from either resource libraries or other system DLLs /
executables.
If your string expression includes two images separated by a vertical bar inside a single set of curly
brackets, the first will be displayed when the RADIO_BUTTON is OFF (normal state), the second while the
RADIO_BUTTON is ON. For example:
"{!Stop|C:\MYBMP\Go}"
See RADIO_BUTTON OPT=char$, p. 337.
Format 2 Deletes: RADIO_BUTTON REMOVE [*] ctl_id:sub_id[,ERR=stmtref]

Use the RADIO_BUTTON REMOVE format to delete a RADIO_BUTTON. By default all local
RADIO_BUTTONs are deleted when a window is removed/dropped or the application issues a BEGIN.
Global RADIO_BUTTONs can be removed manually or cleared with a START directive.
Format 3: RADIO_BUTTON {DISABLE} [*] ctl_id:sub_id[,ERR=stmtref]

Use the RADIO_BUTTON DISABLE format to gray out a RADIO_BUTTON and make it inaccessible to the
user and your programs.
Format 4: RADIO_BUTTON {ENABLE} [*] ctl_id:sub_id[,ERR=stmtref]

Use the RADIO_BUTTON ENABLE format to restore a disabled RADIO_BUTTON.
Format 5 Sets Focus: RADIO_BUTTON GOTO [*] ctl_id:sub_id[,ERR=stmtref]

Use the RADIO_BUTTON GOTO format to set the Focus on your RADIO_BUTTON, ready for the user's
next action.

Format 6 Pushes / Releases: RADIO_BUTTON {ON | OFF} [*] ctl_id:sub_id[,ERR=stmtref]
Use the RADIO_BUTTON ON format as a logical Push to make it appear that the RADIO_BUTTON has
been pressed. Use RADIO_BUTTON OFF to make it appear that the RADIO_BUTTON has been
released.
Format 7 READ Mode: RADIO_BUTTON READ [*] ctl_id,var,mode$[,ERR=stmtref]

The RADIO_BUTTON READ format returns your sub_id for the currently active RADIO_BUTTON in your
numeric variable. (The value is zero if none are active.)
ProvideX returns a single-character hex value for the mode / keystroke the user chose to activate the last
RADIO_BUTTON. Possible values returned in mode$ can include:
$01$ <Mouse-Click>
$0D$ <Enter>
$20$ <Space Bar>
Once READ, this field is reset to $00$
For example, to determine which RADIO_BUTTON sub_id has been pressed and the mode used:
0100 RADIO_BUTTON READ 1000,which,how$
Format 8: RADIO_BUTTON {HIDE | SHOW} [*] ctl_id:sub_id[,ERR=stmtref]

Use the RADIO_BUTTON HIDE format to hide your RADIO_BUTTON from display. (The user can't see it
or gain access to it, even though it is still active and accessible to your program.) Use the
RADIO_BUTTON SHOW format to restore the users display and access.

RANDOMIZE Set Random Key
Directive RANDOMIZE
Format:
Assign Random# Seed RANDOMIZE seed
Where =
seed Numeric value or expression to be used as the seed by the random number
generator.
Description:
Use the RANDOMIZE directive to assign a seed to be used by the random number generator. ProvideX
uses your given value to define the starting point for the random number generator (system variable RND).
Use the RANDOMIZE directive to have ProvideX return a repeatable random sequence.
See also: RND Random Number Generator, p. 364(v)
RND( ) Return Random Number, p. 365(f)
Example:
In this example, ProvideX will RANDOMIZE 1 or create a repeatable random sequence using 1 as the
seed. Then, for instance, each time the number 2 is encountered in the loop below, it will generate
0.59859266:
1000 FOR I=1 TO 2
1010 RANDOMIZE 1
1020 FOR J=1 TO 5
1030 PRINT RND," ",
1040 NEXT J
1050 PRINT "END OF LOOP ",STR(I)
1060 NEXT I
-:run
0.11337858 0.59859266 0.81950925 0.76559375 0.5199119 END OF LOOP 1
0.11337858 0.59859266 0.81950925 0.76559375 0.5199119 END OF LOOP 2
In the example below, ProvideX will use a repeatable random sequence for indices (i.e. to create a
repeatable number to use each time a particular index number is encountered):
0010 INPUT "Enter random seed:",N
0020 RANDOMIZE N
0030 OPEN (31)"TESTFILE"
0040 FOR I=1 TO 1000
0050 READ (31,IND=INT(RND*100),ERR=0090)R$
0060 PRINT RND," ",R$," ",
0070 NEXT I
0080 PRINT "DONE"; CLOSE (31); STOP
0090 ...

RCD( ) Return Next Record
Function RCD( )
Format:
Return Next Record RCD(chan[,fileopt])
Where =
fileopt File options. Valid options for RCD( ) include:
DOM=stmtref Duplicate or Missing Record Transfer
ERR=stmtref Error Transfer
Returns: Contents of next or given record
Description:
The RCD( ) function returns the contents of either the next record in your given file or of the record you
identify in a KEY=, RNO=, or IND= option, if any. ProvideX effectively issues a READ RECORD directive
when it encounters this function and returns the contents of the given record.
See also: READ RECORD Read Record from File, p. 348(d)
Example:
0010 OPEN (13)"\CONFIG.SYS"
0020 PRINT RCD(13,END=40)
0030 GOTO 0020
0040 STOP
-:run
rem device=c:\other\tools\ziptools\aspippm1.sys FILE=NIBBLE.ILM SPEED=10 QUIET

RDX( ) Convert to RADIX-40 from ASCII
Function RDX( )
Format:
Convert to Radix-40 RDX(ascii$[,ERR=stmtref])
Where =
ascii$ Character string containing ASCII data. String expression.
Returns: RADIX-40 equivalent of given ASCII string
Description:
The RDX( ) function is used to convert data from normal ASCII to RADIX-40. Conversion to RADIX-40
compresses three characters (any of 0-9, A-Z, ., -, $, or space) into two bytes of data (16 bits).
To convert data back to ASCII, use the inverse function, TRX( ).
See also: TRX( ) Convert ASCII to RADIX-40, p. 437(f)
Example:
0010 LET A$=LST(PGM(65000)); PRINT "string: ",QUO,A$,QUO
0020 PRINT HTA(A$)
0030 PRINT HTA(RDX(A$))
-:run
string: "65000 END "
363530303020454E4420
2CB106686E600000

READ Read Data from File
Directive READ
Format:
Read Data READ (chan[,fileopt])varlist
Where =
fileopt File options. Valid options for READ include:
BSY=stmtref Traps Error #0: Record/file busy (Ver. 4.10)
DIR=num Direction Indicator
DOM=stmtref Missing record transfer
TIM=num Maximum time delay to wait
'@(...)'. The items in the list must be comma-separated.
Description:
Use the READ directive to read data from the file you identify by channel.
When it's read, the data will be split into one or more fields, either separated by the currently defined
delimiter or defined by embedded formats (headers, etc.), with the contents of the first field placed in
variable 1, the second field in variable 2, and so on.
ProvideX will convert numeric data automatically on a READ statement when moving it to numeric
variables. Numeric data converted during a READ directive does not use the DP or TH System
Parameters, p. 537 for European decimal settings.
If you want to skip a field in the record, use an asterisk '*' as a place holder instead of a variable name.
You can refer to an IOLIST instead of using a list of variables in varlist. To do this, use IOL=iol_ref. Your
iol_ref can be a line number or statement label for the line containing an IOLIST, or it can be a string
containing a compiled IOLIST.
If you don't include variables in your READ directive, ProvideX will use the IOL= option (if you included
one) in the OPEN statement for your given file.
If your varlist contains more variables than there are current fields in the record, then ProvideX initializes
the additional variables to either zero (for numeric variables) or a null string (for string variables).
The READ directive will advance the file position to the next record (or, if you use a KEY= or IND= option,
to the record you identify then) and if you use the KNO= option, the current access key will be changed
accordingly.
ProvideX supports use of the READ directive with *memory* (a memory-resident file or queue of records,
Ver. 4.10).
See also: *MEMORY* Create & Use Memory File, p. 590

FIND Locate and Read Data, p. 152(d)
EXTRACT Read and Lock Data, p. 136(d)
OPEN Open a File for Processing, p. 299(d)
Example:
0410 READ (1,ERR=1000,DOM=1200)A,B,*,*,E$
Automatic Padding with KEY=Option

When you use KEY=string$:string$[:string$][...] ProvideX will automatically pad key segments (Ver.
4.10). This is valid only if you have keyed files with segmented key definitions. Then, ProvideX right-pads
the key segment using $00$ (NULLS) to the segments full length. For example:
KEYED "TEST", [1:1:5]+[2:1:6]+[3:1:8]

READ (1,KEY=A$:B$:C$)
is the same as:
READ (1,KEY=PAD(A$,5,$00$)+PAD(B$,6,$00$)+C$)
NOTE: The last segment in a compound key will not be padded.

READ DATA Read Data from Program
Directive READ DATA
Format:
1 Read DATA READ DATA varlist,...[,ERR=stmtref]

2 Read from String READ DATA FROM data$[,REC=rec_pfx$][SEP=char$] TO varlist[,ERR=stmtref]
Where =
varlist List of variables to receive the values from the DATA statements. Comma-separated
numeric and string variables are allowed.
data$ Data to be parsed into the varlist. String expression.
rec_pfx Record prefix. Optional. String expression.
char$ (Ver. 4.20). Character to use as separator to parse the data, e.g. SEP=".". Dynamic
SEP=* separators are not supported.
NOTE: If the READ DATA statement also contains a REC= clause, the
REC= clause must precede the SEP=clause.
Description:
Use the READ DATA directive to read data embedded in your program.
See also: DATA Define Data Elements, p. 66(d)
RESTORE Reset/Change Program Data Position, p. 360(d)
Format 1 READs DATA Statement into Variables: READ DATA varlist,...[,ERR=stmtref]

Use this format to transfer the values/expressions from DATA statements in your program to the variables
you identify in the varlist. When the READ DATA directive is executed, ProvideX evaluates each
expression in the DATA statements, in order, and places the values into the corresponding variables
defined in your READ DATA directive.
ProvideX increments an internal pointer to the next data expression during the READing of DATA. When
the end of a DATA statement is reached, the next DATA statement in the program is used. Use a
RESTORE directive to reset the pointer to the start of the first DATA statement.
Example: Error 2
Unless you include the ERR=option, ProvideX generates an Error #2 when the pointer is at End of File.
0010 DATA "Dog","Cat","Pig"
0020 DATA "Pig","Cat","Dog"
0030 READ DATA X$
0040 PRINT X$," | ",
0050 GOTO 0030
1000 RESTORE
-:BEGIN
-:RUN

Dog | Cat | Pig | Pig | Cat | Dog | 0030 READ DATA X$
Error #2: END-OF-FILE on read or File full on write
1:END
-:EDIT 30
-:0030 READ DATA X$,ERR=1000
-:BEGIN
-:RUN
Dog | Cat | Pig | Pig | Cat | Dog | DONE
-:?ERR
0
Example: Error 26
ProvideX generates an Error #26 if your variables dont match your data in type (string or numeric). This
means that you cant use a lone variable in your READ DATA directive (as in the example above) if you
have mixed data. However, you can use asterisks "*" as place holders for other variables to do a selective
read of a lone variable in mixed data.
In the example below, without a full variable list and the ERR=option, ProvideX reports the mismatch of the
string data ("Dog") with numeric variable "X".
0010 DATA 1,2,3,"Dog","Fat"
0020 DATA 4,5,6,"Pig","Cat"
0030 READ DATA X
0040 PRINT X,Y,Z,"| ",A$,"| ",B$,"| "
0050 GOTO 0030
1000 RESTORE
-:BEGIN
-:RUN
1 0 0| | |
2 0 0| | |
3 0 0| | | 0030 READ DATA X
Error #26: Variable type invalid
1:END
-:EDIT 30
-:0030 READ DATA X,*,*,*,B$,ERR=1000
-:BEGIN
-:RUN
1 0 0| | Fat|
4 0 0| | Cat|
DONE
?ERR
0
See also: ERROR_HANDLER Define Generic Handler, p. 125(d)
SETERR Set Error Transfer, p. 384(d)
Format 2: READ DATA FROM data$[,REC=rec_pfx$][SEP=char$] TO varlist[,ERR=stmtref]

You can READ DATA FROM a string to initialize a list of variables or to parse a record into different
IOLISTS.
Example: Initialize Variables

You can READ DATA TO an IOLIST to initialize all variables.
0040 PRINT X,Y,Z,A$
0050 IOLIST X,Y,Z,A$

0060 READ DATA FROM "" TO IOL=0050 ! Numerics to 0(zero), strings to ""
0070 PRINT "DONE:",X,Y,Z,"|",A$,"|"
0080 REM GOTO 0030
0090 RESTORE
0100 STOP
-:END
-:RUN
1 2 3Cat
DONE: 0 0 0||
0010 READ DATA FROM "",REC=WORK$ TO IOL=IOL(WORK)
Example: Parse Record

You can use READ DATA to parse a record into different IOLISTs.
0100 READ RECORD (1)R$
0200 IF R$(1,1)="T" THEN READ DATA FROM R$ TO IOL=8000
0200: ELSE READ DATA FROM R$ TO IOL=8010
8000 IOLIST TYPE$,TRN_DATE$,TRN_AMOUNT
8010 IOLIST TYPE$,PAY_DATE$,PAY_AMOUNT

READ RECORD Read Record from File
Directive READ RECORD
Format:
Read Record READ RECORD (chan[,fileopt])var
Where =
fileopt File options. Valid options for READ RECORD include:
DIR=num Direction Indicator
var$ String variable. Receives the contents of the record.
Description:
Use the READ RECORD directive to read a record from the file (channel) you identify. The complete
record's data portion will be returned to your given string variable.
You should use the READ RECORD statement when dealing with native-mode operating system files,
when exchanging data between ProvideX and other applications, or when you want to read a complete
record, including data field separators.
The READ RECORD directive will advance the file position to the next record (or the record you identify if
you use the KEY= or IND= options) and, if you use the KNO= option, the current key access number will
be changed accordingly.
ProvideX supports use of the READ RECORD directive with *memory* (a memory-resident file or queue
of records, Ver. 4.10).
See also: RCD( ) Return Next Record, p. 341(f)


KEYED "TEST", [1:1:5]+[2:1:6]+[3:1:8]

is the same as:

Example:
When this example is RUN each record is displayed on the screen in the format shown below. At EOF, the
"End-of-file" message is displayed.
0010 OPEN (13)"PVX_KEYD"; LET X$=FIB(13)

0020 LET K$=KEY(13,END=1000)
0030 READ RECORD (13,KEY=K$)R$
0040 PRINT R$ ! Prints complete record
0050 GOTO 0020
1010 END
-:end
! ... series of records, displayed in format shown below:
123461
JULIES CATERING
UNIT 20
6 2ND ST
ANYTOWN
ON
K0K0K0
... etc.
...
End-of-file

REC( ) Expand IOLIST Specification
Function REC( )
Format:
1 From I/O Object Code REC(iol_obj$[,REC=var$][,ERR=stmtref])

2 Expand from IOLIST REC(IOL=iol_ref[,REC=var$][SEP=char$][,ERR=stmtref])
3 VIS( ) as Record Prefix REC=VIS(rec_name$[,ERR=stmtref])
4 Return Default Value REC=(FILE chan[,ERR=stmtref])
Where =
iol_obj String expression which contains the object code of an IOLIST.
var$ String variable. Optional record name/prefix for all of the variables in the IOLIST.
iol_ref Line number or statement label of the IOLIST statement.
char$ (Ver. 4.20). Character to use as separator to parse the data, e.g. SEP=".". Dynamic
SEP=* separators are not supported.
NOTE: If the REC( ) function statement also contains a REC= clause, the
REC= clause must precede the SEP=clause.
rec_name$ String value to be evaluated and used as the record name. String expression.
FILE chan File (channel) from which the REC=value will be returned.
Returns: String, name/contents of IOLIST
Description:
The REC( ) function returns the name or contents of an IOLIST and can be used to define a record prefix.
Format 1 Expands IOLIST from Object Code: REC(iol_obj$[,REC=var$][,ERR=stmtref])

With this format, the string returned by the REC( ) function is expanded from a string expression consisting
of the object code of an IOLIST.
Format 2 Expands IOLIST: REC(IOL=iol_ref[,REC=var$][SEP=char$][,ERR=stmtref])

The string returned by the REC( ) function in this format is expanded from a variable list (IOL=iol_ref).
In both the above formats, you can add a REC= clause to assign a record name as a prefix to all the
variables in the list (similar to a prefix for a composite string variable). That is, the variable you identify in
your string variable defines a prefix for the variable names in your IOLIST. Both formats also allow you to
have other functions and directives return values based on a variable name for the record, e.g. LEN (X$)
and PRINT X$.
You can also use a SEP=char$ (Ver. 4.20). Note that if you include both this and a REC=clause, the
REC=clause must precede the SEP= clause.
Example:
In the example below, ProvideX would place the input data in CUST.NAME$, CUST.ADR1$ and
CUST.ADR2$ using the IOLIST at line 0110 as a template (even though there is no matching prefix in the

IOLIST). That is, you can use the same IOLIST as a template for different REC=prefix specifications.
0100 PRINT X$
0110 IOLIST NAME$,ADR1$,ADR2$
0120 INPUT EDIT "Name",@(9),": ",CUST.NAME$
0130 INPUT EDIT "Address 1: ",CUST.ADR1$
0140 INPUT EDIT @(8),"2: ",CUST.ADR2$
0150 LET X$=REC(IOL=0110,REC=CUST$)
0160 IF LEN(X$)>100 THEN PRINT "TOO-LONG"; GOTO 0120
0170 PRINT X$
-:run
BRETTS BODYSHOP
123 SOME ST.
ANYTOWN SK S0M 0V0
The values are also displayed with the prompts below. The user edits to change them:
Name : YVONNES BODYSHOP
Address 1: 123 SOME RD.
2: NEWTOWN SK S0M 0V0
YVONNES BODYSHOP
123 SOME RD.
NEWTOWN SK S0M 0V0
Format 3 for Dynamic Record Prefix REC=VIS(rec_name$[,ERR=stmtref])

Use this format to assign the REC= prefix value dynamically during READs, WRITEs, OPENs and other
directives (Ver. 4.). When you use REC=VIS( ), ProvideX evaluates the string value in VIS( ) and uses it as
the name of the RECord prefix.
Format 4 Gets Default Value: REC=(FILE chan[,ERR=stmtref])

Use this format to obtain the name of the REC= default value for your given file.

REFILE Clear Data from File
Directive REFILE
Format:
Erase Data in File REFILE filename$[,ERR=]
Where =
filename$ Name of the file to clear. String expression.
Description:
Use the REFILE directive to erase all data in your specified file. If you use the REFILE directive to erase a
file, the file still exists in the system but contains no data. (ProvideX returns disk space to the system while
preserving the lock.) Any READ directives for the file will return an End-of-File message.
Using either the REFILE or PURGE directive is faster than deleting the file and recreating it.
If your given filename does not already exist, ProvideX returns an Error #12: File does not exist
(or already exists). If the file is in use by another user, ProvideX returns an Error #0: Record/
file busy. Unlike the PURGE directive, the REFILE directive works if the file is not OPENed.
REFILE "[WDX]somefile.ext"... (If you are running an earlier version of
626.
See also: LOCK Reserve File for Exclusive Use, p. 247(d)
PURGE Clear Data from a File, p. 333(d)
Example:
0010 REFILE "PRNTFL"! Pre-clear datafile
0030 LOCK (2)
0040 PRINT (2)'FF',"Date:",DAY,@(40),TTL$
0050 ...

RELEASE Terminate ProvideX
Directive RELEASE
Format:
End ProvideX Session RELEASE {num}
Where =
num Status to be returned to the Operating System when ProvideX terminates. Optional.
Numeric expression.
Description:
Use the RELEASE directive to terminate your ProvideX session and return to the Operating System. Your
numeric value is returned to the O/S as a termination value, allowing for external testing of error conditions
(e.g. by the system shell processor or using a 'C' program).
When you use the RELEASE directive in a compound statement, it must be the final directive.
See also: BYE Terminate ProvideX, p. 32(d)
QUIT Terminate ProvideX, p. 334(d)
Example:
12000 RELEASE 101

REM Programmer Remark
Directive REM
Format:
1 Programmers Remark REM comments ...

2 ! = REMARK ! comments
Where =
! (exclamation ProvideX accepts the exclamation mark as an acceptable substitute for typing the
mark) word REM.
comments Remarks. Programmer's comments or documentation. Numeric and/or string.
Description:
Use the REM directive to insert program remarks and comments (e.g. documentation and notes) in your
program. The REM statement has no effect on the execution of the program. ProvideX treats all
characters in a statement following the REM directive as comments. The REM directive is the last one
processed in any statement.
Since ProvideX embeds the comment text following the REM directive in the compiled form of the
program, remarks occupy memory space when the program is LOADed and RUN.
Examples:
0010 REM Invoice Generation Program - INVGEN
0020 ! Written by: Kathryn Doe, Anytown, Canada
0530 LET A1=A1-X9 ! Stock from Inventory

REMOVE Delete Record from File
Directive REMOVE
Format:
Delete a Record REMOVE (chan[,fileopt])
Where =
chan Channel or logical file number of the file from which to delete the record.
fileopt File options. Valid options for REMOVE include:
BSY=stmtref To trap Error #0: Record/file busy
KEY=num Record key
Description:
Use the REMOVE directive to delete a record from a file. The directive is not supported for all file types
(i.e. not for INDEXED files). The REMOVE directive and the specific options are dependant on the specific
file type.
For KEYED, DIRECT or SORT files, the KEY= option is mandatory to identify the record to be REMOVEd.
The key specified must be the primary key for the file. With multi-keyed files, ProvideX REMOVEs all
related alternate keys from the file automatically when executing this directive.
ProvideX supports use of the REMOVE directive with *memory* (a memory-resident file or queue of
records, Ver. 4.10).
Example:
0010 OPEN (20)"CSTFLE"
0020 INPUT "What customer do we delete? ",C$
0030 IF C$="" THEN STOP
0040 REMOVE (20,KEY=C$,DOM=0100)
0050 PRINT "Well thats gone.."
0060 GOTO 0020
0100 PRINT "Could not find ",C$
0110 GOTO 0020

RENAME Change a File's Name
Directive RENAME
Format:
Change Filename RENAME old_name${, | TO }new_name$[,ERR= stmtref]
Where =
old_name$ Name of an existing file to be renamed. String expression.
new_name$ New name for the file. String expression.
Description:
Use the RENAME directive to change the name of an existing file. The first string must contain the current
name of the file. (The file must already exist.) Use the second string expression for the new name of the
file.
When the OR system parameter is set, the RENAME directive will assume that the new filename contains
a fully expanded O/S pathname to the same directory as the old filename.
If you omit the pathname, the standard ProvideX search rules and file naming conventions will apply to the
renamed file.
Restrictions:
The new filename must not duplicate an existing filename.
You must have exclusive access to the file you are renaming.
Some Operating Systems do not allow you to rename the file to a different directory.
Examples:
0010 ERASE "ordlst"
0020 RENAME "ordcur","ordlst"
0030 KEYED "ordcur",6
RENAME "OLDFILE" TO "NEWFILE"

RENUMBER Change Program Line Numbers
Directive RENUMBER
Format:
Renumber Program Lines RENUMBER [new_line1[,step_val[,range_start][,range_end]]]
Where =
new_line1 New starting line number (default is 0010).
step_val Increment or step value between line numbers (default is 10). Numeric expression.
range_start Starting line number or label at which to begin renumbering. Optional. Use to define
the start of an existing range in the program for renumbering.
range_end Ending line number or label with which to stop renumbering. Optional. Use to define
the end of an existing range in the program for renumbering.
Description:
Use the RENUMBER directive to assign new line numbers to the current program. During the
renumbering process, ProvideX adjusts all references to the lines being renumbered (e.g. GOTOs, ERR=
options, etc..) to reflect the new line number.
By default, the complete program is renumbered. You can choose to resequence only selected ranges of
the program. All references (GOTOs, etc.) are adjusted in either case.
You can use embedded REMark statements in the program to control renumbering. If a REMark line starts
with a number (e.g. 4000 REM 4000), ProvideX uses the number as the absolute line number (assuming
it is less than or equal to the current resequence number).
Example:
->LIST
0001 FOR I = 1 TO 40
0002 READ (1,ERR=18)A,B
0003 PRINT A,B
0007 NEXT I
0010 STOP
0014 REM 100 - Error procedure
0018 EXITTO 0008
->RENUMBER
->LIST
0010 FOR I=1 TO 40
0020 READ (1,ERR=0110)A,B
0030 PRINT A,B
0040 NEXT I
0050 STOP
0100 REM 100 - Error procedure
0110 EXITTO 0045
In line 0110 (renumbered version) ProvideX generated line number 0045 in the EXITTO statement since
no line number 0008 existed in the original version.

REPEAT Repetitive Execution
Directive REPEAT
Format:
Loop Again REPEAT
Description:
Use the REPEAT directive to create conditional looping in a program.
After processing the REPEAT directive, ProvideX proceeds with execution until an UNTIL directive is
encountered. If the expression in the UNTIL directive is FALSE (zero), execution loops back to the
statement following the REPEAT directive. If TRUE (other than zero), the looping terminates and
execution continues from the statement after the UNTIL directive.
You can use the EXITTO directive to halt a REPEAT/UNTIL loop prematurely.
See also: UNTIL End of REPEAT Loop, p. 447(d)
Example:
0090 PRINT 'CS',"Standard TAX calculation..."
0100 INPUT "How much was your INCOME? $",CASH
0110 REPEAT
0120 INPUT "How much TAX did you pay? $",TAXES
0130 LET CASH=CASH-TAXES
0140 PRINT "You have $",CASH," left"
0150 UNTIL CASH<=0
0160 PRINT "Okay you have paid enough."
-:RUN
Standard TAX calculation...
How much was your INCOME? $1.98
How much TAX did you pay? $1.65
You have $ 0.33 left
How much TAX did you pay? $.33
You have $ 0 left
Okay you have paid enough.
-:

RESET Reset Program State
Directive RESET
Format:
Reset to Start Values RESET
Description:
The RESET directive does the following:
1. Resets PRECISION to the default value of 2. As of Ver. 4.20, also resets FLOATINGPOINT
to standard decimal notation. (In prior versions, FLOATINGPOINT notation was left
unchanged, i.e. ON if ON...)
4. Resets DATA position to the start of the program
5. Re-enables rounding mode
As of Ver. 4.20, if you set 'RR' Reset on RUN, p. 556(p) ON, ProvideX will also perform a reset for RUN
directives.
Example:
0030 RESET

RESTORE Reset/Change Program Data Position
Directive RESTORE
Format:
Reset DATA Pointer RESTORE [stmtref]
Where =
Description:
Use the RESTORE directive to change the position of the DATA READ pointer. When a program is first
LOADed (or following a BEGIN directive), the DATA READ pointer is set to the start of the program. As the
data is read, the pointer is advanced through the various DATA statements in the program.
To set the DATA READ pointer to a given location, include a statement reference in your RESTORE
directive. Omit the stmtref to set the DATA READ pointer to the default position at the start of the program.
ProvideX returns an End of File message when all DATA statements in the program have been READ.
See also: READ DATA Read Data from Program, p. 345(d)
DATA Define Data Elements, p. 66(d)
Example:
0010 DATA 1,2,3,"Cat"
0020 DATA 4,5,6,"Dog"
0030 READ DATA X,Y,Z,A$,ERR=0050
0040 PRINT X,Y,Z,A$; GOTO 0030
0050 INPUT "Do you want to see the last one again? (Y/N)",X$
0060 IF X$="Y" OR X$="y" THEN RESTORE 0020; GOTO 0030
-:run
1 2 3Cat
4 5 6Dog
Do you want to see the last one again? (Y/N)y
4 5 6Dog
Do you want to see the last one again? (Y/N)n
DONE

RET Operating System's Last Error Code
Numeric System Variable RET
Returns: Integer, Operating System ERRor + 256
Description:
This numeric system variable returns an integer reporting the Operating System's error code associated
with the last operating call. ProvideX generates this value by adding 256 to the error code value in the
ERR system variable.
See also: ERR Last System-Detected Error Value, p. 123(v)
Example:
-: PRINT "RET = ",RET
RET = 258

RETRY Re-Execute Failing Instruction
Directive RETRY
Format:
Re-Execute Statement RETRY
Description:
The RETRY directive returns control to the statement on which the last error transfer occurred. This allows
you to take corrective action and retry the statement. You can use *RETRY to emulate this directive in a
statement reference. See Labels: Logical Statement References, p. 582.
If an error occurs on a statement where you have used any of the ERR=, DOM= or END= options, or
where you have used a SETERR directive, ProvideX does the following:
saves the statement number and directive where the error occurred (as a RETRY address),
passes control to the file option or SETERR statement reference to handle the error, and
returns control to your RETRY directive using the RETRY address.
You can find the currently saved RETRY address or line reference in TCB(11). ProvideX returns an
Error #27: Unexpected or incorrect WEND, RETURN, or NEXT (i.e., no return address on an
error) if it encounters your RETRY directive with no previous statement saved.
The saved statement number and directive are cleared by any of the following directives: BEGIN, CLEAR,
LOAD, RESET, START. You can also clear the RETRY address by executing a RUN directive with a
program name specified.
When you use it in a compound statement, the RETRY directive must be the final directive.
As of Ver. 4.20, if you set 'RR' Reset on RUN, p. 556(p), ProvideX will perform a reset for RUN directives.
See also: TCB( ) Return Task Information, p. 424(f)
Example:
0010 OPEN (1)"CUSTFL"
0020 INPUT (0,ERR=1000)"Enter customer number: ",C
0030 READ (1,ERR=1010,KEY=STR(C:"000000"))C$,N$
0040 PRINT C$," ",N$
0050 STOP
1000 PRINT 'RB','LF',"Invalid customer. "; RETRY ! Rings bell, retries 0020
1010 PRINT 'RB',"Cannot find customer: "; GOTO 0020
-:run
Enter customer number: 123987
Cannot find customer:
Enter customer number: ABC
Invalid customer.
Enter customer number: 123456
123456 ABC MFG

RETURN Return from a Subroutine
Directive RETURN
Format:
End Subroutine, Go Back RETURN
Description:
The RETURN directive terminates the current GOSUB or SETESC subroutine. In the case of a GOSUB
routine it returns control to the directive following the GOSUB directive. In the case of SETESC it returns
control to the statement which was interrupted. If ProvideX encounters a RETURN directive without an
associated subroutine, ProvideX returns an Error #27: Unexpected or incorrect WEND,
RETURN, or NEXT.
When you use the RETURN directive in a compound statement, it must be the final directive.
You can use the *RETURN label to emulate the directive in a statement reference (Ver. 4.01).
See also: GOSUB ... RETURN Execute Subroutine, p. 165(d)

Example:
0100 ! 100
0110 INPUT "Enter start date DD/MM/YY: ",D$
0120 GOSUB 1000
0130 LET D1$=D$
0140 INPUT "Enter ending date DD/MM/YY: ",D$
0150 GOSUB 1000
0160 LET D2$=D$
1000 ! 1000
1010 IF LEN(D$)<>8 THEN GOTO 1080
1020 IF D$(3,1)<>"/" OR D$(6,1)<>"/" THEN GOTO 1080
1030 LET D=NUM(D$(1,2),ERR=1080),M=NUM(D$(4,2),ERR=1080),Y=NUM(D$(7,2),ERR=10
1030:80)
1040 IF D<1 OR D>31 THEN GOTO 1080
1050 IF M<1 OR M>12 THEN GOTO 1080
1060 RETURN
1070 !
1080 PRINT "Invalid: Restart..."
1090 EXITTO 0100
-:run
Enter start date DD/MM/YY: 033199
Invalid: Restart...
Enter start date DD/MM/YY: 31/03/99
Enter ending date DD/MM/YY: 16/04/99
DONE

RND Random Number Generator
Numeric System Variable RND
Returns: Random number, range 0 (zero) to 1, PRECISION 8
Description:
This numeric system variable returns a different random number each time you use it to return a value.
The value returned will range from 0 (zero) to 1 with a PRECISION of 8.
Example:
0010 FOR I=1 TO 3
0020 PRINT RND,
0030 NEXT
0040 PRINT " DONE"; END
-:run
0.76559375 0.5199119 0.9505763 DONE

RND( ) Return Random Number
Function RND( )
Format:
Generate Random # RND(seed[,ERR=stmtref])
Where =
seed Numeric expression must be (or result in) an integer. The value of this number is
used to determine the result of the function.
Returns: Random numbers based on given seed
Description:
The RND( ) function returns random numbers based on your given seed number. The following table
describes the value returned based on the seed value:
Seed Returns:
>0 If your seed is greater than zero, the random number returned is between zero and
the given number.
=0 If your seed=0 (zero), returns a random number between 0 and 1, with
PRECISION=8.
<0 If your seed is less than zero, the function initializes the seed value used to generate
random numbers and returns a random number between 0 and 1 with
PRECISION=8.
Each call to the RND( ) function will return a different random number. To change the seed value for the
random number generation you can either execute a RANDOMIZE directive or call RND( ) with a negative
value. If your value is not an integer, Providex returns an Error #41: Invalid integer
Example:
0010 LET A=9.87
0020 FOR I=1 TO 10
0030 PRINT RND(9),
0040 NEXT
0050 PRINT 'LF',RND(0)
0060 PRINT RND(-1)
0070 PRINT RND(INT(3.2*3.67))
0080 PRINT RND(INT(A))
0090 PRINT " DONE"; END
-:run
1 1 7 0 7 7 4 4 5 7
0.05947216
0.11337858
1
2
DONE

RNO( ) Return Next Record Number
Function RNO( )
Format:
Return Next Record # RNO(chan[,fileopt])
Where =
fileopt File options. Valid options for RNO( ) include:
Returns: Integer, position of next/given record
Description:
The RNO( ) function returns an integer reporting the position in your given file of either the next record or of
the record you identify when you use the KEY= or IND= options. The RNO( ) value is the absolute ordinal
position of the record in the file. The first record in a file has RNO=1 (one), the second RNO=2, and so on.
In a KEYED file, the record number depends on the key chosen and its value relative to all other records in
the same file.
NOTE: ProvideX supports the RNO( ) function for ODBC files. See also: File Handling.
Example:
0020 INPUT "Which record? ",@(15),K$,
0030 IF K$="" THEN CLOSE (13); PRINT "DONE"; STOP
0040 READ (13,KEY=K$,ERR=0100)
0050 PRINT " Key ",K$," is Rec# ",RNO(13,END=0130)
0060 GOTO 0020
0100 REM 100
0110 PRINT " is invalid",@(40),"...Please try again"
0120 GOTO 0020
0130 PRINT @(22),"...Sorry...END-OF-FILE"
0140 END
-:end
-:run
Which record? ABCDEF is invalid ...Please try again
Which record? 123456 Key 123456 is Rec# 2
Which record? DONE ! User hit <Enter>
-:run
Which record? 123461 ...Sorry...END-OF-FILE

ROUND Control Rounding
Directive ROUND
Format:
Set Rounding ON/OFF ROUND {ON | OFF}
Description:
Use the ROUND directive to control the automatic rounding of values during calculations. If you use the
ROUND ON directive, ProvideX will round all values to the PRECISION currently in effect before assigning
them to numeric variables. The ROUND OFF directive terminates the rounding process. With ROUND
OFF, ProvideX maintains all values at full 14-digit precision.
The ROUND directive has no effect if FLOATINGPOINT mode is active.
See also: PRECISION Change Current Precision, p. 317(d)
FLOATINGPOINT Switch to Scientific Notation, p. 154(d)
Examples:
With ROUND OFF
0010 PRECISION 2
0020 ROUND OFF
0030 LET A=3*(2/3)
0040 PRINT A
-:run
2
With ROUND ON:
0010 PRECISION 2
0020 ROUND ON
0030 LET A=3*(2/3)
0040 PRINT A
-:run
2.01

RUN Transfer and Execute a Program
Directive RUN
Format:
Start/Resume Execution RUN [prog$[;entry$]][,ERR=stmtref]
Where =
prog$ Name of the program to LOAD and execute. Optional. String expression.
;entry$ Name of starting statement label to use as entrypoint in the program. Optional. If
included, append to the prog$ string expression (e.g. RUN
"MY_PROG;STARTING_LABEL").
Description:
Use the RUN directive to start or resume the execution of a program. You can include the name of a
program to LOAD and then RUN.
The RUN directive performs the following actions if a program is already LOADed:
1. Resets the current precision to 2.
2. Enables ROUNDING.
3. Clears FOR/NEXT, GOSUB/RETURN, and WHILE/WEND stack.
4. Resets SETERR and SETESC addresses and any saved RETRY address.
If you are LOADing a program or if your current program has not been interrupted, ProvideX begins
execution at the program statement with the lowest line number. If the current program was interrupted (by
an error, or a BREAK or ESCAPE directive) ProvideX resumes execution from the statement where the
program left off.
You can embed the RUN directive in a program to provide an overlay facility. The RUN directive affects
neither user data nor files.
When you use it in a compound statement, the RUN directive must be the final directive.
You can assign an optional line label entrypoint for the RUN program. To do this, append a semicolon and
the starting label name to the program name (e.g. RUN "PROG;STARTING_LABEL"). After the program
is loaded, ProvideX internally issues a GOTO directive and starts execution at the assigned entry point.
As of Ver. 4.20, if you set 'RR' Reset on RUN, p. 556(p), ProvideX will also perform a reset for RUN
directives.
Examples:
0010 REM In main program, EXECUTION mode
0020 RUN "INVGEN;DUE_DT"
0010 REM in "INVGEN" program (GOTO DUE_DT at line 4010)

4000 REM
4010 DUE_DT:
4020 REM... routine to calculate due dates
5040 RUN "PAY"+A$ ! ProvideX begins execution of program named "PAY"+A$

Example in COMMAND mode:
0010 FOR I=1 TO 10
0020 PRINT I,
0030 NEXT I
0040 STOP
-:BEGIN
-:RUN
1 2 3 4 5 6 7 8 9 10-:

SAVE Write Program to File
Directive SAVE
Format:
Save Program SAVE [EDIT] [prog_name$[,prog_size][,OWN=owner_id[,FLG=flg:flg:flg]]]
Where =
EDIT You can use the optional keyword EDIT with the SAVE directive to have ProvideX
logically break the lines into segments and indent them.
See also: 'LE' SAVE and LIST: Indent Statements, p. 549(p)
LIST List Program Lines, p. 224(d)

prog_name$ Filename to receive the program. Optional. String expression.
prog_size Program size. Optional. Numeric expression.
Options The OWN= and FLG= options are designed for use by registered application
developers. They are used to encrypt programs and establish activation keys to run
the programs.
owner_id Optional package number (owner ID) to which this program is to be assigned.
Numeric expression.
flg Optional package flags. If you use these, delimit them with : (the colon) and use
numeric expressions: integers between 1 and 25.
Description:
Use the SAVE directive to copy/write the current program to your given filename. (Include the pathname if
the directory you want is neither current nor in your PREFIX definition.) If the file does not already exist, a
PROGRAM file is created. If you use the prog_size parameter, the file specified must not already exist.
If the output of the file is a PROGRAM file type, ProvideX writes it to the file in internal (compiled) format.
For SERIAL and INDEXED file types, ProvideX writes the program in display (LIST) format. You can only
use the SAVE directive for SERIAL, INDEXED, and PROGRAM files.
Examples:
->SAVE "PROG1A"
->SAVE "/usr/a-r/PROGS/ARLIST"
You can SAVE or SAVE EDIT a text file containing the source of a program. Be sure to pre-create your
SERIAL text file.
SERIAL "PROG00.TXT"
LOAD "PROG00"
SAVE EDIT "PROG00.TXT" ! Formatted with line breaks and indents
NOTE: You can RUN, CALL or PERFORM text files that contain programs just as you would
any regular program file.
See also: SERIAL Create a Sequential File, p. 375(d)

SELECT Select/Query From ... Where
Directive SELECT
Format:
Possible Query Conditions:

SELECT iol_list[,REC=rec_id$] FROM {filename$ | chan}[,KNO=key_num] [BEGIN range_start$]
(continued) [END range_end$] [WHERE expression][,ERR=stmtref]
Where =
iol_list List of variables to be read from the file. If the file contains a dictionary, then only
those fields specified will be returned. Otherwise (with no dictionary) the fields will
represent the first, second, third nth fields. If you use an asterisk * the field is
seen as an embedded Data Dictionary. You can use IOL=stmtref as your iol_list.
rec_id Record prefix. Optional. String expression.
filename$ Name of the file to be opened and read from. String expression.
chan Channel or logical file number to be read from.
key_num Access key number (primary or alternate). Numeric expression.
range_start$ Starting key of the range to select. String expression.
range_end$ Ending key of the range to select. String expression.
expression Condition must return TRUE or FALSE. Numeric or string expression.
Description:
Use the SELECT directive to open, read and query records from the specified data file or just to read data
from a specified file number.
As each record is read, ProvideX processes any logic you include following the SELECT directive up to the
NEXT RECORD. When ProvideX encounters a NEXT RECORD statement with no records found for a
nested SELECT, it will locate the corresponding SELECT statement.
If you include a WHERE clause, ProvideX will process only those records WHERE the condition is TRUE.
The BEGIN and END clauses are only supported for KEYED and MEMORY files. As of Ver. 4.20, you can
use these clauses with WindX-connected files. Note that, if you are using BEGIN and END in SELECT
statements for files with descending keys, your END value must be lower than the BEGIN value.
NOTE: As of Ver. 4.20, because ProvideX pads descending keys to their full length with
$FF$, the BEGIN value is item$+$FF$ and your END value should be item$+$00$ so
that the ENDing key is less than the BEGINning key. That is, as of Ver. 4.20, the
correct format is SELECT * FROM filename BEGIN item$ END item$+$00$.
(Although the incorrect statement SELECT * FROM filename BEGIN item$ END
item$+$FF$ worked in prior versions, it no longer does.)
You must either include a NEXT RECORD directive to end your SELECT loop or instruct ProvideX to exit
the SELECT loop early (with an EXITTO directive). If you use the EXITTO directive, the file will be
CLOSEd.
NOTE: Prior to Ver. 4.20, the CONTINUE and BREAK directives (and corresponding
*CONTINUE and *BREAK labels) are not supported for use with SELECT / NEXT
RECORD directives. As of Ver. 4.20, you can use BREAK commands in SELECT
structures.

See also: NEXT RECORD End of SELECT, p. 286(d)
Example:
0010 SELECT IOL=0100 FROM "VEND_FILE",KNO=1 BEGIN "ABC CO." END "THAT CO." WHERE
0010:CITY$="CLARENDON"
0020 PRINT REC(IOL=0100)
0030 NEXT RECORD
0100 IOLIST VEND$,NAME$,ADDR1$,ADDR2$,CITY$,PROV$,POSTAL$,INV_DT$,INV,AMT,TERMS,
0100:DUE_DT$
-:run
123460
GORDONS WEBSITES
SUITE 1900
2000 1ST ST.
CLARENDON
ON
K0K0K0
0
0
0
DONE

SEP ProvideX Field Delimiter
String System Variable SEP
Returns: String, SEP value, default $8A$
Description:
This string system variable contains the default record field separator (ProvideX default SEP=$8A$). Note
that when you WRITE using an IOLIST, SEP is the field delimiter. SEP value $8A$ is not a printable
character. Use HTA( ) to display the hex value:
0540 PRINT HTA(SEP)
-:run
8A
The way you set the SEP=value is similar to the way you set a file option (i.e., within a directive like OPEN
or GRID, etc.). You can specify the SEP value using an ASCII value, a hex value or a variable. The three
examples below set the column SEP value for GRID 7000 as the colon (":" or hex value $3A$).
1 GRID 7000,@(5,5,35,15),FMT="[Company Name]C15 [Address]L20",SEP=":"
2 GRID 7000,@(5,5,35,15),FMT="[Company Name]C15 [Address]L20",SEP=$3A$
3 LET MY_SEP$=":"
GRID 7000,@(5,5,35,15),FMT="[Company Name]C15 [Address]L20",SEP=MY_SEP$
TIP: You can use SEP=DLM when READing directories, for instance in LIST_BOXes, to
have ProvideX append the operating system delimiter to subdirectory names. See
also DLM Return System Directory Delimiter, p. 97(v).
Treeview LIST_BOX Example:

0010 LIST_BOX 10,@(5,5,25,10),OPT="e|",
0020 LET F=1,D$="."
0030 NXTDIR:
0040 OPEN (F)D$
0050 NXTFILE:
0060 IF F$(1,1)="."
0070 IF MID(F$,-1)<>DLM
0070:GOTO NXTFILE
0090 F++
0100 GOTO NXTDIR
0110 ENDDIR:
0110:CLOSE (F)
0120 F--
0130 IF F>0
0140 ESCAPE

SEP( ) Return Field Separator
Function SEP( )
Format:
Return Field Separator SEP(chan)
Where =
chan Channel or logical file number of an OPEN file.
Returns: Either value of SEP (single-character string) for OPEN file on given channel or NUL ("")
Description:
The SEP(channel) function returns either a single character string reporting the SEP or field separator
value (in hex) for a given file OPEN on a given channel or it returns "" (NULL).
The value returned is the value you set in the SEP=option when creating a KEYED or INDEXED file (a
single character string which can be anything from $00$ to $FF$).
The function returns "" (NULL) for a dynamic field separated file (a keyed or indexed file created using a
SEP=* option). With this type of file, ProvideX stores each field in the record with a one-byte prefix
identifying the type and length of data that immediately follows.
Example:
In this example, the function returns $8A$, the ProvideX default separator value.
->open (14)"pvx_dir"
->?hta(sep(14))
8A

SERIAL Create a Sequential File
Directive SERIAL
Format:
Create Sequential File SERIAL filename$[,max_rec[,max_datasize]][,ERR=stmtref]
Where =
filename$ String variable that defines the name of the SERIAL (sequential) file to create.
max_rec Estimated number of records the file is to contain. The default is no initial allocation
of file space, with no limit as to final size. (Not used in most operating system
implementations.) Numeric expression.
max_datasize Maximum size of the data portion of the record. (Optional on most operating
systems.) Numeric expression.
Description:
When you use the SERIAL directive to create a SERIAL (sequential or flat) file, ProvideX creates a
standard text data file in a format the Operating System can access directly.
Your record size is "for documentation purposes only" on most operating systems. If you do specify the
size, make it large enough to hold all the data fields written to the file for each record.
If a file of the name you use already exists, Providex returns an Error #12: File does not exist
(or already exists).
Examples:
Both examples below create files whose structures are viewed by Providex as SERIAL (or unknown type):
0010 SERIAL "PRNTFL",,133
0010 SERIAL A$+""+B$,100,50,ERR=1090
SERIAL "[WDX]somefile.ext"... (If you are running an earlier version of
626.
In older versions, for instance, you would use:
EXECUTE "[wdx]serial ""c:\tmp\junk.txt"""
Programs without Line Numbers

ProvideX supports programs written without line numbers. At present the only way to define or edit a
program without line numbers is to use an external editor such as 'notepad' under WINDOWS or 'vi' in
UNIX. When you create a SERIAL file containing such a program and LOAD it into ProvideX, ProvideX
assigns arbitrary line numbers to allow for standard console editing, but will not allow any new / edited line
to reference line numbers. (You can use logical statement labels.)
See also: Labels: Logical Statement References, p. 582
'NN' No Line Numbers as References, p. 551(p)

SAVE Write Program to File, p. 370(d)

SET_FOCUS Set Input Focus
Directive SET_FOCUS
Format:
1 Focus ON SET_FOCUS ctl_id

2 Retry SET_FOCUS RETRY ctl_id
3 Read CTL Value SET_FOCUS READ ctl_id
Where =
ctl_id Unique ctl_id of your custom control (BUTTON, LIST_BOX, DROP_BOX, etc.) to
which to direct subsequent input. Numeric expression.
Description:
Use the SET_FOCUS directive to set the Focus on the custom control you want to receive the next user
input. Providex returns an Error #65: Window element does not exist or already exists
if you use SET_FOCUS for a non-existent or disabled control item.
Format 1 Sets Focus ON: SET_FOCUS ctl_id

Setting the focus to a control directs subsequent terminal input to it, unless the user overrides it with the
mouse. If the value of the ctl_id is zero, input is directed to the screen INPUT directives.
Example:
1000 BUTTON 100,@(10,10,10,2)="Write"
1010 BUTTON 101,@(15,10,10,2)="Delete"
1030 SET_FOCUS 100
The next keyboard input will be directed to the Write' button.
Format 2 Retries: SET_FOCUS RETRY ctl_id

Use the SET_FOCUS RETRY format to set an internal "modified" flag on the control. If the user attempts
to <Tab> away from the control, it will retry its associated CTL event. You can use this in input validation
(i.e. when an application detects invalid input). You can issue a SET_FOCUS RETRY directive to have
ProvideX reprocess the input field whether the user changes something or simply <Tab>s away from it.
Format 3 READs CTL Value: SET_FOCUS READ ctl_id

Use SET_FOCUS READ to obtain the CTL value of the control which currently has focus. The CTL value
is 0 (zero) if no control has focus.

SET_NBF Set Number of Keyed I/O Buffers
Directive SET_NBF
Format:
Obsolete: (Included here for completeness only.) This directive is obsolete and has been
replaced by the 'BF' System Parameter. See 'BF'=num Common Buffers, p. 539(p).
Set Number of Buffers SET_NBF buffers
Where =
buffers Number of internal key I/O buffers. Numeric expression.
Description:
You can use the SET_NBF directive to adjust the number of internal buffers to be used by the key I/O
manager. Use values in the range 0 (zero) to 25. By allocating more buffers, you can typically obtain
better keyed access performance. Normally the default of 10 buffers yields good overall performance. If
you use the BF parameter to set the number of buffers to zero, this will force ProvideX to allocate local or
file-specific buffers (controlled by the parameter FB).
Using this directive to optimizing system performance takes a great deal of experience. Many factors
influence the number of buffers required. The system may slow down if too many buffers are assigned,
causing excessive queue searching. Too few buffers may cause additional disk I/Os. In a single user
environment (e.g. MS-DOS) more buffers will typically improve performance, since ProvideX will use
these buffers to cache disk reads and writes.

SET_PARAM Set System Parameters
Directive SET_PARAM
Format:
Set System Parameter(s) SET_PARAM [param_list]
Where =
param_list List of mnemonics and optional values for setting various System Parameters for
your ProvideX environment.
Description:
Use the SET_PARAM directive to set System Parameters. These parameters set internal options in
ProvideX. For the list of possible parameters that can be set, see the section on System Parameters, p.
537 at the end of this Language Reference.
You can find the current value or state of these parameters using the PRM( ) function and the system
variable PRM.
See also: PRM Current ProvideX Parameter Settings, p. 324(v)
Examples:
0100 PRINT PGN
0110 SET_PARAM 'OP'
0120 PRINT PGN
-:run
C:\PVX\MANUAL\TST\TST_EGS
TST_EGS
SET_PARAM AH ! Switches Alternative Heading ON

SET_PARAM -AH ! Minus sign switches AH OFF
SET_PARAM BY=0 ! sets the Base Year to Julian calendar base
SET_PARAM BY=1970 ! resets Base Year to default
You can use a Boolean value to reset a switch. For example:
SET_PARAM AH=0 ! switches AH off
->?prm('ah')
0

SETCTL GOSUB on CTL Event
Directive SETCTL
Format:
Set Control Value SETCTL val:stmtref
Where =
val CTL value to intercept. Numeric expression.
Description:
When ProvideX executes your SETCTL directive, it intercepts CTL values on INPUT statements and
transfers control via a GOSUB to your specified line or statement label. On completion of the subroutine
(e.g. on a RETURN) control will pass back to the INPUT statement where the event was intercepted.
To reset a SETCTL, set the stmtref to 0000. If your stmtref = 0000, the logic to intercept the CTL value is
deleted.
See also: CTL Control Code: Key Used to End Input, p. 53(v)
GOSUB ... RETURN Execute Subroutine, p. 165(d)
NOTE: SETCTL is only valid for the program it was executed in, not any subsequent
programs (e.g. those initiated through CALL, PERFORM or RUN directives).
Example:
0010 SETCTL 3:2000
0020 SETCTL 4:9000
0100 INPUT (0,err=0100) @(x,y), "Enter Name:",A$
2000 ! refresh screen
2010 PRINT 'RS',; RETURN
9000 ! exit routine
9010 EXITTO 9900
9900 END
In the above example, whenever the CTL value is 3 on the INPUT statement (i.e. the user hits the <F3>
key), control is passed to the subroutine at line 2000. When the RETURN statement is executed, control
passes back to the line that contained the INPUT statement.

SETDAY Change Local Date
Directive SETDAY
Format:
Set System DAY Variable SETDAY [date$]
Where =
date$ Date to assign to the DAY variable for the current session. String expression.
Description:
Use the SETDAY directive to set or change the current local processing date for the current user and
session (returned in the DAY variable). The DAY_FORMAT of the string-expression is the default, MM/
DD/YY, unless you specify a different setting in a DAY_FORMAT directive. ProvideX will continue to
update the altered date based on the current time and date.
The altered date will stay in effect until the end of the session or until the execution of a START directive.
Then ProvideX reverts to the Operating System's current date. Note that this directive calculates an offset
from the current Operating System date/time. If the Operating System date is altered after the execution of
the SETDAY directive, a corresponding change will be reflected in the value of DAY.
See also: DAY Return Current System Date, p. 67(v)
NOTE: This directive only affects the user executing the directive.
Example:
0090 SETDAY "11/15/00"
0100 PRINT DAY
0110 SETDAY "02/26/00"
0120 PRINT "Today's date is ",DAY
->RUN
11/15/00
Today's date is 02/26/00
The date 02/26/99 is only in effect for the current session. If the O/S date and time are advanced by 3
days (to the 18th of November) during the current session, then the current session date 02/26/99 will be
advanced to 02/29/99 for the current user.

SETDEV Set Device Type Name
Directive SETDEV
Format:
Set Device Type Name SETDEV (chan)lcs_devtype$
Where =
chan Channel or logical file number of the file for which the device type is being overridden.
devtype$ The lower-case string value defining the device type. Its maximum length is 12
characters. String expression.
Description:
Use the SETDEV directive to make dynamic changes in the value of the DEVICE TYPE field maintained by
ProvideX for device files. This directive is applicable primarily to device drivers and then only those that
can support more than one device type on the same port.
When you use this directive, the device driver '*DEV/DIAL-UP" changes the device type field for a dial-up
terminal based on the type of terminal actually connecting to ProvideX.

SETDEV TSK( ) Add to the TSK( ) List
Directive SETDEV TSK( )
Format:
Add to Task Table SETDEV TSK( ) task$
Where =
task$ String of characters to add to the TSK( ) table. String expression.
Description:
Use the SETDEV TSK( ) directive to add the value of your string to the end of the internal table for the
TSK( ) function. Each time SETDEV TSK( ) is used, the task$ is evaluated and appended to the internal
table.
Dont include a task number in your SETDEV TSK( ) directive. (That generates a syntax Error #20.)
ProvideX automatically supplies the next available number in sequence. The order of the table is
determined by the order in which your SETDEV TSK( ) directives are executed. ProvideX places the string
from the first SETDEV TSK( ) into TSK(0), the second into TSK(1) and so on. If you use the TSK( )
function with an invalid task number, ProvideX returns an Error #41: Invalid integer encountered
(range error or non-integer).
See also: TSK( ) Returns Entry from Task List, p. 438(f)
Example:
0100 SETDEV TSK()"lp - hp laserjet on johns desk"
0110 SETDEV TSK()"p1 - epson printer - spooled"
0120 PRINT TSK(0),'LF',TSK(1)
LP - hp laserjet on johns desk
P1 - epson printer spooled

SETERR Set Error Transfer
Directive SETERR
Format:
1 Error Transfer to Line/Label SETERR stmtref[,ERR=stmtref]

2 Error Transfer to Program SETERR prog$
3 Error Transfer to Entrypoint SETERR prog$[;entry$]
Where =
prog$ Name of a generic error-trapping program. Define it once and its good for the rest
of the session throughout the system.
;entry$ Optional entry label in the error-trapping program. Define once per session.
Description:
Use the SETERR directive to define the transfer address for any error for which you have not used the
ERR= option. While a SETERR is in effect, any error (divide check, subscript range error, etc.) transfers
control to the statement number, label or program you specify in the SETERR directive. To disable the
SETERR transfer in a program, use statement number 0000 as your stmtref.
Once a SETERR transfer occurs, ProvideX inhibits further SETERR transfers until either another SETERR
is executed or a RETRY directive re-executes the statement which caused the error. This prevents
system looping caused by errors in an error handler.
Order of Precedence:
The chart below shows the order of precedence for error handling:
ERR= Error trapping at the line level

SETERR stmtref General error trapping within a program
SETERR "prog;entry" General error trapping for the current
session. Entrypoint is optional.
... else ... Drop to the console and report the error
See also: Error Processing
Examples:
3160 SETERR 3230
3170 DATA 1,2,3,"CAT"
3180 DATA 4,5,6,"DOG"
3190 READ DATA IOL=3220
3200 PRINT IOL=3220
3210 GOTO 3190
3220 IOLIST X,Y,Z,A$
3230 PRINT "GOTCHA"
3240 SETERR 0000 ! Disables SETERR
3250 STOP
-:GOTO 3160; BEGIN; RUN
1 2 3CAT
4 5 6DOG
GOTCHA

SETESC Set Interrupt Handler Procedure
Directive SETESC
Format:
1 Subroutine Interrupt-Handler SETESC stmtref

2 Subprogram Interrupt-HandlerSETESC prog_name$
Where =
prog_name$ Program ProvideX is to call to process break / escape signals. Use a NULL string ("")
to reset the SETESC prog_name$.
Description:
Use the SETESC directive to specify the subroutine or subprogam to handle a break request. You can use
this directive to prevent a user from breaking out of a program during critical periods or for security
reasons.
See also: SETESC On / Off: Set Interrupt Processing ON/OFF, p. 387(d)
Format 1 for Interrupt Handler in Subroutine: SETESC stmtref

Use this format to specify a subroutine written to handle break requests. If a SETESC is active and the
user enters <Break> or <Esc>, ProvideX performs a GOSUB to the statement you designate in this format
of the SETESC directive. Use the RETURN directive if you want control to return to the original program
flow after the subroutine processes the break request.
To deactivate the SETESC directive, set the stmtref to 0000.
Example:
0010 SETESC BREAK_IT
0020 FOR I=1 TO 1000000
0030 PRINT I,
0035 IF I=50000 THEN SETESC 0000
0040 NEXT I
0050 STOP
1000 REM BREAK HANDLER ---
1005 BREAK_IT:
1010 PRINT 'LF',"Please wait till I'm finished."
1030 PRINT "... I've lost track."
1040 PRINT " I'll have to start again."
1050 LET I=1
1055 WAIT 5 ! Or messages flash by, user doesnt see, breaks again...and again
1060 ! RETURN [REMarked to prevent loops each time user hits <CTL-BREAK> ... ]
-:RUN
1 ... ... ...
58 14959 14960 14961 14962 14963 14964 14965 14966 14967 14968 14969 14970 14971
14972 14973 14974 14975 14976 14977 14978 14979 14980 14981 14982 14983 14984 1
4985 14986 14987 14988 14989 14990 14991 14992 14993 14994 14995 14996 14997 149
98 14999 15000 15001 15002 15003 15004 15005 15006 15007 15008 15009 15010 15011
15012 15013
When the user hits <Ctrl-Break> above, the program halts the display at loop 15013 and the messages
are displayed:

Please wait till I'm finished.
... I've lost track.
I'll have to start again.
If you use similar examples, try making the RETURN conditional and/or lengthen the WAIT. Otherwise, the
user misses the messages and retries the <Break> key. Since the program RETURNS and restarts with
each <Break> (not a judicious use of the RETURN directive in this instance), your user will have time for
other things (like calling you) while the machine recovers from its <Break>down. Line 0035 (above)
terminates SETESC handling.
Format 2 for Interrupt Handler in Subprogram: SETESC prog_name$

You can use this format to specify a program ProvideX is to CALL automatically to process break / escape
signals. When the program EXITs, execution will resume.

SETESC On / Off: Set Interrupt Processing ON/OFF
Directive SETESC ON or OFF
Format:
1 Interrupt Process ON/OFF SETESC {ON | OFF}

2 Enable/Disable for Range SETESC {DISABLE | ENABLE}
Description:
Use the SETESC directive to enable/disable recognition of the <Esc> and <Break> keys in ProvideX.
Format 1 Sets ON/OFF in Program: SETESC {ON | OFF}

If you apply a SETESC OFF directive in your current session or program, ProvideX treats your users
subsequent use of the break keys as equivalent to a carriage return or <Enter>. That is, the users <Esc>
key or <CTL-C> terminates the current input (e.g. by advancing to the next input) but does not let the user
halt a program in EXECUTION mode from the keyboard. A <Ctrl-Break> retries the current input but does
not halt program execution.
If you use SETESC ON, ProvideX recognizes your users <Ctrl-Break> input and halts EXECUTION.
Example 1:
0010 SETESC BREAK_IT
0020 DATA 1,2,3,"CAT"
0030 DATA 4,5,6,"DOG"
0040 DATA 7,8,9,"PIG"
0050 DATA 3,2,1,"DONE"
0060 READ DATA A,B,C,X$,ERR=0110
0070 PRINT A,B,C,X$
0080 INPUT "Try to break out: ",Y$
0090 GOTO 0060
0100 BREAK_IT: PRINT "That was easy."; STOP
0110 PRINT "Error on the READ (EOF)"
0120 STOP
Results when RUN under DOS / WINDOWS with SETESC ON, then OFF:
-:SETESC ON -:SETESC OFF

User Entered: -:RUN -:RUN
1 2 3CAT 1 2 3CAT
<Enter> Try to break out: Try to break out:
4 5 6DOG 4 5 6DOG
<Esc> Try to break out: Try to break out:
7 8 9PIG 7 8 9PIG
<Ctrl-C> Try to break out: Try to break out:
3 2 1DONE 3 2 1DONE
<Ctrl-Break(s)> Try to break out: That was Try to break out: Try to
easy. break out: Try to break
-: out: Try to break out: Try
to break out:
Your SETESC ON / OFF directive is in effect for the duration of the session or until you reverse it with your

next SETESC OFF / ON.
Format 2 for Range of Statements: SETESC {DISABLE | ENABLE}

When you use the SETESC DISABLE directive, that disables SETESC for a range of statements.
ProvideX ignores all subsequent SETESC stmtrefs until a SETESC ENABLE is encountered. You can
make use of the DISABLE option in debugging a program which has embedded SETESC directives.

SETFID Set FID(0) Definition
Directive SETFID
Format:
Define FID(0) Settings SETFID fid_def$
Where =
fid_def$ String value to define FID(0). Its maximum length is 12 characters. String
expression.
Description:
Use the SETFID directive to make dynamic changes in the value of FID(0). Many old applications use the
value of FID(0) to give the current terminal a unique identifier. The SETFID directive lets you define the
actual value to be returned by the FID(0) function.
By default, ProvideX uses the value contained in the external system environment variable PVXFID0 as
the value for FID(0). If this external variable is not defined, the value of T0 (T zero) is used.
You would typically only use this directive once during a ProvideX session, and then usually in the
START_UP program.
See also: FID( ) Return File Information Descriptor, p. 145(f)
Example:
In this example, the value in the WHO system variable will be something like "SMITHJ":
0010 ! START_UP
0020 OPEN (1)"MYCONFIG"
0030 READ (1,KEY=WHO,ERR=0050)X$
0040 SETFID X$
0050 CLOSE (1)
The following example defines a unique session and terminal FID in a WINDOWS environment, given a
directory called C:\FIDS with the files "T5", "T5", "T6", T7", "T8" ... and so on. (This could also be done
with Terminal_IDs of 3 characters or more.)
In a START_UP program:
0010 OPEN (1) "C:\FIDS"
0020 READ (1,END=1000) ID$
0030 IF ID$(1,1)="." GOTO 0020 ! Skip "." and ".."
0040 %FID_FILE=GFN
0050 OPEN LOCK (%FID_FILE,RTY=0,ERR=0020) PTH(1)+DLM+ID$
0060 SETFID ID$
0070 CLOSE (1)
....
1000 MSGBOX "Sorry. No free FID for this station. End another session & try again"
1010 QUIT
This logic will open and leave open a file pertaining to the station FID. Once the task ends, the FID file will
be available for another session.

SETMOUSE Control MOUSE
Directive SETMOUSE
Format:
1 ON/OFF SETMOUSE {ON | OFF}

2 Define Mouse Region SETMOUSE [*]@(col,line,width,height){= | :}[expression]
3 Use String to Define Event SETMOUSE [*]string${= | :}[expression]
4 Use Current Window Size SETMOUSE [*]@(*){= | :}[expression]
5 Clear Mouse Settings SETMOUSE CLEAR
Where =
* (asterisk) The first instance of an asterisk in Formats 2 through 4 above defines the mouse
event as being for all windows. (Optional.) The second instance of the asterisk in
Format 4 is a size option. See the next row of this chart.
col,line, Mouse region coordinates. Numeric expressions: starting column, starting line, width
width,height (number of columns) and height (number of lines).
If you use an optional single asterisk instead of col,line, width,height, you define the
mouse region for the event as equal in size to the current window.
= | : Operators control mouse event processing:
: (colon) Process if mouse button is pressed (or dragged) in the region.
= (equals sign) Process if mouse button is released in the region.
expression Expression to define the type of function for mouse events in the specified region:
if numeric, the CTL value to return
if string, the directive to EXECUTE
string$ Character string to be compared to the current screen contents. String expression.
Description:
Use the SETMOUSE directive to define and control mouse events. By default, the mouse events are tied
to the current window only. The SETMOUSE directive now supports fractional coordinates to two decimal
places (Ver. 4.10).
NOTE: Only a single SETMOUSE directive can be active for the same region at any time.
Format 1 Enables or Disables the Mouse: SETMOUSE {ON | OFF}

Use SETMOUSE ON to enable the mouse or SETMOUSE OFF to disable it.
Format 2 Defines Mouse Region: SETMOUSE [*]@(col,line,width,height){= | :}[expression]

Use this format to define the region in which a mouse event can occur. You can use an optional asterisk to
define the mouse event as being for all windows instead of just the current window.
Example:
0010 REM Return CTL=4 when mouse released on line 20 in columns 0 through 5
0010 SETMOUSE ON
0020 PRINT 'CS',@(0,20),"[Quit]",

0030 SETMOUSE @(0,20,6,1)=4
0100 INPUT @(10,10),"Enter name:",X$
0110 IF CTL=4 THEN GOTO 9000 ! Wrap-up
Format 3 Uses String to Define Event: SETMOUSE [*]string${= | :}[expression]

Use this format to define a character string to set the function the mouse event will generate. To remove a
mouse event definition use a NULL "" expression. You can use an optional asterisk to define the mouse
event as being for all windows instead of just the current window.
Example:
This logic returns CTL=6 whenever the mouse is released on the string 'Help' and CTL=4 on the string
'Quit'. Whenever the mouse is released on the word 'Calc', ProvideX CALLs "CALC" then returns to the
current statement after "CALC" is executed.
0010 SETMOUSE ON
0020 SETMOUSE *"Help"=6 ! Help request
0030 SETMOUSE *"Quit"=4 ! Quit request
0040 SETMOUSE *"Calc"="CALL ""CALC"""
Format 4 Uses Current Window Dimensions: SETMOUSE [*]@(*)(= | :}[expression]

The first optional asterisk defines the mouse event as being for all windows instead of just the current
window. Use the second asterisk "*" in this format to define the mouse region as equal to the dimensions
of the current window.
Format 5 Clears All Settings: SETMOUSE CLEAR

Use this format to remove all previously defined SETMOUSE regions.

SETTIME Set Local Time
Directive SETTIME
Format:
Set Current Time for User SETTIME [time]
Where =
time Current time of day for the user session. Numeric expression.
Description:
Use the SETTIME directive to set or change the current processing time (returned in the TIM, TME, and
TMS variables). The value of the your time must be between 0 and 24 (the desired time of day based on a
24 hour clock). Once set, the time will be continuously updated based on the operating system clock.
ProvideX will continuously update the date and time based on your altered time until the end of your
session or until the execution of a START directive. Then ProvideX reverts to the Operating System's time.
Note that this directive calculates an offset from the current Operating System date/time. If that date/time
is altered after the execution of the SETTIME directive, a corresponding change will be reflected in the
values of TIM/TME/TMS.
See also: TIM Time in Hours Past Midnight, p. 427(v)
TME Time In Hours Past Midnight, p. 428(v)
TMS Seconds Expired in Current Minute, p. 430(v)
NOTE: This directive only affects the user executing the directive.
Example:
0100 PRINT TIM
0110 SETTIME 1.10
0120 PRINT "Current time",TIM
RUN
8.51
Current time 1.10
If the O/S time were advanced by an hour (i.e. from 8.51 to 9.51), that hour would also be added to the
time for the current session, advancing the current sessions time to 2.10 and setting TIM, TME and TMS
to the new value.

SETTRACE Enable Program Tracing
Directive SETTRACE
Format:
1 Set Trace, Define File SETTRACE [(chan)]

2 Trace File String SETTRACE PRINT (string$)
Where =
chan Channel or logical file number of the file to which the trace output is to be written.
string$ Contents of the string will be sent to the trace window or file that is active. If no trace
device is active, the directive is ignored.
Description:
When you use the SETTRACE directive, ProvideX lists all statements as they are executed until an
ENDTRACE is encountered.
The END and STOP directives halt tracing. Tracing is suppressed during the execution of a password-
protected program.
When tracing, ProvideX lists the statements either to the terminal or to a file (if you designate one in a
SETTRACE PRINT directive). If you use a file, you have to OPEN it first and if it's a SERIAL file, you have
to LOCK it.
It can be confusing if an error occurs in the output/trace file, since the error will be reported as an error for
the current statement being traced, which itself may not be in error.
See also: ENDTRACE End Trace Output, p. 116(d)
Examples:
0010 I=3
0020 A=A*A
0030 I=I-1; IF I<>0 THEN GOTO 0020
->SETTRACE
->run
0010 I=3
0020 A=A*A
0030 I=I-1; IF I<>0 THEN GOTO 0020
0020 A=A*A
0030 I=I-1; IF I<>0 THEN GOTO 0020
0020 A=A*A
0030 I=I-1; IF I<>0 THEN GOTO 0020
->endtrace

SGN( ) Return Sign of Value
Function SGN( )
Format:
Return Sign (by Status Code) SGN(num[,ERR=stmtref])
Where =
num Value whose sign is to be returned. Numeric expression.
Returns: Status code, 0 (zero), 1 or -1
Description:
The SGN( ) function returns a numeric status code for the sign of a value:
Returns When
0 Value is 0 (ZERO)
1 Value is POSITIVE
-1 Value is NEGATIVE
Example:
?SGN(23.492) ! yields 1
?SGN(4-4) ! yields 0
?SGN(4-7.34) ! yields -1

SHORT_FORM Use Short Variable Names
Directive SHORT_FORM
Format:
Use Short Variable Names SHORT_FORM
Description:

Use the SHORT_FORM directive to have the compiler input-parsing accept only short variable names
(emulation/compatibility mode). Its complementary directive is LONG_FORM which allows long variable
names.
Programs can be written in either SHORT_FORM or LONG_FORM or in a combination of both and can
run in either mode.
See also: 'SF' Short_Form Variables, p. 557(p)
LONG_FORM Use Long Variable Names, p. 249(d)
Example:
SHORT_FORM
-:ABCDE$="ABCDE$ IS NOT OK"
Error #20: Syntax error ...BCDE$="ABC... (Long variable name not accepted)
-:A$="A$ IS OKAY"
-:LONG_FORM
-:LONG_NAME$="LONG_NAME$ IS OK"
-:

SHOW Show Control
Directive SHOW
Format:
Show Hidden Control SHOW ctl_id
Where =
ctl_id Unique ctl_id for the hidden object or custom control (BUTTON, LIST_BOX, etc.).
Description:
Use the SHOW directive to redisplay your given hidden control object so that the user can see it and the
program can set the Focus on it.
(The HIDE directive hides a control from display. While the control is hidden it is still active for the
purposes of reading/writing but the user cannot see it, nor can the program set Focus on it.)
See also: HIDE Hide Control, p. 178(d)
Example:
0010 BUTTON BTN.VISA,@(10,10,10,2)="&Visa Info"
0100 READ (1,KEY=CUST_ID$)IOL=1000
0110 IF CST.TERM$="CHQ" THEN HIDE BTN.VISA ELSE SHOW BTN.VISA

SID System Identification Code
String System Variable SID
Returns: String, Operating System identification code
Description:
This string system variable returns a string reporting the system identification code as defined by the
Operating System.
Example:
->?SID
MSDOS
->

SIN( ) Sine Function
Function SIN( )
Format:
Return SINE SIN(num[,ERR=stmtref])
Where =
num Number whose SINE will be returned. Numeric expression.
Returns: Numeric, range -1 to 1
Description:
The SIN( ) function returns the SINE of the numeric expression specified. It will return a numeric value
between -1 and 1, rounded to the current PRECISION in effect. Its inverse function is ASN( ).
Example:
0060 FOR I=-1000 TO 1000 STEP 100
0070 PRINT SIN(I)," ",
0080 NEXT
0090 PRINT " DONE"
0100 END
-:run
-0.83 -1 -0.89 -0.54 -0.04 0.47 0.85 1 0.87 0.51 0 -0.51 -0.87 -1 -0.85 -0
.47 0.04 0.54 0.89 1 0.83 DONE

SORT Create a File for Sorting
Directive SORT
Format:
Create Data SORT File SORT filename$,max_keysize[,max_rec][,ERR=stmtref]
Where =
filename$ Name of the SORT file to create. String expression.
max_keysize Maximum key size to be maintained for this file. Numeric expression.
max_rec Estimated number of records that the file is to contain. Default is no initial
allocation of file space,with no limit on final size. Numeric expression.
Description:
Use the SORT directive to create a data SORT file (a file with a key but no data record portion). You must
include the size of the key along with the name. The maximum SORT key size allowed is 127. If your
given file name already exists, ProvideX returns an Error #12: File does not exist (or
already exists).
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag, e.g., SORT
Examples:
0010 SORT "CSTFLE",6,100 creates a file with the following structure:
Keyed file: C:\OTHER\MANUALS\PVX\CST\CSTFLE
Maximum Record size ..........: 0 (Sort file)
0010 SORT A$+"_"+B$,10,100,ERR=1090 creates the following structure:

Keyed file: C:\OTHER\MANUALS\PVX\CST\CST_TST
Maximum Record size ..........: 0 (Sort file)

SQR( ) Square Root
Function SQR( )
Format:
Return Square Root SQR(num[,ERR=stmtref])
Where =
num Value whose square root is to be returned. It must be a positive number. Numeric
expression.
Returns: Numeric, square root of given value
Description:
The SQR( ) function returns the square root of the number you provide, rounded to current PRECISION. If
you use an invalid value (e.g. a negative value such as SQR(-2.345)), ProvideX returns an Error
#40: Divide check or numeric overflow.
Example:
0010 INPUT "Length of one side: ",A
0020 IF A=0 THEN GOTO 0080
0030 INPUT "Length of other : ",B
0040 IF B=0 THEN GOTO 0080
0050 PRINT "Hypotenuse is : ",SQR(A*A+B*B,ERR=0070)
0060 GOTO 0010
0080 INPUT "Need 2 sides. Try again? Y/N: ",A$
0090 IF A$="Y" OR A$="y" THEN GOTO 0010
0100 PRINT "DONE"
-:run
Length of one side: ! User hit <Enter>
Need 2 sides. Try again? Y/N: y
Length of one side: 2.3
Length of other : 1.65
Hypotenuse is : 2.83

SRT( ) Sort String
Function SRT( )
Format:
1 Sort Equal Len. Elements SRT(string$,fixed_len[,ERR=stmtref])

2 Sort Delimited Elements SRT(string$[,dlm_char$][,ERR=stmtref])
Where =
string$ String to be sorted. String expression.
fixed_len Numeric expression. Length of each element in the string (all the same fixed length).
dlm_char$ Delimiter for each string element. If you omit this, SEP=$8A$ is the default.
Returns: Sorted character string
Description:
The SRT( ) function returns a sorted character string. The string elements are internally sorted into
ascending sequence. The order of duplicate elements is undefined.
TIP: To sort a string into descending order, use the NOT function to invert the bits in the
string prior to and after sorting. See also NOT( ) Invert String Bits/Logical Condition,
p. 288(f) .
Format 1 for Fixed Length Elements: SRT(string$,fixed_len[,ERR=stmtref])

If each element in the string is the same fixed length, use this format to sort the string.
Examples:
0100 REM To sort in ascending order:
0110 A$="0231405242670291234403242"
0120 PRINT SRT(A$,5)
->RUN
0231403242052421234467029
0200 REM To sort in descending order:

0220 PRINT NOT(SRT(NOT(A$),5))
->RUN
6702912344052420324202314
Format 2 for Delimited Elements: SRT(string$[,dlm_char$][,ERR=stmtref])

If each element in the string has a delimiter or SEP character, use Format 2 of the SRT( ) to sort the string.
ProvideX considers the first character of dlm_char$ to be your delimiter. (The default is the current SEP
value.)
0300 REM To sort with delimited strings:

0310 A$="THE BROWN FOX JUMPED OVER THE DOG " ! Blank as delimiter, ends string
0320 PRINT SRT(A$," ")
->RUN
BROWN DOG FOX JUMPED OVER THE THE

SSN System Software Identifier
String System Variable SSN
Returns: 16-character string, software identifier
Description:
This string system variable returns a sixteen character system software identifier. The first 4 characters
report the version number, characters 6-8 report the machine classification, and 10-16 report the software
serial number.
Example:
->?SSN
0322f001-0004029
->

SSZ( ) Return Sector Size
Function SSZ( )
Format:
Return Sector Size SSZ(drive[,ERR=stmtref])
Where =
drive Disk drive whose sector size is to be returned (ignored). Numeric expression.
Returns: Always 256
Description:

The SSZ( ) function has been provided for compatibility with Business Basic systems. In ProvideX, it
always returns 256.

START Restart ProvideX
Directive START
Format:
1 Start START [max_mem[,prog_name$]][,ERR=stmtref]

2 Launch Separate Task START prog_name$,T_id[,ERR=stmtref]
Where =
max_mem Number of 1024-byte units of memory you want to limit ProvideX to using.
prog_name$ Character string defining the initial program to be loaded and run. String expression.
T_id Terminal ID in FID(0) format for the new session. Numeric expression.
Description:
Use the START directive to specify the maximum amount of memory to be allocated to the user and
optionally the program to LOAD and RUN. If you omit the memory size, ProvideX uses the current
memory limits.
Format 1 Initializes Session: START [max_mem[,prog_name$]][,ERR=stmtref]

This format completely reinitializes the current session by closing all files, clearing all user data (including
GLOBAL variables), and clearing the current program. All memory currently allocated to the session is
released to the system and a new limit is defined.
Examples:
->START 10 ! Reinitializes with 10KB
->START 20,"INVGEN" ! Runs program INVGEN with 20KB
->START ! Reinitializes with same memory size.
Conversion Processes:
By default, a START will close ALL files and clear ALL variables. To simplify conversion processes, you
can set the 'QS' parameter ON, so that a statement like START nnn,"this_prog" will only clear local
variables (the same as a BEGIN) and start the specified program. However, we normally recommend that
you use BEGIN; RUN "this_prog" to start a new program set and that you reserve START to
completely restart the session.
NOTE: In ProvideX, the memory size might be different from other Business Basics due to
the nature of memory management for variables, arrays, program sizes, etc. You can
set the 'IZ' system parameter to have ProvideX ignore any memory size restrictions.
See also: 'IZ' Ignore Max. Memory Setting, p. 548(p)
'QS' START, Not Initialized, p. 555(p)
Format 2 Launches Separate Task: START prog_name$,T_id[,ERR=stmtref]

You can launch a new session, separate from the task issuing the START command. The contents of T_id
(your terminal identifier) will be assigned to the FID(0) value of the new session.

STK( ) Program Call Stack
Function STK( )
Format:
Return Stack Information STK(level[,ERR=stmtref])
Where =
level Program CALL stack level. Numeric expression.
Returns: String, program line number (characters 1 to 5) plus full pathname
Description:
The STK( ) function returns a character string reporting the program line number (5 digits) and program
(full path name) being executed at the program level specified.
Use a negative value to specify a level relative to the current level. ProvideX returns an Error #41:
Invalid integer encountered (range error or non-integer) if your given level does not
exist.
Example:
The current directory is "/usr/test". In program "PROG1":
0100 CALL "STACKER"
In program "/usr/test/STACKER"
0010 PRINT "Level 1=",STK(1)
0020 PRINT "Level 2=",STK(2)
0030 PRINT "Level -1=",STK(-1)
When run:
Level 1=00100/usr/test/PROG1
Level 2=00020/usr/test/STACKER
Level -1=00100/usr/test/PROG1
The next example prints all the programs in the stack:
0010 I=1-PRM('B0')
0020 PRINT STK(I,ERR=*NEXT); I=I+1; GOTO 20
NOTE: You can use PRM('B0') to circumvent a potential problem should the base level be
level 0, rather than 1.

STOP Halt Program Execution
Directive STOP
Format:
End Current Program STOP
Description:
Use the STOP directive to terminate the currently running program. If the current program is a
subprogram, then control is immediately passed back to the calling program. Otherwise all open files are
closed, a RESET operation is performed, and the next location counter is set to the start of the program.
If ProvideX was in EXECUTION mode (executing a given program name), then ProvideX performs an
automatic QUIT directive and returns the user to the Operating System. If ProvideX was in COMMAND
mode, it returns you to COMMAND mode.
When you use the STOP directive in a compound statement, it must be the final directive.
END Halt Execution of Program, p. 112(d)
Example:
0030 LET A$="Hello "
0040 GOSUB 1000
0050 PRINT B$,"|"
0060 STOP
1000 IF A$="" THEN LET I=0; RETURN
1010 FOR I=LEN(A$) TO 1 STEP -1
1020 IF A$(I,1)<>" " THEN EXITTO 1040
1030 NEXT
1040 LET B$=A$(1,I)
1050 RETURN
-:RUN
Hello|

STP( ) Strip Leading/Trailing Characters
Function STP( )
Format:
1 Strip Character STP(string$,stp_code[,stp_char$][,ERR=stmtref])
Where =
string$ String expression to be processed.
stp_code Numeric code:
0 - Strip leading
1 - Strip trailing
2 - Strip both leading and trailing
3 Strip all occurances
stp_char$ Optional character to be stripped from string. If you omit this, blanks are stripped.
String expression.
Examples:
STP(PTR$,3,$1B$) ! strips out all escape characters
STP("Hello there",3,"e") ! strips out every lower-case "e"
Returns: Stripped character string
Description:
The STP( ) function returns a character string generated by stripping specified instances of a character
from the string expression.
Format 1 Strips Character: STP(string$,stp_code[,stp_char$][,ERR=stmtref])

Use STP( ) Format 1 to strip the first character of stp_char$ (spaces if omitted) from the value in your
string$. The data is stripped either from the start or end (or from both start and end) of the string$
depending on your stp_code value. You can also use this function to strip all occurrences of a given string
expression.
ProvideX returns an Error #41: Invalid integer encountered (range error or non-
integer)if the value you use in stp_code is not in the range 0 to 3.
Examples:
Given A$ = " This is a test " STP( ) Returns:

STP(A$,0) "This is a test "
STP(A$,1) " This is a test"
STP(A$,2) "This is a test"
STP("000Test00",2,"0") "Test"
STP(A$,3) "Thisisatest"

STR( ) Convert Numeric to String
Function STR( )
Format:
1 Numeric to ASCII STR(num[:mask$][,err_val][,ERR=stmtref])

2 ASCII String to Mask STR(string$:mask$[,err_val][,ERR=stmtref])
Where =
num Numeric value to convert to a character string.
string$ String value to convert and validate. String expression.
mask$ Format mask to be used in the conversion process. String expression.
err_val Optional error value to return should the conversion fail. Numeric expression.
If you omit the err_val and the conversion fails, ProvideX will either report an Error
#43: Format mask invalid or return the value unformatted, depending on your
setting for the System Parameter 'FI' Ignore Format Mask Errors, p. 545(p).
Returns: String, converted and validated
Description:
The STR( ) function converts and validates strings. You can add a format mask to specify the size and
format of the resultant character string. When you include a format mask, the STR( ) function returns a
string value converted from a numeric using the default decimal point and thousands separator set by the
'DP' and 'TH' System Parameters, p. 537. (If you omit the format mask, 'DP' and 'TH' settings are
ignored.)
See also: 'DP'=num Decimal Point Symbol, p. 542(p)
Format 1 for Numeric String to ASCII: STR(num[:mask$][,err_val][,ERR=stmtref])

Use this format to convert a numeric value to an ASCII character string.
Examples:
A$=STR(5*6) ! (yields A$="30")
A$=STR(5*6:"000") ! (yields A$="030")
A$=STR(.01:"0.00") ! (yields A$="0.01")
A$=STR(99:"0.00","****") ! (yields A$="****")
Format 2 for ASCII String to Mask: STR(string$:mask$[,err_val][,ERR=stmtref])

Use this format to convert and validate a string value based on the contents of a format mask. The format
mask dictates the size and content of each of the results.
Examples:
A$=STR("cat":"AAA") ! (yields A$="CAT")
A$=STR("MIKE":"Aa(10)") ! (yields A$="Mike")
A$=STR("1234567":"000-0000") ! (yields A$="123-4567")

A$=STR("AB":"00","**") ! (yields A$="**")
See also: "Numeric Format Masks" and "String Format Masks".

SUB( ) Substitute
Function SUB( )
Format:
Substitute (Ver. 4.20) SUB(string$,search_for$,replace_with$[,instance])[,ERR=stmtref]
Where =
string$ String expression containing the string in which to search-and-replace / perform the
substitution.
search_for$ Value for which to search. String expression. Cannot be NULL.
replace_with$ Text to replace the original (search_for$) text, if found. String expression. You must
include a replace_with$ value, but the value can be NULL (e.g.
SUB(A$,B$,"",0,ERR=100).
instance (Optional.) Which occurrence to find. Integer:
0 All occurrences (assumed if not given)
>0 Specific occurrence, searching left to right within the string$ (i.e.,1=first
occurrence, 2=second occurrence ...).
<0 Specific occurrence, searching from right to left (i.e., -1=first occurrence
from end, -2=second occurrence from end of string$ ...
Returns: Converted string
Description:
The SUB( ) function performs a substitution within a string (Ver. 4.20). Searches are performed without
regard to case. The value being searched_for cant be NULL. (That generates an Error #46: Length
of string invalid.) If no substitutions occur, no error is generated.
Example:
0110 LET A$="Hello there",B$="e",Z$=SUB(A$,B$,"",0)
0110 PRINT Z$+" "+A$
0120 END
-: run
Hllo thr Hello there

SWITCH Branch Control
Directive SWITCH
Format:
Control Branching SWITCH expression
Where =
expression String or numeric expression to control branching.
Description:
Use the SWITCH directive to have control branch to one of a list of possible statements
ProvideX evaluates your expression to determine the target statement for the branch. If the CASE isnt a
defined one, the DEFAULT applies. If a match is found, execution continues after the matching CASE until
a BREAK is encountered or the END SWITCH statement is reached.
NOTE: Since SWITCHes are maintained on the stack, you mustnt break within another
stacked context. When ProvideX encounters an EXITTO or RETURN within the scope
of a SWITCH, it removes the current FOR / GOSUB / WHILE / REPEAT entry from the
stack, but does not exit the SWITCH.
See also: END SWITCH End Branching of a Program, p. 114(d)
CASE Branch Points, p. 36(d)
DEFAULT Branch If No Matching CASE, p. 74(d)
Example:
Preset the value of A$ if you RUN this example, or see the chart below the LISTing for sample results.
5000 SWITCH A$
5040 CASE "Nephew"
5060 DEFAULT
5080 END SWITCH
5090 PRINT "DONE"

A$="Alligator" Domestic Animal CASE matched. Note that "Alligator" in this example
Break drops through with no BREAK to intervene between it
DONE and the other cases. "Alligator" doesnt DEFAULT to
"Wild Animal".
Break
DONE
a$="cat" Wild Animal DEFAULTs. Not defined. (Note that CASE is case-
DONE sensitive.)


SWP( ) Swap Data
Function SWP( )
Format:
Swap Data SWP(string$[,swp_code][,ERR=stmtref])
Where =
string$ String expression whose bytes are to be swapped.
swp_code Type of byte-swapping to be performed. Numeric expression. See the chart below.
Returns: Conversion of data, native machine format to / from ProvideX common format
Description:
The SWP( ) function is designed to simplify the conversion of data between native machine format and
ProvideX common format. ProvideX processes data with the most significant information to the left (i.e.
you read the data from left to right) where some computers store data with the most significant data at the
right.
The SWP( ) function gives you a convenient way of rearranging the data so it can be exchanged. If you
don't supply a swap type, the function will rearrange the data according to the native operating mode of the
machine. For example, on the INTEL 80x86 CPUs, a SWP( ) of "12345678" yields "87654321".
Unfortunately not all swapping algorithms are this easy. Some computers swap every two characters,
some every four characters and some every eight characters. The following table describes the various
types of swapping based on a value of "12345678":
Type Value Type Value

0 12345678 4 56781234
1 21436587 5 65872143
2 34127856 6 78563412
3 43218765 7 87654321
NOTE: This function is compatible with other languages. Just contain the swap type in a
single byte as the binary value of the desired type (i.e. $01$, $02$, ...).

SYS Operating System Identification
String System Variable SYS
Returns: String, name of Operating System
Description:
This string system variable returns a character string telling you the name of the Operating System.
Example:
->?SYS
MS-DOS

SYS( ) Invoke Operating System Command
Function SYS( )
Format:
1 For Every O/S Except UNIX SYS(command$[,ERR=stmtref])

2 Only for UNIX SYS(pid[,signal][,ERR=stmtref])
Where =
command$ Command to be processed. String expression.
pid UNIX Process ID value to check / notify. Numeric expression.
signal Optional signal value to send to the UNIX Process ID. Numeric expression.
Returns: Operating System code identifying command passed to it by the function
Description:
The SYS( ) function passes your string or numeric PID to the Operating System command processor for
execution.
Format 1 for Every O/S except UNIX: SYS(command$[,ERR=stmtref])

The function returns the Operating Systems code identifying the command. The SYS( ) function will return
a zero if the task is running and not zero (usually -1) if it is unsuccessful. The value in the system variable
RET can be checked for an error value if the function was unsuccessful.
0010 PRINT 'CS',"Menu"

0020 PRINT " 1: List directory"
0030 PRINT " 2: Run WORD processor"
0040 PRINT " 3: Run SPREADSHEET"
0050 PRINT " X: Sign off"
0060 INPUT "Enter selection:",X$
0070 IF X$="1" THEN LET X$="ls"; GOTO 0500
0080 IF X$="2" THEN LET X$="wp"; GOTO 0500
0090 IF X$="3" THEN LET X$="123"; GOTO 0500
0100 IF X$="X" THEN QUIT
0110 PRINT 'RB',; GOTO 0060
0500 A=SYS(X$)
0510 IF A<>0 THEN PRINT "Command '"+X$+"' FAILED"
0520 GOTO 0020
Format 2 for UNIX: SYS(pid[,signal][,ERR=stmtref])

You can send a signal from another PVX session or from the UNIX shell to generate a CTL event using a
SIGNAL 2 (a SIGBREAK that initiates a program's SETESC branch) and you can also send signals from
inside a ProvideX program. The GID variable contains the binary value of the UNIX Process ID
(pid=dec($00$+gid)). You can use this value with the SYS( ) function to create a signal to another
process:
X=SYS(pid,2)
where the first argument is the PID signal to send and the second is the signal number.

TCB(89) returns the numeric value of the current Process ID (PID). You can use this as a replacement for
the use of DEC($00$+GID) to retrieve the current PID value (Ver. 4.).

SYSTEM_HELP Invoke Windows Help
Directive SYSTEM_HELP
Format:
Invoke Windows Help SYSTEM_HELP help_path$[,help_key$][,ERR=stmtref]
Where =
help_path$ Pathname of the help file. String expression.
help_key$ Key to start with in the help file. This string expression must exactly match an entry
unless the first character is:
"?" to denote a partial key
"#" to denote that the key is the help index
Description:
NOTE: This directive only functions in WINDOWS or with the WindX terminal driver. When
using WindX, the help file must be resident on, or directly accessible to, the remote
workstation.
Use the SYSTEM_HELP directive to invoke the standard WINDOWS Help system. You must supply your
own help files created in accordance with the WINDOWS standard.
You can indicate the key to start with in the Help index. (Optional.) If you use a partial key (?), the help
subsystem tries to find the entry in the Help index that most closely matches it. If the first character is a #
then the key is considered the Help index for the file. If the first character is neither "?" nor "#", your key
must be an exact match for an entry in the help index.
Example:
1000 INPUT "Enter customer ID:",C$
1010 IF CTL=1 THEN SYSTEM_HELP "OENTRY.HLP","Client"; GOTO 1000
The SYSTEM_HELP directive lets you use files other than those with a .HLP extension (Ver. 4.03).
ProvideX passes these files directly to the WINDOWS Shell command for processing. This allows
WINDOWS to apply normal file associations to automatically launch the appropriate application. Preface
your second argument for SYSTEM_HELP with a # and append it to the first argument for URL handling.
For example:
For SYSTEM_HELP "http://www.pvx.com/support.htm","mymark" you would have:
http://www.pvx.com/support.htm#mymark
Passing this to SYSTEM_HELP will automatically launch the default browser (if any) and jump to the web
page requested.

SYSTEM_JRNL File System Journalization
Directive SYSTEM_JRNL
Format:
( To Create a System Journal SERIAL journal$ )

1 OPEN System Journal SYSTEM_JRNL OPEN journal$
2 ENABLE Journalization SYSTEM_JRNL ENABLE filename$
3 DISABLE Journalization SYSTEM_JRNL DISABLE filename$
Where =
journal$ Name of the SERIAL file being used as the journal. String expression. (First,
create the journal as an empty SERIAL file, then OPEN it.)
NOTE: There should be only one common journal for the whole
system (i.e. the create and OPEN commands should only be
executed once).
filename$
Description:
Use the SYSTEM_JRNL directives to have ProvideX log all updates to specified data files. The journal file
will log all updates to a data file, including both before and after images.
Format 1 OPENs System Journal: SYSTEM_JRNL OPEN journal$

Use this format to OPEN your journal (a SERIAL file). For example:
SERIAL "MYJRNL"
SYSTEM_JRNL OPEN "MYJRNL"
See also: SERIAL Create a Sequential File, p. 375(d)
Journal Contents
The physical journal file is a binary file that has a special format designed for quick write access and fairly
efficient retrieval. Each of the journal files records has a 16-byte header consisting of:
Byte(s) Contents
1 Type of record (O-Open, A-After, B-Before, etc...)
2-4 Record size in bytes
5-8 Time of day that the record was written in seconds past Jan 1/1980
9-12 Address of prior record for session
13-16 Address of related record. For example:
After/Before image points to file Open record
Open file record points to User login record
The rest of the record is the before/after image of the data. The file itself has a four-byte header with the
address of the last record on the file.

Format 2 ENABLEs Journalization: SYSTEM_JRNL ENABLE filename$
Use this format to ENABLE journalization of a data file.
NOTE: If you have ENABLEd journalization for a data file, you cant access that file unless
your journal file is OPEN.
With ProvideX journalization you specify which files are to be journalized as a file attribute.
Format 3 DISABLEs Journalization: SYSTEM_JRNL DISABLE filename$

Use this format to DISABLE journalization of a data file.

TABLE Define Translation Table
Directive TABLE
Format:
Define Translation Table TABLE hex-table
Where =
hex-table Hex conversion table which consists of multiple hex digit pairs.
Description:
Use the TABLE directive to define the conversion table ProvideX is to use for subsequent TBL=stmtref
options in I/O operations or with the TBL( ) function. Use the first pair of hex digits to define the conversion
mask, the remaining hex pairs to define the converted data bytes.
See also: TBL( ) Convert String Via Table, p. 422(f)

Translation Tables
Example:
0020 TABLE 0F30313233343536373839414243444546

TAN( ) Tangent Function
Function TAN( )
Format:
Return Tangent TAN(num[,ERR=stmtref])
Where =
num Numeric expression whose Tangent will be returned.
Returns: Numeric, rounded, Tangent of given number
Description:
The TAN( ) function returns the Tangent of your given numeric expression. The numeric value returned will
be rounded to the current PRECISION in effect. Its inverse function is ATN( ) Arc-Tangent Function, p.
21(f).
Example:
FLOATING POINT
-:PRINT TAN(1)
.15574077246549E+01
-:PRINT TAN(-3.14159/2)
-.75369599539306E+06

TBL( ) Convert String Via Table
Function TBL( )
Translation Table Format:
1 TBL in Program TBL(string$,TBL=tbl_stmtref[,ERR=stmtref])

2 TBL in Variable TBL(string$,tbl_var$[,ERR=stmtref])
3 Translate Using Numerics TBL(position,expr_0[$],expr_1[$] ... ,expr_n[$][,ERR=stmtref])
4 Convert Char$ to Char$ TBL(var$,compare$,table$)
Where =
string$ String of characters to be translated or replaced. String expression must be all
characters or all numeric.
tbl_stmtref (Optional if your TABLE is embedded in the same statement as the TBL( )function.) If
you refer to a program tbl_stmtref, it must contain a conversion TABLE.
tbl_var$ String variable. Contains conversion table to replace elements in the string$. String
expression.
position Determines which expression to use. Positional or numeric expression, range 0
(zero) to n.
expr_0[$]n List of expressions to be returned. Numeric or string expressions. Restriction: The
expressions must all be the same type (i.e., all characters or all numerics).
var$ String variable. Contains a string to be translated or replaced.
compare$ String table to compare character by character with the value in var$. String
expression.
table$ Table to use for conversion when a character in the compared value matches the
value in var$. String expression.
Returns: Converts string to values in table
Description:
The TBL( ) function converts a string (all characters or all numeric) to the corresponding values set in a
given translation table.
See also: ProvideX Translation Tables
Format 1 for Translation Table in Program: TBL(string$,TBL=tbl_stmtref[,ERR=stmtref])

Use this TBL( ) format if your translation table to convert the string$ is an embedded table in your program.
If you include a tbl_stmtref, it must refer to a program statement containing a conversion table defined by a
TABLE directive. This statement reference is optional if your conversion table is embedded in the same
statement as the TBL( )function
See also: TABLE Define Translation Table, p. 420(d)
Format 2 for Translation Table in Variable: TBL(string$,tbl_var$[,ERR=stmtref2])

Use this TBL( ) format if your translation table to convert the string$ is in a variable.

Format 3 Translates Using Position: TBL(position,expr_0[$],expr_1[$] expr_n[$][,ERR=stmtref])
Use this format of the TBL( ) function to obtain a value based on the numeric value of an expression (Ver.
4.). The value the TBL( ) function returns depends on the value of position. If its 0 (zero), then the value
of expr_0 will be returned, if 1, then expr_1 will be returned and so on
NOTE: The values for expr_0[$], expr_1[$], n[$] can be either string or numeric. The only
requirement is the they must be ALL the same: either all string or all numeric.
Format 4 for Character to Character Conversion: TBL(var$,compare$,table$)

Use this format to do a character-to-character conversion of a string (Ver. 4.). ProvideX replaces each
character in the string variable that matches a character in the first comparison string expression with the
corresponding character from the table. That is, when a character in the string variable matches a
character in compare$, then:
compare$ character 1 is replaced by table$ character 1 in var$,

and so on.
Examples:
T$="W"
P$=TBL(POS(T$="DWM"),"???","Daily","Weekly","Monthly")
?P$
Weekly
PRINT "Expires:",TBL(EXP_DT$="",EXP_DT$,"Never")
In this example, if EXP_DT$ is NULL, the logical expression EXP_DT$= will yield 1. A NULL date will
print Never. Otherwise, it will yield 0 (zero) and the value of EXP_DT$ will be printed. In effect, this
form of the TBL( ) function becomes: TBL(logical_expr, else_value,true_value).
let string$="ABCDEFG 123"
newstring$=tbl(string$,"ACF ","123_") ! newstring$ is "1B2DE3G_123"
newstring$=tbl("ABCDEFG 123","ACF ","123_")

TCB( ) Return Task Information
Function TCB( )
Format:
1 Return Task Info. TCB(tcb_code[,ERR=stmtref])

2 Activation Info. (Ver. 4.20) TCB(pkg_index,info_reqd[,ERR=stmtref])
Where =
tcb_code Value indicating what type of information is to be returned. Numeric expression.
pkg_index (Ver. 4.20) A number from 0 to the number of packages installed. Package 0 will
always be the ProvideX activation.
info_reqd (Ver. 4.20) Any of the following values:
0 - Actual Package Number (0 is the base ProvideX package #)
1 - The expiry date (format YYYYMMDD) as a numeric value. Value=0
means no expiry date.
2 - Package Activation Flags (32-bit flags as a numeric)
Returns: Various system control values
Description:
The TCB( ) function returns various system control values. The value returned depends on the value of
the function number you specify. See the table, below. (Note that TCB(numbers) not included in the
sequence are reserved for future use.)
TCB( ) Returns the following value:

0 (Ver. 4.20) Actual ProvideX package number (0 is the base ProvideX package #)
1 (Ver. 4.20) The ProvideX package expiry date as a numeric value (format YYYYMMDD).
Value=0 means no expiry date.
2 (Ver. 4.20) ProvideX package Activation Flags (32-bit flags, numeric)
3 Internal system error code (ERRNO)
4 Current statement number. (Only reported when running a program, not in command mode.)
5 The line number of the last error
6 SETESC statement number
7 SETERR statement number
8 Top statement number in GOSUB stack
9 Zero (0) - Reserved for future use.
10 Internal system error code (ERRNO)
11 Retry statement number
12 Current level number
13 Also current level number (ProvideX includes current level in both TCB(12) and TCB(13) for
compatibility with other Business Basics.)
14 Current precision (-1=FLOATINGPOINT)
15 Current maximum memory size in bytes

16 Length of string found in last MSK function
17 Current level of user functions
18 Current iteration of Range assignment
20 Number of arguments in 'CALL'
21 Current activation flags
22 # days left for current activation
23 Maximum user count
24 # of Users Available
25 Operating System Version #
27 (Ver. 4.20) Reports current sessions user slot number and type of slot. See also 1U Force
Session to Dedicated User Slot, p. 538(p)
>0 = Dedicated non-shared user slot number being used
<0 = Shared user slot number being used
0 = Task is not being counted in the user slot table (background task)
30 Statement # of last error in called program
31 Last object to lose focus
40 SETTRACE file number (if active)
41 # of duplicate labels on last save
42 # of unknown state labels on last save
43 The offset to the last detected error in the last statement compiled. Reports the number of
characters before the error occurred (Ver. 4.01).
44 The number of seconds of offset to GMT (Greenwich Mean Time)
45 Daylight Savings indicator:
0 - Not currently in Daylight Savings
1 - Daylight Savings active
50 # file reads
51 # file writes
52 # Keyed IO forced buffer flushes
53 # programs loaded from disk
54 # programs loaded from program cache
55 Program Swapouts
56 Program Swapins
57 Program reloads from disk
60 Keyed file header busy retries (DOS/WINDOWS)
61 Busy record count
62 # of unsuccessful file opens

NOTE: For TCB(63) to TCB(66), below, the values in the system parameters VR and VW define
the number of read/write retries before a data read/write error will be generated (Ver. 4.01).
See also: VR=num Verify READ, p. 561(p)
VW=num Verify WRITE, p. 561(p)

63 Number of READs verified.
64 Number of WRITEs verified
65 Number of READ mis-compares
66 Number of WRITE mis-compares
80 Last VBX status or error code. See CUSTOM_VBX Create/Control VBX, p. 56(d) for a list of
codes and explanations.
81 Last Window LPARAM value
82 Will return the Windows O/S version: (32-bit PVX only)
0 if running under Windows 3.1
1 if running under Windows 95
2 if running under Windows NT
-1 if running 16-bit PVX
83 Status of the debug window
84 Last WinExec status after an INVOKE or a SYS( )
87 For UNIX only. Returns PID of lock conflict (Ver. 4.03). When a file I/O attempt is made and
fails due to a lock, TCB(87) returns the PID of the process owning the lock. You can use this
process ID along with the output of a ps command to identify who has a record locked.
88 Returns the WindX version number or 0 (zero) if not running under a WindX session (Ver.
4.10).
89 Returns numeric value of current Process ID (PID) (Ver. 4.12).
This allows for PID values which are larger than the 16-bit values returned by GID, and will
remain constant for 32-bit, upcoming 64-bit (and beyond) operating systems. Replaces the
use of DEC($00$+GID) to retrieve the current PID value.
91 Returns the current Task/Thread Priority level (Ver. 4.02).
Three System Parameters control the priority of a task, primarily to balance the load in a
Client/Server environment:
Q_=num Lowest Task Priority, p. 555(p)

Q^=num Highest Task Priority, p. 555(p)
QF=num Task Priority Factor, p. 555(p)
99 Program security flags
100 High memory in use (MS-DOS only)

TIM Time in Hours Past Midnight
Numeric System Variable TIM
Returns: System time, PRECISION 6 decimal numeric
Description:
This numeric system variable returns the current system time in hours past midnight. The value is returned
as a PRECISION 6 decimal numeric.
Example:
0100 PRINT TIM
0110 SETTIME 1.10
0120 PRINT "Current time",TIM
RUN
19.341613
Current time 1.100502

TME Time In Hours Past Midnight
Numeric System Variable TME
Returns: System time, PRECISION 6 decimal numeric
Description:
This numeric system variable returns the current system time in hours past midnight, with a PRECISION of
6.
Example:
->?TME
18.868844

TMR( ) Timer
Function TMR( )
Format:
Reset or Return Value TMR(tmr_code[,ERR=stmtref])
Where =
tmr_code Your value indicates what type of information you want returned. Numeric
expression, integer range 0 to 2. See the chart in the TMR Description, below.
Returns: Number of seconds or hours or, if reset, 0 (zero). See the chart below.
Description:
The values returned by the TMR( ) function are:
TMR( ) Value: Returns

0 Resets the timer to 0.
1 Returns the difference in seconds between NOW and the last occurance of TMR(0).
2 Returns the difference in hours between NOW and the last occurance of TMR(0).

TMS Seconds Expired in Current Minute
Numeric System Variable TMS
Returns: Integer, range 0 (zero) to 60, system time in seconds passed in current minute
Description:
This numeric system variable returns an integer reporting the current number of seconds that have passed
in the current minute according to the Operating Systems clock. The value is an integer, maximum 60.
Example:
->?TMS
15

TRANSLATE Translate Contents of Variable
Directive TRANSLATE
Format:
1 Translate from String TRANSLATE var$,table$,offset

2 From Variable to Variable TRANSLATE to_var$,from_var$,offset
3 Translate 1 Character TRANSLATE var$,to_char$,from_char$
Where =
var$ String variable to be translated.
table$ or Conversion table to be used as the new value(s) in the translation. String expression.
from_var$
to_var$ Variable in which the translation is performed. Starting at the offset, to_var$ receives
the translation of its own old values to the corresponding new values (from the table
or from_var$ string).
from_char$ Character to be searched_for and replaced.
to_char$ New character to replace the original from_char$. (All instances of the from_char$ in
the var$ string are replaced with the to_char$.)
offset Base value to subtract from the characters in the variable to calculate the offset into
the table during conversion. Numeric expression.
Description:
Use the TRANSLATE directive to convert / translate a string variable on a character-by-character basis
using a conversion table or value. You can use this directive to convert data from one character set to
another (e.g. ASCII to EBCDIC).
Format 1 Translates From String: TRANSLATE var$,table$,offset_base

Use this format to replace a character in a string variable with a character from a table string / expression.
ProvideX performs the conversion process by taking each character from the variable, subtracting the
offset from its binary value and using the result as an offset into the table whose character will then replace
the original character in the variable. When ProvideX computes the offset into the table, it will treat an
offset of zero as the first character from the table. If the result of the subtraction is an offset that exceeds
the length of the table then no conversion takes place for the character.
Example:
0110 LET A$="ABCD"
0130 TRANSLATE A$,"ZYXWVUTS",DEC("A")
0140 PRINT A$
->GOTO 110
->RUN
ZYXW
Format 2 Translates From Variable: TRANSLATE to_var$,from_var$,offset_base

Use this format to copy the character-by-character values from one variable to another variable up to the
length of the shorter variable. In this format, Providex also uses a numeric starting offset into the target
table.

Example:
0110 LET A$="1234567890"
0120 LET B$="ABCD"
0130 TRANSLATE A$,B$,DEC("3")
0140 PRINT A$
->GOTO 110
->RUN
12ABCD7890
Format 3 Translates Single Character: TRANSLATE var$,to_char$,from_char$

Use this format to replace all instances of a given character in a string variable with another character.
Example:
0110 LET STRVAR$="ABxDEFG xxx"
0120 TRANSLATE STRVAR$,"C","x"
0130 PRINT STRVAR$
-:run
ABCDEFG CCC

TRISTATE_BOX Define/Control TRISTATE_BOX
Directive TRISTATE_BOX
Format:
1 Define/Create TRISTATE_BOX [*]ctl_id, @(col,line,width,height)=contents$[,fileopt]

2 Delete TRISTATE_BOX REMOVE [*]ctl_id [,ERR=stmtref ]
3 Disable/Enable TRISTATE_BOX {DISABLE | ENABLE} [*]ctl_id [,ERR=stmtref ]
4 Set Focus To TRISTATE_BOX GOTO [*]ctl_id [,ERR=stmtref ]
5 Logical Push/Release TRISTATE_BOX {ON | OFF} [*]ctl_id [,ERR=stmtref ]
6 Read Activation State TRISTATE_BOX READ [*]ctl_id,state$[,ERR=stmtref ]
7 Update TRISTATE_BOX WRITE [*]ctl_id,state$[,ERR=stmtref ]
Where =
* (asterisk) Optional. Use a leading asterisk to denote a global TRISTATE_BOX.
ctl_id Unique logical identifier for the TRISTATE_BOX control object. Numeric expression.
Integers, range: -32000 to +32000. Avoid integers that conflict with keyboard
definitions (e.g. function key CTLs like 4).
@(col,line, Position and size of the TRISTATE_BOX region. Numeric expressions. Column and
line coordinates for top left corner, width in number of columns, height in number of
width,height)
lines. Note that width and height are for the total area (box plus text/description).
Use line coordinate -1 to display the TRISTATE_BOX on the toolbar.
contents$ Text/pictures for your TRISTATE_BOX. As of Ver. 4.20, ProvideX supports both
{bitmaps} and {icons}. See TRISTATE_BOX Contents$, p. 434.
fileopt File options. Valid options for TRISTATE_BOX include:
OPT=char$ Single character parameters. See TRISTATE_BOX
OPT=char$, p. 434.
TBL=char$ Single character translation
state$ Current state of the TRISTATE_BOX (ON, OFF or other - e.g., as is).
Description:
Use the TRISTATE_BOX directive to create and control TRISTATE_BOX control objects. A
TRISTATE_BOX is a check box in which your user can toggle between three states: ON to select an
option, OFF to disable it, or your choice of a third state. See the Tristate_Box Example, p. 435 for an
illustration.
BUTTON Define/Control BUTTON, p. 28(d)


TRISTATE_BOX Description:
OPT=char$
A Auto: Generates a CTL signal for every character the user enters.
B Bitmap Button: A bitmap button is a bitmap whose width is divided into four images.
As of Ver. 4.20, you can use this attribute to custom design TRISTATE_BOXes of
any colour, style or shape by controlling the bitmap image that appears. Each of
the four divisions represents what your TRISTATE_BOX bitmap image will look like
in a particular state:
1st qtr. Image when TRISTATE_BOX is disabled.
2nd qtr. Image in the normal (released) state.
3rd qtr. Image when mouse is positioned over TRISTATE_BOX.
4th qtr. Image when the TRISTATE_BOX is pressed.

broken into quarters (yielding, for instance, 12 bitmap images
for a TRISTATE_BOX).
D Disabled: User cannot access the TRISTATE_BOX
F Flat Button: TRISTATE_BOX shows no raised outline unless the mouse is over the
TRISTATE_BOX or the TRISTATE_BOX is pushed (Ver. 4.20).

Example: BUTTON 10,@(10,10,10,2)="&OK",OPT="F"
H Hide: Do not display the TRISTATE_BOX.
S Signal: Generates CTL value but does not alter focus.
T Strip trailing spaces
Format 1 Creates: TRISTATE_BOX [*] ctl_id, @(col,line,width,height)=contents$[,fileopt]

Use your value in ctl_id to give your TRISTATE_BOX a unique identifier. This value generates a CTL
whenever the TRISTATE_BOX is toggled. If your ctl_id has a leading asterisk, the TRISTATE_BOX is
considered global (not tied to a specific window).
TRISTATE_BOX Contents$
Your contents$ string expression defines the text/picture to appear on the TRISTATE_BOX. In the text,
you can use an & (ampersand) preceding a character to identify it as a hot key the user can press in
conjunction with the <Alt> key to activate the TRISTATE_BOX from the keyboard.
Bitmaps and Icons:

To add a bitmap to a TRISTATE_BOX, you can include the absolute path to the .bmp file in the contents$
or use the name of one of Best Software Canada Ltd.s embedded bitmaps. As of Ver. 4.20, ProvideX
supports {icon} images for use on TRISTATE_BOXes. Your icon filename must have .ico as an
extension.

DLLs /executables.
Examples:
"{!Add}Add" ! Displays the {!Add} bitmap in front of the text "Add"
"Delete{!Del}" ! Displays the {!Del} bitmap after the text "Delete"
If your string expression includes three bitmaps separated by a vertical bar inside a single set of curly
brackets, the first will be displayed when the TRISTATE_BOX is in its normal state (OFF), the second while
the TRISTATE_BOX is ON and the third when the TRISTATE_BOX is in your third state.
Tristate_Box Example
0120 TRISTATE_BOX 102,@(2,19,12,3)="{!File_Save}&Save"
0130 TRISTATE_BOX 103,@(22,15,12,2)="&Destroy{!Trash|!Trash_open|!Bomb_blast}"

0140 TRISTATE_BOX 104,@(22,19,12,3)="{!Lite_Green|!Lite_Yellow|!Lite_Red}"
0150 INPUT (0,HLP="Tristate_Box")@(40,18),"Select...: ",'CL',X$
0160 IF CTL>100 AND CTL<105 THEN TRISTATE_BOX READ CTL,B$; PRINT @(40,19),"Sele
0160:ction:",CTL,":",B$,'CL',; GOTO 0150
Format 2 Deletes: TRISTATE_BOX REMOVE [*] ctl_id [,ERR=stmtref]

Use the TRISTATE_BOX REMOVE format to delete a TRISTATE_BOX. By default, if TRISTATE_BOXes
are not global, they are deleted when a window is removed/dropped or the application issues a BEGIN.
Global TRISTATE_BOXes can be removed manually or cleared by a START.
Format 3: TRISTATE_BOX {DISABLE | ENABLE} [*] ctl_id [,ERR=stmtref]

Use the TRISTATE_BOX DISABLE format to disable or gray-out a TRISTATE_BOX. (Your user can see
the selection, but not access it and your program will not have access to it.) Use the TRISTATE_BOX
ENABLE format to restore access to a disabled TRISTATE_BOX.
Format 4 Sets Focus: TRISTATE_BOX GOTO [*] ctl_id [,ERR=stmtref]

Use the TRISTATE_BOX GOTO format to set the Focus on your TRISTATE_BOX so that it is ready to
receive the next user input.
Format 5 for Logical 'Push'/Release: TRISTATE_BOX {ON | OFF} [*] ctl_id [,ERR=stmtref]
Use the TRISTATE_BOX ON format to make it appear that a TRISTATE_BOX selection has been made.
Use the OFF format to make it appear that it has been released.
Format 6 READs Activation Mode: TRISTATE_BOX READ [*] ctl_id,state$[,ERR=stmtref]

The TRISTATE_BOX READ format returns the current state of the TRISTATE_BOX ("0" for OFF, "1" for
ON, or "2" for other).

Format 7 Updates: TRISTATE_BOX WRITE [*] ctl_id,state$[,ERR=stmtref]
Use the TRISTATE_BOX format above to WRITE or update new values for the TRISTATE_BOX.

TRX( ) Convert ASCII to RADIX-40
Function TRX( )
Format:
Convert Radix-40 to ASCII TRX(rdx_40$[,ERR=stmtref])
Where =
rdx_40$ Character string containing RADIX-40 data.
Returns: ASCII equivalent of given RADIX-40 data
Description:
The TRX( ) function converts data from RADIX-40 to normal ASCII.
RDX( ) performs the inverse function, converting ASCII to RADIX-40. RADIX-40 lets you compress three
characters (any of 0-9, A-Z, ., -, $, or space) into two bytes of data (16 bits).
See also: RDX( ) Convert to RADIX-40 from ASCII, p. 342(f)
Example:
0010 LET A$=LST(PGM(65000)); PRINT "string: ",QUO,A$,QUO
0020 LET B$=HTA(RDX(A$)); PRINT B$
0030 PRINT HTA(TRX(B$))
-:run
string: "65000 END "
2CB106686E600000
37304F394B4D36504A374F20374F41374E54365044365044

TSK( ) Returns Entry from Task List
Function TSK( )
Format:
Return Task Table Value TSK(num[,ERR=stmtref])
Where =
num Desired index / entry in the internal TSK( ) table. Numeric expression, range 0 to n.
Returns: String, value of task internal TSK( ) table
Description:
The TSK( ) function returns a string value from the internal TSK( ) table. The specific table entry returned
is determined by the value of your argument or task number. An error is generated if the entry has not
been set up in the TSK( ) table (using a SETDEV TSK( ) directive).
See also: SETDEV TSK( ) Add to the TSK( ) List, p. 383(d)
Example:
0010 SETDEV TSK() "this is table entry 0"
0020 SETDEV TSK() "this is table entry 1"
0030 PRINT TSK(1)
->run
this is table entry 1
NOTE: An argument of -1 always returns "[Pvx" which is the internal header for files.

TSM Error Status of Current Program
String System Variable TSM
Returns: String, error status of current program
Description:

This string system variable returns a string reporting the error status of the currently running program.
(This is included in ProvideX primarily for compatibility with other Business Basics.) Its contents are:
Contents
(1,1) "0"
(2,16) Name of program with last error.
Padded with nulls.
(18,5) Line with error
(23,5) Error status
(28,5) Operating system error code

TXH( ) Text Height
Function TXH( )
Format:
Return Text Height TXH(text$[,chan][,SIZ=num][,FNT="font,sz{,attr}"][,ERR=stmtref])
Where =
text$ Your string expression.
file options Valid file options:
SIZ=num
ERR =stmtref
chan Channel or logical file number of the terminal from which to read.
Returns: Text height in graphical units (i.e. @X(col) and @Y(line) values)
Description:
NOTE: For use in graphics mode.

The TXH( ) function returns text height in graphical units (similar to pixels). If you set a size, TXH( ) will
return the height required to print your given text with no line exceeding the size. If you omit SIZ= or let
SIZ=0 (zero), then ProvideX assumes you want single line height. If you omit the channel, then ProvideX
assumes it's dealing with the main window.
Example:
In this example, the text is forced to fit the dialogue box width with font height also forced. Note the
truncation of lines: a potential recipe for disaster unless you set wordwrap ON in a FONT statement.
0010 LET L=0
0020 PRINT 'CS'
0030 OPEN (1)"RECIPE"
0035 PRINT 'DIALOGUE'(2,3,40,20,"Test TXH",OPT="Z")
0036 REM Wordwrap should be set on: e.g. PRINT FONT("ARIAL",1,"W")
0050 LET W=TXW(R$) ! Get width of text
0060 IF W>@X(40) THEN LET W=@X(40) ! Force <= same size as standard text 40
column width
0070 LET H=TXH(R$,SIZ=W) ! Make it fit
0080 LET L=L+1
0090 PRINT 'TEXT'(@X(0),@Y(L),@X(0)+W,@Y(L)+H,R$)
0100 GOTO 0040
0110 CLOSE (1)
0215 INPUT *
-:run
Cranberry Crumble Pie (untested)
Topping
1 1/2 c. flour 3 Tbsp. milk
1 Tbsp. sugar 1/4 tsp. salt
1/4 c. oil/melted butter
Mix in processor. Put 1/2 in bottom of pie plate/
Filling
4 c. rhubarb 3 c. cranberries

3 eggs 1 3/4 c. sugar
1/4 c. flour
Pour rhubarb/cranberries over crust. Mix remain
over fruit. Top with rest of crust.
Bake 10 minutes at 400 and 45 minutes at 300 o
brown.

TXW( ) Text Width
Function TXW( )
Format:
Return Text Width TXW(text$[,chan][,FNT="font,sz{,attr}"][,ERR=stmtref])
Where =
file no Channel or logical file number of the terminal to read from.
file options Valid file options:
ERR =stmtref
Returns: Text width in graphical units (i.e. @X(col) and @Y(line) values)
Description:
The TXW( ) function returns text width in graphical units for the given string. If you omit the channel, then
ProvideX assumes it is dealing with the main window. TXW( ) does not include the & ampersand character
during width calculations.
See also: TXH( ) Text Height, p. 440(f)
Example:
If you want to create a window based on the length of a message, you can use the TXW function to
determine the size of the window / dialogue to create. For example:
0100 LET W1=TXW(Line1$,FNT="MS Sans Serif")
0130 LET W=MAX(W1,W2,W3)
0140 LET W=INT(W/16)+4 ! Allow for up to 4 extra white spaces
0150 PRINT 'DIALOGUE'(c,l,W,5,TITLE$),'SR','CS',
0160 PRINT 'FONT' ("MS Sans Serif" ),
0170 PRINT 'TEXT'(@X(2),@Y(1),Line1$),
Notes:
1) The logical width is always 16 times the column number.
2) In the 'TEXT' mnemonic, if you omit End points, then the system calculates them.

UCS( ) Return Upper Case String
Function UCS( )
Format:
Return Uppercase String UCS(string$[,ERR=stmtref])
Where =
string$ String whose upper case ASCII counterpart is to be returned. String expression.
Returns: UPPERCASE string equivalent of lower case string
Description:
The UCS( ) function replaces all lower case ASCII characters in a given string with their corresponding
upper case values.
See also: LCS( ) Return Lower Case String, p. 217(f)
Example:
0010 INPUT "Enter name: ",NAME$
0020 LET NAME$(2)=LCS(NAME$(2))
0030 LET NAME$(1,1)=UCS(NAME$(1,1))
0040 PRINT "Name is: ",NAME$
-:run
Enter name: rOBERT
Name is: Robert
NOTE: If an asterisk '*' is passed to the UCS( ) function instead of a string, the function will
return the 256 byte Uppercase Conversion Table. The printable characters start at
position 33, so PRINT A$(33) will display the results. See the example below.
Example:
-:A$=UCS(*)
Note that if you try to print the entire UCS table (i.e., in this case, PRINT A$), ProvideX returns an Error
#29: Invalid Mnemonic or position specification, since the first part of the table contains
unprintable keystrokes (e.g. <Esc> key character $1B$, etc.)
-:PRINT HTA(A$)
000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627
505152535455565758595A5B5C5D5E5F604142434445464748494A4B4C4D4E4F5051525354555657
A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7
C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
-:PRINT POS($20$=A$) ! $20$=the blank (start of print characters in UCS string)

33
-:PRINT A$(33)
!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_ÀBCDEFGHIJKLMNOPQ
RSTUVWXYZ{|}~-
??

UID USER ENV Variable or Network ID
String System Variable UID
Returns: String, current UserID
Description:
This string system variable returns the current UserID. On systems without user registration, it returns the
value of the environment variable USER or the Network UserID.
See also: WHO Current UserID, p. 471(v)
Example:
->PRINT UID
SMITHJ

UNLOCK Remove Exclusive Use from File
Directive UNLOCK
Format:
Remove Exclusive Use UNLOCK (chan[,ERR=stmtref])
Where =
chan Channel or logical file number of the file to be unlocked.
Description:
Use the UNLOCK directive to release a previously LOCKed file. If your given file is not already locked,
ProvideX returns an Error #14: Invalid I/O request for file state.
NOTE: As of Ver. 4.20, WindX supports the use of this directive via the [WDX] tag. (If you are
running an earlier version of ProvideX on a WindX PC, you still need to encapsulate
your command in an EXECUTE "[WDX]..." directive.) See [WDX] Tag: Directs Action
to Client Machine, p. 626.
See also: LOCK Reserve File for Exclusive Use, p. 247(d)
Example:
0010 OPEN (30,ERR=0100)"GLFILE"
0020 LOCK (30,ERR=0120)
0030 READ (30,KEY="HEProvideXR")A
0040 IF A>0 THEN GOTO 0100
0050 UNLOCK (30)
0060 PRINT "Nothing on file to process.."
0070 STOP
0100 REM 100 Error handling

UNT Lowest LOCAL Channel Not Open
Numeric System Variable UNT
Returns: Integer, lowest channel number NOT OPEN
Description:
This numeric system variable returns an integer reporting the lowest channel number currently NOT
OPEN. The value is an integer.
Example:
0010 LET CHAN_NUM=UNT
0020 OPEN (CHAN_NUM)"FILENAME"
->?CHAN_NUM
1
NOTE: Some older Business Basics OPENed the printer on Channel (1). If you are dealing
with such applications in legacy code, try using the HFN Highest Available LOCAL
File Number, p. 177(v) instead of UNT.

UNTIL End of REPEAT Loop
Directive UNTIL
Format:
Defines End of Loop UNTIL num
Where =
num Condition ends REPEAT looping when true. Numeric expression.
Description:
Use the UNTIL directive to define the end of a REPEAT loop in a program.
After your REPEAT directive is processed, ProvideX executes your code up to a statement with an UNTIL
directive. If the expression in the UNTIL directive is FALSE (zero), ProvideX loops back to the directive
following the REPEAT directive and resumes execution. On the other hand. if it's TRUE (not zero),
Providex terminates the loop and continues execution with the statement after the UNTIL directive.
Use a conditional EXITTO directive to exit a REPEAT / UNTIL loop before its completion.
See also: REPEAT Repetitive Execution, p. 358(d)
Example:
0010 PRINT 'CS',"Standard TAX calculation..."
0100 INPUT "How much was your INCOME? $",CASH
0110 REPEAT
0120 INPUT "How much TAX did you pay? $",TAXES
0130 LET CASH=CASH-TAXES
0140 PRINT "You have $",CASH," left"
0150 UNTIL CASH<=0
0160 PRINT "Okay you have paid enough."
-:BEGIN
-:RUN
Standard TAX calculation...
How much was your INCOME? $1.98
How much TAX did you pay? $1.65
You have $ 0.33 left
How much TAX did you pay? $.33
You have $ 0 left
Okay you have paid enough.

UPK( ) Unpack Numeric Data
Function: Compatible with Other Business Basics UPK( )
Description:

Use the UPK( ) function to unpack numeric data for conversion from older Business Basics where the
PCK( ) function was used to pack numeric data. ProvideX supports this function only for conversion from
other Business Basics. See other Business Basic manuals for information on the use of this function.

USER_LEX Define Directive Keywords
Directive USR_LEX
Format:
Define Keyword Alternate USER_LEX alt_string$=directive$
Where =
alt_string$ Alternate/translated form to be used in place of a ProvideX directive.
directive$ Standard ProvideX directive.
Description:
Use the USER_LEX directive to extend the internal ProvideX compiler definitions to include new symbols
and directives. You can use this directive to simplify a conversion from other languages to ProvideX.
After ProvideX executes the USER_LEX directive, any statements sent to the ProvideX compiler where
your alternate string expression is found will be translated into the internal object code for the standard
string in directive$. It is mandatory that you use valid ProvideX object syntax in the directive$. Use spaces
in the string expression to indicate that spaces can exist in the string when compiling.
Example:
To allow the use of SPC( ) in lieu of PAD( ):
USER_LEX "SPC ("= "PAD ("
NOTE: The internal syntax values in the directive$ must include the proper spacing and all
related control characters. In the above example "SPC"="PAD" alone is not
acceptable. You must include the space and open parenthesis after SPC and after
PAD to indicate that a space can occur between the word (SPC / PAD) and the open
parenthesis.

USER_LEX LOAD Load Directive Keywords
Directive USER_LEX LOAD
Format:
Load Lexicon/Table USER_LEX LOAD filename$
Where =
filename$ Name of a file containing a User Lexicon. String expression.
Description:
Use the USER_LEX LOAD directive to load an alternate internal lexicon / table. Your lexicon can be used
to simplify a conversion from other programming languages to ProvideX or to provide for support of
languages other than English. The LEX table consists of all the ProvideX keywords for directives,
functions and variables. ProvideX supplies a utility program, "*LEXEDIT", to create and maintain these
tables.
Warning: Be very careful when modifying syntax tables. While it is possible to create syntax
tables for other languages and to add additional syntax to the external table, the
wrong changes can make your programs unLISTable. (The syntax tables affect both
the LISTing and EDITing of programs.) Do not attempt to create or edit the syntax
tables unless you are an experienced programmer and are familiar with these tables.
Contact your local distributor of ProvideX for assistance.

V_SCROLLBAR Define/Control Vertical Scroll Bar
Directive V_SCROLLBAR
Format:
1 Define/Create V_SCROLLBAR ctl_id,@(col,line,width,height)[,fileopt]

2 Placement V_SCROLLBAR ctl_id WINDOW [,fileopt]
3 Delete V_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]
4 Disable/Enable V_SCROLLBAR {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
5 Set Focus To V_SCROLLBAR GOTO ctl_id[,ERR=stmtref]
6 Read Setting: V_SCROLLBAR READ ctl_id,setting,max,[rgn_chg][,arrow_chg][,ERR=stmtref]
7 Update V_SCROLLBAR WRITE ctl_id,marker,max[,ERR=stmtref]
8 Hide/Show V_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the V_SCROLLBAR. Numeric expression. Integers,
@(col,line, Position and size of the V_SCROLLBAR region. Numeric expressions. Column and
lines.
fileopt File options. Valid options for V_SCROLLBAR include:
OPT=char$ Single character parameters
Valid options for OPT=char$:
D - Disabled: User cannot access the scrollbar
H - Hide: Do not display the scrollbar
A - Auto: Generates CTL value for each movement
s - Scroll: Allows control to scroll in a resizable/scrollable dialogue box
setting Numeric variable to receive the current V_SCROLLBAR setting.
marker Relative position to set as the V_SCROLLBAR marker. Numeric expression between
1 and the maximum.
max Logical maximum value of the V_SCROLLBAR. Numeric expression.
rgn_chg Amount to increase/decrease the V_SCROLLBAR setting when the user selects the
region above/below the marker. Numeric expression. (Default: max/width)
arrow_chg Amount to increase/decrease the V_SCROLLBAR setting when the user selects the
arrow at the top/bottom edge of the V_SCROLLBAR. Numeric expression. (Default:
1)
Description:
Use the V_SCROLLBAR directive to create a vertical / V_SCROLLBAR control object on the screen. Your
program logic can read and adjust a value by increments to control logical record position within a file
every time the user moves the V_SCROLLBAR.
See also: H_SCROLLBAR Define/Control Horizontal Scroll Bar, p. 174(d)

Formats 1 and 2: Define/Create

Use either V_SCROLLBAR Format 1 or 2 (below) to define or create your Vertical Scrollbar.
Your value in ctl_id gives the V_SCROLLBAR a unique identifier. This value is generated as a CTL
whenever the V_SCROLLBAR is selected and changed.
Format 1 Creates in Current Window: V_SCROLLBAR ctl_id,@(col,line,width,height)[,fileopt]

Use V_SCROLLBAR Format 1 to create a V_SCROLLBAR inside the current window.
Example:
0010 V_SCROLLBAR 100,@(70,2,2,20)
This defines a V_SCROLLBAR 2 columns wide, 20 lines high, starting at column 70 on line 2. Whenever
the V_SCROLLBAR is selected a CTL 100 will be generated.
V_SCROLLBAR Example
0100 ! 100 - Vertical Scroll Bar Example
0110 LET VAL=1,MX=400,BJMP=25,SJMP=1

0120 V_SCROLLBAR 101,@(6,14,1,10)
0130 V_SCROLLBAR 102,@(15,14,2,10)
0140 V_SCROLLBAR 103,@(25,14,3,10)
0150 V_SCROLLBAR 104 WINDOW
0160 INPUT (0,HLP="V_SCROLLBAR")@(40,18),"Select...: ",'CL',X$
0170 IF CTL<101 OR CTL>104 THEN GOTO 0210
0180 V_SCROLLBAR READ CTL,VAL,MX,BJMP,SJMP
0190 V_SCROLLBAR WRITE CTL,VAL,MX
0200 PRINT @(40,19),"Selection:",CTL,":",STR(VAL),'CL',; GOTO 0160
Format 2 Creates at Edge of Window: V_SCROLLBAR ctl_id WINDOW [,fileopt]

Use the V_SCROLLBAR format with WINDOW to create a V_SCROLLBAR at the edge of the window.
Format 3 Deletes: V_SCROLLBAR REMOVE ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR REMOVE format to delete a V_SCROLLBAR.
Format 4: V_SCROLLBAR {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR DISABLE format to disable or gray-out a V_SCROLLBAR. (Your user can see,
but not gain access to it, and its inaccessible to your programs.) Use the V_SCROLLBAR ENABLE
format to restore access to a disabled V_SCROLLBAR.
Format 5 Sets Focus: V_SCROLLBAR GOTO ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR GOTO format to set the Focus on your V_SCROLLBAR, ready for the next event.

Format 6: V_SCROLLBAR READ ctl_id,setting,max,[rgn_chg[,arrow_chg][,ERR=stmtref]
Use the V_SCROLLBAR READ format to read the current setting of the V_SCROLLBAR.
NOTE: Once a user has selected a new position, its your responsibility to READ it to return
the value to your program.
Example:
0120 V_SCROLLBAR READ 100,X,1000
0130 V_SCROLLBAR WRITE 100,X,1000
Line 0120 reads the scrollbar position relative to 1000 and line 0130 updates the settings.
Format 7 Updates: V_SCROLLBAR WRITE ctl_id,marker,max [,ERR=stmtref]

Use the V_SCROLLBAR WRITE format to update or write the current V_SCROLLBAR settings.
Format 8: V_SCROLLBAR {HIDE | SHOW} ctl_id[,ERR=stmtref]

Use the V_SCROLLBAR HIDE format to hide the V_SCROLLBAR. It will still be active, but hidden from
the user's view (and inaccessible). Use V_SCROLLBAR SHOW to restore the display and make the
V_SCROLLBAR accessible to the user.

VARDROP_BOX Define/Control Variable Drop Box
Directive VARDROP_BOX
Format:
1 Define/Create VARDROP_BOX ctl_id, @(col,line,width,height)[,fileopt]

2 Delete VARDROP_BOX REMOVE ctl_id[,ERR=stmtref]
3 Disable/Enable VARDROP_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
4 Set Focus To VARDROP_BOX GOTO ctl_id[,ERR=stmtref]
5 Load List VARDROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]
6 Load Array VARDROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]
Note that the curly brackets around {ALL} are "real" brackets (i.e. part of the syntax).
7 Load/Delete Element VARDROP_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]
8 Get Element VARDROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]
9 Read Current Selection VARDROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]
10 Read Current Index VARDROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
11 Update Current Setting VARDROP_BOX WRITE ctl_id,element$[,ERR=stmtref]
12 Update Current Index VARDROP_BOX WRITE ctl_id,index[,ERR=stmtref]
13 FOCUS Notification VARDROP_BOX SET_FOCUS ctl_id,alt_id[,ERR=stmtref]
14 Report All Changes VARDROP_BOX AUTO ctl_id[,ERR=stmtref]
15 Hide/Show VARDROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the VARDROP_BOX. Numeric expression. Integers,
@(col,line, Position and size of the VARDROP_BOX region when expanded. Numeric
expressions. Column and line coordinates for top left corner, width in number of
width,height)
columns, height in number of lines.
(Note that VARDROP_BOX height when not expanded is governed by the system
and is roughly 1.5 times the standard graphic font height.)

Where =
fileopt File options. Valid options for VARDROP_BOX include:
KEY=char$ Hot key
LEN=num Maximum input length
OPT=char$ Single character parameter
D - Disable the VARDROP_BOX. User cannot gain access.
H - Hide: Do not display the VARDROP_BOX
A - Auto: Generates a CTL signal for every character entered
T - Strip trailing spaces
s - Scroll: Allows control to scroll in a resizable/scrollable dialogue box
array_name$ Name of an array to load into the VARDROP_BOX. String variable followed by {ALL}.
index Position of the element in the VARDROP_BOX. Numeric expression. Integers: the
index of the first element is 1.
delete an element. For instance, VARDROP_BOX LOAD 86,4,* will "eighty-six"
(remove) element 4 from VARDROP_BOX 86.
VARDROP_BOX (e.g. $01$ for a <Mouse-Click> or $0D$ for <Enter>).
alt_id CTL value to generate when the VARDROP_BOX gains focus.
Description:
Use the VARDROP_BOX directive to create and control variable drop boxes on the screen. A
VARDROP_BOX normally occupies a single line on the screen with a {down arrow} on the right side and
allows variable input. That is, the user can select any element from a list of items associated with the
VARDROP_BOX or can enter any other value. To view the list the user presses the {down arrow}.
Because a VARDROP_BOX list is in dropdown form, a VARDROP_BOX takes a smaller amount of space
on your screen than a comparable VARLIST_BOX. In addition, ProvideX automatically supplies vertical
scrollbars if the number of elements overflows dropdown box size. You can combine these features to
optimize your screen design when display space is at a premium.
See also Dynamic Control Object PROPERTIES, p. 572 for a list of properties and settings you can
apply to VARDROP_BOXes.
Format 1 Creates: VARDROP_BOX ctl_id, @(col,line,width,height)[,fileopt]

Use the format above to create your VARDROP_BOX, giving it a unique ctl_id. When a user selects an
item from a variable drop box, or adds an item not on the list, the associated ctl_id you give to the
VARDROP_BOX is used to generate a CTL.

Example:
0010 VARDROP_BOX 100,@(2,14,12,6)
0020 VARDROP_BOX LOAD 100,"Cat/Dog/Pig/"
This creates a VARDROP_BOX that generates a CTL=100 when an item is selected from it. The
VARDROP_BOX is loaded with the items Cat, Dog, and Pig. The user can select any of the three items
supplied or enter any other value.
You can use the FNT= option to set the font for the VARDROP_BOX. If you omit this, the "System" default
font is used. If you use FNT="*, the asterisk sets the font to standard text mode fixed font.
Format 2 Deletes: VARDROP_BOX REMOVE ctl_id[,ERR=stmtref]

Use the VARDROP_BOX REMOVE format to delete a VARDROP_BOX.
Format 3: VARDROP_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

When you DISABLE a VARDROP_BOX, your user can see it, but it will be grayed out and inaccessible to
users and your programs. Use the VARDROP_BOX ENABLE format to restore access to a disabled
VARDROP_BOX.
Format 4 Sets Focus: VARDROP_BOX GOTO ctl_id[,ERR=stmtref]

Use the VARDROP_BOX GOTO format to set the Focus on a VARDROP_BOX, ready for the next user
input.
LOAD Formats 5,6,7:

Use the VARDROP_BOX LOAD formats below to load items into a VARDROP_BOX. You can load your
element(s) as a delimited string, as an array of string elements, or individually.
Format 5 Loads Delimited String: VARDROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

When you LOAD items from a delimited string, each element must be delimited by the character you use
as the last character in the string.
Examples:
0100 VARDROP_BOX LOAD 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
0500 VARDROP_BOX LOAD 15000,"Fox"+SEP+"Cat"+SEP+"Dog"+SEP
Format 6 Loads Array: VARDROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

When you LOAD your VARDROP_BOX from an array, note that the curly brackets in {ALL} are "real" (i.e.
Format 7 Loads Item: VARDROP_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]

When you load a VARDROP_BOX one element at a time, the index refers to the element before which the
new element is to be inserted. For instance, if you use a value of 1, your element is inserted at the start of
the list. If your index value is zero, the element will be appended to the end of the list.
If you have more items on your list than will fit the physical screen size of your VARDROP_BOX, ProvideX

automatically supplies scrollbars.
To remove or delete individual elements from a VARDROP_BOX, use an asterisk in place of your
element$. For example:
VARDROP_BOX LOAD 86,4,* ! Deletes item whose index=4 from drop box 86
Format 8 Gets Element: VARDROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]

Use the VAR_DROP FIND format to retrieve a specific element from a VARDROP_BOX.
READ Formats 9 and 10

Use VARDROP_BOX READ formats (below) to read which element the user has selected from the
VARDROP_BOX.
Use a string variable to return information on how the element was selected. The value returned will be:
$01$ For a <Mouse-click>
$0D$ If the user hit <Enter>
$00$ Once this value is read it is reset to $00$.
Format 9 READs Current Element: VARDROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

Use a string variable in your VARDROP_BOX READ to receive the value of the currently selected element.
You can use an optional second variable to receive the selection method (i.e. mode$).
Format 10 READs Current Index: VARDROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]

Use a numeric variable in your VARDROP_BOX READ to receive the index of the element your user has
selected.
NOTE: Once a user has made a selection, its your responsibility to READ it to return the
value to your program.
WRITE Formats 11 and 12:

Use the WRITE formats (below) to set or update the current selection in the VARDROP_BOX. The value
you write can be one of the elements loaded into the VARDROP_BOX or any other value.
Format 11 Using Element String: VARDROP_BOX WRITE ctl_id,element$[,ERR=stmtref]

Use VARDDROP_BOX WRITE with a string expression to update the current selection by element.
Format 12 Using Element Index: VARDROP_BOX WRITE ctl_id,index[,ERR=stmtref]

Use VARDDROP_BOX WRITE with a numeric expression to update the current selection by element
index.

Format 13 for FOCUS Notification: VARDROP_BOX SET_FOCUS ctl_id,alt_id[,ERR=stmtref]
Use the VARDROP_BOX SET_FOCUS format to obtain notification when Focus changes. SET_FOCUS
generates an alternate CTL value whenever Focus shifts to your VARDROP_BOX .
Format 14 Reports All Changes: VARDROP_BOX AUTO ctl_id[,ERR=stmtref]

Use the VARDROP_BOX AUTO format to have ProvideX automatically generate a CTL whenever the
current selection is changed. This lets you track changes in which_selection_is-highlighted in a
VARDROP_BOX.
Format 15: VARDROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]

Use the VARDROP_BOX HIDE format to hide your VARDROP_BOX from display. The user can't see or
access it, even though it is still active for use by your program. Use the VARDROP_BOX SHOW format to
restore the display.

VARLIST_BOX Define/Control Variable List Box
Directive VARLIST_BOX
Format:
1 Define/Create VARLIST_BOX ctl_id,@(col,line,width,height)[,fileopt]

2 Delete VARLIST_BOX REMOVE ctl_id[,ERR=stmtref]
3 Disable/Enable VARLIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]
4 Set Focus To VARLIST_BOX GOTO ctl_id[,ERR=stmtref]
5 Load List VARLIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]
6 Load Array VARLIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]
Note that the curly brackets around {ALL} are "real" brackets (i.e. part of the syntax).
7 Load/Delete Element VARLIST_BOX LOAD ctl_id,index,element$[,ERR=stmtref]
8 Get Element VARLIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]
9 Read Current Selection VARLIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]
10 Read Current Index VARLIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
11 Update Current Item VARLIST_BOX WRITE ctl_id,element$[,ERR=stmtref]
12 Update Current Index VARLIST_BOX WRITE ctl_id,index[,ERR=stmtref]
13 FOCUS Notification VARLIST_BOX SET_FOCUS ctl_id,alt_id[,ERR=stmtref]
14 Report All Changes VARLIST_BOX AUTO ctl_id[,ERR=stmtref]
Where =
ctl_id Unique logical identifier for the VARLIST_BOX. Numeric expression. Integers,
@(col,line, Position and size of the VARLIST_BOX region. Numeric expressions. Column and
line coordinates for top left corner, width in number of columns, height in number of
width,height)
lines.
fileopt File options. Valid options for VARLIST_BOX include:
KEY=char$ Hot key
LEN=num Maximum input length
OPT=char$ Single character parameter
D - Disabled: User cannot access the VARLIST_BOX
H - Hide: Do not display theVARLIST_BOX
s - Scroll: Allows VARLIST_BOX to scroll in a resizable/scrollable dialogue
box
See Format 1, below, for information on FNT=options.

Where =
array_name$ Name of array to load into the VARLIST_BOX. String variable followed by {ALL}.
index Position of the element in the VARLIST_BOX. Numeric expression. Integers: the
index of the 1st element is 1.
delete an element. For instance, VARLIST_BOX LOAD 86,4,* will "eighty-six"
(remove) element 4 from VARLIST_BOX 86.
VARLIST_BOX (e.g. $01$ for a <Mouse-Click> or $0D$ for <Enter>).
alt_id CTL value to generate when the VARLIST_BOX gains focus.
Description:
Use the VARLIST_BOX directive to create and control variable list boxes on the screen. Variable input is
allowed. That is, the user can select any element from a list of items associated with the VARLIST_BOX or
can enter any other value.
See also Dynamic Control Object PROPERTIES, p. 572 for a list of properties and settings you can
apply to VARLIST_BOXes.
Format 1 Creates: VARLIST_BOX ctl_id, @(col,line,width,height)[,fileopt]

Use the format above to create your VARLIST_BOX, giving it a unique ctl_id. When a user selects an item
from a VARLIST_BOX, or adds an item not on the list, the associated ctl_id you give to the VARLIST_BOX
is used to generate a CTL.
Example:
0010 VARLIST_BOX 100,@(2,14,12,6)
0020 VARLIST_BOX LOAD 100,"Cat/Dog/Pig/"
This creates a VARLIST_BOX that generates a CTL=100 when a user selects or enters an item. The
VARLIST_BOX is loaded with the items Cat, Dog, and Pig. The user can select any of the three items
supplied or can add any other value to the VARLIST_BOX.
You can use the FNT= option to set the font for the VARLIST_BOX. If you omit this, the "System" default
font is used. If you use FNT=*, the asterisk sets the font to standard text mode fixed font.
Format 2 Deletes: VARLIST_BOX REMOVE ctl_id[,ERR=stmtref]

Use the VARLIST_BOX REMOVE format to delete a VARLIST_BOX.
Format 3: VARLIST_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

When you use the VARLIST_BOX DISABLE format, your user can see it, but it will be grayed out and
inaccessible. Use the VARLIST_BOX ENABLE format to restore access to a disabled VARLIST_BOX.
Format 4 Sets Focus: VARLIST_BOX GOTO ctl_id[,ERR=stmtref]

Use the VARLIST_BOX GOTO format to set the Focus on a VARLIST_BOX, ready for the next user action.

LOAD Formats 5, 6 and 7:
Use the LOAD formats below to load items into a VARLIST_BOX. You can load your element(s) as a
delimited string, as an array of string elements, or individually.
Format 5 Loads Delimited List: VARLIST_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

When you load items from a delimited string, each element must be delimited by the character you use as
the last character in the string.
Examples:
0100 VARLIST_BOX LOAD 10000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"
0500 VARLIST_BOX LOAD 14000,"Fox"+SEP+"Cat"+SEP+"Dog"+SEP
Format 6 Loads Array: VARLIST_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

You can LOAD a complete array into your VARLIST_BOX. Note that the curly brackets around {ALL} are
"real" brackets (i.e. part of the syntax).
Format 7 Loads/Deletes Element: VARLIST_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]

When you LOAD a VARLIST_BOX one element at a time, the index refers to the element before which the
element is to be inserted. For instance, if you use a value of 1, your element is inserted at the start of the
list. If your index value is zero, the element will be appended to the end of the list.
If you have more items on your list than will fit the physical screen size of your VARLIST_BOX, ProvideX
automatically supplies scrollbars.
To remove or delete individual elements from a VARLIST_BOX, use an asterisk instead of element$.
For example:
VARLIST_BOX LOAD 86,4,* ! Deletes item whose index=4 from varlist_box 86
Format 8 Retrieves Element: VARLIST_BOX FIND ctl_id,index,var$[,ERR=stmtref]

Use the VARLIST_BOX FIND format to return a specific element from a VARLIST_BOX.
READ Formats 9 and 10:

Use the READ formats (below) to read which element the user has selected from the VARLIST_BOX. Use
a string variable to return information on how the element was selected. The value returned for the mode$
will be:
$02$ for <Mouse-double-click> or

$0D$ if the user hit <Enter>.
$00$ Once this value is read it is reset to $00$.
Format 9 for Current Element: VARLIST_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

Use a string variable to receive the value of the currently selected element. The second string variable
(e.g. mode$) receives the method of selection. Optional.

Format 10 for Current Index: VARLIST_BOX READ ctl_id,var[,mode$][,ERR=stmtref]
You can use a numeric variable to return the index of the element the user has selected. The string
variable to return the method of selection is optional.
NOTE: Once a user has made a selection, its your responsibility to READ it to return the
value to your program.
WRITE Formats 11 and 12: Update Current Setting

Use the VARLIST_BOX WRITE formats below to set or update the current selection in the VARLIST_BOX.
The value you write can be one of the elements loaded into the VARLIST_BOX or any other value.
Format 11 Updates Using String: VARLIST_BOX WRITE ctl_id,element$[,ERR=stmtref]

Use a string expression to update a given element as the current selection.
Format 12 Updates Using Index: VARLIST_BOX WRITE ctl_id,index[,ERR=stmtref]

Use your given index number to update it as the current selection.
Format 13 for FOCUS Notification: VARDROP_BOX SET_FOCUS ctl_id,alt_id[,ERR=stmtref]

Use the VARLIST_BOX SET_FOCUS format to obtain notification when the focus changes. SET_FOCUS
generates an alternate CTL value whenever focus shifts to your VARLIST_BOX.
Format 14 Reports All Changes: VARDROP_BOX AUTO ctl_id[,ERR=stmtref]

Use the VARLIST_BOX AUTO format to have ProvideX automatically generate a CTL whenever the
current selection is changed. This lets you track changes in which selection is highlighted in a
VARDROP_BOX.

VIA Assign Variable Indirectly
Directive VIA
Format:
1 Assign to Variable VIA var$=expression

2 To Composite Variable VIA composite$,var_1$[[,subsc]]=expr[, ... n]
Where =
var$ String variable , e.g. animal$, containing the name of the variable to be used, e.g.
"domestic$".
composite$ String variable. (Name of a variable defined as composite string.)
composite$,var_ Name and optional subscript(s) of a variable in the composite string. String
1$[subscript] to n expression. You can include from 1 to 3 optional numeric expressions in square
brackets, comma-separated, as subscripts for the variable. (The inner set of
square brackets is "real" (i.e. part of the syntax).)
expression Value you want assigned to the named variable, e.g. "cat".
Description:
Use the VIA directive to assign a value to a variable where the variable name is contained in another string
variable. The target variable's type (numeric or string) is based on the type of expression.
Format 1 Assigns To Variable: VIA var$=expression

Use this VIA format to assign the value in the expression to a variable whose name is stored in var$ (i.e. to
assign VIA the var$). If you use a string, then ProvideX automatically appends a $ to the variable name.
Example:
0030 LET ANIMAL$="pet", PET$="dog"
0040 VIA ANIMAL$="cat"
0050 PRINT ANIMAL$," ",PET$; END
When RUN, results in pet cat.
Format 2 In Composite Variable: VIA composite$,var_1$[[,subsc]]=expr ... n

You can assign the value of the expression to a variable in a composite string. In this format, you can
specify up to 3 subscripts for the variable(s).
Example:
0010 IOLIST X$,Y$,Z$
0020 DIM PET$:IOL=0010
0030 LET X$="Dogs",Y$="Cats",Z$="!" REM Assign values to variables
0040 VIA PET$,"X$"="Lotsa",PET$,"Y$"="and",PET$,"Z$"="Its raining"
0050 PRINT PET.X$," ",X$," ",PET.Y$," ",Y$
0060 LET PET.X$=X$,PET.Y$=Y$
0070 PRINT PET.Z$," ",PET.Y$," and ",PET.X$,Z$
-:run
Lotsa Dogs and Cats
Its raining Cats and Dogs!

VIDEO_PALETTE Control Video Colours
Directive VIDEO_PALETTE
Format:
1 Read Palette VIDEO_PALETTE READ var$[,ERR=stmtref]

2 Change Palette VIDEO_PALETTE string$[,ERR=stmtref]
3 Read Palette Indexed Table VIDEO_PALETTE READ INDEXED var$[,ERR=stmtref]
4 Change Indexed Table VIDEO_PALETTE INDEXED string$[,ERR=stmtref]
Where =
var$ String variable to receive the current VIDEO_PALETTE or INDEXED table settings.
string$ String expression containing the new VIDEO_PALETTE or INDEXED table settings to
be used.
Description:
ProvideX supplies a 16-colour video palette with direct access to the standard 16 colours provided by
WINDOWS. Use the VIDEO_PALETTE directive to modify the 16-colour video palette in ProvideX.
Format 1 Reads Palette: VIDEO_PALETTE READ var$[,ERR=stmtref]

Use this format to READ the current settings of the VIDEO_PALETTE, which consists of a string of 16 3-
byte entries where each byte defines the intensity of the colours RED, GREEN and BLUE. For example,
the 3-byte entry for bright (foreground) green is $00FF00$, magenta is $FF00FF$ ...
VIDEO_PALETTE READ X$ will return you the following defaults in a single string. (The string is only
punctuated by spaces below to show you the sixteen 3-byte entries.)
$000000 FF0000 00FF00 FFFF00$
$0000FF FF00FF 00FFFF FFFFFF$
$808080 800000 008000 808000$
$000080 800080 008080 C0C0C0$
Format 2 Changes Palette: VIDEO_PALETTE string$[,ERR=stmtref]

You can use this format to change / reset the VIDEO_PALETTE, as in VIDEO_PALETTE X$ where X$
contains your new values.
NOTE: Changing the palette may not work on all systems. (This depends on the colour
capabilities of the PC hardware.)
Format 3 Reads Palette Indexed Table: VIDEO_PALETTE READ INDEXED var$[,ERR=stmtref]

There is also an INDEXED table to reference the VIDEO_PALETTE. This index table consists of 48
entries: six 8-byte tables, where each byte represents an index into the VIDEO_PALETTE described
above.
The first 8 bytes represent the standard foreground colours.

The second 8 bytes represent the colours used when the 'SB' mnemonic is in effect
The third 8 bytes represent the colours used when the 'BB' mnemonic is in effect

The fourth 8 bytes represent the colours used when both 'BB' and 'SB' are in effect
The fifth 8 bytes represent the "Background" colours
The sixth 8 bytes represent the colours used when 'BR' and 'SB' are in effect
Use the READ format to return the current settings in the index table, as in VIDEO_PALLETTE READ
INDEXED X$.
See also: 'BB' DOS: Begin Blinking, p. 494(m)
'BR' Begin Reverse_Video, p. 497(m)
'SB' Set Mode to Background, p. 526(m)
Format 2 Changes Palette Indexed Table: VIDEO_PALETTE INDEXED string$[,ERR=stmtref]

You can use this format to change / reset the VIDEO_PALETTE index table, as in VIDEO_PALETTE
INDEXED X$ where X$ contains your new values.

VIN( ) and VIS( ) Obtain Value of Variable
Functions VIN( ) and VIS( )
Format:
1 VIN( ) Numeric Variable VIN(string$[,ERR=stmtref])

2 VIN( ) Composite Numeric VIN(composite$,var_1$[[,subscr]]=expr[, ... n])
3 VIS( ) String Variable VIS(string$[,ERR=stmtref])
4 VIS( ) Composite String VIS(composite$,var_1$[[,subscr]]=expr[, ... n])
NOTE: You can use the optional ,ERR=stmtref with each of the formats above.
Where =
string$ String expression containing the name of a variable to be used.
composite$ String variable which has been defined as a composite string.
var_1[$] to String expression containing the name of a variable in the composite string.
var_n[$]
[subscr] Optional. Up to 3 numeric values, comma-separated, representing the subscripts to
apply to var_1$ ... Note that the inner square brackets around the [subscr] value are
"real" (i.e. part of the syntax).
Returns: Contents (value) of variable(s), numeric or string
Description:
The VIN( ) function returns the numeric value (contents) of a variable where the name of the numeric
variable is stored in a string variable. The VIS( ) function returns the string value (contents) of a string
variable whose name is stored in a string variable.
See also: VIA Assign Variable Indirectly, p. 463(d)
Format 1 Gets Value, Numeric: VIN(string$[,ERR=stmtref])

The VIN( ) function returns the numeric contents of a numeric variable whose variable name is stored in
the string$.
Format 2 for Composite Numeric: VIN(composite$,var$,[,[subscript,..]][,ERR=stmtref])

The VIN( ) function returns the value contained in each numeric variable you name (where the variable is
part of a composite string). You can choose to specify up to three subscripts for the variable.
Format 3 Gets Value, String: VIS(string$[,ERR=stmtref])

The VIS( ) function returns the contents of a string variable whose variable name is stored in the string$.

Format 4 for Composite String: VIS(composite$,var$,[,[subscript,..]][,ERR=stmtref])
The VIS( ) function returns the value contained in each string variable you name (where the variable is part
of a composite string). You can choose to specify up to three subscripts for the variable.
Examples:
0100 INPUT "Record key:",K$
0110 READ (1,KEY=K$,DOM=0100)IOL=8000
0120 INPUT "What field?",F$
0130 IF F$="" THEN STOP
0140 PRINT F$,"=", VIS(F$); GOTO 0120
->DOG$="DALMATIANS", DOG=101
->PRINT VIN("DOG")," ",VIS("DOG")
101 DALMATIANS

WAIT Temporarily Halt Execution
Directive WAIT
Format:
Define Length of Wait WAIT seconds
Where =
seconds Number of seconds to wait. Numeric expression, range: 0 to 600 seconds, i.e., a
maximum of 10 minutes.
Description:
Use the WAIT directive to have the system suspend execution for the number of seconds you indicate in
the numeric expression.
During the time the program is suspended, the SETESC directive is deferred. This directive will only be
processed once the WAIT interval has elapsed.
NOTE: The accuracy of the timing varies from operating system to operating system. In
MS-DOS, the WAIT is accurate to within 1/19th of a second. On most UNIX (and
UNIX-like) systems, the WAIT is accurate to within one second.
Example:
0110 READ (1,ERR=1000,KEY=K$)N$
1000 REM Test for busy record
1010 IF ERR=0 THEN PRINT @(0,22),"Busy. will retry";
1010: WAIT 5; RETRY

WEND End of WHILE Processing
Directive WEND
Format:
Define End of While Loop WEND
Description:
Use the WEND directive to mark the end of a WHILE/WEND loop. When ProvideX reaches the WEND
directive, the expression defined in the currently active WHILE is re-evaluated. If the result of the
evaluation is not zero, control is returned to the directive following the WHILE. If the value is 0 (zero,
FALSE), control transfers to the directive following the WEND.
If ProvideX encounters a WEND directive but is not currently processing a WHILE / WEND loop, it returns
an Error #27: Unexpected or incorrect WEND, RETURN, or NEXT. All FOR / NEXT, GOSUB
/ NEXT, and WHILE / WEND sequences executed within the WHILE / WEND loop must be completed.
See also: WHILE Repeat Statements, p. 470(d)
Example:
0100 WHILE A$<>"E"
0110 LET K$=KEY(1,END=1000)
0120 READ (1)N$
0130 PRINT "Key: ",K$," Name: ",N$
0140 INPUT "Delete (Y/N):",A$
0150 IF A$="Y" THEN REMOVE (1,KEY=K$)
0160 WEND
0170 STOP
1000 PRINT "End-of-file..."
1010 EXITTO 0170

WHILE Repeat Statements
Directive WHILE
Format:
Loop Again WHILE num
Where =
num Numeric expression. When the evaluated value of the expression is 0 (zero, FALSE)
looping ends.
Description:
Use the WHILE directive for conditional looping in a program. ProvideX executes all directives between a
WHILE directive and the next WEND directive repeatedly until the value of the numeric expression is 0
(zero).
When ProvideX encounters a WHILE directive, it evaluates your numeric expression. If the value is not
zero, ProvideX continues execution until a corresponding WEND directive is encountered, at which point
the numeric expression is re-evaluated. ProvideX continues to loop back to the directive following the
WHILE directive until a 0 (zero) value is reached. When the value is zero, ProvideX advances to the next
statement that contains a WEND directive, where it terminates the loop. Then control transfers to the
statement following the WEND.
You can use a conditional EXITTO directive to exit a WHILE / WEND loop early.
See also: WEND End of WHILE Processing, p. 469(d)
Example:
0100 WHILE A$<>"E"
0110 LET K$=KEY(1,END=1000)
0120 READ (1)N$
0130 PRINT "Key: ",K$," Name: ",N$
0140 INPUT "Delete (Y/N):",A$
0150 IF A$="Y" THEN REMOVE (1,KEY=K$)
0160 WEND
0170 STOP
1000 PRINT "End-of-file..."
1010 EXITTO 0170

WHO Current UserID
String System Variable WHO
Returns: String, current UserID
Description:
This string system variable returns the current UserID. On systems without user registration, it returns the
value of the environment variable USER or the Network user ID.
See also: UID USER ENV Variable or Network ID, p. 444(v)
Examples:
0010 ! START_UP
0020 OPEN (1)"MYCONFIG"
0030 READ (1,KEY=WHO,ERR=0050)X$
0040 SETFID X$
0050 CLOSE (1)
->?WHO
LINDAM

WINPRT_SETUP Windows Printer Setup
Directive WINPRT_SETUP
Format:
1 Read Current Selection WINPRT_SETUP READ var$[,ERR=stmtref]

2 Read Properties WINPRT_SETUP READ PROPERTIES var$[,ERR=stmtref]
3 Write Selection WINPRT_SETUP WRITE printer$[,ERR=stmtref]
4 Write Properties WINPRT_SETUP WRITE PROPERTIES settings$[,ERR=stmtref]
5 List Printers in Full WINPRT_SETUP LIST var$[,ERR=stmtref]
6 List Only Printer Name WINPRT_SETUP DIRECTORY var$
7 Windows Printer Dialogue WINPRT_SETUP INPUT var$[,ERR=stmtref]
Where =
var$ String variable. Receives the returned value for printer name(s) or properties.
printer$ String expression to select the current printer by name.
settings$ String expression to assign property values.
Description:
Use the WINPRT_SETUP directive to control the currently selected WINDOWS printer and its properties.
Example:
0100 READ (1,KEY="PRTR")P$
0110 WINPRT_SETUP WRITE P$
0120 OPEN (2)"*WINPRT*;ASIS"
See also: Examples: Queues for *WINPRT* / *WINDEV*, p. 599
WINPRT_SETUP Properties
The default properties of a printer are determined by the individual printer/driver manufacturers. You dont
have access to margin control. Some properties (e.g. collate, ordered printing) are not available for all
drivers. Others (e.g. font, point size) vary from printer to printer. Default paper size seems to be
consistently letter size (8 1/2" x 11", expressed as PAPERSIZE=1 for DMPAPER_LETTER). See
PAPERSIZE=num Property, p. 473 for a list of paper size codes.
The properties assigned to your WINDOWS printer (printer/driver dependent) can include:
RANGE = from:to
COLLATE=YES/NO
COPIES=n
ORIENTATION=PORTRAIT/LANDSCAPE
PAPERSIZE=n
PAPERLENGTH=n(mm)
PAPERWIDE=n(mm)
SCALE=n(%)
SOURCE=n
QUALITY=n
RESOLUTION=n:n
COLOR=YES/NO

DUPLEX=n
TRUETYPE=n
FILE=+/-/filename
OFFSET=X:Y
Most properties are self-explanatory, like copies=1. Some need a little explanation. For instance, the
assignment you use for the offset property is =x:y in thousandths of an inch and is the offset to the
print area from the upper left corner of the page. (If you assign offset=750:500, for example, that
offsets the print area three-quarters of an inch from the left margin and half an inch down from the top
margin.)
TRUETYPE=num Property
Valid TRUETYPE numeric settings include:
1 Print TT fonts as graphics
2 Download TT fonts as soft fonts
3 Substitute device fonts for TT fonts
DUPLEX=num Property
Valid numeric settings for printers capable of double-sided printing (DUPLEX) are:
1 Duplex is OFF
2 Duplex in Portrait
3 Duplex in Landscape
QUALITY=num Property
Valid QUALITY numeric settings are:
-1 Draft
-2 Low Resolution
-3 Medium Resolution
-4 High Resolution
PAPERSIZE=num Property
The chart below lists paper sizes according to print.h, with the the Internal Name followed by the number to
use as the PAPERSIZE=num option for the print drivers, followed by a more general description of the
paper.
/* paper selections */
/* Warning: The PostScript driver mistakenly uses DMPAPER_ values between * 50
and 56. Don't use this range when defining new paper sizes. */
Paper: Internal Name num Size / Description

DMPAPER_LETTER 1 Letter 8 1/2 x 11 in
DMPAPER_LETTERSMALL 2 Letter Small 8 1/2 x 11 in
DMPAPER_TABLOID 3 Tabloid 11 x 17 in
DMPAPER_LEDGER 4 Ledger 17 x 11 in
DMPAPER_LEGAL 5 Legal 8 1/2 x 14 in
DMPAPER_STATEMENT 6 Statement 5 1/2 x 8 1/2 in
DMPAPER_EXECUTIVE 7 Executive 7 1/4 x 10 1/2 in
DMPAPER_A3 8 A3 297 x 420 mm

Paper: Internal Name num Size / Description
DMPAPER_A4SMALL 10 A4 Small 210 x 297 mm
DMPAPER_B4 12 B4 250 x 354
DMPAPER_B5 13 B5 182 x 257 mm
DMPAPER_FOLIO 14 Folio 8 1/2 x 13 in
DMPAPER_QUARTO 15 Quarto 215 x 275 mm
DMPAPER_10X14 16 10x14 in
DMPAPER_11X17 17 11x17 in
DMPAPER_NOTE 18 Note 8 1/2 x 11 in
DMPAPER_ENV_9 19 Envelope #9 3 7/8 x 8 7/8
DMPAPER_ENV_12 22 Envelope #12 4 \276 x 11
DMPAPER_ENV_14 23 Envelope #14 5 x 11 1/2
DMPAPER_CSHEET 24 C size sheet
DMPAPER_DSHEET 25 D size sheet
DMPAPER_ESHEET 26 E size sheet
DMPAPER_ENV_DL 27 Envelope DL 110 x 220mm
DMPAPER_ENV_C5 28 Envelope C5 162 x 229 mm
DMPAPER_ENV_B4 33 Envelope B4 250 x 353 mm
DMPAPER_ENV_ITALY 36 Envelope 110 x 230 mm
DMPAPER_ENV_MONARCH 37 Envelope Monarch 3.875 x 7.5 in
DMPAPER_ENV_PERSONAL 38 6 3/4 Envelope 3 5/8 x 6 1/2 in
DMPAPER_FANFOLD_US 39 US Std Fanfold 14 7/8 x 11 in
DMPAPER_FANFOLD_STD_GERMAN 40 German Std Fanfold 8 1/2 x 12 in
DMPAPER_FANFOLD_LGL_GERMAN 41 German Legal Fanfold 8 1/2 x 13 in
DMPAPER_USER 256

Format 1 to Read Selection: WINPRT_SETUP READ var$
Use the WINPRT_SETUP READ format to read the currently selected default printer name. The value
returned in your string variable will be the O/S name of an existing physical queue. For example:
-: WINPRT_SETUP READ PRTR$
-: ?PRTR$
HPLaserJet III on \\machine_1\hp
Format 2: WINPRT_SETUP READ PROPERTIES var$

Use the WINPRT_SETUP READ PROPERTIES format to read the current settings of the PROPERTIES
associated with your current printer. The values are returned in a semicolon-separated list.
Example:
->OPEN (1)"*WINPRT*"
->WINPRT_SETUP READ PROPERTIES PROP$
->?PROP$
RANGE=ALL;COLLATE=NO;COPIES=1;ORIENTATION=PORTRAIT;PAPERSIZE=1;SOURCE=1;RESOLU
TION=300:300;OFFSET=0:0;TRUETYPE=2;DRIVER=WINSPOOL
Format 3 to Update Selection: WINPRT_SETUP WRITE printer$

Use the WINPRT_SETUP WRITE format to write or change the currently selected default printer, using a
string expression to pass the system the name of the printer to use. For example:
->winprt_setup write "Canon BJC-4300 on \\machine_2\canon"
Format 4: WINPRT_SETUP WRITE PROPERTIES settings$

Use the WINPRT_SETUP WRITE PROPERTIES format to write or change the current properties, using a
string expression to pass the system the property assignments to use. For example:
LET P$="COPIES=2;ORIENTATION=LANDSCAPE"
WINPRT_SETUP WRITE PROPERTIES P$
Format 5 to List Available Printers: WINPRT_SETUP LIST var$

Use the WINPRT_SETUP LIST format to obtain a comma-delimited LIST of all the printers defined in the
system. Note that if you use this format on a workstation which does not have printers installed, there will
be no value in your string variable and ProvideX will return an Error #12: File does not exist
(or already exists).
->winprt_setup list choices$

->? choices$
HP LaserJet III on \\machine_1\hp,Envoy 7 Driver on EVY:,Canon BJC-4300 on
\\machine_2\canon,Acrobat PDFWriter on LPT1:,Default PostScript Printer on
LPT1:,Default PostScript Pri (Copy 1) on LPT1:,Acrobat Distiller 3.0 on
LPT1:,Acrobat Distiller 3.0 (Copy 1) on LPT1:,
Format 6 Lists Printer Names Only: WINPRT_SETUP DIRECTORY var$

You can use the DIRECTORY keyword to return a comma-delimited list of printers with just the printer
portion of the names, excluding the ON Device portion (Ver. 4.12).

->winprt_setup directory choices$
->? choices$
HP LaserJet III,Envoy 7 Driver,Canon BJC-4300,Acrobat PDFWriter,Default Post-
Script Printer,Default PostScript Pri (Copy 1),Acrobat Distiller 3.0,Acrobat
Distiller 3.0 (Copy 1),HP LaserJet 2100 Series PCL 6,
Format 7 Displays Printer Dialogue: WINPRT_SETUP INPUT var$

Use the WINPRT_SETUP INPUT format to display the WINDOWS Printer Selection dialogue box, allowing
the user to select a printer. Your string variable returns the name of the printer selected by the user.
->? current$ ! Colour inkjet is current setting

Canon BJC-4300 on \\machine_1\canon
->winprt_setup input current$ ! User changes current selection to laser printer

->? current$
HP LaserJet 2100 Series PCL 6 on \\machine_1\hp
->

WRITE Add/Update Data in File
Directive WRITE
Format:
1 Write WRITE (chan[,fileopt])varlist

2 Write Lock WRITE LOCK (chan[,fileopt])varlist
Where =
chan Channel or logical file number of the file to which to write.
fileopt File options. Valid options for WRITE include:
BSY=stmtref Traps Error #0: Record/file busy
DOM=stmtref Duplicate record transfer
END=stmtref File full transfer (EOF)
KEY=num Record key value. See also: Automatic Padding with
KEY=Option, p. 477
TIM=num Maximum time delay
BSY= Option:
You can use the BSY=stmtref option with READ, WRITE, REMOVE directives (and
other similar directives). It allows you to trap Error #0: Record/file busy
specifically (Ver. 4.10). For example:
READ (chan,dom=NoRec,bsy=InUse,Err=Unknown)recdata$
varlist List of variables, literals, mnemonics, IOL= options, and/or location functions '@(...)'.
The items in the list must be comma-separated.
Description:
You can use the WRITE directive to add/update a record to your file (logical file number / channel).
ProvideX also supports use of the WRITE directive with *memory* (a memory-resident file or queue of
records, Ver. 4.10).
See also: RCD( ) Return Next Record, p. 341(f)


KEYED "TEST", [1:1:5]+[2:1:6]+[3:1:8]

is the same as:

Format 1: WRITE (chan[,fileopt])varlist

If the specific record already exists (INDEXED, DIRECT, or SORT files) and you include the DOM=stmtref
option, control transfers to the stmtref. Otherwise, the specified record is updated.
Examples:
0410 WRITE (1,ERR=1000,DOM=1200)A,B,Z9$
An IND=index clause is mandatory if you are writing to an INDEXED file. For example:
0810 LET I=0
0820 OPEN (8)"PVX_INDX"
0830 READ (8)IOL=110,ERR=0950
0840 LET I=I+1 ! This reserves an empty record at index 0
0850 CALL "SOMETHING",IOL=0110,ERR=950
0900 WRITE (8,IND=I,ERR=9000)IOL=0110
0910 GOTO 0830
The KEY=num is mandatory if you are writing to a KEYED file with an external key or to a DIRECT or SORT
file. For example:
0710 OPEN (7)"PVX_SORT"
0720 READ (6)CUST$,NAME$,*,*,*,*,*,*,*,*,*,ERR=0750
0730 WRITE (7,KEY=CUST$)
No KEY= option is allowed if you are writing to a KEYED file whose primary key is composed of data
fields embedded in the record data. In KEYED files with multiple keys, the WRITE directive will
automatically update all alternate keys. For instance, alternate keys 0 [1:1:6] and 1 [2:1:10] will be
updated in the example below:
KEYED "PVX_KEYD",[1:1:6],[2:1:10],,256
0220 READ (6)CUST$,NAME$,*,*,*,*,*,START_DT$,CRED_LIM,TERMS,END_DT$,ERR=0250
0230 WRITE (2)IOL=0100
ProvideX will use the variables in the varliable list either in delimited form or in accordance with any format
specified (e.g. with headers, etc.). The contents of these fields are used to generate the actual data
record. Numeric data converted during a WRITE directive does not use the DP or TH System
Parameters, p. 537 for European decimal settings.
The list of variables can refer to an IOLIST (using IOL=iol_ref) as above. The iol_ref can be the line
number or statement label of the line containing your IOLIST, or it can be a string containing a compiled
IOLIST.
If you omit the list of variables from your WRITE directive, ProvideX will use the IOL (if any) specified on
your OPEN statement for the file.
See also:OPEN Open a File for Processing, p. 299(d)
When You Write to *Memory*

You can use WRITE and/or WRITE RECORD directives to update records in a memory file using an iolist
or a string expression. You can add records by index, inserting records at your given index number.
ProvideX will not overwrite existing records. You can use the DOM= option when you write to a memory
file.
A WRITE operation will check the last entry in the key table for the key being added before proceeding to
the top of the key chain to determine the new entry point. This dramatically increases the speed of writing
additional records in sequential order.

Examples:
The first two examples below insert a new record at index 3 without overwriting the current record at index
3. The record that was at index 3 is now at index 4 and the number of records in the file has increased by
one.
WRITE (14,IND=3)IOL=2010 or
WRITE RECORD (14,IND=3)"DOGCATPIG"
To update a given record in your memory file, you can use the KEY=option with a given key value:
0910 WRITE (14,KEY=KK$,DOM=0920)IOL=2010 or
WRITE RECORD (14,KEY=KK$)A$
Format 2 for Lock: WRITE LOCK (chan[,fileopt])varlist

Use the WRITE LOCK format to ensure that once the file has been written to, it remains locked. For
example:
9010 WRITE LOCK (9,ERR=2000)IOL=0110
When you use the LOCK option, ProvideX doesnt release an EXTRACTed record. It maintains the
extraction to prevent potential timing problems and maintain counters and totals in batch processing,
sparing you the need to re-extract. For example:
9010 WRITE LOCK (9, KEY=K$)
NOTE: If a SERIAL file is not LOCKed before you write to it, an Error #13: File access
mode invalid will occur on your WRITE directive. You can use OPEN LOCK for
your SERIAL file to prevent this error from occurring on the WRITE. For example:
SERIAL "PVX_SER",,256
0510 OPEN LOCK (5)"PVX_SER"
0520 READ (6)CUST$,NAME$,ADDR1$,ADDR2$,CITY$,PROV$,POSTAL$,START_DT$,CREDLIM,
0520:TERMS,END_DT$,ERR=0550
0530 WRITE (5)IOL=0090
0540 GOTO 0520
0550 STOP
See also: 'XI' Extract Ignore, p. 563(p)

WRITE RECORD Add/Update Record in File
Directive WRITE RECORD
Format:
Add/Update Record WRITE RECORD (chan[,fileopt])contents$
Where =
chan Channel or logical file number of the file to which to write.
fileopt File options. Valid options for WRITE RECORD include:
DOM=stmtref Duplicate record transfer
END=stmtref File full transfer (EOF)
TIM=num Maximum time delay
contents$ String (literal, expression, or variable) that contains the contents of the record to write.
Description:
Use the WRITE RECORD directive to add / update a record for your file (logical file number / channel). If
the specific record already exists (INDEXED, DIRECT, or SORT files) and you include the DOM=stmtref
option, control transfers to the stmtref. Otherwise, the specified record is updated.
In KEYED files with multiple keys, the WRITE RECORD directive will automatically update all alternate
keys.
ProvideX supports use of the WRITE RECORD directive with *memory* (a memory-resident file or queue
of records, Ver. 4.10).

KEYED "TEST", [1:1:5]+[2:1:6]+[3:1:8]

is the same as
Example:
0010 OPEN (1)"OLDFIL"

0050 GOTO 0030
1000 CLOSE (1); CLOSE (2)
1010 END
When You Write to *Memory*

You can use WRITE and/or WRITE RECORD directives to update records in a memory file using an iolist
or a string expression. You can add records by index, inserting records at your given index number.
ProvideX will not overwrite existing records. You can use the DOM= option when you write to a memory
file.
A WRITE operation will check the last entry in the key table for the key being added before proceeding to
the top of the key chain to determine the new entry point. This dramatically increases the speed of writing
additional records in sequential order.
Examples:
The first two examples below insert a new record at index 3 without overwriting the current record at index
3. The record that was at index 3 is now at index 4 and the number of records in the file has increased by
one.
WRITE (14,IND=3)IOL=2010 or
WRITE RECORD (14,IND=3)"DOGCATPIG"
To update a given record in your memory file, you can use the KEY=option with a given key value:
0910 WRITE (14,KEY=KK$,DOM=0920)IOL=2010 or
WRITE RECORD (14,KEY=KK$)A$

XEQ( ) In-line Subprogram Execute
Function XEQ( )
Format:
Execute Subprogram XEQ(subprog$,expression,arg,arg,[,ERR=stmtref])
Where =
subprog$ Name of the subprogram to call. String expression.
expression Expression will be evaluated after the call and used as the return value for the
function.
arg,arg... Arguments to pass to the subprogram. Comma-separated list.
Returns: Returns evaluated value in expression after executing in-line CALL
Description:
The XEQ( ) function executes an in-line CALL directive. When ProvideX encounters the XEQ( ) function,
the subprogram named in the function will be CALLed with any arguments supplied. When the
subprogram exits, the XEQ( ) function evaluates the expression and returns it.
The primary advantage of XEQ( ) is in single-line GLOBAL functions. Consider the following example:
Was: 0010 CALL "GETDTE",DT,DATE$
0020 PRINT "Date:",DATE$
Now: 0010 PRINT "Date:",XEQ("GETDTE",_D$,DT,_D$)
Or you could define a GLOBAL function in a startup program:
DEF FN%DTE$(_DT)=XEQ("GETDTE",_D$,_DT,_D$)
Then:
0010 PRINT "Date:",FN%DTE$(DT)

XFA( ) Extended Field Attributes
Function XFA( )
Format:
Return Field Attributes XFA(varlist[,ERR=stmtref])
Where =
varlist List of variables in the string template.
Returns: Extended field-attribute information re: string template
Description:

The XFA( ) function returns extended field attribute information stored in a string template:
Format: Returns:
XFA(var," ") A list of variables.
XFA(var,"fieldname") Description of the field
XFA(var,"fieldname","userfield") User-defined portion of the field
Dont Do This:
0120 DIM CST$:IOL=0130 REM does NOT create a valid string template for XFA( )
0130 IOL=NAME$,ADDR$,CITY$,ZIP$ REM valid IOL for the composite string above
0140 REM But XFA(string above) generates Error #26: Variable type invalid
0150 REM
Instead, Apply This Example:

0170 REM XFA( )is for use with other Business Basics string template formats
0180 LET J$="B JONES",K$="23 SOME ST.",L$="MYCITY",M=78923
0190 DIM CST$:"NAME:C(20*),ADDR:C(30*),CITY:C(20*),ZIP:N(10*):type=cur"
0200 LET CST.NAME$=J$
0210 LET CST.CITY$=K$
0220 LET CST.ADDR$=L$
0230 LET CST.ZIP=M
0240 REM
0250 PRINT XFA(CST$,"")
0260 PRINT XFA(CST$,"NAME")
0270 PRINT XFA(CST$,"ZIP","type")
-:END
-:RUN
NAME
ADDR
CITY
ZIP
cur

-> HTA(XFA(CST$,"NAME"))
01C00A0001000100000014
The hex string of the XFA( ) function in the previous example reports the following information about the
string template field attributes.
Bytes Information Returned:

1,1 Code 1-8 for field type
2,1 Flag bit
3,1 Field terminator
4,2 Size of repeating field or $0001$ if not repeating
6,2 Field number, based on linefeeds.
8,2 Field offset if prior field is variable length
10,2 Field length
12, User defined attributes
(See the reference manuals of other Business Basics for more information.)

XOR( ) Exclusive 'OR' Strings
Function XOR( )
Format:
Exclusive OR Comparison XOR(string$,compare$[,ERR=stmtref])
Where =
string$ Initial string value. String expression.
compare$ String value to compare in an Exclusive OR with the initial string value. Its length
must match that of the initial string. String expression.
Returns: Result of exclusive logical OR comparison of 2 equal-length strings
Description:
The XOR( ) function performs a bit-wise Exclusive OR comparison of two strings. It returns the string
generated as a result of the exclusive logical OR. The length of the comparison string must equal the
length of the initial string or ProvideX returns an Error #26: Variable type invalid.
Binary Result
0 XOR 0 0
1 XOR 0 1
0 XOR 1 1
1 XOR 1 0
Sample Comparison Results:

XOR($41$,$42$) yields Hex 03, 00000011
XOR($41$,$25$) yields Hex 64, 01100100
XOR($5A$,$DD$) yields Hex 87, 10000111
Example:
0040 READ (1,END=1000)F$
0050 R$=XOR(F$(1,2),$2020$) ! Convert to lower case
0060 ...

Mnemonics
Appendix: Mnemonics
Description:
Use mnemonics to control the output of information to both terminals and printers. This appendix includes
information on output sequences and an alphabetical listing of the standard mnemonics defined in
ProvideX for most terminals and printers.
NOTE: Mnemonics are specific to the channel on which they are defined and are only valid
while the channel remains OPEN. When the channel is CLOSEd, the mnemonics are
cleared.
Mnemonic Settings, Window / Region

When you send output to the screen, ProvideX remembers all graphics mnemonics until a 'CS' mnemonic
is performed or the window is destroyed. This enables Windows to repaint your window properly when
required (task switch ...).
Windows API: 3 Frame Styles

ProvideX has three Windows API frame styles available to it. The 'WINDOW' terminal mnemonic uses
WS_BORDER frame style, which is not popular with everyone. However, it has advantages: it maintains a
global menu and buttons and is always relative to the main window. A 'DIALOGUE' mnemonic, on the
other hand, uses WS_DLGFRAME, which is more popular, but requires absolute screen position and
doesn't allow global menus and buttons.
To change the look of the 'WINDOW' frame without losing 'WINDOW' functionality, you can use the
WS_THICKFRAME style. To do this, add OPT="Z" to the 'WINDOW' mnemonic:
PRINT 'WINDOW'(10,10,40,10,"Title",OPT="Z")
X,Y Coordinates
When you use graphics mnemonics (ARC, CIRCLE ...), the values for x,y and radius are logical screen
coordinates, not line and column coordinates. Use the functions @X(col) and @Y(line) to convert column
/ line values to screen coordinates (i.e. graphical units similar to pixels).
0110 LET RADIUS=(100)

0120 LET X=@X(45)! X=720 graphical units
0130 LET Y=@Y(20)! Y=600 graphical units
0140 PRINT @(45,15),'CIRCLE'(X,Y,RADIUS,1)
See also: @X( ) and @Y( ) Convert X/Y Coordinates, p. 11(f)
To Create Mnemonics
You can add new mnemonics by using the MNEMONIC directive to meet your specific requirements.


Output Sequences for Special Mnemonics
Output Sequences
Format:
Define Variable =ESC+"[\id_char{modifier}fmt_code"
Where =
\id_char Identifier for the variable. Include the backslash in the syntax. Valid identifiers
include:
\b Bottom margin of window/scroll region
\h Height of window/scroll region
\l (Lower case L). Left margin of window/scroll region
\r Right margin of window/scroll region
\t Top margin of window/scroll region
\w Width of window/scroll region
\A Current attributes in binary
\B Background colour index
\C Current column
\F Foreground colour index
\L Current line
modifier Optional modifier(s) of the variables value. If you include these operators, insert
them between the variable and the output format_code. You can include one or more
of the modifiers. The list below shows the valid modifiers and their associated
functions:
+ (Plus sign) Add the value of the next byte
- (Minus sign) Subtract the value of the byte
& (Ampersand) AND the value of the next byte
^ (Caret) XOR the value of the next byte
| (Pipe) OR the value of the next byte
fmt_code Mandatory output format_code following each variable. Valid format codes include:
2 Output is two byte ASCII
3 Output is three byte ASCII
a Output is ASCII plain text number (base 0)
b Output is single byte binary (base 0)
A Output is ASCII plain text number (base 1)
B Output is single-byte binary (base 0x20)
T Table output. Following T, the next byte must contain the number of
bytes in the table. The table must follow that in the output sequence. If
the number of bytes you use exceeds table length, no output is
generated.
Description:
Some mnemonics require variables to generate the specific output sequence (e.g. the line and column
number in the @@ mnemonic). Use the substitution and conversion format above to create your final
character sequences. That is, you must identify the variable using a leading \ (backslash) followed by the
one-character variable identifier and a format code. When you include such variables in your output
sequences you can also include a modifier (optional).

Mnemonics Categories
Graphic Terminal Terminal Terminal
Printer Terminal
Mnemonics, Mnemonics Mnemonics Mnemonics
Mnemonics Mnemonics
Terminals (contd.) (contd.) (contd.)
+S 'CR' '*H' 'DIALOGUE' 'LD' '-T'

-S DEFAULT '2D' 'DN' 'LF' '+T'
'ARC' and DF '3D' 'DO' 'LI' 'TEXTWDW'
BOX or BX 'EF' 'AB' 'DROP' and LPI 'TR'
CAPTION' 'EL' 'B?' 'WD' LS 'TW'
CIRCLE' 'EP' 'Bn' -E and +E 'LT' +U'
CPI 'FF' 'BACKGR' or 'BK' 'EB'* 'MAGENTA', -U
'CURSOR' 'LF' 'BB' 'EE' '_MAGENTA' 'UC'
DEFAULT 'LP' 'BE' 'EG' MAXSIZE 'UP'
and DF OFFSET 'BG' 'EI'* 'ME' '-V' and '+V' (4.20)
'FILL' 'RM' 'BI' 'EJ'* 'MINSIZE '-W' and '+W'
'FONT' 'Sn 'BJ' 'EL' 'MN'* 'WC'
'FRAME' 'SL' 'BLACK' and EM 'MODE' 'WHITE'* and
'IMAGE' 'SP' '_BLACK'* 'EO' 'MOVE' '_WHITE'
JC 'VT' 'BLUE' and 'ER'* 'NI' ''WINDOW and
JD '_BLUE' 'ES' '-P' WA
JL 'BM' 'ET' '+P' 'WM'
JR Special 'BO' 'EU'* 'POP' WR WP
'LINE' Attached 'BR' 'EW' 'PUSH' and 'WRAP' BW EW
LPI Printer 'BS' '-F' WC 'WS'
'MESSAGE' Mnemonics: 'BT'* '+F' 'RB' XP
'PEN' 'BU' 'Fn' 'RC' 'YELLOW' and
'PICTURE' 'PS' 'BW'* 'FF' 'RED' and '_YELLOW'
'PIE' 'PE' 'C0', 'C1', 'C2' 'FL' '_RED' ZX (4.20)
'POLYGON' 'CE' 'GE'* 'RL'
'RECTANGLE' 'CF' 'GF' 'RM'
SIZE 'CH' 'GOTO' and RP (4.20) Special
'TEXT' 'CI' 'WG' 'RS' Terminal
'CL' 'GREEN', 'RT' Mnemonics
CP '_GREEN' +S
CPI 'GS' -S '*C'
'CR' *H 'SB' '*I'
'CS' +I SC '*O'
'CURSOR' -I 'SCROLL' '*R'
'CYAN' and I2 SD *X
'_CYAN' 'IC' 'SF'* '@@'
'-D' 'IMAGE' 'SHOW' 'AT'
'+D' JD 'SIZE' 'GD'
'DC' JC SL 'WX'
DEFAULT and JR 'SN'*
DF JL SP
LB SR
'LC'* 'SX'
'SWAP'

Mnemonics List
Mnemonics List
Description:
The mnemonics defined in ProvideX are listed here. Theyre in ASCII sort order, except in three cases ( -
+ _ ): mnemonic keywords with an initial plus sign, minus sign or underscore are in the listing under their
second character. (For example, youll find _BLUE under "B" with BLUE and +S / -S under "S".)
NOTE: An asterisk beside a mnemonic indicates a default setting, as in 'BLACK'*. Inside

the apostrophes, an asterisk is part of the syntax, as in *C ("Star-C").
*C Automatic: Output on CLOSE

Mnemonic (Special) For Terminals
Sent Automatically on CLOSE *C
Description:
ProvideX sends the *C ("Star-C") mnemonic to the file automatically when a CLOSE is executed.
NOTE: For *WINDEV* devices, because the WINDOWS Spooler will automatically reset the
printer when closed, the '*C' mnemonic is ignored.
For additional information regarding the use of special terminal mnemonics (e.g., '@@', '*C', '*I', '*O',
'*R', *X, 'AT', 'GD', 'WX') when you create a terminal device driver, see the Users Guide on Device
Drivers. See also Output Sequences for Special Mnemonics, p. 487.
'*H' Control Screen Colours

Mnemonic For Terminals
Control Screen Colours '*H' =colour$
Where =
colour$ Numeric colour code. Characters 1 to 7:
1: Background colour for highlighting *[...] searches
0-7 in ASCII for standard background colours
8-? in ASCII for bright/Foreground colours
"R" if highlight is to use Reverse Video
2: Colour for Variables
3: Colour for Literals
4: Colour for Remarks
5: Colour for Error Lines
6: Colour for Mnemonics
7: Colour for Statement #s or Labels
For characters 2-7 the colour codes are 0-7 for standard foreground colours and 8-?
for the dim / background colours. The command mode scanning feature uses
Highlight=Yellow.
Description:
Use '*H' ("Star-H") to determine screen colours for LISTings and LST( ) functions.

Example:
MNEMONIC '*H'=";4:>1=;9"
*I Input Conversion Table

Input Conversion Table *I=table$
Description:
When you use *I ("Star-i"), you can create a 256-character terminal input conversion table. As
characters are received from the terminal, the values in this table are used to replace the data received by
the program.
For additional information regarding the use of special terminal mnemonics (e.g.,
'@@','*C','*I','*O','*R',*X,'AT','GD','WX') when you create a terminal device driver, see the Users Guide
on Device Drivers. See also Output Sequences for Special Mnemonics, p. 487.
*O Output Conversion Table

Output Conversion Table *O=table$
Description:
When you use *O ("Star-o"), you can create a 256-character terminal output conversion table. As
characters are sent from the program to the terminal, the values in this table are used to replace the data
sent by the program.
*R O/S Command String

Command String *R=command$
Description:
When you use *R ("Star-R") you can send an operating system command string to be executed when the
file is CLOSEd by the program.
*X Program to Call on CLOSE

Program to Call MNEMONIC (chan)*X="prog_name[;entry][;params]"
Where =
chan Logical file number or channel.
prog_name$ Name of the program. String expression.

Where =
entry Name of starting statement label to use as entrypoint in the program. Optional. If
included, add to the prog_name string expression (e.g. RUN
"PROG;STARTING_LABEL").
params Parameters (if any) needed in your called program. If you include a list, its comma-
separated.
Description:
Use *X ("Star-X") with your MNEMONIC directive to designate a program to CALL on the closing of a
channel (Ver. 4.10). ProvideX actually CALLs the program after physically closing the channel but before
channel information (such as mnemonics) is cleared.
NOTE: LFA (or LFO) returns the file value, but the file has been physically closed (so dont
try to READ or WRITE to it). However, its structures are intact so you can look at your
OPT( ), PTH( ), MNM( ) ... values.
Example:
If you need parameters, include them after the label name as in the example below:
-:LOAD "TSTX"
-:LIST
0010 LBL:
0020 MSGBOX "HELLO--"+SEP+"FIL="+STR(LFA)+SEP+"MNM="+MNM(*X,LFA)
0030 END
-:OPEN (1)"\JUNK.TXT"
-:MNEMONIC (1)*X="TSTX;LBL;My backspace key is orange"
-:CLOSE (1)
'2D' Use 2D Controls

Use 2D Controls '2D'
Description:
Use 2D (two-dimensional controls) to disable '3D' controls.
'3D' Use 3D Controls

Use 3D controls '3D'
Description:
To initiate 3D controls, you must use the 3D System Parameter with the 3D mnemonic.
Example:
To initiate 3D controls, you would use:

0010 PRINT '3D',; SET_PARAM '3D'
@@ Define Cursor_Position Sequence

Define Sequence @@=esc_seq$
Where =
esc_seq$ ESC+ "[ and a string expression defining the cursor position coordinates, using the
format:
\id_char{modifier | ;}format_code
For example, @@=ESC+"[\LA;\CAH". See also Output Sequences for Special
Mnemonics, p. 487.
Description:
Use @@ to define cursor position sequence.
on Device Drivers.
'AB' Abort (For Windows Spooler)

Mnemonic For Printers / Terminals
Abort for WINDOWS Spooler 'AB'
Description:
For WINDOWS Spooler Only. Use 'AB' to abort output to the WINDOWS print spooler. See also
Examples: *WINPRT* / *WINDEV* Printing, p. 602.
Example:
print (30)ab
ARC Define / Draw ARC

Mnemonic For Graphics Mode, Terminals
Define Arc ARC(x,y,radius,aspect,angle_1,angle_2)
Where =
x,y Coordinates for the centre of the drawing, in graphical units. Numeric expression.
radius Radius of the circle, in graphical units. Numeric expression.
aspect Aspect ratio / viewpoint. (Ratio=1 results in no tilt.) Numeric expression.
angle_1 Starting angle, in degrees. Numeric expression.
angle_2 Ending angle, in degrees. Numeric expression.
Description:
Use ARC to draw (print) an arc on the device. Use graphical units or @X(col) and @Y(line) functions for
x,y and radius. The ARC will extend from the starting angle1 to angle2. The ARC mnemonic uses the
current 'PEN' attributes.

Example:
The example below draws two different-coloured arcs. Aspect ratio=3 tilts the resulting drawing into an
elliptical "shape". (Since this ellipsis is really two arcs as opposed to an enclosed shape, FILL attributes
dont apply.) Aspect ratio=1 would join the arcs in a circular shape instead.
0060 PRINT 'PEN'(1,3,1)
0070 PRINT 'ARC'(800,250,75,3,1,75)
0080 PRINT 'PEN'(1,3,6)
0090 PRINT 'ARC'(800,250,75,3,75,1)
AT Character_Attribute Output Sequence

Attribute Sequence AT=out_seq$
Description:
Use AT to define a character attribute output sequence. See also Output Sequences for Special
Mnemonics, p. 487.
on Device Drivers.
'B?' Light Gray Background

Light Gray Background 'B?'
Description:
Use 'B?' to set the background colour to light gray for the text region when your directive sends output to
the terminal (as in PRINT, INPUT, etc.).
Example:
In this example, the prompt and users name will both be on a gray background. The rest of the screen
displays your current default background colour.
0010 INPUT 'B?','WHITE',"Please enter your name: ",NAME$,
'Bn' Background Colour by Number

Background Colour Number 'Bn'
Where =
n Numeric colour code. Valid options include:
0 - Black* 4 - Blue
1 - Red 5 - Magenta
2 - Green 6 - Cyan
3 - Yellow 7 - White
Description:
Use the format above to define the background colour for the text region when your directive sends output
to the terminal (as in PRINT, INPUT, etc.).

Example:
In this example, the prompt and users response will both be in white text on a blue background.
0010 INPUT 'B4','WHITE',"Please enter your name: ",NAME$,
'BACKGR' Next Colour Is Background

Choice, Long or Short Form:
Next Colour Is Background 'BACKGR' or BK
Description:
You can use either BACKGR or BK to designate that the next colour mnemonic (e.g. BLUE) is the
background colour for the text region when your directive sends output to the terminal (as in PRINT,
INPUT, etc.).
Example:
0020 PRINT 'BK','BLUE','WHITE',"Hello, ",USER_ID$,
'BB' DOS: Begin Blinking

Mnemonic (In DOS) For Terminals
Begin Blinking 'BB'
Description:
For DOS Terminals. Use 'BB' to begin blinking the characters sent to the terminal. Use an 'EB' mnemonic
to end blinking mode.
'BE' Begin Echoing

Begin Echoing 'BE'
Description:
Use BE to begin echoing characters entered from the keyboard in response to an INPUT (or READ,
FIND, ...) directive. Echoing is ON by default for channel 0 (zero, the main terminal). For other channels,
echoing is OFF by default. Use 'EE' to end echoing.
'BG' Begin Generating Error #29

Begin Generating Error #29 'BG'
Description:
Use 'BG' to begin generating Error #29: Invalid Mnemonic or position specification
whenever an invalid mnemonic is executed. Use EG to end generation of Error #29.
'BI' Begin Input_Transparency

Begin Input Transparency 'BI'

Description:
Use 'BI' to begin input transparency mode. (All input is accepted without any system interpretation of
control codes. With BI activated, a SIZ= option on an INPUT directive is the only way you can specify a
terminator / end of input.) Use 'EI' to end input transparency mode.
Example:
We recommend that you use 'ME' Begin Edit_Mode, p. 518(m)when you need to return input one
character at a time. However, it is also possible to use 'BI' in combination with SIZ=1 to return input one
character at a time. Then, each character is returned as entered. Standard characters are returned in the
variable you specify (e.g. CHAR$, below). Function and edit keys are returned in the system variable CTL.
Your program will still be responsible for processing all the edit keys.
0010 INPUT (0,SIZ=1) 'BI', CHAR$, 'EI' ! This will echo the data
0010 OBTAIN (0,SIZ=1) 'BI', CHAR$, 'EI' ! This will not echo
'BJ' Join BOX Intersections

Begin Joining Boxes 'BJ'
Description:
Use 'BJ' to begin joining BOX intersections. After you use this mnemonic, all BOX edge lines which
intersect existing graphic line characters will be adjusted to join the intersecting lines properly. Use EJ to
end box joining.
Example:
0030 PRINT 'BOX'(4,6,16,10,"Box 1",'BJ')
0040 PRINT 'BOX'(19,6,10,10,"Box 2")
0050 PRINT 'EJ'
BK (see BACKGR)
See 'BACKGR' Next Colour Is Background, p. 494(m)
'BLACK' and _BLACK Text Foreground /_Background

Mnemonics For Terminals
1 Output_Text Foreground= 'BLACK'
2 Output_Text Background= '_BLACK'
Description:
When your directive sends text as output to the screen (as in PRINT, INPUT, etc.), these mnemonics set
BLACK as the display colour for that text and/or its background.
Example:
INPUT '_CYAN','BLACK',"Please enter your name: ",Name$,
'BLUE' and _BLUE Text Foreground /_Background

1 Output_Text Foreground= 'BLUE'
2 Output_Text Background= '_BLUE'

Description:
BLUE as the display colour for that text and/or its background.
Example:
INPUT '_BLUE','WHITE',"Please enter your name: ",Name$,
'BM' Begin Output of Markup Files

Begin Output of Markup Files 'BM'
Description:
Use 'BM' to begin output of markup files containing embedded mnemonics. For instance, in the ProvideX
*VIEWER*, BM sends all data directly to the print file without interpretation (in tokenized format including
mnemonics). This allows you to send print jobs to any WINDOWS printer. Use EM to end markup.
'BO' Begin Output_Transparency

Begin Output Transparency 'BO'
Description:
Use 'BO' to begin output transparency mode. (All printed output is sent directly to the terminal without
checking for embedded mnemonics, i.e. $1B$ (Esc) followed by the mnemonic code.) Use EO to end
output transparency mode.
'BOX' Define / Draw a Box

Choice, Long or Short Form: BOX or BX
1 Define a Box 'BOX'(col,line,width,height[,title$[,attrib$]])
Where =
@(col,line, Position / coordinates. Numeric expressions. Column and line for the top left corner.
width,height) Width in number of columns, height in number of lines.
title$ Optional BOX title. String expression.
attrib$ Attributes. Optional. If you include attributes, use a string of one or more mnemonics.
Description:
You can use either 'BOX' or 'BX' in the format to draw a BOX. If you include a title, its displayed, left-
justified, on the top line of the box unless the AH system parameter is set. If you include attributes, these
are sent to the terminal before the BOX is displayed.
See also: 'AH' Alternative WINDOW / BOX Heading, p. 538(p)
Example:
The BOXes in the example are drawn (printed) joined and have titles. Your current FILL and PEN
settings are ignored when you use BOX:
0020 PRINT 'PEN'(2,3,6),'FILL'(3,8)
0030 PRINT 'BOX'(4,6,16,10,"Box 1",'BJ')

0040 PRINT 'BX'(19,6,10,10,"Box 2")
0050 PRINT 'EJ'
'BR' Begin Reverse_Video

Begin Reverse Video 'BR'
Description:
Use 'BR' to begin sending characters to the terminal in reverse video mode. Use an 'ER' mnemonic to end
reverse video mode. (When you have colour attributes, ProvideX uses the background colour as the
foreground colour and vice-versa.) Use ER to end reverse video mode.
'BS' Cursor Back One Space

Cursor Back One Space 'BS'
Description:
Use BS to move the cursor back one position to the left. ProvideX ignores this mnemonic if the cursor is
in column 0 (zero).
BT * Begin Type_Ahead
Begin Type-Ahead Mode 'BT'
Description:
Default. Use 'BT' to begin type-ahead mode. This mode lets the user enter input before the execution of
an INPUT statement. ProvideX supplies an internal buffer for the characters entered. Use ET to end
type-ahead mode.
See also: CI Clear Type_Ahead Buffer, p. 499(m)
'BU' Begin Underscoring

Begin Underscoring 'BU'
Description:
Use BU to begin underscoring of characters sent to the terminal. Use 'EU' to end underscoring.
'BW' * (see WRAP)

Begin WrapAround. See WRAP WrapAround ON/OFF, p. 535(m)

'BX' (see BOX)
See 'BOX' Define / Draw a Box, p. 496(m)
'C0', 'C1', 'C2' Control Cursor Display_Mode

1 Hide Cursor C0
2 Display Normal Cursor C1
3 Use INSERT Mode Cursor C2
Description:
Use Cn (where n = 0 (zero), 1 or 2) to control how the cursor is displayed.
'CAPTION' Replace Caption for Window

Change Caption 'CAPTION'(text$)
Where =
text$ Replacement caption. String expression.
Description:
Use your CAPTION(text$) to change the caption for the current window. If the current window does not
have a caption, ProvideX replaces the caption on the main window. (Graphics display only.)
To find out the caption for the current window you can use a MULTI_LINE READ directive with CTL=0, as
in MULTI_LINE READ 0,A$.
'CE' Clear Screen from Cursor to End

Clear From Cursor to End CE
Description:
Use CE to clear your screen from the cursor position to the end of the screen.
'CF' Clear Foreground Mode

Clear Foreground Mode 'CF'
Description:
Use CF to clear SF mode (high-intensity Foreground mode) for characters on the screen.
'CH' Cursor Position at Home

Position Cursor at Home 'CH'

Description:
Use CH to position the cursor at home, i.e. @(0,0). The screen is not cleared.
CI Clear Type_Ahead Buffer

Clear Type-Ahead Buffer CI
Description:
Use CI to clear the users input from the type-ahead buffer. See also BT * Begin Type_Ahead, p.
497(m).
CIRCLE Define / Draw CIRCLE

Define Circle 'CIRCLE' (x,y,radius,aspect)
Where =
x,y Coordinates for the centre of the circle, in graphical units. Numeric expression.
radius Radius of the circle, in graphical units. Numeric expression.
Description:
Use CIRCLE to draw (print) a circle on the device. Use graphical units or @X(col) and @Y(line) functions
for x,y and radius. The CIRCLE mnemonic uses your current 'PEN' and FILL attributes.
Example:
0170 PRINT 'PEN'(1,3,1),'FILL'(2,6)
0180 PRINT 'CIRCLE'(720,600,100,1)
0190 PRINT 'PEN'(1,3,6),'CIRCLE'(950,600,100,2)
'CL' Clear Line from Cursor to End

Clear from Cursor to Line-EndCL
Description:
Use CL to clear the current line from the cursor position to the end of the line.
CP Condensed Print for Screen

Condense Print CP
Description:
Only on terminals which support this. Use CP to reduce your window or region and font to condensed
print. To restore the screen and font to regular size, use 'SP' Standard Print, p. 529(m).
In ProvideX, a 'CP' or 'SP' mnemonic affects only the data that follows the mnemonic.

Example:
10 open(1)"LP"
20 print (1)"NORMAL"+'cp'+"COMPRESSED"+'SP'+"NORMAL"
30 close(1)
If the example above were run in ProvideX, the word COMPRESSED would be in condensed print and the
word NORMAL would be in standard print. (In some other Business Basics, the font for the complete line
is affected and for this example, would be in standard print.)
CPI Logical Characters / Inch

Mnemonic For Graphics Mode, Printers
Logical Characters/Inch 'CPI'(chars)
Where =
chars Logical characters per inch. Numeric expression.
Description:
Use CPI to set the logical CPI (characters per inch) for printing in graphics mode. As a rough guide to
equivalent sizes:
Point size -12 = 6 LPI, 10 CPI
Point size -10 = 7.2 LPI, 12 CPI
Point size - 7 = 10 LPI, 16 CPI
See also: LPI Logical Lines / Inch, p. 516(m)
TXH( ) Text Height, p. 440(f)
TXW( ) Text Width, p. 442(f)
Example:
With both channels (30) and (1) OPEN:
0060 PRINT (30)'CPI'(120/7.5),LPI(6),Data$
0070 PRINT (1)'CPI'(16),Data$
'CR' Carriage Return

Return to Column 0 'CR'
Description:
Use CR to return to column 0 (i.e. Carriage Return without line feed).
'CS' Clear Screen

Clear Screen 'CS'
Description:
Use CS to clear the screen and set the cursor position @(0,0).
As alternatives, you can use CH (Cursor Home without clear screen) and FF (Form Feed, alternative to
clear screen for print data).

'CURSOR' Control Cursor, Define Mouse Pointer
1 Cursor ON (Default) 'CURSOR'("ON")
2 Disable Cursor 'CURSOR'("OFF")
3 Cursor in Replace Mode 'CURSOR'("REP")*

4 Cursor in Insert Mode 'CURSOR'("INS")
5 Change Mouse Pointer 'CURSOR'(num)
Where =
num Numeric code for graphic to use as mouse pointer. (Graphics display only.) Valid
codes include:
0 - Arrow 6 - Hand in crossed circle ("No" hand)
1 - Wait (Hourglass) 7 - Rabbit in hat
2 - I-Beam 8 - Happy face
3 - Movement arrows 9 - Sad face
4 - Sizing arrow 10 - Resize vertical Up/Down arrow (Ver. 4.20)
5 - Hand 11 - Resize horizontal Left/Right arrow (Ver. 4.20)
12 - Not allowed (diagonal line across circle,
Ver. 4.20)
Description:
Use the CURSOR formats above to control cursor and mouse pointer displays.
Note that you can control cursor format during input as long as your INPUT, OBTAIN or READ RECORD
statement meets the following criteria:
the input directive does not cause echoing
the statement has an input limit of 1 character (SIZ=1)
'ME' Begin Edit_Mode, p. 518(m) is not active
for INPUT Get Input from Terminal, p. 192(d) when 'BI' Begin Input_Transparency, p.
494(m) is set
'CYAN' and _CYAN Text Foreground /_Background

1 Output_Text Foreground= 'CYAN'
2 Output_Text Background= '_CYAN'
Description:
CYAN as the display colour for that text and/or its background.
Example:
INPUT '_CYAN','WHITE',"Please enter your name: ",Name$

'+D' and '-D' Disabled Object: Gray_Out ON/OFF
For Disabled Objects:
1 Dim / Gray Out +D
2 Dont Gray Out -D
Description:
Use +D and -D to control whether or not disabled objects are dimmed (i.e. grayed out).
'DC' Delete Character at Cursor

Delete Character at Cursor DC
Description:
Use DC to delete the character at the current cursor position. (Text shifts one position to the left for all
characters to the right of the cursor on the same line.)
'DEFAULT' Define Mnemonic as Default

Mnemonic For Graphics Mode, Printers / Terminals
Choice, Long or Short Form: 'DEFAULT or DF
1 Define Mnemonic as Default [(chan)]mn_name$(settings),DEFAULT
Where =
mn_name$ Mnemonic keyword (a mnemonic string, e.g. FONT in FONT("Arial")).
settings Valid attributes and options for your given mnemonic (if any).
Description:
Use either DEFAULT or DF in the format to define a mnemonic as the default for an OPEN channel. You
can, for instance, set a default for font, reverse video, blinking, underscore, foreground / background, etc.
Example:
To set a variable pitch font in *WINPRT* printing as the standard default font for an OPEN channel:
0010 OPEN (30)"*WINPRT;ASIS"
0020 PRINT (30)'FONT'("Arial",-7),'DF'
DF (see DEFAULT)
See 'DEFAULT' Define Mnemonic as Default, p. 502(m).
'DIALOGUE' Define / Draw DIALOGUE Region

Define Region 'DIALOGUE' (col,line,width,height[,wdw_id],[title${,attrib$}]

Where =
wdw_id Your DIALOGUE windows unique ID_number. Numeric expression.
title$ Optional title. String expression.
attrib$ Attribute string. Valid options include:
* Creates a resizeable window with automatic scrollbars for text plane. For
example:
PRINT DIALOGUE(1,1,60,20,"Title",OPT="*"),
- Window has a Minimize button
? Window supports Win95 Help button
^ Window is always on top. For DIALOGUE only (not applicable to the
WINDOW mnemonic). For example:
PRINT DIALOGUE(1,2,30,3,"My Top Dog",OPT="^")
c Window is a child of the current window
C Disables {X} close button on title bar of window and eliminates the system
control menu from the title bar.
h Window has no title bar
m Enables the "maximize" box in top right corner of window (only for
dialogue windows created with OPT="*")
M Window has a menu bar
s Dialogue( ) returns a CTL to signal when the dialogue view state is
changed (Ver. 4.nn):
CTL=-1106 when the dialogue is minimized
CTL=-1107 when the dialogue is restored to normal state
CTL=-1105 when the dialogue is maximized.
(Note that CTL=-1105 is also returned for Z option (below) if dialogue has
been resized.)
S Window has a private Status line / Message Bar
x Disables {X} close button on title bar of window and eliminates the system
control menu from the title bar.
X Enables {X} close button on title bar of window and supports the system
control menu on the title bar.
Z Creates a resizeable window. When the user resizes the window a CTL
=-1105 is generated.
Description:
Use DIALOGUE to define a new window which is not contained in the main ProvideX screen. In a non-
WINDOWS environment this does the same as a WINDOW OPT="string_of_characters" mnemonic.
TIP: The DIALOGUE mnemonic with OPT=^ can be useful for error message windows.
Although your users can still perform other operations, the error message will be
Always on Top as a constant reminder to deal with the error.
ProvideX uses the WS_DLGFRAME frame style from the WINDOWS API for the 'DIALOGUE' mnemonic.
See also: Windows API: 3 Frame Styles, p. 486.
Example:
The example below creates a dynamic, resizable / scrollable picture viewer using a DIALOGUE window
which is large enough to display the complete picture. A 'SIZE' mnemonic fits the window to the screen.
The user is supplied with scroll bars to view the desired image.
0010 CALL "*picture;Get_size","c:\windows\clouds.bmp",WD,HI
0020 LET WD=INT(WD),HI=INT(HI)
0030 PRINT 'DIALOGUE'(10,10,WD,HI,"MY Photo",OPT="*-m"),

: 'SIZE'(30,10),'B?','SR','CS',
(Note that ProvideX normally redraws the TEXT plane below the picture. Line 0040, below,
suppresses the TEXT plane to avoid flicker.)
0040 PRINT '-T',
0050 PRINT 'PICTURE'(0,0,@X(WD),@Y(HI),"C:\windows\clouds.bmp"),
0060 OBTAIN 'C0',*; IF CTL<>4 THEN GOTO *SAME
'DN' Move Cursor Down a Line

Move Down DN
Description:
Use DN to move the cursor down a line.
'DO' Delete Objects in Scroll Region

Delete Object DO
Description:
Use DO to delete all objects that start (top left corner) in the current scroll region.
'DROP' Drop Identified Window

Choice, Long or Short Form: 'DROP' or WD
1 Drop Window DROP(wdw_id)
Where =
wdw_id Your windows unique ID number. Numeric expression.
Description:
Use either DROP or WD in the format to drop the identified window. If this window does not exist or is
the only window, ProvideX returns an Error #57: No such window defined. If wdw_id=-1, all
windows except the primary window are dropped.
Example:
30400 LET WW_ADD=HWN(0)
30410 PRINT %W_MSG$,WINDOW(20,8,40,8,WW_ADD,"Deleting Sku"
30410:),CS,SB,
30420 LET DEL_SKU$=FROM_SKU$,SAVE_KEY$=COMP$+FORM$
30430 !
30440 LET ADD_SKU$=TO_SKU$
30460 GOSUB DELETE_ITEM
30470 READ (E855FENT_H,KEY=SAVE_KEY$)IOL=0310
30480 PRINT WG(W_ADD),WD(WW_ADD),%NORM_SCR$,

+E and -E Multi_Line: <Enter> as <Tab>
For Multilines:
1 Allow <Enter>=<Tab> +E
2 Disable <Enter>=<Tab> -E
Description:
Use +E and -E to control the use of the <Enter> key to <Tab> in MULTI_LINEs.
EB * DOS: End Blinking_Mode

Mnemonic (In DOS) For Terminals
End Blinking Mode EB
Description:
For DOS Terminals. Default. Use 'EB' to end blinking of characters sent to the terminal. This is the
opposite of 'BB'.
'EE' End Echo_Mode

End Echo EE
Description:
Use 'EE to end echoing of characters sent to the terminal. This is the opposite of 'BE'.
'EF' End Expanded_Print

Mnemonic For Printers
End Expanded Print 'EF'
Description:
Use 'EF' to finish expanded print mode. This is the opposite of 'EP'.
'EG' End Generation of Error #29

Stop Generation of Error #29 'EG'
Description:
Use 'EG' to stop generation of Error #29: Invalid Mnemonic or position specification
whenever an invalid mnemonic is executed. This is the opposite of BG.
See also: 'EG' End Generation of Error #29, p. 542(p)
EI * End Input_Transparency
End Input Transparency EI

Description:
Default. Use EI to end input transparency mode. This is the opposite of 'BI'.
EJ * End BOX_Joining
End BOX Joining EJ
Description:
Default. Use EJ to end automatic joining of box intersections for BOX mnemonic drawings. This is the
opposite of 'BJ'.
Example:
0030 PRINT 'BOX'(4,6,16,10,"Box 1",'BJ')
0040 PRINT 'BOX'(19,6,10,10,"Box 2")
0050 PRINT 'EJ'
'EL' Start Edit_Key Load

Start Edit Key Load EL
Description:
Use EL to start loading Edit keys. This is the opposite of SL.
This feature is only included for compatibility with other languages. See the Installation Guide regarding
conversion and compatibility modes for additional information on this mnemonic. See also DEFCTL
Define/Redefine CTL Values, p. 75(d) during conversions.
MAS90 and ProvideX Utilities:

Because MAS90 changes the values of the function keys, some of the standard ProvideX utilities do not
work unless you PRINT 'FL',"1",'EL',"1" just prior to running any of the ProvideX utilities. When
you are done and RUN "MAS90", it will reset the function keys to the required settings.
EM End Output_Markup
End Output Markup Mode EM
Description:
Use EM to end output of markup files containing embedded mnemonics. This is the opposite of 'BM'.
EO * End Output_Transparency
End Output Transparency 'EO'
Description:
Default. Use EO to end output transparency mode. This is the opposite of 'BO'. If you want to send
<Esc>EO as a mnemonic, you must use it as a stand-alone mnemonic, e.g., PRINT 'BO'+X$,'EO'.
If you want to send <Esc>EO as part of your data, embed it in an expression (e.g. PRINT
'BO'+X$+'EO') instead of using it as a stand-alone. Then, ProvideX evaluates EO as an embedded
<Esc>EO and sends it without interpretation to the device / printer.

'EP' Start Expanded_Print
Expanded Print 'EP'
Description:
Use 'EP' to begin expanded print (either double wide or double high depending on the type of printer). Use
'EF' to end expanded print.
ER * End Reverse_Video
End Reverse Video ER
Description:
Default. Use ER to end reverse video mode. This is the opposite of 'BR'.
'ES' Send ESC $1B$ to Device

Send ESC=$1B$ ES
Description:
Use ES to send the ASCII ESCape $1B$ to the device. This is normally used as a preamble to sending a
control sequence to the terminal.
'ET' End Type_Ahead

End Type-Ahead ET
Description:
Use ET to end type-ahead mode. This is the opposite of 'BT'. See also:BT * Begin Type_Ahead, p.
497(m).
EU * End Underscoring
End Underscoring EU
Description:
Default. Use EU to end the underscoring of characters. This is the opposite of 'BU'.
'EW' (see WRAP)

End Wraparound. See WRAP WrapAround ON/OFF, p. 535(m).

'+F' and -F Change_of_Focus: Signal ON/OFF
1 Signal Change of Focus +F
2 Dont Signal Change -F
Description:
Use +F and -F to control whether or not ProvideX signals a change of Focus. If you use +F, ProvideX
signals a change of Focus by issuing a CTL=1000.
'Fn' Foreground Colour by Number

Foreground Colour by Number 'Fn'
Where =
n Numeric code. Default=7, White. Valid options include:
0 - Black* 4 - Blue
1 - Red 5 - Magenta
2 - Green 6 - Cyan
3 - Yellow 7 - White *
Description:
When your directive sends text as output to the terminal (as in PRINT, INPUT, etc.), you can use the format
above to define the foreground colour for that text.
Example:
In this example, the prompt and users response will be in white text (F7) on a blue background (B4).
0010 INPUT 'B4','F7',"Please enter your name: ",NAME$,
'FF' Form Feed

Form Feed FF
Description:
FF is normally used with printers (as a form feed to advance a page) but you can also use it as an
alternative to CS for clearing the screen (to allow programs intended for printer output to send data to a
terminal).
'FILL' Define FILL Style

Define FILL 'FILL' (pattern,colour)
Where =
pattern Numeric code for FILL pattern type. Valid codes are:
0 - No fill 4 - Crossed line
1- Solid fill 5 - Bottom left to top right
2 - Horizontal lines 6 - Top left to bottom right
3 - Vertical lines 7 - Diagonal crossed lines

Where =
colour Numeric code for FILL colour. Valid codes are:
0 - Black 8 - Dark gray
1 - Red 9 - Burgundy
2 - Green 10 - Dark green
3 - Yellow 11 - Gold
4 - Blue 12 - Navy blue
5 - Magenta 13 - Dark purple
6 - Cyan 14 - Dark cyan
7 - White 15 - Light gray
Description:
Use FILL to define the current fill pattern and colour for an OPEN channel. (Default is the terminal.)
Example:
0100 PRINT 'PEN'(1,3,1),'FILL'(2,6),'CIRCLE'(224,450,100)
'FL' Begin Function_Key Load

Start Function Key Load FL
Description:
You can use FL to start loading Function keys.
This feature is only included for compatibility with other languages. See the Installation Guide regarding
conversion and compatibility modes for additional information on this mnemonic. See also DEFCTL
Define/Redefine CTL Values, p. 75(d) during conversions.
MAS90 and ProvideX Utilities:

Because MAS90 changes the values of the function keys, some of the standard ProvideX utilities do not
work unless you PRINT 'FL',"1",'EL',"1" just prior to running any of the ProvideX utilities. When
you are done and RUN "MAS90", it will reset the function keys to the required settings.
'FONT' Define / List Fonts

1 Define Font 'FONT'(name$,size[,attrib$[,angle]])
2 List Channels Fonts FONT(LIST*[,chan])
3 List Fonts, Properties FONT(LIST PROPERTIES[,chan])
4 List Sizes for a Font 'FONT'(LIST name$)
Where =
name$ Font name. String expression. Font must exist in the system.
size Numeric. Use positive values for font sizes relative to the current default for the device
(e.g. .5 for half size, 2 for double, etc.). Use negative sizes for absolute font size in
points. As a rough guide to equivalent sizes:

Where =
attrib$ Font attributes. Optional string expression. Valid codes include:
& Underscore the character following the '&' (as in hot keys)
B Bold
C Center text
F Show focus lines around text
I Italics
N Numeric data alignment
R Right justify text
S Fills only text background (not whole region) with chosen colour
U Underscore (or "_")
W Word wrap
# Same as "N"
In addition, you can control character set. Default is ANSII character set 0.
! Use symbol character set (char. set 2)
O Use OEM character set (char. set 255)
J Use Japanese character set (char. set 128)
D Use character set 1 or current default for the given font
angle Slant for printing, in degrees. Optional.
Description:
FONT defines the current font and returns comma-delimited font and property (attribute) lists for the
channel (default=the terminal). It also returns a size list for a specific (existing) font.
Example:
f$="MS Serif"; ? 'FONT'(LIST F$) ! returns sizes for MS Serif font:
13,16,19,21,27,35,10,11,
0100 PRINT 'FONT'("MS Serif",-11)
NOTE: FONT works with *WINPRT* but not with character-mode printers. See *WINPRT*
Device File: Windows Printing, p. 596.
'FRAME' Define / Draw a FRAME

Define a Frame 'FRAME'(x,y,x,y,style[,title$])
Where =
x,y Placement coordinates, top left and bottom right, in graphical units. Numeric
expression.
style Determines the style level and bevel sizes in creating the frame. Numeric expression:
>0 FRAME is elevated button with bevel width=style value
<0 FRAME is inset with bevel width=style value
=0 FRAME appears etched.
title$ Frame title. Optional. String expression.
Description:
Use FRAME to draw (print) a frame on the screen. Use graphical units or @X(col) and @Y(line) functions
for beginning and ending the frame.

Example:
0010 PRINT 'FRAME'(100,100,450,450,10,"Hello There")
GD Define Graphics Character Set

Define Graphics Character Set GD
Description:
Use GD for graphics character set definition. See also Output Sequences for Special Mnemonics, p.
487.
on Device Drivers.
GE * End Graphics Data

End Graphics Data GE
Description:
Default. Use GE to end graphics data transmission. This is the opposite of GS.
'GF' Default Font for Window Objects

Default Font for Objects GF
Description:
Use GF to define the default graphic font for all objects to be created in the window.
'GOTO' Make Window Current

Choice, Long or Short Form: GOTO or WG
1 Make Window Current 'GOTO'(wdw_id)
Where =
wdw_id Your windows unique ID_number. Numeric expression.
Description:
Use either GOTO or WG in the format to make the identified window the current window and move it the
top of the window stack. ProvideX generates an Error #57: No such window defined if the
identified window does not exist.
Example:
30400 LET WW_ADD=HWN(0)
30410 PRINT %W_MSG$,WINDOW(20,8,40,8,WW_ADD,"Deleting Sku"
30410:),CS,SB,
30420 LET DEL_SKU$=FROM_SKU$,SAVE_KEY$=COMP$+FORM$

30430 !
30440 LET ADD_SKU$=TO_SKU$
30460 GOSUB DELETE_ITEM
30470 READ (E855FENT_H,KEY=SAVE_KEY$)IOL=0310
30480 PRINT WG(W_ADD),WD(WW_ADD),%NORM_SCR$,
'GREEN' and _GREEN Text Foreground /_Background

1 Output_Text Foreground= 'GREEN'
2 Output_Text Background= '_GREEN'
Description:
GREEN as the display colour for that text and/or its background.
Example:
INPUT '_GREEN','WHITE',"Please enter your name: ",Name$
'GS' Start Graphics Data Transmission

Begin Graphics Data GS
Description:
Use GS to start graphics data transmission. To end transmission of graphics data, use GE.
HIDE (see SHOW * / HIDE)

See 'SHOW' * / 'HIDE' Control Window Display, p. 528(m)
+I and -I Multi_Line: Implied Decimals ON/OFF

For Numeric Multilines:
1 Enable Implied Decimals +I
2 Disable Implied Decimals -I
Description:
Use PRINT +I during system startup to activate support for implied decimal points for ALL numeric
MULTI_LINEs. Use PRINT -I to cancel it. (For a single MULTI_LINE use OPT=i to suppress
implied decimal use.)
I2 Ignore Max. Record Count (No ERR 2)

Ignore Max. Record Count I2
Description:
Use I2 to have ProvideX ignore maximum record count (i.e. ignore Error #2: END-OF-FILE on

read or File full on write).
'IC' Insert a Space at Cursor

Insert Space IC
Description:
Use IC to insert a space at the current cursor position and shift all remaining characters on the line one
position to the right.
'IMAGE' Define a Graphics Group

1 Define Graphics Group IMAGE(group$)
2 Delete Graphics Group IMAGE(DELETE group$)
3 Enable/Disable Group IMAGE({ENABLE | DISABLE} group$)
4 Hide/Show Group IMAGE({HIDE | SHOW} group$)
Where =
group$ Your IMAGE groups name. String expression. If you omit the group$ name when
you define your group, the default group$ is "" (NULL).
Description:
ProvideX normally queues all mnemonics since the last CS (to supply information in case WINDOWS
needs to redraw the screen). In consequence, if you are constantly creating graphics, you can exhaust
system resources. The IMAGE mnemonic helps you to circumvent this potential problem.
When you use IMAGE to define and control the display of graphics groups, all graphics mnemonics
following the IMAGE mnemonic are grouped. You can DISABLE or HIDE the group to remove it from
view and ENABLE or SHOW the group to make it visible.
When you use the IMAGE(DELETE group) format to destroy your group, ProvideX returns the resources
to the system.
NOTE: Instead of drawing graphics on top of other graphics to 'erase', use the 'IMAGE'
mnemonic to group your mnemonics, then DISABLE or DELETE the group to remove
it.
Example:
Note that if you clip this example to RUN it, some of the line overflows will generate apparent syntax errors.
To clear the error messages so that you can RUN, just type LIST or use either slash before you run.
0010 ! Display 'image' groups
0020 PRINT 'CS'
0030 LET FACE$='PEN'(1,4,3)+'ARC'(800,200,105,1,1,360)
0040 LET NOSE$='PEN'(1,4,0)+'LINE'(800,205,800,235)
0050 LET LEFT_EYE$='PEN'(1,2,4)+'FILL'(1,0)+'CIRCLE'(765,170,20)
0060 LET RIGHT_EYE$='PEN'(1,1,0)+'FILL'(1,0)+'CIRCLE'(835,170,18,1)
0070 LET WINK$='PEN'(1,4,0)+'ARC'(765,170,20,1,165,15)+'FILL'(1,0)+'CIRCLE'(775
0070:,170,10)
0080 LET SMILE$='PEN'(1,3,0)+'ARC'(800,230,45,1,190,350)
0090 PRINT 'IMAGE'("HAPPY"),FACE$,NOSE$,SMILE$
0100 PRINT 'IMAGE'("WIDE_EYED"),LEFT_EYE$+RIGHT_EYE$; WAIT .5

0110 PRINT 'IMAGE'(DISABLE "WIDE_EYED")
0120 PRINT 'IMAGE'("WINK"),WINK$,RIGHT_EYE$; WAIT 1; PRINT 'IMAGE'(DELETE "WINK")
0130 PRINT 'IMAGE'(ENABLE "WIDE_EYED"); WAIT 1
0140 PRINT 'IMAGE'(DELETE "HAPPY"),'IMAGE'(DELETE "WIDE_EYED")
0150 PRINT @(0,12); LIST
0160 PRINT WINK$,RIGHT_EYE$,NOSE$,SMILE$; END
JC Justify Centre
Justify Centre JC
Description:
Use JC for center-justification in graphics printing.
JD Justify Decimal-Aligned
Justify Decimal-Aligned JD
Description:
Use JD for decimal alignment in graphics printing.
JL Disable JR for Numeric

Disable Numeric JR JL
Description:
Use JL (Justify Left) to disable forced right-justification of numeric values when printing with a
proportional font. See JD for decimal alignment and JR for right-justification.
JR Right-Justify Numeric
Right-Justify Numeric JR
Description:
Use JR to force right-justification of numeric values when printing with a proportional font. You can use
JD for decimal alignment and JL to disable forced right-justification.
LB LINE_Colour in Break Points

Line_Colour, Break Points LB(n)
Where =
n Numeric colour code. Default=4 (Blue). Valid colour options for line # in Break Points:
0 - Black 4 - Blue *
1 - Red, 5 - Magenta
2 - Green 6 - Cyan

Description:
Use LB to define colour for line # in Break Points.
LC * Mixed-Case User Input

Allow Mixed_Case LC
Description:
Default. Allow upper and lower case (i.e. mixed case) for user input. This is the opposite of 'UC'.
'LD' Delete Current Line

Delete Current Line LD
Description:
Delete the current line and shift all subsequent lines up one line.
'LF' Line Feed (Advances Line)

Line Feed 'LF'
Description:
Use 'LF' to advance one line and return to column 0.
'LI' Insert Line

Insert Line LI
Description:
Insert a blank line at the current position and push all subsequent lines down one. The bottom line on a full
screen will be lost.
'LINE' Define / Draw a LINE

Define a LINE 'LINE'(x,y,x,y[,x,y ...])
Where =
x,y Sets of x,y point / position coordinates, in graphical units. Numeric expression.
Description:
Use LINE to draw (print) a line on the device (e.g. terminal). Use graphical units or @X(col) and @Y(line)
functions for your various coordinates. The LINE mnemonic joins these using the current 'PEN' attributes.
Example:
0010 print 'line'(224,450,355,420,210,400)

'LP' * Line_Printer Mode
Line Printer Mode 'LP'
Description:
Default. Use 'LP to switch the printer from serial printer mode to line printer mode. In line printer mode,
output that overlays data on the print line replaces the data.
LPI Logical Lines / Inch

Logical Lines / Inch 'LPI'(lines)
Where =
lines Logical lines/rows per inch for graphics mode. Numeric expression.
Description:
Use LPI to set the logical LPI (lines per inch) value in graphics printing. As a rough guide to equivalent
sizes:
See also: CPI Logical Characters / Inch, p. 500(m)
TXH( ) Text Height, p. 440(f)
TXW( ) Text Width, p. 442(f)
Examples:
0060 PRINT (30)LPI(6),
0070 PRINT (1)'LPI'(76/10),
LS Line Colour for Syntax Error

Line Colour, Syntax Error LS
Where =
n Numeric colour code. Default = 1 (Red). Valid codes include:
0 - Black 4 - Blue
1 - Red* 5 - Magenta
2 - Green 6 - Cyan
Description:
Use LS to control the colour for Syntax Error displays.

'LT' Move Left One Column
Move Left LT
Description:
Use LT to move one column to the left.
Example:
0010 PRINT "OH_X",'LT',"Hello",'RT',"There"
-:RUN
OH_Hello There
'MAGENTA' and '_MAGENTA' Text Foreground/_Background

1 Output_Text Foreground= 'MAGENTA'
2 Output_Text Background= '_MAGENTA'
Description:
MAGENTA as the display colour for that text and/or its background.
Example:
INPUT '_MAGENTA','WHITE',"Please enter your name: ",Name$
MAXSIZE / MINSIZE User Limits on Window_Resizing

1 Users Maximum Setting MAXSIZE(width,height)
2 Users Minimum Setting MINSIZE(width,height)
Where =
width,height Size limits on the users permission to resize a window. Width in columns, height in
lines. Numeric expression.
NOTE: The values you use for MINSIZE must not exceed your values for
MAXSIZE. By default, MINSIZE is set to 0,0 and MAXSIZE is set
to the originally-defined window size. If you set MAXSIZE(0,0)
then the total defined window size is used.
Description:
Use MAXSIZE and MINSIZE to limit the maximum and minimum window sizes your users can set.
NOTE: These mnemonics only affect the window size that the user can set, not what the
program sets as the size. They have no effect on the 'SIZE' mnemonic.
Example:
In the example below, the user is limited to resizing the scrollable DIALOGUEs display area by reducing it
to a MINSIZE of 5 columns by 5 lines or increasing it a MAXSIZE of 40 columns by 15 lines:

0010 PRINT DIALOGUE(1,1,80,25,"Title",CS,OPT="Z")
0020 PRINT SIZE(30,10),
0030 PRINT MINSIZE(5,5),
0040 PRINT MAXSIZE(40,15),
'ME' Begin Edit_Mode

Begin Edit Mode ME
Description:
Use ME to begin edit mode. In edit mode, a value for input editing control keys which can't be executed
(e.g. up / down arrows) will be returned to your program in the CTL variable instead of being rejected. Use
MN to end edit mode. That is, when you use ME, ProvideX uses its built-in edit functions to format and
process all keyboard input, but terminates input and returns values to your program when it encounters
keystrokes the input editor doesnt handle
Example:
0010 INPUT "Enter Amount:", 'ME', AMNT:"$###,##0", 'MN'
'MESSAGE' Define MESSAGE Line

1 Define Message_Line Text 'MESSAGE'(text$)
2 Create Additional Segments 'MESSAGE'(DEF start_1[,start_2[,start_3]])
3 Reset MESSAGE Line 'MESSAGE'(DEF 0)
4 Define Location for Printing 'MESSAGE'(text$,segment)
Where =
text$ Text to display. String expression.
start_# Column number where optional additional segments begin. Default segment 0 is
@column 0. You can have up to 4 segments (0, 1, 2 and 3). Define optional segments
1, 2 and 3 by specifying their starting column number. Numeric expressions.
segment Segment # for display. Numeric expression. Valid range: 0 (zero) to 3.
Description:
Use MESSAGE to print text on the Message_Line at the bottom of the ProvideX window. The
Message_Line can have up to 4 segments, numbered 0 (zero), 1, 2 and 3.
When you can create optional Message_Line segments 1, 2 and 3, ProvideX places the segment
separator at the column number you specify in start_# for the corresponding segment(s). Reset to a single
segment (segment 0 at column 0) by DEFining segment 0 (zero).
You can send MESSAGES to segment 0 and to your DEFined segments by segment number. By default,
if you omit the segment number, your text is displayed in segment 0 (zero) starting at column 0 (zero).
NOTES: If you use a positive column number, the segments separator is offset that many
columns from the left of the Message_Line.
Use negative values to have the separators placement offset from the right instead.
If you want to centre text within a segment, use $09$ (a <Tab> character) as the first
character of the text to print.

Example:
0010 print 'message'(def 7,-20) ! create seg1 @(7), seg2 @(20 cols from right)
0020 print 'message'("") ! NULL displayed in segment 0
0030 print 'message'("hello",1),'message'("there",2)
0040 print "To reset the message bar PRINT 'message'(def 0)"
MESSAGE Bar Region Events (Ver. 4.20)

<Left-mouse-click> and <Right-mouse-click> events are now supported in the MESSAGE bar region.
ProvideX returns CTL values when the user clicks on a segment in the MESSAGE bar region (Ver. 4.20).
Each of the four possible segments of the MESSAGE bar region has been assigned a different negative
CTL value. The event is reported on the button UP only. The return values are shown in the chart below.
MESSAGE Region <Left-mouse-button-up> <Right-mouse-button-up>

1st area (segment zero) CTL= -1410 CTL= -1400
2nd area (segment 1) CTL= -1411 CTL= -1401
3rd area (segment 2) CTL= -1412 CTL= -1402
4th area (segment 3) CTL= -1413 CTL= -1403
'MINSIZE (see MAXSIZE / MINSIZE)

See MAXSIZE / MINSIZE User Limits on Window_Resizing, p. 517(m)
'MN' * End Edit_Mode

End Edit_Mode MN
Description:
Default. Use MN to end edit mode. This is the opposite of ME.
Example:
'MODE' Set Attributes and Colour

Set Attributes and Colour 'MODE' (attrib$)
Where =
attrib$ Attribute string. One-, two- or three-character string which MODE uses as follows:
1 character = the new attribute setting.
2 characters = the current foreground and background colour bytes.
3 characters = first byte for new attributes, followed by the colour bytes.

Description:
Use 'MODE' to set the current attributes and colour directly.
'MOVE' Relocate Current Window

Choice, Long or Short Form: 'MOVE' or WM
1 Move Current Window 'MOVE' (col,line)
Where =
col,line Starting coordinates (top left) of new location. Numeric expression, column and line.
Description:
Use either MOVE or WM in the format to relocate the current window to a new placement starting with
the top left corner at your col,line coordinates.
NI Validate: Next Input is Numeric

Next Input is Numeric NI
Description:
Use NI to indicate that the next input is to contain only numeric data ( 0-9, -, $, the comma and the
decimal point).
OFFSET Offset for *WINPRT*

Offset for *WINPRT* OFFSET
Description:
This is the OFFSET mnemonic for *winprt*. See WINPRT_SETUP Windows Printer Setup, p.
472(d).
'+P' and '-P' Mouse Movement: Define Signal

1 Signal Pixel-to-Pixel Change +P
2 Signal Line/Column Change -P
Description:
Use +P to transmit mouse movements on any change of position (pixel by pixel movement). Use -P to
transmit mouse movements only on a change of line / column.
'PE' Attached Printer: Disable Port

Mnemonic (Special) For Attached Printers
Disable Attached Printer Port 'PE'

Description:
PE disables the attached printer port on the terminal. The system automatically sends this mnemonic as
output after all data is sent to an attached printer.
'PEN' Define PEN Style

Mnemonic For Graphics Mode
1 Define PEN 'PEN'(style,width,colour)
Where =
style Numeric code for PEN style. Valid codes are:
0 - No pen 3 - Dotted
1 - Solid pen 4 - Dash-dot
2 - Dashed 5 - Dash-dot-dot
width PEN width, in graphical units. Numeric expression.
NOTE: PEN styles 2 (Dashed), 3 (Dotted), 4 (Dash-dot) and 5 (Dash-dot-

dot) only work if PEN width equals 1. PEN style 1 (Solid) is the
only style that works if PEN width is greater than 1. (This is an
internal WINDOWS API specification / restriction.)
colour Numeric code for PEN colour. Valid codes are:
0 - Black 8 - Dark gray
Description:
Use PEN to set the current pen style, width, and colour for graphics drawing.
Example:
0010 PRINT 'PEN'(1,10,6)
0020 PRINT 'LINE'(225,450,350,400)
'PICTURE' Define / Draw PICTURE

Define Picture 'PICTURE'(x,y,x,y,name$[,option])
List Embedded Pictures variable$='PICTURE'(*)
Where =
x,y,x,y Point / position coordinates for top left and bottom right, in graphical units. Numeric
expression.
name$ Name of your graphic (e.g. C:\your_PATH\your.BMP). String expression. As of Ver.
4.20, ProvideX supports {icon} images. Your icon filename must have .ico as an
extension.

Where =
option Numeric code, defines how the picture is drawn. Valid options include:
0=Align at top-left
1=Center/crop within region
2=Scale to fit
3=Tile bitmaps to fill the given area
variable$ String variable to receive the list of pictures embedded in ProvideX.
* (asterisk) To have ProvideX return a list of its embedded pictures. For example:
X$='PICTURE'(*)
PRINT X$
Description:
Use PICTURE to draw (print) a picture on the device (e.g. terminal). Your x,y,x,y coordinates define
placement and size (top left and bottom right corners). Use graphical units or @X(col) and @Y(line)
functions.
Example:
PRINT 'PICTURE'(100,100,600,600,"<C:\your_PATH\your.BMP>",2)
'PIE' Define / Draw PIE Slice

Define Pie Slice 'PIE'(x,y,radius,aspect,angle_1,angle_2)
Where =
x,y Coordinates for the centre of the pie, in graphical units. Numeric expression.
radius Radius of the pie, in graphical units. Numeric expression.
angle_1 Starting angle, in degrees. Numeric expression.
angle_2 Ending angle, in degrees. Numeric expression.
Description:
Use PIE to draw (print) a pie slice on the device (e.g. terminal). Use graphical units or @X(col) and
@Y(line) functions for x,y and radius. The PIE slice extends from starting angle 1 to angle 2. The PIE
mnemonic uses your current PEN and FILL attributes.
Example:
The example that follows displays a pie cut into two uneven PIE slices:
0030 PRINT 'PEN'(1,3,8),'FILL'(2,6)
0040 PRINT 'PIE'(224,450,100,1,45,1)
0050 PRINT 'PEN'(1,3,6),'FILL'(4,15)
0060 PRINT 'PIE'(260,440,100,1,1,45)
'POLYGON' Define / Draw POLYGON

Define Polygon 'POLYGON'(x,y,x,y,x,y,x,y ... )

Where =
x,y Set of point / position coordinates, in graphical units. Numeric expression.
Description:
Use POLYGON to draw (print) a polygon (e.g. triangle, hexagon ...). ProvideX joins your various x,y
points to form the polygon. Use graphical units or @X(col) and @Y(line) functions for your coordinates.
The POLYGON mnemonic uses your current 'PEN' and 'FILL' attributes.
Example:
The example below creates an irregular four-sided figure by setting the coordinates for the four corners.
0030 PRINT 'PEN'(1,3,8),'FILL'(2,6)
0040 PRINT 'POLYGON'(224,450,100,100,400,200,390,390)
'POP' Remove Current Window, Restore Previous

Restore Previous Window POP or WR
Description:
Use either POP or WR to remove the current window from the top of the stack and restore the previous
window.
'PS' Attached Printer: Enable Port

Mnemonic (Special) For Attached Printers
Enable Attached_Printer Port 'PS'
Description:
'PS' enables the attached printer port on the terminal. The system automatically sends this mnemonic as
output before all data is sent to an attached printer.
'PUSH' Save / Copy Current Window

Save / Copy Current Window PUSH or WC
Description:
Use either PUSH or WC to save and copy the current window to open a new window with exactly the
same size, position and attributes.
'RB' Ring Bell

Ring Bell RB

Description:
Use RB to ring the bell.
'RC' Return Cursor Address

Return Cursor Address RC
Description:
Use RC to return the current cursor address as a four-character string containing the current line and
column.
'RECTANGLE' Define / Draw 'RECTANGLE'

Define Rectangle 'RECTANGLE'(x,y,x,y)
Where =
x,y,x,y Point coordinates for top left and bottom right corners, in graphical units. Numeric
expression.
Description:
Use RECTANGLE to draw (print) a rectangle defined by your two sets of x,y coordinates. Use graphical
units or @X(col) and @Y(line) functions. The RECTANGLE mnemonic uses your current 'PEN' and
'FILL' attributes.
Example:
0030 PRINT 'PEN'(1,3,8),'FILL'(2,6)
0040 PRINT 'RECTANGLE'(100,100,400,600)
'RED' and _RED Text Foreground /_Background

1 Output_Text Foreground= 'RED'
2 Output_Text Background= '_RED'
Description:
RED as the display colour for that text and/or its background.
Example:
INPUT 'RED','_WHITE',"Please enter your name: ",Name$
'RL' Return Line Contents

Return Line Contents RL
Description:
Use RL to return the contents of the current line with the next terminal input.

NOTE: In graphics mode, if a terminal mnemonic transmits the contents of the screen to the
program, the data consists of four bytes for each character. The first two bytes are
the background and foreground characters, the third byte holds the character
attributes, and the fourth byte is the actual character on the screen.
Example:
0040 PRINT 'CS'
0050 PRINT @(5,5),DIM(10,"A")
0060 INPUT @(5,5),'RL',B$
0070 PRINT B$
When RUN:
AAAAAAAAAA
AAAAAAAAAA
'RM' Reset to Default Mode

Reset Mode RM
Description:
Use RM to reset to default attributes (colour, reverse video mode, underscoring mode, etc.). See also:
User's Guide 'RM' Reset Mode.
'RP' Terminal Read to End

Terminal Read to End RP
Description:
(Ver. 4.20) This mnemonic performs the same function as the TR (Terminal Read from Start) mnemonic,
except that it reports values from the current cursor location to the end of the screen.
(TR returns the screen contents from 0,0 to the current cursor location.)
'RS' Restore Screen

Restore Screen RS
Description:
Use RS to restore the complete terminal screen from the information in memory. This mnemonic can be
used to reset the screen after transmission errors or when operating system output has disrupted screen
contents.
'RT' Move Right One Column

Move Right RT
Description:
Use RT to move one column to the right.

Example:
0010 PRINT "Oh_x",'LT',"Hello",'RT',"There"
-:RUN
Oh_Hello There
+S and -S Solid Lines: Substitution ON/OFF

1 Substitute Solid Lines +S
2 Dont Substitute -S
Description:
When you use +S, ProvideX automatically replaces two or more occurrences of the underscore, dash or
equals sign ( _ - =) with solid underlines in graphics mode when printing to *WINPRT*. This only applies
to fields that are printed separately. (Primarily for use in legacy code where these characters were used in
place of solid lines.) Use -S to disable +S.
NOTE: This is not for use on terminals.
Example:
0010 DIM A$(10,"_"),B$(10,"-"),C$(10,"=")
0020 LET CHAN=UNT; OPEN (CHAN,ERR=*END)"*winprt*"
0030 PRINT (CHAN)'FONT'("MS Sans Serif",1),'DF',
0040 PRINT (CHAN)'-S',@(0),A$,@(12),B$,@(24),C$
0050 PRINT (CHAN)'+S',@(0),A$,@(12),B$,@(24),C$
0060 PRINT (CHAN)@(0),A$+" "+B$+" "+C$
In the example above, ProvideX will only print solid lines when it executes line 0050. It will neither print
solid lines for line 0040 (with -S) nor for line 0060 (where the string expression does not exclusively
contain underscores, dashes and/or equals signs).
'Sn Slew to Channel #

Slew to Channel # 'Sn
Description:
Use Sn to slew to the channel number specified by n. S6 is the same as VT.
'SB' Set Mode to Background

Set Background Mode SB

Description:
Use SB to set background mode. (Characters are displayed at low intensity / dimmed.)
'SCROLL Define/Control Scroll Region

1 Define SCROLL Region SCROLL(col,line,width,height)
Choices, Long or Short Forms:
2 Start / Enable Scrolling SCROLL("ON") or SE
3 Reset to Full Window SCROLL("RESET") or SR
4 Disable Scrolling SCROLL("OFF") or SD
Where =
@(col,line, Position / coordinates of the region. Numeric expressions. Column and line for the top
width,height) left corner. Width in number of columns, height in number of lines.
Description:
Use 'SCROLL' to define or change the scroll region in the screen / window. All subsequent mnemonics for
cursor position, clearing, deletion and insertion will only affect this defined area.
If the cursor advances beyond the last line: When SCROLL is ON, ProvideX moves all the lines on the
screen up one line. With scrolling OFF, ProvideX returns the cursor to the first column in the first line. You
can use SE or SD to enable or disable the scroll region.
You can use 'SR' or 'SCROLL'("RESET") to reset the scroll region to the full window / screen. For a
window with a border, the border is included in the SCROLL region.
NOTE: The values ON, OFF and RESET can be literals, variables or string expressions.
SD (see SCROLL)
Scroll Disable. See 'SCROLL Define/Control Scroll Region, p. 527(m)
SE (see SCROLL)
Scroll Enable. See 'SCROLL Define/Control Scroll Region, p. 527(m)
'SF * Set Mode to Foreground

Set Foreground Mode SF
Description:
Default. Use SF to set foreground mode. (Characters are displayed at high intensity.) Use CF to clear
'SF' mode.
See also: 'SB' Set Mode to Background, p. 526(m)

'SHOW' * / 'HIDE' Control Window Display
1 Show Window (Default 'SHOW'(n)
2 Hide Window 'HIDE'(n)
Where =
n Numeric code. Valid codes are:
0 ProvideX window is minimized
1 Sets normal mode
2 Uses full screen
3 PRINT SHOW(3) will restore a hidden window to its previous state
(minimized, maximized or normal). Ver. 4.20.
-1 Hides the window
Description:
Show or hide a window (graphics display only). The default is to display the window.
NOTE: You must restore or SHOW a hidden window through your program, since you cant
send data input directly to it.
SIZE Control Visual SIZE of Window

1 Define SIZE SIZE(width,height)
Where =
width,height Your window / regions width in columns and height in lines. Numeric expression.
Description:
Use SIZE to control the visual size of a window.
NOTE: There is no effect on the SIZE mnemonic when you use MINSIZE and MAXSIZE (to
control the window size that your user can set).
Example:
To reSIZE a dynamic window to the columns and lines specified:
PRINT 'SIZE'(40,10)
'SL' Start VFU_Load

Start VFU Load 'SL'
Description:
Use 'SL' to start VFU load. The data following SL (from SL up to an 'EL' mnemonic) defines the VFU
channels. The total number of characters defines the page length, the characters themselves represent
the channel numbers which can be slewed to. (See also 'Sn'.) The first character must be a 1 (channel 1).

'SN' * Native Screen Mode
Set Native Screen Mode SN
Description:
Default. When you use SN, the "clear" mnemonics fill the cleared regions with the current colour and 'RM'
(Reset Mode) resets the output to the default colours.
'SP' Standard Print

Standard Print 'SP'
Use SP to switch to standard print from CP Condensed Print for Screen, p. 499(m). In ProvideX, a
'CP' or 'SP' mnemonic affects only the data that follows the mnemonic.
Example:
10 open(1)"LP"
20 print (1)"NORMAL"+'cp'+"COMPRESSED"+'SP'+"NORMAL"
30 close(1)
If the example above were run in ProvideX, the word COMPRESSED would be in condensed print and the
word NORMAL would be in standard print. (In some other Business Basics, the font for the complete line
is affected and for this example, all text would be in standard print.)
SR (see SCROLL)
Scroll Reset. See 'SCROLL Define/Control Scroll Region, p. 527(m)
'SWAP' Swap Windows on Stack

Swap Windows on Stack SWAP
Description:
Use SWAP to swap the top two windows on the window stack.
'SX' Set Extended Screen Mode

Set Extended Screen Mode SX
Description:
Use SX to set extended screen mode. (The "clear" mnemonics fill the cleared regions with the default
colour and 'RM' (Reset Mode) turns off all visible attributes.)
This feature is only included for compatibility with other languages. See the Users Guide regarding
conversion and compatibility modes for additional information on this mnemonic.

'+T' and '-T' Text Display ON/OFF
1 Enable Text Display +T
2 Disable Text Display -T
Description:
Use +T to re-enable the display of the text screen and have ProvideX redraw the TEXT plane. Note that
this can cause flickering in some cases. You can use -T to disable the display and avoid flickering.
See the example in 'DIALOGUE' Define / Draw DIALOGUE Region, p. 502(m).
'TEXT' Draw TEXT

Mnemonic For Graphics Mode, Printers / Terminals
1 Define 'TEXT' 'TEXT'(x,y[,x,y],text$,option$)
Where =
x,y Point coordinates for top left and (optionally) bottom right, in graphical units. Numeric
expressions.
text$ Your text. String expression.
option$ Your attribute options string can include:
& Underline the &ed character
C Center Text
F Show Focus lines around Text
N Numeric Data
R Right Justify
S Fills only the text background (not whole region) with chosen Background
Colour
W Word Wrap
# Same as N
Description:
Use 'TEXT' to draw (print) your text in graphics mode, starting at the point set by your first x,y coordinates.
Use graphical units or @X(col) and @Y(line) functions for your coordinates. The TEXT mnemonic uses
your current FONT and colour attributes (i.e. 'RED', 'BLUE', ...).
Use the optional second set of x,y parameters to define the bottom right corner of a rectangular region for
displaying the text. You can use TXH( ) Text Height, p. 440(f) and TXW( ) Text Width, p. 442(f) to make
sure the text fits the region.
NOTE: For WINDOWS printers, if the current background colour is white, the output will be
considered TRANSPARENT (i.e. with no background fill).
Example:
0010 PRINT 'FONT'("MS Serif",-11)
0020 PRINT 'GREEN','TEXT'(240,420,"&Hello","&")
'TEXTWDW' Create Text Window

Create 'TEXTWDW'(col,line,width,height[,wdw_id][,title$][,attrib$][,OPT=val$])

Where =
wdw_id Unique window ID number. Optional. Numeric expression.
title$ Title string. Optional. Use a string expression / literal.
attrib$ Attribute string. Optional. If you include attributes, use a string of one or more
mnemonics to define the defaults for the window.
OPT=val$ Valid OPT= values for defining windows in a graphics environment (ignored in text
mode):
Z Creates a resizeable window
C Disables X close button on title bar, eliminates system control menu from
title bar.
x Disables "X- close button on title bar, eliminates system control menu
from title bar.
X Enables X- close button on title bar, supports system control menu on
title bar.
m Enables the maximize box in top right corner of window (only available
with OPT=Z)
* Creates a dynamic, resizable window with automatic scrollbars.
Description:
Use TEXTWDW to to create a Text_Style window under Windows. If you include a title, a box of the
defined height and width will be drawn around the window and the title will be left-justified on the top line of
the box.
Example:
PRINT 'TEXTWDW'(10,10,50,10,"Title",OPT="*")
'TR' Terminal Read from Start

Terminal Read from Start TR
Description:
Use TR to transmit an image to a program as a string. TR returns the screen contents from 0,0 to the
current cursor location.
As of Ver. 4.20, you can also use 'RP' Terminal Read to End, p. 525(m). This mnemonic performs the
same function as the TR mnemonic, except that it reports values from the current cursor location to the
end of the screen.
NOTE: In graphics mode, if a terminal mnemonic transmits the contents of the screen to the
program, the data consists of four bytes for each character. The first two bytes are
the background and foreground characters, the third byte holds the character
attributes, and the fourth byte is the actual character on the screen.
'TW' Transmit Windows as String

Transmit Window as String 'TW'

Description:
Use TW to transmit the active windows to the program as a string (to be read in the next INPUT
statement).
+U' * and -U Screen Refresh ON/OFF

1 Refresh is ON (Default) +U'
2 Refresh is OFF -U
Description:
For WINDOWS only. Use +U to turn ON screen refresh. Use -U to turn it OFF. The default is ON.
'UC' Convert Input to Upper Case

Convert to Upper Case 'UC'
Description:
Use UC to convert all subsequent user input to upper case. Use the 'LC' mnemonic to end upper-case
conversion and allow the use of mixed case.
'UP' Move Up One Line

Move Up 'UP'
Description:
Use UP to move the cursor up one line.
Example:
0010 PRINT "Oh_x",'LT',"Hello",'UP',"There"
+V' * and -V Control Row Highlighting (Ver. 4.20)

1 Full-line Highlight +V'
2 First Column Highlight -V
Description:
As of Ver. 4.20, you can use the print mnemonic +V to turn ON full-line highlighting. Then the user can
click on any column of a Listview (Report Style) LIST_BOX to highlight a row. When you use -V the user
must click on the first column to highlight the LIST_BOX row.
By printing either of these mnemonics, you can adjust the highlight style for your application without having
to modify each occurrence of a Listview (Report Style) LIST_BOX in your application. See also: Row
Highlighting in Listview Report Style, p. 237.
'VT' Slew to S6, Vertical Tab

Slew to S6, Vertical Tab 'VT'

Description:
Use 'VT' to slew to channel 6 (vertical tab - same as 'S6').
'+W' and '-W' WINDOWS_Style Windows

1 Use WINDOWS Style '+W'
2 Disable WINDOWS Style '-W'
Description:
Use +W to enable creation of WINDOWS-style windows. Use -W to disable creation of WINDOWS-
style windows. With WINDOWS-style disabled, all windows are created with text characters.
'WA' (see WINDOW and WA)

See WINDOW Define / Draw Window, p. 534(m)
'WC' (see PUSH)

Window Copy. See 'PUSH' Save / Copy Current Window, p. 523(m)
'WD' (see DROP)

Window Drop. See 'DROP' Drop Identified Window, p. 504(m)
'WG' (see GOTO)

Window Goto. See 'GOTO' Make Window Current, p. 511(m)
'WHITE' * and _WHITE Text Foreground /_Background

1 Output_Text Foreground= 'WHITE'
2 Output_Text Background= '_WHITE'
Description:
WHITE as the display colour for that text and/or its background.
Example:
INPUT 'WHITE','_GREEN',"Please enter your name: ",Name$

WINDOW Define / Draw Window
Choice, Long or Short Form WINDOW or WA
1 Define Window 'WINDOW'(col,line,width,height[[,wdw_id][,title$][,attrib$][,OPT=]])
Where =
wdw_id Unique window ID number. Optional. Numeric expression.
title$ Title string. Optional. String expression.
attrib$ Attribute string. Optional. If you include attributes, use a string of one or more
mnemonics to define the defaults for the window.
OPT=vals Valid OPT= values for defining windows in a graphics environment (ignored in text
mode):
Z Creates a resizeable window
C Disables X close button on title bar, eliminates system control menu from
title bar.
x Disables "X- close button on title bar, eliminates system control menu
from title bar.
X Enables X- close button on title bar, supports system control menu on
title bar.
m Enables the maximize box in top right corner of window (only available
with OPT=Z)
* Creates a dynamic, resizable window with automatic scrollbars.
Description:
Use either WINDOW or WA in the format to draw (print) a new window. If you include a title, a box of the
defined height and width is drawn around the window. The title will be left-justified on the top line of the
box unless the AH system parameter is set.
ProvideX mnemonics use one of three frame styles from the Windows API:
WS_DLGFRAME for the 'DIALOGUE' mnemonic
WS_BORDER style for the 'WINDOW' mnemonic.
WS_THICKFRAME by using OPT="Z" with the 'WINDOW' mnemonic
See also: Windows API: 3 Frame Styles, p. 486.
Example:
PRINT 'WINDOW'(5,5,100,40,"Title",OPT="*")
WM (see MOVE)
Window Move. See 'MOVE' Relocate Current Window, p. 520(m)

WP DOS: Wide Printer, 40-Column Mode
Mnemonic (In DOS) For Printers
Wide Printer, 40 Columns WP
Description:
For MS-DOS only. Use WP to use 40-column mode, wide printer.
WR (see POP)
Window Remove. See 'POP' Remove Current Window, Restore Previous, p. 523(m)
WRAP WrapAround ON/OFF

1 Set Wrap Around ON 'WRAP'("ON") or BW
2 Set Wrap Around OFF 'WRAP'("OFF") or EW
Description:
Set WRAP ON / OFF or use BW (Begin WrapAround) and EW (End WrapAround) to control automatic
word-wrapping at the end of the line.
ON: Default. When information is entered in the last column of the screen or window region, the cursor
will advance to the first position of the next line.
OFF: Continued output overtypes at the last position on the line.
WS (see SWAP)
Window Swap. See 'SWAP' Swap Windows on Stack, p. 529(m).
WX Windows Definition Sequence

Windows definition sequence WX=esc_seq$
Description:
Use WX for windows definition sequence. See also Output Sequences for Special Mnemonics, p. 487.
on Device Drivers.
XP DOS: Line Mode

Mnemonic For DOS Terminals
Set Line Mode XP
Description:
Use XP to control EGA / VGA 43/50 line mode (MS-DOS only).

'YELLOW' and _YELLOW Text Foreground /_Background
1 Output_Text Foreground= 'YELLOW'
2 Output_Text Background= '_YELLOW'
Description:
YELLOW as the display colour for that text and/or its background.
Example:
INPUT 'YELLOW','_GREEN',"Please enter your name: ",Name$
ZX Return Attributes as per BBx (Ver. 4.20)

Use BBx Values ZX
Description:
You can use ZX (Ver. 4.20) to resolve inconsistency in the attributes format and the FIN values when you
run ProvideX with code designed for BBx. (In prior versions, the attributes as returned when issuing a 'TR'
Terminal Read from Start, p. 531(m) in graphics mode had the foreground and background values
reversed and an incorrect window scroll region position.)
If you print the ZX mnemonic PVX will report the attributes and FIN values consistent with BBx. For
example:
-:print hta('zx')
1B5A58
NOTE: BBx is a registered trademark of Basis International Ltd.

System Parameters
System Parameters
Description:
This appendix lists the system parameters you can set in ProvideX and describes their functions. Each
parameter consists of a two-character code enclosed in apostrophes. Where noted, the listed parameter
is obsolete (included for completeness only).
NOTES: The list is in ASCII sort-order, except for parameters beginning with either
!(exclamation mark) or *(asterisk), which are at the end of the list.
Where noted, the parameters are system-specific. You can use the PRM system
variable (e.g. PRINT PRM) to return a string of most of your systems parameters with
their current values. (Some are hidden from the PRM list unless set.)
As of Ver. 4.20, ProvideX for DOS is only available on request.

You can use the ProvideX *UCP utility or the SET_PARAM directive to alter the current settings for your
system parameters.
See also: SET_PARAM Set System Parameters, p. 379(d)
PRM Current ProvideX Parameter Settings, p. 324(v)
Example:
PRINT PRM lists the following defaults in ProvideX for WINDOWS 32-bit as of Ver. 4.20:
-'3D',-'AD',-'AH','AI'=10,-'B0','BF'=10,-'BT',-'BX','BY'=1970,-'CD','CS','CT'=0,
'CU'=36,-'D0','DC','DF'=0,'DL'=0,'DP'=46,'DT'=0,'DW'=0,-'EG','EL'=0,-'EO',-'ES',
-'EX',-'F4','FB'=5,-'FC','FF'=0,-'FI','FO'=0,-'FU',-'FL','FP','FS'=138,-'FT',-'F
X',-'F,',-'I0',-'I2','IC',-'IM','IR','IS'=5,-'IZ',-'KR','LB'=4,-'LC',-'LD',-'LE'
,'LS'=1,-'LU',-'LZ','MB'=0,'MF'=50,-'MP','NE',-'NI',-'NK',-'NL',-'NN',-'NR',-'OC
','OL'=25,'OM',-'OP','OR','OW'=0,'PC'=10,'PD'=2,-'PO',-'PU','PW'=36,-'PZ','QF'=1
,'Q_'=2,'Q^'=2,-'QS',-'QT',-'RI','RN'=1,'RP',-'RR',-'RS',-'SC',-'SD',-'SF',-'SK'
,'SL'=32,-'SP',-'SR','SV'=1,'SZ'=32000,-'TB','TC'=0,'TH'=44,-'TL',-'TN',-'TT',-'
TU',-'TX','VP'=48,'VR'=0,'VW'=0,'WB','WD'=10000,-'WF','WH'=0,'WI'=1000,-'WK','WT
'=2,-'XC',-'XF',-'XI',-'XT',-'ZP',-'DD','!B'=3,'!U'=0,-'1U'
Saving / Restoring System Parameters

To avoid conflicts with other software components, we strongly recommend that you save the current
settings for parameters you need to change (with the exception of BX - see below), and then reset them
when done.
Exception: The 'BX' parameter is the only exception to this recommendation, since it affects a
series of System Parameters. Never attempt to save / change / restore 'BX'. It should
be set / reset only at the start of a session.
Example:
0010 sv_ex=prm('ex'); SET_PARAM -'EX'
.....
9900 SET_PARAM 'EX'=sv_ex

System Parameters
1U Force Session to Dedicated User Slot
Description:
(As of Ver. 4.20)
ON: ProvideX will try to use a dedicated user slot for the session. In effect this
removes the shared nature of PVX under WINDOWS or WindX and also affects
FacetTerm sharing.
OFF: ProvideX will attempt to use shared user slots for the session. That is, the
same terminal is considered a single user regardless of the number of
invocations.
TCB(27) returns the User Slot Number this session is using and whether it is
dedicated, shared or a background task (Ver. 4.20). See TCB( ) Return Task
Information, p. 424(f).
NOTE: Once you set 1U ON, you cant turn it OFF unless the application
terminates.
Default: OFF
'3D' 3D in Windows
Description:
ON: To display a 3D look in WINDOWS, you must use this parameter with the '3D'
mnemonic. That is, to initiate 3D controls, use:
PRINT '3D',; SET_PARAM '3D'
OFF: To display a 2D look. You can use the 2D mnemonic to disable the 3D
mnemonic (e.g., PRINT '2D', ...).
Default: OFF
'AD' Auto-DIM Array
Description:
ON: To auto-DIM an array.
OFF: You must use DIM Define Arrays and Strings, p. 82(d).
Default: OFF
Example:
SET_PARAM AD
LET X$[ALL]=Y$[ALL]
'AH' Alternative WINDOW / BOX Heading
Description:
ON: To use the alternative WINDOW / BOX heading (with the title in inverse
video, centered on the top line).
OFF: The title is text, left-justified on the top line of your WINDOW / BOX.
Default: OFF

System Parameters
'AI'=num Automatic Line-Numbering Increment
Description:
(As of Ver. 4.20)
SET: To assign a value for the default line numbering increment for LOAD, RUN,
CALL, or PERFORM directives with an ASCII text program and/or when you
use the AUTO directive. Prior to Ver. 4.20, ASCII text programs were always
numbered by 10, allowing for only 6500 lines.
Default: AI=10 (i.e. AUTO increment by 10).
NOTE: AI is reset to the default value=10 when a START is issued.
'B0' Base Zero for Level / Window
Description:
ON: To set zero as the base number for level and window.
OFF: The base number for level and window is
Default: OFF
NOTE: This setting affects HWN( ) Highest Unused Window Number, p. 184(f),
which relies on the base window number.
Warning: If you run your application with B0 set, make sure that it is set on both the
UNIX host and the WindX PC. Otherwise, the wrong windows will be
addressed. (You can set B0 either by using -B0 as an argument on the WindX
PCs startup command line or as a statement from the host, i.e. EXECUTE
"[wdx]SET_PARAM 'B0'".)
'BF'=num Common Buffers
Description:
SET: To define the number of common database keyed I/O buffers to be maintained
by the system.
Default: BF=10
NOTE: When you set BF=0 (zero, no common buffers), ProvideX uses your
setting in the FB system parameter (dedicated buffers).
'BT' Binary Test: 1st Read
Description:
ON: Binary test for serial files. Tests the first read when using binary file access
(ISZ=option).
OFF:
Default: OFF
'BX' BBx Emulation
Description:
ON: To use ProvideX in BBx emulation mode.
OFF: To use ProvideX in standard mode (FF=0).
Default: OFF
NOTE: Use the LZ system parameter to control rounding of leading zeros. (This
functionality was previously controlled by the BX parameter.)

System Parameters
'BY'=num Base Year
Description:
SET: To define the base year for the JUL( ) and DTE( ) functions.
NOTE: The JUL( ) function uses January 1 of the base year as day 0 (zero). If you
SET_PARAM BY=0 (zero), the JUL( ) and DTE( ) functions operate under
the Julian calendar where day 0 is around 4713 BC.
Default: BY=1970
'CD' Check Current Directory
Description:
ON: To check the current directory list before checking the PREFIX list for a file.
OFF: The current directory is searched after the PREFIXes (normal method).
Default: OFF
CE (Obsolete) Error in Call
Description:
N/A: Included here for completeness only.
'CF' Bypass Console Flush
Description:
ON: To bypass console flush for print statements. On UNIX systems, you can use
CF to improve display performance (no waiting for O/S acknowledgment after
every PRINT statement).
OFF:
Default:
'CS' Coloured Syntax
Description:
ON: ProvideX displays your program with coloured syntax when you use the LIST
directive and the LST( ) function.
OFF: Coloured syntax is not applicable.
Default: ON
See also: '*H' Control Screen Colours, p. 489(m)
CT=num Character Timeout
Description:
SET: To improve handling of character timeouts for slower devices.
Default: CT=0
'CU'=num Currency Symbol
Description:
SET: To assign your currency symbol / character for formatted numeric data I/O.
Use the ASCII value of your character.
Default: CU=36 or CU=ASC("$")

System Parameters
D0 Divide by Zero
Description:
ON: ProvideX returns 0 (zero) for divisions by zero (Ver. 4.10).
OFF: Division by zero results in an Error #40: Divide check or numeric
overflow.
Default: OFF
'DC' Destructive Cursor
Description:
ON: To use a destructive cursor. (Moving from left to right, replace intervening
characters with spaces up to the new cursor position).
OFF: The cursor jumps over the intervening characters.
Default:
Example: SET_PARAM 'DC'=0
PRINT @(15),"B", @(10), "A", @(20), "C"
With DC OFF, the screen output is " A B C". The cursor jumps first to
column 15, prints the B, then jumps to column 10, prints the A and finally jumps
to column 20 and prints a C.
SET_PARAM 'DC'
PRINT @(15),"B", @(10), "A", @(20), "C"
With DC ON, ProvideX uses a destructive cursor (line print mode, as in BBx
and some MAI systems). The preceding example would result in " A C",
because the output driver simply issues spaces when advancing on the same
line. With DC on, after printing the B and A, the driver uses 9 spaces to
position itself at column 20 to print the C. The destructive cursor overwrites the
B with the space.
'DD' Convert DOS Directory Delimiter (All Platforms Except UNIX)
Description:
ON: To replace the normal MS-DOS reverse slash (\) in path names with a
standard slash (/).
OFF:
Default: OFF

System Parameters
DF,DL,DW Enforced Delay Times on Event
DF=num Hundredths of a second to wait after each FF
DL=num Hundredths of a second to wait after each LF (implied or explicit LineFeed)
DW=num Hundredths of a second to wait after WI is exhausted
Description:
(As of Ver. 4.20)
SET: To add automatic delay times to your application without having to insert WAIT
statements into your application. Use these parameters to have ProvideX
return control to the O/S for longer periods of time.
Each parameter takes a numeric value from 0 to 1000:
0 indicates no delay (default for all)
1 indicates a forced WAIT 0 when the event occurs
All other values from 2 through 1000, indicate the number of 100ths of a
second to delay on each event occurrence.
NOTE: The DF and DL delays only apply to LF and FF when sent to a device,
WINDOWS print spooler, or a WindX-connected file.
Defaults: Zero, no delay (i.e. DF=0, DL=0 and DW=0)
DL See DF,DL,DW Enforced Delay Times on Event, p. 542(p)

'DP'=num Decimal Point Symbol
Description:
SET: To assign your decimal point symbol / character for use in formatted numeric
data I/O. Use the ASCII value of your character.
NOTE: The 'DP' setting is used if I/O is formatted in INPUT, OBTAIN, PRINT and
the STR( ) function (and ignored for unformatted I/O). It is always ignored
by the NUM( ) function and when using WRITE, READ, FIND or EXTRACT
directives in converting numeric data.
Default: DP=46 or DP=ASC("."), the decimal point.
'DT'=num Device Timeout
Description:
SET: To set the number of seconds to wait for output to a device before a device
error is returned.
Default: DT=0
DW See DF,DL,DW Enforced Delay Times on Event, p. 542(p)

'EG' End Generation of Error #29
Description:
ON: To ignore invalid mnemonics instead of generating Error #29.
OFF: To generate Error #29: Invalid Mnemonic or position
specification for invalid mnemonics.
Default: OFF
See also: 'BG' Begin Generating Error #29, p. 494(m)
'EG' End Generation of Error #29, p. 505(m)

System Parameters
'EL' Encryption Level
Description:
SET: To establish the optimum level of program password protection. As of Ver.
4.20, ProvideX recognizes 5 encryption levels (0 to 4) to prevent unauthorized
use of password-protected programs. Although Best Software Canada Ltd.
currently limits what level of encryption is actually shipped with the product
(normally only levels 0 and 1 are included), you can contact us to work out an
agreement to use a higher level if you need more security.
Prior to Ver. 4.20, ProvideX only supported password protection at encryption
level 0 (zero) and you could only LOAD or RUN programs with password
protection at level zero. Now, if you create your programs (Ver. 4.20 or greater)
at a level greater than zero, you can still force the encryption level to zero, so
that such programs are available for use in prior versions of Providex.
Default: EL=0
Return Val: Use PRINT PRM(EL) to find out what your current setting is.
EM Execute Main Level Only
Description:
EO Embedded EO Mnemonics
Description:
ON: To handle embedded EO mnemonics (to end output transparency). ProvideX
scans strings following a BO mnemonic for embedded ESC+"EO".
This parameter simplifies the conversion to ProvideX from other languages.
(Ver. 4.10).
NOTE: When EO is ON, any ESC+"EO" sequence embedded in the data will
terminate output transparency mode.
OFF: The strings are not checked for embedded EO mnemonics.
Default: OFF
Examples:
The example below shows a typical use of the BO (begin) and EO (end)
output transparency mnemonics. The EO mnemonic is not embedded in the
string, so ProvideX will automatically recognize it and terminate a BO
mnemonic.
PRINT(chan)BO,"some sequence",EO
In the next example, the EO mnemonic is embedded in the string (appended
using the +plus sign).
PRINT(chan)BO+"some sequence"+EO
In this case, if the EO system parameter is OFF (the default), the embedded
EO mnemonic is ignored. When the EO parameter is ON, ProvideX
recognizes the embedded mnemonic and ends output transparency.
ES Show O/S Extended Status / Errors in Command Mode
Description:
ON: To display O/S errors in command mode. ES is used primarily by developers
to enforce good programming standards.
OFF: ES should normally be OFF. No display of O/S errors in command mode.
Default: OFF

System Parameters
'EX' Apply EXECUTE at Level 0
Description:
ON: To have your EXECUTE directives affect the program at level 0.
OFF: ProvideX changes the current program.
NOTE: If the EXECUTE directive starts with a line number, ProvideX modifies the
current program and the line becomes part of the current program,
unless the system parameter EX is ON, in which case it modifies the
program at level 1.
See also: EXECUTE Execute Basic Instruction, p. 131(d)
Default: OFF
'F,' Format Overflow: Suppress Commas, Retry
Description:
ON: To suppress commas when numeric formats overflow (i.e., thousands
separators are stripped) and retry the format.
OFF: To generate an Error #43: Format mask invalid on format mask
overflows.
(The error is not returned in cases like 0100 INPUT EDIT "Enter
value:",INV_AMT:"$##,##0.00" where the directive allows for more input
than the mask accommodates.)
Default: OFF
'F4' Return CTL=4 for Exit
Description:
ON: To return CTL=4 when the user chooses the WINDOWS {X} exit icon or the
<F4> function key to close / exit.
OFF: To return CTL=-1999.
Default: OFF
'FB'=num Dedicated File Buffers
Description:
SET: To assign the number of dedicated file buffers to use for each file.
NOTE: ProvideX uses your FB setting if you set BF=0 (zero, no common
buffers).
Default: FB=5
'FC' (MS-DOS, WINDOWS) Force File Commit
Description:
ON: To force O/S file-commit to any updated keyed file on an INPUT or WAIT
statement.
OFF:
NOTE: Not for UNIX.
Default: OFF
FE (Obsolete) Generate Format Mask Errors
Description:

System Parameters
'FF'=num FID Format
Description:
SET: To define the format of information returned by the FID( ) function. There are 4
possible formats:
0 - ProvideX standard format
1 - Thoroughbred emulation
2 - Rexon emulation
3 - BBX emulation.
NOTE: If you set FF to 0 or 3 and switch PO (Path Original) ON, the FID( ) and
FIB( ) functions return the original path used when the file was OPENed.
Default: FF=0 (zero, for the ProvideX standard format)
'FI' Ignore Format Mask Errors
Description:
ON: To ignore format mask errors (no Error #43) and simply convert the data as if
no format mask exists.
OFF: To generate an Error #43: Format mask invalid for format mask
errors.
Default: OFF
'FL' Filename in Lower Case
Description:
ON: To pass filenames to the O/S in lower case.
OFF: If FU (Force Upper Case) is ON, ProvideX uses upper case when it passes
filenames to the O/S. Otherwise, no case conversion takes place.
Default: OFF. (FN is ON but not displayed in the PRM settings and there is no
filename conversion.)
See also: 'FN' Filename Asis: No Case Conversion, p. 545(p)
FFN( ) Find File Number, p. 140(f) for a UNIX example using these
parameters for case-insensitive searches.
'FN' Filename Asis: No Case Conversion
Description:
ON: ProvideX passes filenames to the O/S with no case conversion.
OFF: Case conversion is governed by the current setting of either FL (Forces lower
case) or FU (Forces upper case).
Default: ON unless FL or FU is ON. The FN setting is not displayed in the list
returned using PRINT PRM.

System Parameters
'FO'=num Format Overflow Character
Description:
SET: To assign the format overflow symbol / character you want returned as fill on
format errors. Use the ASCII value of your character. For example, to assign
the asterisk as the overflow character, SET_PARAM using either FO=42 or
FO=ASC("*").
Default: FO=0 (zero). ProvideX returns Error #43: Format mask invalid.
Example:
In the example below, ProvideX displays 6 asterisks instead of Error #43:
SET_PARAM 'FO'=ASC("*")
PRINT 123456.78:"##0.00"
******
'FP' Floating Point
Description:
ON: To use floating point hardware automatically if its available on your machine.
OFF: ProvideX leaves FP switched OFF if floating point hardware is not available.
Default: ON if your computer has a floating point processor. Otherwise, OFF.
'FS'=nnn Default Field Separator
Description:
SET: To assign the default field separator / character for the SEP system variable.
Use the ASCII value of your character, either as a decimal value or by using the
ASC( ) function. You can also use the ASCII value of the character that is
current in the DLM system variable.
Default: FS=138 ($8A$, not a printable character) or FS=ASC(SEP)
Example:
In this example, the current value in the DLM system variable (the backslash,
"\") replaces the SEP value 8A (i.e., CHR(138)) as the default field separator:
-:a$=sep;?hta(a$),asc(sep)
8A 138
-:set_param 'fs'=asc(dlm);? hta(sep),asc(sep)
5C 92
'FT' Trapping the <F10> Key
Description:
ON: To use the <F10> key to activate the menubar (the standard WINDOWS
default). In effect, <F10> acts as an <Alt-key>.
OFF: To have the <F10> key behave like any other function key.
Default: OFF. (ProvideX overrides the WINDOWS default.)

System Parameters
FU' Filename in Upper Case
Description:
ON: To pass filenames to the O/S in upper case.
OFF: If FL (Force Lower-Case) is ON, ProvideX uses lower case when it passes
filenames to the O/S. Otherwise, no case conversion takes place.
Default: OFF. (FN=1 / ON but not displayed in the PRM list and there is no filename
conversion.)
'FN' Filename Asis: No Case Conversion, p. 545(p)
'FX' Force EXTRACT
Description:
ON: To return Error #13: File access mode invalid if the program does
not EXTRACT before all rewrites.
OFF:
Default: OFF
HC (Obsolete) Hide Cursor
Description:
'I0' Ignore Null Substring (No ERR 47)
Description:
ON: To treat all substrings of 0 (zero) length, starting at offset 0 (zero), as valid
NULL strings and not generate Error #47.
OFF: A null substring (e.g. X$(0,0)) results in an Error #47: Substring
reference out of string.
Default: OFF
'I2' Ignore Max. Record Count (No ERR=2)
Description:
ON: To ignore maximum record counts. No Error #2 is reported.
OFF: To report Error #2: END-OF-FILE on read or File full on write
on maximum record count.
Default: OFF
'IC' Ignore Case-Sensitivity for *[ ] Scan
Description:
ON: To have the on-line scan function *[ ] scan for matches regardless of upper or
lower case.
OFF: The scan function *[ ] does case-sensitive searches.
Default: ON
'IM' Insert Mode for Input
Description:
ON: To use insert mode during INPUT.
OFF: Cursor is in replace mode during INPUT.
Default: OFF

System Parameters
'IR' Insert Mode Reset (Decimal Point Input)
Description:
ON: To reset insert mode upon entry of a decimal with input to the right of the
decimal during formatted numeric entry.
OFF:
Default: ON
IS=num CTL for Input Ending on SIZ=
Description:
SET: To assign the control value (CTL) to be returned when input terminates on a
SIZ= clause (Ver. 4.10).
Default: IS=5
'IZ' Ignore Max. Memory Setting
Description:
ON: To ignore the maximum memory setting defined by either the START directive
or 'SZ' parameter.
You can use the 'IZ' parameter when converting an application from another
language where the values on the START directives may be incompatible with
ProvideX standards.
OFF:
Default: OFF
JC (Obsolete) Jump Cursor
Description:
'KR' Keyed File I/O Emulates BBx
Description:
ON: To switch the KEYED file I/O module to BBx emulation mode. KEP( ) function
returns the key of the record prior, the next record to be read. KEY( ) functions
don't switch keys.
OFF: See normal behaviour for KEYED Create Single/Multi-Keyed File, p. 211(d)
Default: OFF
'LB'=num Colour for Line # in Break Points
Description:
SET: Numeric colour code. Valid colour options for line number in break points:
0 - Black 4 - Blue*
1 - Red 5 - Magenta
2 - Green 6 - Cyan
Default: LB=4, Blue
'LC' LIST Variables in Lower Case
Description:
ON: To have the LST( ) function and LIST directive return variable names in lower
case.
OFF: Variable names are LISTed in upper case.
Default: OFF

System Parameters
'LD' LIST Directives in Lower Case
Description:
ON: To have the LST( ) function and LIST directive return directives in lower case.
OFF: Directives are LISTed in upper case.
Default: OFF
'LE' SAVE and LIST: Indent Statements
Description:
ON: To indent program statements for SAVEs to a serial file and for the LIST
directive.
OFF: Program statement are not indented.
Default: OFF
LF Long_Form Variables
Description:
ON: SET_PARAM LF to have the compiler allow long variable names. The
LONG_FORM directive also turns LF ON.
OFF: The compiler restricts variable names to a single letter or a letter followed by a
number. Use either SET_PARAM -LF or the SHORT_FORM directive to
cancel 'LF'.
Default: OFF
LP (Obsolete) Line Printer Mode
Description:
'LS' Colour for Program Line with Syntax Error
Description:
SET: Numeric colour code. Valid colour options for line# with syntax errors:
0 - Black 4 - Blue
1 - Red * 5 - Magenta
2 - Green 6 - Cyan
Default: LS=1, Red
'LU' Lock Unnecessary: Sequential WRITE
Description:
ON: To make lock unnecessary on WRITEs to sequential files. (No Error #13 on
WRITE without lock.)
OFF: A "sticky" parameter. ProvideX generates Error #13: File access mode
invalid if there is no lock on the first WRITE to an OPEN file number.
NOTE: File access mode is checked once, on the first WRITE after OPENing. An
error wont be generated on a subsequent unlocked WRITE if the file
number is continuously OPEN between WRITEs (even if the parameter is
switched OFF between writes).
ALSO: Set LU ON to use the *VIEWER* Device File: Print Preview, p. 591.
Default: OFF

System Parameters
LZ Rounding of Leading Zeros
Description:
ON: To suppress rounding of leading zeros. This was previously controlled by the
BX parameter.
OFF:
Default: OFF
MB=num MegaBytes: File Segment Size
Description:
SET: To control segment size in multi-segmented files. MB must be set ON to
activate the multi-segmented file feature.
ProvideX calculates the approximate size of each segment in megabytes,
based on the block size of a file:
Segment size in bytes = 512 + ((BKSZ - 6) * BKSZ)
BKSZ above represents the block size of the file. You can use the BSZ=option
when you create the file, to override the default block size. The maximum
number of segments allowed for a file based on the block size are listed below:
Valid Maximum
Block Sizes # of Segments
32K 128
16K 64
8K 32
4K 16
2K 8
1K 4
Default: MB=0
'MF'=num Multi_Line Size Factor
Description:
SET: You could reduce or increase this factor but we dont recommend it. By default,
WINDOWS creates Multi_Line input 50% larger than font size to allow for white
space top and bottom.
Default: MF=50
'MP' MOD( ) Returns Positive Value
Description:
ON: To have the MOD( ) function always return a positive number.
OFF: See normal behaviour for MOD( ) Return Modulus, p. 268(f).
Default: OFF
'MS'=num Memory for Program Swap (DOS Only)
Description:
SET: To assign the amount of normal system memory (in KB) that will be used as
program swap space.
Default: MS=
'NE' Subprogram Error Report
Description:
ON: To have errors occurring in subprograms reported in the subprogram.
OFF: The error will be returned to the CALLing program.
Default: ON

System Parameters
'NI' Ignore Blanks in Numeric Fields
Description:
ON: To ignore spaces in numeric fields.
OFF: Spaces in numeric fields return an Error #26: Variable type invalid.
Default: OFF
'NK' NULL Key Stripping
Description:
ON:
OFF:
Default: OFF
'NL' Suppress LET Directive in LISTings
Description:
ON: To suppress the LET directive in LISTings.
OFF: LET directive is displayed in LISTings.
Default: OFF
'NN' No Line Numbers as References
Description:
ON: Statements that reference line numbers are invalid. For instance, GOTO 1050
is not allowed. ProvideX returns Error #85: Program does not
support line numbers. You have to use a statement label as in GOTO
Label_1050.
OFF: You can use statements that reference line numbers. (No Error #85.)
Default: OFF
'NR' No Intermediate Rounding on Division
Description:
ON: To prevent intermediate rounding on divisions. (This only affects divisions, not
other operations like multiplication.)
OFF: Intermediate rounding is performed.
Default: OFF
'NS'
Description:
ON:
OFF:
Default:
NX (Obsolete) No Exit and End of Program
Description:
'OC' Commit Prior to OPEN
Description:
ON: To have the system commit all file updates and locks prior to OPEN.
OFF:
Default: OFF

System Parameters
'OF'=num Max. Size Before Output Flush (UNIX Only)
Description:
SET: To define the maximum transmission size to be sent to an output device before
forcing an output flush. Some UNIX systems and drivers can suffer overrun
conditions if this parameter is not set.
Default: OF=255 on AIX systems
'OL'=num Maximum Buffers for OPEN LOAD
Description:
SET: To control the default maximum number of keyed buffers for OPEN LOADed
files.
Default: OL=25
'OM' Old-Style Mask
Description:
ON: To use old style MSK( ) function logic or OR. MSK( ) is now compatible with the
UNIX GREP command.
OFF: See normal behaviour for MSK( ) Scan String for Mask, p. 274(f).
Default: ON
'OP' Return Original Program Name
Description:
ON: To have the PGN( ) function return the original program name.
OFF:
Default: OFF
'OR' Full O/S Path for Rename
Description:
ON: To treat the destination (second) parameter in a RENAME directive as
containing a fully expanded O/S path for the renamed file.
OFF: Standard ProvideX search rules and file-naming conventions apply to the
renamed file.
Default: ON
'OW'=num Owner Application Code
Description:
SET: To assign an owner application code to all your SAVEd programs.
Default: OW=0 (zero, no code set)

System Parameters
'PC'=num Program LOAD Caching
Description:
SET: To use caching techniques for program LOADing to improve performance.
ProvideX will maintain the most recent programs (subprograms) in memory to
reduce the time required to reload them.
Default: PC=10
NOTE: ProvideX doesnt check the network for program changes, because if it
did there would be little if any performance improvement using program
cache. Since the program cache setting is local to the machine, any
changes to the "disk file" will not be reflected across the network until the
user initiates a new session, changes the PC settings or saves the
program locally.
Example: Given a program containing the following statement, saved on machine A as
"callme":
0010 MSGBOX "Original",
When a second machine (with 'PC'=8) calls this program, the message box
displays Original. Even if the text is changed on machine A (e.g. from
"Original" to "New") and the program is saved, when the second machine calls
"callme" again, the message box still displays Original.
Even if you erase that program on machine A and try to call it from the second
machine, the original program will still be run.
'PD'=num Default PRECISION for Current Session
Description:
(As of Ver. 4.20)
SET: To assign the default number of decimal places for the current session
(PRECISION range 0 to 14).
Default: PD=2
NOTE: This parameter is reset to 2 if a START command is issued.
'PF' EMS Page Frame (DOS Only)
Description:
ON: To use the EMS page frame for work space, increasing the available memory
by 64KB on those systems that have EMS.
OFF:
Default: ON if EMS is available on the machine.
'PO' Path Original
Description:
ON: To return the original pathname specified in the FID( ) function
OFF: The expanded pathname is returned.
NOTE: If you set FF to 0 or 3 and switch PO (Path Original) ON, the FID( ) and
FIB( ) functions return the original path used when the file was OPENed.
Default: OFF
'PS'=num Max. Program Size (KB) (DOS Only)
Description:
SET: To assign the maximum program size (in KB) that ProvideX will allow.
Default: PS=

System Parameters
PT Prompt in Command Mode
Description:
ON: To generate a prompt in COMMAND mode. This is the opposite of QT.
OFF: A prompt is not generated in COMMAND mode.
Default: OFF
PU Upper-Case PREFIX
Description:
ON: To convert any file names in an OPEN( ) statement to upper case when
scanning a PREFIX file for a key matching the filename (Ver. 4.10). Use this to
simplify SQL migrations where all filenames must be in upper case.
OFF: ProvideX does not convert case when scanning a PREFIX file for a match.
Default: OFF. Normally, the keys in a PREFIX file are case-sensitive.
PW=num Password Character for MULTI_LINE
Description:
SET: To assign the password character to be displayed in MULTI_LINEs to mask
input denoted as a password. Use the ASCII value of your character.
Default: PW=36 (i.e. $, the dollar sign)
PZ Suppress Program Size Warning
Description:
As of Ver. 4.20, for programs over 64K.
ON: ProvideX does not warn you if your program size is larger than 64K.
OFF: You receive a warning when you attempt to SAVE a program larger than 64K.
Default: OFF

System Parameters
Q_, Q^, QF Control Task Priority
Description:
Three parameters control the priority of a task, primarily to balance the load in a
Client/Server environment (Ver. 4.02):
Q_ - Lowest Task Priority
Q^ - Highest Task Priority
QF - Factor: Frequency of Decrement
NOTE: PVXWIN32.EXE supports five levels (range: lowest 0 to highest 4). The
current priority level is stored in TCB(91).
Q_=num Lowest Task Priority

Description:
SET Q_ To assign the lowest task priority level. When an application exceeds value of
WI (WINDOWS Instruction Count system parameter), its priority level is
decremented until it reaches the value of the Q_ Parameter.
Default: Q_=2
Q^=num Highest Task Priority

Description:
SET Q^ To assign the highest task/thread priority level. The priority level is always
reset to the Q^ value anytime a WAIT is executed or when terminal input is
requested.
Default: All applications run at Q^=2.
QF=num Task Priority Factor

Description:
SET QF To control how frequently the priority level is decremented. Setting QF to a
higher value will force the application to run for a longer duration at the given
priority level before switching to the next lower priority level or until the Q_
value is reached.
The overall number of instructions between priority level switching is based on
an exponential formula using the values of the WI and QF parameters.
Default: QF=1
'QS' START, Not Initialized
Description:
ON: To assist in conversions. A START command which includes the name of a
program to run at startup will only clear local variables (same as a BEGIN) and
start the specified program. Providex will only re-initialize on a simple START
issued from the console.
OFF: A START command to re-initialize ProvideX will close all files and clear all
variables.
Default: OFF
See also: START Restart ProvideX, p. 404(d)

System Parameters
'QT' No Prompt in Command Mode
Description:
ON: To suppress the prompt in COMMAND mode. This is the opposite of PT.
OFF: To generate a prompt in COMMAND mode.
Default: OFF
RI Round Multi_Line Inputs
Description:
ON:
OFF:
Default: OFF
RN=num Rounding Control
Description:
SET: To control when and how rounding will occur (Ver. 4.10). The valid values for
RN, below, are additive:
1 = On any assignment
2 = On any Add, Subtract
4 = On any Multiply, Divide, Power, or Modulus
8 = On any math function (SIN( ), COS( ), LOG( ), etc.)
64 = On all intermediate values in an expression
128 = Before any numeric data is written to file
256 = At the end of any expression
512 = Before all numeric compares
Default: RN=1 (on any assignment)
Example:
The statement SET_PARAM RN=644 sets the parameter to round on any
Multiply or Divide + with a WRITE directive + on all compares. (The sum of
4+128+512 is 644.)
RP *WINDEV* Raw Print (WindX / WINDOWS Only)
Description:
ON: To use the direct-to-spooler interface for *WINDEV* RAW printing (Ver. 4.10).
OFF: To use the old PASS THROUGH method of printing with *WINDEV*.
Warning: We recommend that you return to old *WINDEV* mode only if your client
has sudden problems.
Default: ON
'RR' Reset on RUN
Description:
ON: ProvideX will issue a RESET command whenever a RUN statement is
executed.
OFF: See normal behaviour for:
Default: OFF

System Parameters
'RS' Round STR( )
Description:
ON: To use rounding for the STR( ) function.
OFF: See normal behaviour for STR( ) Convert Numeric to String, p. 408(f).
Default: OFF
'SB' Self-Block Extracts
Description:
ON:
OFF:
Default: OFF
'SC' Show Cursor
Description:
ON: To keep the cursor visible during processing.
OFF: The cursor is hidden during processing. The cursor is restored for any user
input.
Default: Under MS-DOS the default is OFF. In other systems, it's ON.
'SD' Subdirectory Slash
Description:
ON: To append a trailing slash to the name of a subdirectory entry returned when
READing a directory.
OFF: No trailing slash is returned with the subdirectory entry.
Default: OFF
'SF' Short_Form Variables
Description:
ON: SET_PARAM SF to have the compiler restrict variable names to a single letter
or a letter followed by a number. The SHORT_FORM directive also turns SF
ON.
OFF: The compiler will allow long variable names. Spaces are required between
directives and variable names. Use either SET_PARAM -SF or the
LONG_FORM directive to cancel 'SF'.
Default: OFF
SK Shrink Keyed Files
Description:
ON: To shrink KEYED files when executing PURGE or REFILE directives. ProvideX
returns the freed space to the O/S.
OFF: By default, ProvideX simply re-initializes the file header information when it
encounters a PURGE / REFILE directive for a data file (KEYED or DIRECT).
This means that if you accidentally PURGE / REFILE such a data file, the
ProvideX File Reconstruct utility can salvage most, if not all, of the information
originally stored in the file.
See also: PURGE Clear Data from a File, p. 333(d) and
REFILE Clear Data from File, p. 352(d).
Default: OFF

System Parameters
'SL'=num Save Command Lines
Description:
SET: To assign the number of command input lines to preserve internally. Range: 4
to 100.
Default: SL=32
'SP' Set Printer Default / Serial Printer Mode
Description:
ON: To use the ProvideX default printer mode. The file /device receiving PRINT
commands will not be buffered and overprints will print a new line over the
current line.
OFF: The printers will simply replace the contents of the print buffer.
Default: OFF
'SR' Small READs
Description:
ON:
OFF:
Default: OFF
'SV'=num Save as Old Ver. Object Code
Description:
SET: To generate object code for use in the older versions of ProvideX.
Default: SV=1, the current programs object-version level.
'SZ'=num Max. Memory Size for Session
Description:
SET: To define the maximum memory (KB) that the session is allowed to use. You
can also change the value by using SZ=num in your START directive.
Default: SZ=32000 as of Ver. 4.20. (For older WINDOWS versions, 1024 or the
maximum memory available, whichever is less, and 512 under UNIX / Linux.)
NOTE: Under WINDOWS, the maximum setting is 32767. Under UNIX / Linux the
limit has been increased from 512 to 32000.
ALSO: If the 'IZ' parameter is ON, the 'SZ' parameter is ignored.
'TB' Toolbar Size
Description:
ON: Toolbar width and coordinates are calculated based on the number of columns
in the window.
OFF: Toolbar width and coordinates are calculated based on 80 columns, regardless
of the number of columns in the window.
Default: OFF

System Parameters
'TC'=num TIP Window Colour
Description:
SET: To assign the fill colour for the "Tip" window. If the colour code is in the range
from 0 to 7 then the respective colour is used as fill. If the colour code is in the
range from 8 to15, then 50% of the colour is used.
Valid colours are:
0 - Current default 8 - Dark gray
Default: TC=0 (zero as of Ver. 4.20). Current WINDOWS default tip colour, specified in
the users desktop. To match other WINDOWS applications on the users
system.
NOTE: In prior versions, 0 was the colour code for Black and the Default setting
was 11 (Yellow).
'TH'=num Thousands Separator
Description:
SET: To assign your thousands separator / character for use in formatted numeric
data I/O. Use the ASCII value of your character.
NOTE: The 'TH' setting is used if I/O is formatted in INPUT, OBTAIN, PRINT and
the STR( ) function (and ignored for unformatted I/O). It is always ignored
by the NUM( ) function and when using WRITE, READ, FIND or EXTRACT
directives in converting numeric data.
Default: TH=44 or TH=ASC(",") for the comma.
TL LIKE Emulates Thoroughbred
Description:
ON: To have the LIKE operator use a simplified pattern match which emulates the
behaviour of LIKE in Thoroughbred for conversions from Thoroughbred (Ver.
4.10). This pattern matching is:
no mask character: the complete string on the left must match
the character * in the mask stands for any number of characters
the character ? in the mask stands for any single character
OFF: LIKE will use the same pattern matching that MSK( ) does.
Default: OFF
See also: Operators Supported in ProvideX, p. 587 for the LIKE operator
MSK( ) Scan String for Mask, p. 274(f)
Example:
"ABCDEF" matches "*DEF", "ABC???", "*CD*" but not "ABC" or "?".
TN Strip Trailing Nulls
Description:
ON: To strip trailing NULLs from the end of READ RECORDs.
OFF: Trailing NULLs are not stripped.
Default: OFF

System Parameters
'TT' Timed Trace
Description:
ON To have all trace output prefaced by the current time (in seconds).
OFF: Trace output does not have a time stamp.
Default: OFF
TU WindX Turbo Mode
Description:
ON: To gain efficiency of throughput by telling WindX not to acknowledge messages
for directives/functions that have no return value (e.g. a WRITE for a graphical
control). This improves speed in NOMADS.
NOTE: WindX Turbo Mode is set on the host/server.
ALSO: ON: You lose error detection capability at the host end, since WindX
reports errors locally (i.e. on the WindX client). Trouble-shoot by
changing the application logic or turning the parameter OFF.
OFF: Each tokenized message sent by your server to WindX for the client is
acknowledged and errors are reported to your server, guaranteeing that your
application and WindX are fully synchronized (but at some cost to overall
transmission speed).
Default: OFF
TX Default BBX String-Template Separator
Description:
As of Ver. 4.20
ON: BBx style string templates that use the (*) format will default to the LF ($0A$)
as a separator rather than using $8A$ as the separator.
OFF: BBx style string templates default to $8A$ as the separator.
Default: OFF
'UM' Upper Memory Blocks (DOS Only)
Description:
ON: ProvideX uses Upper Memory Blocks to increase memory space.
OFF:
Default: ON if UMBs exist on the machine.
'VM' Direct Memory Addressing (DOS Only)
Description:
ON: All screen I/O under DOS uses direct memory addressing.
OFF: Screen I/O uses BIOS calls.
Default: ON
VP=num Variable Pitch
Description:
SET: To assign the average character width for PRINT @(x,y) positioning with
proportional fonts. Use the ASCII value of your character.
Default: VP=48 or VP=ASC("0") for zero.

System Parameters
VR=num Verify READ
Description:
SET: To verify all data file READs by re-reading and comparing. The values set in
VR define the number of retries before a data READ error will be generated.
NOTE: VR can be helpful in tracking down hardware-related data corruption
problems. (There is some impact on system performance.) TCB( )
returns the following values for this parameter:
TCB(63)- Number of READs verified
TCB(65)- Number of READ mis-compares
Default: VR=0
VW=num Verify WRITE
Description:
SET: To verify all data file WRITEs by re-reading after WRITEs to check data
integrity. The values set in VW define the number of retries before a data
WRITE error will be generated.
NOTE: VW can be helpful in tracking down hardware-related data corruption
problems. (There is some impact on system performance.) TCB( )
returns the following values for this parameter:
TCB(64)- Number of WRITEs verified
TCB(66)- Number of WRITE miscompares
Default: VW=0
WB' WindX BREAK Recognition
Description:
ON: To enable WindX BREAK recognition.
OFF: To disable WindX BREAK recognition.
Default: ON
'WD'=num Defer File WRITEs
Description:
SET: To defer all file writes until nnn updates have been done, the file is CLOSEd, or
an INPUT is requested from channel #0 (terminal). The WD parameter only
affects keyed file I/O. Performance can be improved in single user
environments if the 'WD' parameter is set high.
Default: WD=10000 in a single user environment under DOS & WINDOWS.
Otherwise WD=0.
Example:
SET_PARAM WD=10000
'WF' Force Windows Screen Update (WindX / WINDOWS Only)
Description:
ON: To have PVXWIN force an update of the Windows screen whenever a change
is made by the program.
OFF: The screen will be updated on INPUTs, WAITs, or after processing the number
of instructions set by the 'WI' parameter.
Default: OFF

System Parameters
'WH'=num Delay Retry: Locking File Headers (All Platforms Except UNIX)
Description:
SET: To define the number of tenths of a second to delay between retries in locking
file headers.
Default: WH=0 (zero tenths of second)
WI=num Windows Instruction Count (WindX / WINDOWS Only)
Description:
SET: To assign the Windows Instruction Count.
NOTE: The overall number of instructions between priority level switching is
based on an exponential formula using the values of the WI and QF
parameters. See the Q_, Q^ and QF system parameters which control
task priority.
See also: Q_=num Lowest Task Priority, p. 555(p)
Q^=num Highest Task Priority, p. 555(p)
QF=num Task Priority Factor, p. 555(p)
TCB( ) Return Task Information, p. 424 (f) (i.e., TCB(91))
Default: WI=1000
Example:
SET_PARAM WI=1000
'WK' Keep Window
Description:
ON: To prevent WINDOW graphics from being automatically dropped when you
use a BEGIN (or END in command mode).
OFF: WINDOW graphics are automatically dropped when you use a BEGIN (or
END in command mode).
Default: OFF
'WL' Force WRITE LOCKs
Description:
ON: To force WRITE LOCKs always on READ/WRITE. Any I/O for a keyed data file
will temporarily block all other access. For that split second only one access
will be allowed.
OFF: ProvideX allows multiple simultaneous READ I/Os but only one WRITE access.
Default: OFF
See also: 'WL' Block Access on READ/WRITE (UNIX Only), p. 562(p)
'WL' Block Access on READ/WRITE (UNIX Only)
Description:
ON: To temporarily block all other access for both READ and WRITE directives to a
keyed data file. (For that split second, only one access will be allowed.)
OFF: ProvideX will allow multiple simultaneous READ accesses to a KEYED file but
only one WRITE access.
Default: OFF
See also: 'WL' Force WRITE LOCKs, p. 562(p)

System Parameters
'WT'=num Number of Retries
Description:
SET: To assign the number of retries ProvideX makes internally for busy records/
files. The retries are performed at one second intervals.
Default: WT=2
XC WindX Continues After TCP Error
Description:
ON: To have WindX continue after a TCP WRITE error (i.e. WindX ignores such
errors while printing data to a TCP/IP-connected terminal). This allows a
process to continue operating even if a client terminal disconnects. (The error
will be reported when terminal input is requested.)
OFF: WindX generates the error and cancels the process.
Default: OFF
'XF' Extended File Mode
Description:
Channel 0 (zero) is the console or terminal.
ON: To set extended file mode where the channel numbers range from 1-32767 for
local files and 32768-65000 for global files.
OFF: Channels 1 to 63 are commonly used for local files and 64 to 127 are used for
global files.
NOTE: Before you turn the 'XF' parameter OFF, make sure that none of your
currently OPEN files have extended file numbers (which are inaccessible
when you SET_PARAM -XF).
Default: OFF
'XI' Extract Ignore
Description:
ON: To have the EXTRACT directive only restrict other EXTRACTs of the record
locked. For instance, with WRITE LOCK, it leaves the record extracted.
OFF: The EXTRACT directive will restrict any access to the locked record.
Default: OFF
'XS'=num Extended Memory (KB) (DOS Only)
Description:
SET: To assign the amount of extended memory (in KB) used as program swap
space. If your value exceeds the available extended memory, it will be
adjusted to the maximum allowed.
Default: XS=
'XT' ProvideX Exits to O/S
Description:
ON: To terminate ProvideX and return to the O/S when your application returns to
COMMAND mode (on end of program, a detected error, or an ESCAPE).
OFF: To return and stay in COMMAND mode on end of program, error or ESCAPE.
Default: XT is ON if there is no lead program on the startup PVX command.
Otherwise, its OFF.

System Parameters
ZP Accept Zero-Length Programs
Description:
ON: As of Ver. 4.20, empty program files are considered to be valid. Error #18 is
ignored.
OFF: If you use RUN, CALL, LOAD or PERFORM commands with an empty
program file, that generates an Error #18: Program not loaded/
Invalid program format.
Default: OFF
!9 MAS90: Automatic Date Format
Description:
ON: To convert incoming and outgoing dates for an ODBC connection to MAS90
format automatically.
NOTE: For MAS 90 only (Ver. 4.10); supported for internal ODBC usage.
OFF: No automatic conversion is performed.
Default: OFF
'!B'=num Set Break Character (UNIX Only)
Description:
SET: To assign the break character (UNIX only).
Default: !B=3
'!D' Decimal / Thousands Separator: Legacy Mode
Description:
ON: To use the original method of handling 'DP' (Decimal Point) and 'TH'
(Thousands Separator) prior to Ver. 4.12.
OFF: See the DP and TH system parameters for the current method of handling
these values (Ver. 4.12).
Default: OFF
!F (Obsolete)
Description:
N/A: To revert to the processing order ProvideX used prior to Ver. 3.53 for evaluating
variables in user-defined functions. Included here for completeness only.
!I NOMADS Input Queue
Description:
ON: To activate the NOMADS input queue for macro playback.
OFF: To de-activate the queue.
Default: OFF
!K Descending Key Logic (Legacy)
Description:
ON: To use legacy descending key logic. This is included in ProvideX only to help
programmers who relied on the legacy logics incorrect behaviour. (Issue on
READ(c,KEY=) for primary key with descending segments, resolved Ver. 4.11).
OFF: ProvideX standard logic is used.
Default: OFF

System Parameters
!Q Descending Key Logic (Legacy)
Description:
ON: All ODBC SQL statements are displayed in a message box on the screen.
OFF:
Default: OFF (Hidden)
!S Saving SERIAL Files: Flag Errors
Description:
ON: To flag lines with errors when saving to SERIAL files.
OFF: Errors are not flagged.
Default: OFF
'!T' Accept DP and/or Decimal for Numerics
Description:
ON: To accept either 'DP' or the true decimal point character (".") as a decimal point
for numeric data input.
OFF:
Default: OFF
!U=num (Reserved. For Best Software Canada Ltd. only.)
Description:
N/A: An internal debugging attribute, included here for completeness only.
Default: !U=0.
*K Unique to one customer (Legacy)
Description:
N/A: Used by one customer only, for compatability with SBB. Included here for
completeness only.
*L Unique to one customer (Legacy)
Description:
N/A: Used by one customer only, for compatability with SBB. Included here for
completeness only.

List of Appendices
Appendices: Listing
This part of The ProvideX Language Reference contains a series of appendices describing special
commands and features you can use in the ProvideX programming language. The appendices and
subsections include:
COM Ports and Serial Devices, p. 567
File Options, p. 581
Negative CTL Definitions, p. 583
Operators Supported in ProvideX, p. 587
Specialty *File* Handling, p. 589
*VIEWER* Device File: Print Preview, p. 591
Examples: Queues for *WINPRT* / *WINDEV*, p. 599
Examples: *WINPRT* / *WINDEV* Printing, p. 602
System Limits, p. 606
[WDX] and Other Specialty Command [Tags], p. 608
[DDE] Tag: Dynamic Data Exchange, p. 609
[DLL] Tag: Dynamic Link Library, p. 611
[OCX] Tag: Object Component Extension, p. 612
[ODB] Tag: Open DataBase, p. 613
[RPC] Tag: Remote Procedure Control, p. 614
[TCP] Tag: Transmission Control Protocol, p. 619
[VBX] Tag: Custom VBX, p. 625
Reserved Words, p. 632


COM Ports and Serial Devices
OPENing COM Ports
Format:
1 OPEN Device in DOS OPEN (chan[,fileopt])"port:"

2 OPEN Device in Windows OPEN (chan,fileopt,OPT=string$)"port:"
3 OPEN Device in UNIX OPEN (chan[,fileopt])"/dev/tty2A"
Where =
fileopt File options. Valid options for OPENing a COM port include:
BSZ=num Block size
For WINDOWS only, you can include OPT=string$. The settings for the OPT= option
use the following attributes and format. Note that flow_rate is optional.
Format: OPT="baud_rate,parity,data_bits,stop_bits[,flow_rate]"
port Port ID. For example, OPEN(1,settings$)"COM2:"
Description:
You can OPEN a COM port for direct serial communication and gain access to special serial devices such
as:
label printers
weigh scales
modems
access card readers
... etc.
Some of these devices (e.g. modems) involve two-way communications, where you can set up tasks such
as background processes to monitor the port, with ACK-NAK and/or READ-do processing. Other
devices, such as label printers, use one-way serial communication, e.g. in PRINT statements.
Format 1 In DOS: OPEN (chan[,fileopt])"port:"

When you OPEN a serial device in DOS, ProvideX uses the current DOS "Mode" settings for the port.
Format 2 In WINDOWS: OPEN (chan,options)port

Use this format in WINDOWS to OPEN a serial device for direct access. For WINDOWS only, you can
include OPT=options as, for example, in OPEN (1,OPT=settings$)"COM2:" where the string variable
in the OPT= option contains settings for the attributes.
NOTE: If you omit the OPT= option for your communications settings, ProvideX will default
to the setup in the WINDOWS Control Panel.

WINDOWS OPT= Options
The chart below lists the standard OPT= options for WINDOWS. For more information about the attributes
and settings to use as options for your particular serial device, please see your O/S manual and/or your
device manual.
OPT= Valid Values

baud rate Valid range is 300 to 115200
parity char. Use one of three alpha characters:
N for None
O for Odd parity
E for Even parity
data_bits Use one of three valid values:
1, 7, or 8
stop_bits Use one of the valid values:
-1 (minus one)
0 (zero)
1
1.5
2
flow_rate (Optional.) Valid values include:
x for XON/XOFF software flow
p for RTS/CTS physical/hardware flow
(Omit the value for "none")
Example:
The setting$ assigned in the WINDOWS example below are for the serial communications attributes:
baud rate, parity (n=none), data bits (8), stop bit (1) and flow rate (xon/xoff switch).
12540 let setting$="9600,n,8,1,x"
12550 let printer=hfn
12560 open (printer,isz=1,opt=setting$,err=13000)"COM2:"
12570 print (printer)"Title"
Format 3 In UNIX: OPEN (chan[,fileopt])"/dev/tty2A"

When you OPEN the serial device using this format in UNIX, the port is OPENed with the current
characteristics. To change the settings, you can either set line discipline at the O/S level before starting
ProvideX or use an INVOKE directive after you OPEN the device:
invoke "stty 38400 -IXANY IXON IXOFF ... </dev/tty2A"
WindX TIP: While it is possible to OPEN a serial device on the client PC by using the [WDX] tag,
we recommend against doing this. Instead, we advise you to use a CALL from the
host to a [WDX]subprogram on the remote client PC. Design your subprogram to
OPEN and control the device and its settings. You can return your results to the host
via your CALLs parameters. See also [WDX] Tag: Directs Action to Client Machine,
p. 626.

Command Line, Launching ProvideX
Command Line Options
Format:
1 Windows 32-Bit:
<your_path>\PVX\PVXWIN32.EXE[ cmd_prms][ ini][ prog][ overrides][ pvx_prms][ -ARG list]
2 Windows 16-Bit:
<your_path>\PVX\PVXWIN.EXE[ cmd_prms][ ini][ prog][ overrides][ pvx_prms][ -ARG list]
3 UNIX: <your_path>/PVX/PVX [ prog][ overrides][ pvx_prms][ -ARG arg1 | arg2 | ...]
4 DOS: <your_path>\PVX\PVX.EXE[ prog][ overrides][ pvx_prms][ -ARG list]
Where =
...\PVX\PVXWIN32.EXE Command to start ProvideX in command mode. String expression. Use
the full pathname. For example, in WINDOWS:
...\PVX\PVXWIN.EXE
C:\MY_DIRECTORY\PVX\PVXWIN32.EXE
UNIX: .../PVX/PVX
To return the current value, use ARG(0)
DOS ...\PVX\PVX.EXE
NOTE: As of Ver. 4.20 ProvideX for DOS will only be available
on request.
cmd_prms Optional parameters. For WINDOWS only. Valid parameters:
-HD Starts with initial window hidden
-MN Starts with initial window minimized
ini Name of an INI file to use (for WINDOWS only). Optional. String
expression. You can have a different start-up command with a different
.INI file for each application if you want to set up each application with
have different defaults (for fonts, window size, etc.).
Default: <path_to_Windows_directory>\pvx.ini. For example:
C:\PVX\PVXWIN32.EXE THIS.INI THAT_PROGRAM
To return the current value, use ARG(-1).
As of Ver. 4.20, ProvideX accepts quotes enclosing your .ini filename
and spaces within the .ini filename in the command line argument.
See also: INI File Handling as of Ver. 4.20, p. 570.
prog Name of a program to run at startup (your lead program name, limited to
64 bytes). Optional. String expression. For example:
C:\PVX\PVXWIN32.EXE -PC=10 C:\MY_PROGRAM\TO_RUN_FIRST
To return the current value, use LPG (system variable)
overrides Optional arguments that override startup. Valid overrides:
-ID=FID val FID(0) value the session is to start with
-DR=path Directory ProvideX will use as its HWD (Home
Working Directory)
For example:
C:\PVX\PVXWIN32.EXE THAT_PROGRAM -ID=T0 -DR=MARY

Where =
pvx_prms Optional ProvideX system parameters that can be used on the
Command Line. All ProvideX system parameters are valid, including:
-PC=integer The program cache e.g. -PC=10 programs).
-XT=0 or 1 XT=1 (ON) On return to command mode, end
ProvideX session and return control to the O/S
The dash is mandatory to indicate that the argument is a parameter (no
apostrophes).
-ARG list The dash and keyword (i.e. -ARG) mark the start of a list of optional
arguments you can pass to the program on startup. The list of
or
arguments (arg1, arg2, etc.) is space-separated. If an argument
-ARG arg1 arg2 ... contains spaces, enclose it in quotation marks.
See also: NAR Number of Arguments, Start Providex, p. 284(v)
ARG( ) Command-Line Argument, p. 17(f)
Description:
The chart above describes the syntax elements you can include in your command line to start ProvideX.
We strongly recommend that you always include the full (absolute) pathname of the executable file in this
command.
Examples:
The basic command in Windows:
C:\MY_DIRECTORY\PVX\PVXWIN32.EXE
With a lead program:
C:\MY_DIRECTORY\PVX\PVXWIN32.EXE MY_PROGRAM
With other syntax elements:
C:\PVX\PVXWIN32.EXE -MN PROGRAM_1 -DR=H:\ACCT_PAY
C:\PVX\PVXWIN32.EXE -XT=1 MY.INI MY_PROGRAM -ID=T0 -DR=MARY
C:\MY_DIRECTORY\PVX\PVXWIN32.EXE MY.INI WINDX
C:\MY_DIRECTORY\PVX\PVXWIN32.EXE MY.INI *NTHOST
To Return Command-Line Values

As noted above, you can use the ARG( ) and FID( ) functions as well as the HWD, NAR and LPG system
variables to retrieve the values in current use. For more information, see:
ARG( ) Command-Line Argument, p. 17(f)
HWD Starting/Home Directory, p. 183(v)
LPG Lead Program Name, p. 250(v)
NAR Number of Arguments, Start Providex, p. 284(v)
INI File Handling as of Ver. 4.20

As of Ver. 4.20, Best Software Canada Ltd. has changed the search rules for the default PVX.INI file and
for any INI file specified on the command line which does not have an explicit path.

The new search pattern is:
1) Check the WINDOWS directory ( \Windows or \Winnt )
2) Check the current directory
3) Check the directory where pvxwin32.exe is currently being run.
When ProvideX needs to update your INI file for items such as last WindowState, it will update the INI file
in the location in which it was found during ProvideX initialization, based on the search pattern above. If no
INI file is found during initialization and ProvideX needs to update the INI, then it will create the INI file itself
and place the file in the directory where the pvxwin32.exe program was executed.
The ProvideX activation program (pvxwactv.exe) no longer automatically creates the PVX.INI file and
there is no LIBRARY=lib specified by default on a new installation. To locate the lib directory and the
ProvideX Activation Key file (ACTIVATE.PVX), ProvideX checks first for an INI name. If you dont specify
an INI filename (using either a name specific to your system or the default name PVX.INI), then ProvideX
assumes that the Activation Key file is directly below the directory location where the pvxwin32.exe
executable is being run.
These changes allow multiple applications and applications from different vendors to co-exist on the same
system with simpler installation and less likelihood that the various settings will interfere with each other.
The changes also meet the Windows2000 compliance requirement that an application not put files into the
WINDOWS directory, but maintain them in the applications installation or working directories.
You can look up your current sessions LIB directory and INI filename under the About ProvideX menu
selection on the main ProvideX dropdown menu. (Click on the ProvideX icon in the upper left corner of the
base ProvideX window to display the dropdown menu.)

Dynamic Control Object PROPERTIES
Appendix: Control PROPERTY Assignment
Format:
1 Assign Numeric Property obj_varproperty=num

2 Assign String Property obj_varproperty$=string$
3 Retrieve Numeric Property var=obj_varproperty
4 Retrieve String Property var$=obj_varproperty
5 Read All Properties of Obj var$=obj_var*
Where =
obj_var Numeric variable containing the unique ctl_id of your control object.
Examples:
0010 LET dbox=1000
0020 DROP_BOX dbox,@(10,10,10,10)
PRINT dbox*
(apostrophe) The apostrophe operator is part of the syntax.
property Name of a property ProvideX supports for your given object. Property names are not
case-sensitive. Each object type (e.g. GRID) has a fixed list of properties available.
See the Object Property Table, p. 574 for details, or use the list format to print all
properties of a particular control type. For example, to list the properties for
DROP_BOXes in general (using dbox, a unique object id):
PRINT dbox*
Auto,BackColour,Col,Cols,CurrentItem,CtlName,Enabled,Eom,Focus,Fo
nt,Height,hWnd,Item,ItemCount,ItemText,Key,Left,Line,Lines,Msg,
OnFocusCtl,Parent,Sep,SepLoad,Tbl,TextColour,Tip,Top,Value,Visi-
ble,Width,
num or string$ Numeric or string value to assign to the property, e.g., dboxauto=1.
var[$] Numeric variable to receive the value of a numeric property or string variable to
receive the value of a string property.
Examples:
-:X=dboxwidth
-:PRINT X
82
-:A$=DBOX'MSG$
-:PRINT A$
Hello
Description:
Use the apostrophe operator to assign, retrieve and list your given control objects properties and make
dynamic changes to a control objects properties (Ver. 4.10).

Control Type
The ProvideX common control objects to which you can apply dynamic properties are listed below.
Keyword See also:

MULTI_LINE MULTI_LINE Define/Control MULTI_LINE Input, p. 277(d)
LIST_BOX LIST_BOX Define/Control LIST_BOX, p. 226(d)
LIST_VIEW Listview LIST_BOXes (List and Report Styles), p. 235(d)
TREE_VIEW Treeview LIST_BOXes, p. 239(d)
DROP_BOX DROP_BOX Define/Control DROP_BOX, p. 99(d)
VARLIST_BOX VARLIST_BOX Define/Control Variable List Box, p. 459(d)
VARDROP_BOX VARDROP_BOX Define/Control Variable Drop Box, p. 454(d)
BUTTON BUTTON Define/Control BUTTON, p. 28(d)
CHECK_BOX CHECK_BOX Define/Control CHECK_BOX, p. 37(d)
TRISTATE_BOX TRISTATE_BOX Define/Control TRISTATE_BOX, p. 433(d)
RADIO_BUTTON RADIO_BUTTON Define/Control RADIO_BUTTON, p. 336(d)
V_SCROLLBAR V_SCROLLBAR Define/Control Vertical Scroll Bar, p. 451(d)
H_SCROLLBAR H_SCROLLBAR Define/Control Horizontal Scroll Bar, p. 174(d)
GRID GRID Define/Control Grid, p. 167(d)
NOTE: Although ProvideX also supports objects which are external to ProvideX (e.g.
CUSTOM_VBXes and OCX objects), this appendix does not deal with applying
properties to them. See:
CUSTOM_VBX Create/Control VBX, p. 56(d)

OCX Interface Define Windows Object, p. 294(d
Examples
The examples below illustrate some of the uses you can make of properties.
->MULTI_LINE 100,@(10,10,40,1)
->LET X=100
->PRINT X*
Auto,BackColour,Col,Cols,CtlName,Enabled,Eom,Fmt,Focus,Font,Height,hWnd,Key,Le
ft,Len,Line,Lines,Lock,Msg,Nul,OnFocusCtl,Parent,Sep,TextColour,Tip,Top,Value,
Visible,Width,
->LET XCols=50 ! Multiline adjusts to 50 columns wide
->PRINT XhWnd ! Windows Handle of this particular multiline=208 (values vary)
208
Example in Nomads:
OBJECT: CUST_NAME Defined as Multi_line 30 wide x 1 high
->PRINT CUST_NAME.CTL*

Auto,BackColour,Col,Cols,CtlName,Enabled,Eom,Fmt,Focus,Font,Height,hWnd,Key,Le
ft,Len,Line,Lines,Lock,Msg,Nul,OnFocusCtl,Parent,Sep,TextColour,Tip,Top,Value,
Visible,Width,
->LET CUST_NAME.CTLTip$="This is a NEW Customer Name Tip"
Dynamic Changes:
The next example shows how you can dynamically change properties of one object, based on the value of
another:
IF COUNTRY$ = "CDN" \
THEN ZipFmt$="A0A 0A0" \
ELSE ZipFmt$="00000"
Manipulating Ranges in a GRID:

This example creates a GRID containing 10 columns and 5 rows. Then it selects column two, row zero
(which selects the entire column). Changing the value of the property sets the value of all the selected
cells to that value.
->GRID 10,@(10,10,40,5)
->Y=10
->Ycolumnswide=10
->Yrowshigh=5
->Ycolumn=2
->Yrow=0
->Yvalue$="New Data"
Colour Related Properties

To set colour attributes, you can use the basic nine colours, with an optional prefix for LIGHT or DARK for
all except BLACK and WHITE. You can, for example, use LIGHT CYAN but not LIGHT BLACK or DARK
WHITE. You would just specify BLACK or WHITE. The other seven basic colours are: RED, GREEN,
YELLOW, BLUE, CYAN, MAGENTA and GRAY.
When you set a foreground colour, the LIGHT shade of the colour is the default. The DARK shade is the
default when setting background colours. You can override the defaults by using the keywords LIGHT and
DARK.
Exception: GRAY defaults to DARK GRAY for foreground and LIGHT GRAY for background.
You can also use the 24-bit colour palette by setting a true RGB value using the string "RGB:num num
num" where nnn is an integer in the range 0 to 255 representing the values respectively of red, green, and
blue in the composition of your given colour. For instance, "RGB:192 192 192" (equal measures of 192 for
red, green and blue) produces silver.
"RGB:num num num" and "Default"

RGB will use the specific RGB colour specified. Default will use the WINDOWS default colour for your
given context (foreground or background colour).
Object Property Table

The properties available to you for each of the ProvideX common control objects are listed in the "decision
chart" that follows.

Object Properties Multi- List List Tree Drop Var- Var- Button Check Tri- Radio Vert. Horiz. GRID
Line Box View View Box list drop Box state Button Scroll Scroll
and Explanation Box Box Box Bar Bar
Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Align Grid
Text alignment, for
GRID only: TR,
TC, TL, R, C, L,
BR, BC, BL (Top,
Bottom, Right, Left,
Centre)
Auto Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr VScr HScr Grid
Signal on all
changes
1=True, 0=False
Not for BUTTONS,
CHECKBOXES or
TRISTATE.
BackColour Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Background colour
BackColor Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Background color
(US sp.)
BigJump VScr HScr
Big jump amount,
for SCROLLBARS
only
Bitmap Grid
Bitmap to appear in
cell, for GRID only
CellType Grid
For GRID only.
See GRID Cell
Types, p. 580
Col Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Screen position of
control
Cols Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Control width in
column units
Column Grid
Column reference,
for GRID only
ColumnsWide Grid
Number of grid
columns, for GRID
only
ColumnWidth Grid
Column width in
characters, for
GRID only

CurrentColumn Grid
Current input
column, for GRID
only
CurrentItem L-Bx L-Vw T-Vw D-Bx
Current item with
focus/selected
CurrentRow Grid
Current input row,
for GRID only
CtlName Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
See Control Type,
p. 573 for the list of
keywords to use.
Enabled Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Enabled status flag
1=True, 0=False
Eom Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad
Last change
terminator
ExcelStyle Grid
Excel type grid
0=no grid lines,
1=lines
Fmt Multi L-Bx L-Vw T-Vw Grid
Format for
MULTILINES, all
LISTBOX views
and GRIDS
Focus Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad Grid
Focus status
(1=Has focus)
Not for
SCROLLBARS
Font Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad Grid
Font for control/cell
Not for
SCROLLBARS
Height Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Height of control in
pixels
hWnd Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Windows Handle
for control
Id Rad
Radio button to
reference

ItemCount L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr
Number of items in
list
Key Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Hot key to jump to
control
Left Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Left margin in
pixels
Len Multi
Input length, for
MULTILINES only
Line Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Screen position of
control
Lines Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Number of lines
high
Lock Multi Grid
Lock status, for
MULTILINES and
GRIDS only
MaxValue VScr HScr
Maximum
SCROLLBAR
value
Msg Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad Grid
Message line text,
not for
SCROLLBARS
Nul Multi
Null input display
text, for
MULTILINES only.
OnFocusCtl Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad Grid
On Focus CTL
Event, not for
SCROLLBARS
OverlapEnabled Grid
Allow cells to
overlap, for GRID
only
1=Yes, 0=No
Parent Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Parent Window
Handle

Resizable Grid
Allow user to resize
GRID
1=Yes, 0=No
Row Grid
GRID row
reference
RowHeight Grid
Height of GRID row
in lines
RowsHigh Grid
Number of rows in
GRID
SelectCount L-Bx L-Vw T-Vw Grid
Number of items/
cells selected, for
all LISTBOX views
and for GRIDS
SelectIndex L-Bx L-Vw T-Vw Grid
Index to
SelectItem, for all
LISTBOX views
and for GRIDS.
For Multi-select list
boxes, returns
values base 1 (Ver.
4.20).
SelectItem L-Bx L-Vw T-Vw
Item # in list that is
selected, for all
LISTBOX views
SelectLength Multi V-Lst V-Dr
(Ver. 4.20) Length
of current selected
or highlighted item
in input region
SelectOffset Multi V-Lst V-Dr
(Ver. 4.20) Where
the highlight begins
within the data, or
the current cursor
location if an item
is not highlighted
SelectText Multi V-Lst V-Dr
(Ver. 4.20) The
current selected or
highlighted text.

Sep Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Grid
Field/Column
separator char., not
for BUTTONS,
CHECK BOXES,
SCROLLBARS
SepLoad L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Grid
Separator char. for
each row
SmallJump VScr HScr
SCROLLBAR small
jump value
SwapEnabled Grid
Column swap
allowed
1=Yes, 0=No
Text L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad Grid
Text of item or
label, not for
MULTILINES,
SCROLLBARS
Tbl L-Bx D-Bx Chk Tri Rad
Translation table
TextColour Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Foreground text
colour
TextColor Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Foreground text
colour (US Sp.)
Tip Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad
Tip message, not
for SCROLLBARS
or GRIDS
Top Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Top of control in
pixels
Value Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Current item/cell
value, not for
BUTTONS
Visible Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Control visible flag
1=Yes, 0=No
Width Multi L-Bx L-Vw T-Vw D-Bx V-Lst V-Dr Btn Chk Tri Rad VScr HScr Grid
Width of control in
pixels

Using Cut-and-Paste Properties (Ver. 4.20)
As of Ver. 4.20, SelectOffset, SelectLength and SelectText have been added (see the chart
above) to allow you to query, insert or delete selected / highlighted text in MULTI_LINE, VARDROP_BOX
and VARLIST_BOX input regions. You can use these three properties to replace text programmatically
(i.e. to cut / copy and paste via your programs).
GRID Cell Types

Your GRID cell type can be one of the values listed in the following chart:
GRID Cell Type Explanation

"Normal" Normal text cell containing one line of data
"Multi_line" Normal text cell that can contain multiple lines of text
"Ellipsis" Normal text cell that will display "..." if text exceeds displayable area
"Button" A cell that works like a button if clicked. Text in cell can be changed if not
locked and user double clicks.
"CheckBox" A check box with no 3D effect ( Value = 0 or 1, Text = label)
"CheckBoxRaised" A 3D check box that looks raised
"CheckBoxRecessed" A 3D check box that looks recessed
"CheckMark" A check box that uses a check mark
"CheckMarkRaised" A raised check box that uses a check mark
"CheckMarkRecessed" A recessed check box that uses a check mark
"DropBox" A text cell that allows user to make a selection from a drop down list when
editing. The drop list is loaded from the Text$ attribute.
"DropBoxHideBtn" Same as "DropBox" but the drop down button is shown only when focus is
on the cell.

File Options
Appendix: File Options
Description:
File options are allowed with some (but not all) directives and system functions described in this Language
Reference. A file option is a condition you can include in a directive or system function to fine tune your
code and redirect processing. You can use file options, for instance, to handle exceptions, set the position
of the key, deal with data errors, etc..
List of Standard File Options

Refer to the individual directives and functions to see which file options are allowed. These can include :
BSY=stmtref To trap Error #0: Record/file busy (Ver. 4.10)

DIR=num Direction indicator (not supported by WindX)
KNO=key_num File access key to use, range 0 to 15 (primary or alternate key)
Example:
READ (chan,dom=NoRec,bsy=InUse,Err=Unknown)recdata$
See also: About File OPEN Options, p. 300.
BSZ=num Block size
IOL=iol_ref Default IOLIST
ISZ=num File open for access in binary mode
OPT=string$ File open options
REC=var$ Record prefix
NOTE: You can use KEY\="?" to obtain a list of databases (tables) defined in ProvideX
ODBC. The maximum value for the KNO=option has been increased to 64 for ODBC
file handling.

Labels: Logical Statement References
Appendix: Statement Labels
Format:
ProvideX Built-in Label *keyword
Where =
*keyword Keyword for a built-in ProvideX label (logical statement reference). The keywords that
are currently supported are listed in a chart, below. Include the asterisk.
Description:
ProvideX supports the use of logical statement references (labels) in lieue of line number references in
your applications (Ver. 4.01). You can use the following built-in labels (keywords, with the leading
asterisk) wherever you would use a statement reference (line number or line label). Note that some of the
logical statement labels and the directives they emulate will remove an item from your stack and perform a
RESET:
Keyword Purpose:
*BREAK Emulates a BREAK Immediate Exit of Loop, p. 26(d).
*CONTINUE Emulates a CONTINUE Initiates Next Iteration of Loop, p. 48(d).
*END Emulates an END Halt Execution of Program, p. 112(d).
*ESCAPE Emulates an ESCAPE Interrupt Program Execution, p. 128(d).
*NEXT Goes to the beginning of the next line/statement
*PROCEED Continues to the next statement in a compound statement or to the beginning of the
next line
*RETRY Emulates a RETRY Re-Execute Failing Instruction, p. 362(d).
*RETURN Emulates a RETURN Return from a Subroutine, p. 363(d).
*SAME Goes to the start of current line/statement.
NOTE: Prior to Ver. 4.20, the *CONTINUE and *BREAK labels and the corresponding
directives are not supported for use with SELECT / NEXT RECORD directives. As of
Ver. 4.20, you can use BREAK and *BREAK commands in SELECT structures.
Examples:
The statements that follow illustrate an assignment operator used in conjunction with a post-increment
and built-in ProvideX logical statement labels:
A=0, Y$=""
READ (1,IND=A++,ERR=*NEXT)X$; Y$+=X$; GOTO *SAME
Y$+=RCD(1,IND=A++,ERR=*NEXT); GOTO *SAME
See also: Operators Supported in ProvideX, p. 587.

Negative CTL Definitions
Appendix: Negative CTL Definitions
Description:
ProvideX normally handles all negative CTL values internally. Values are used as follows:
-1 to -999 are used by the input handler to save current instructions, internally call "*CONTROL".
-1000 to -1999 are used for input editing control keys and mouse interaction.
-2000 to -2255 are used for composite character generation.
List of Negative CTL Values

All values below -2255 are reserved for future expansion. See the table below for a list of values.
Negative CTL# Assigned Value Negative CTL #

-1 Invoke utility sub-menu
-2 Invoke screen print utility
-3 Reserved
-4 Display session statistics
-5 Field help
-6 Field query
-7 Program help
-8 Reserved
-9 Reserved
-10 Save current instruction and screen, then call user program $CTL-nnn (-nnn =
to CTL value). Upon exit reset screen and re-execute saved instruction
-999
-1000 Ignore key
-1001 Generate ESCAPE/Break
-1002 Clear input buffer and blank on screen
-1003 Backspace and delete prior character
-1004 Backup one position to left
-1005 Forward one position to right
-1006 Insert a blank at current position
-1007 Delete character at current position
-1008 Skip to next blank character
-1009 Toggle INSERT mode
-1010 Return to start of input (Home)
-1011 Up a line
-1012 Down a line
-1013 Page UP
-1014 Page DOWN

-1015 Tab forward 10 spaces
-1016 Tab backward 10 spaces
-1017 Return to start end reinput
-1018 Go to END of input
-1019 Shift screen to the LEFT
-1020 Shift screen to the RIGHT
-1021 Advance to start of next word
-1022 Go back to start of previous word
-1023 Clear from cursor to end of input
-1024 Restore input line to original value
-1025 Go Home and reset default
-1026 Reserved for future use
to
-1079
-1080 Left mouse down/drag
-1081 Left mouse up
-1082 Reserved for Right mouse down/drag
-1083 Reserved for Right mouse up
to
-1098
-1099 Reject keystroke and ring bell
-1100
-1101 Lost Focus
-1102 Received Focus
-1103 Display Cursor
-1104 Focus has changed
-1105 Window resized
-1106
to
-1199
-1200 Context-sensitive help
-1201
to
-1299
-1300 Start trace window
-1301 Start command window
-1302 Start watch window
-1303 Start breakpoint window

-1304
to
-1309
-1310 End trace
-1311 End command window
-1312 End watch window
-1313 End breakpoint window
to
-1399
-1401 to -1403 MESSAGE Bar Region <Left-mouse-click> Events (Ver. 4.20)
<Left-mouse-click> CTL events are now supported in the MESSAGE bar region.
ProvideX returns CTL values when the user clicks on a segment in the MESSAGE
bar region (Ver. 4.20). Each of the four possible segments of the MESSAGE bar
region has been assigned a different negative CTL value. The event is reported on
the button UP only.
1st area (segment zero) returns CTL= -1400
2nd area (segment 1) returns CTL= -1401
3rd area (segment 2) returns CTL= -1402
4th area (segment 3) returns CTL= -1403
See also: 'MESSAGE' Define MESSAGE Line, p. 518(m).

-1404 to -1408 Reserved for future use
-1409 ToolBar <Mouse-Click> Events (Ver. 4.20)
<Mouse-click> CTL events are now supported in the Toolbar region. The event is
reported on the button UP only.
<Left-Mouse-button-up> returns CTL= -1409
(<Right-Mouse-button-up> returns CTL= -1419)
-1410 to -1413 MESSAGE Bar Region <Right-mouse-click> Events (Ver. 4.20)
<Right-mouse-click> CTL events are now supported in the MESSAGE bar region.
ProvideX returns CTL values when the user clicks on a segment in the MESSAGE
bar region (Ver. 4.20). Each of the four possible segments of the MESSAGE bar
region has been assigned a different negative CTL value. The event is reported on
the button UP only.
1st area (segment zero) returns CTL= -1410
2nd area (segment 1) returns CTL= -1411
3rd area (segment 2) returns CTL= -1412
4th area (segment 3) returns CTL= -1413
See also: 'MESSAGE' Define MESSAGE Line, p. 518(m)

-1419 ToolBar <Mouse-Click> Events (Ver. 4.20)
<Mouse-click> events are now supported in the Toolbar region. The event is
reported on the button UP only.
<Right-Mouse-button-up> returns CTL= -1419
(<Left-Mouse-button-up> returns CTL= -1409)

-1802 to -1803 <Right-mouse-click> Change (Ver. 4.20):
<Right-mouse-clicks> no longer issue CTL=4. A <Right-mouse-button-down>
returns CTL= -1802, while the <Right-mouse-button-up> returns CTL=-1803
Changed in *DEV/WINDOWS and *DEV/WINTERM
-1900 Input Timeout (NOMADS Internal)
-1999 Users window_close request. By default, ProvideX maps this to CTL=4 (in "*dev/
windows"). You can test for CTL=4 in your programs, or you can use DEFCTL to
remap -1999 to a different CTL.
Example:
DEFCTL -1999=10 ! Maps the <F10> key (CTL=10) for close
TIP: You can test the EOM system variable to find out whether the
user pressed the actual Function key or selected one of the
Close options (i.e. the WINDOWS {X} icon). HTA(EOM) returns
$00800004$ for <Alt-F4> or $0080F831$ for the Close option.
See also: 'F4' Return CTL=4 for Exit, p. 544(p)
EOM End of Message Character String, p. 120(v)

-2000 Composite Character Generation
to
Whenever ProvideX detects a CTL value in this range, the character whose ASCII
-2255
value equals the absolute value of CTL less 2000 is placed into the input buffer.
This feature allows you to define input sequences to generate the Extended ASCII
characters even when the terminal cannot generate them.
-2256 Reserved for future expansion
and
below
NOTE: CTL values of -32001 through -32767 and 32001 through 32767 are reserved
internally within ProvideX for use in OCX handling (Ver. 4.20). Please do not use CTL
values in these ranges.

Operators Supported in ProvideX
Appendix: Operators
Description:
This appendix describes the traditional assignment operators (e.g. + - * /) you can use in ProvideX, along
with other operators for which support has been added in recent versions (e.g. the apostrophe operator, C
style operators, the LIKE operator).
Apostrophe: Property Operator

Use the apostrophe operator to set attributes or properties for objects (Ver. 4.10). See the section on
Dynamic Control Object PROPERTIES, p. 572 for detailed information on properties and for formats
using the apostrophe operator.
Assignment Operators
Six assignment operators are included in the general syntax of the language:
Operators Meaning
+= Add to. Can be used with numerics or strings:
Numeric example: A+=1 is the same as A=A+1.
String example: A$+="G" is the same as A$=A$+"G".
-= Subtract from. Not valid for strings.
Numeric only: B-=A+1 is the same as B=B-(A+1)
*= Multiply by. Can be used with numerics or strings.
Numeric example: B*=A+1 is the same as B=B*(A+1)
String example: A$*=5 is the same as A$=A$+A$+A$+A$+A$
/= Divide by. Not valid with strings.
Numeric only: B/=A+1 is the same as B=B/(A+1)
^= Exponentiation. Raise to. Not valid with strings.
Numeric only: B^=A is the same as B=BÂ
|= Modulus / remainder from division. Not valid with strings.
Numeric only: B|=A is the same as B=MOD(B,A)
Auto-Increment and Decrement

In addition to the assignment operators, there are decrement and increment features:
Increment/r Explanation
Decrement
++ Auto-increment (pre-increment when prefixed to variable name, post-increment if
suffixed). For example, ++variable or variable++.
-- Auto-decrement (pre-decrement when prefixed to variable name, post-decrement if
suffixed). For example, --variable or variable--

NOTES: If an error occurs during execution of your directive, no increment or decrement
takes place. (This is true for both pre- and post- operations.)
With PRE-increment or decrement, the value returned is the value of the variable
after the increment or decrement. With POST-increment or decrement, the value
returned is the value of the variable before the increment or decrement. After your
directive is executed, your variable is incremented or decremented by 1.
Example:
The statements below illustrate an assignment operator used in conjunction with a post-increment and
logical statement labels:
A=0, Y$=""
READ (1,IND=A++,ERR=*NEXT)X$; Y$+=X$; GOTO *SAME
or
Y$+=RCD(1,IND=A++,ERR=*NEXT); GOTO *SAME
See also: Labels: Logical Statement References, p. 582.
LIKE Operator
Format:
Compare Strings string$ LIKE mask$
Description:
Use the English-like LIKE operator for string comparisons (Ver. 4.10). The ProvideX default (with the TL
System Parameter set to OFF) is to take the string expression on the left and compare it to the string mask
on the right. In the default mode, you can apply all the regular expression rules of the MSK( ) function to
using the LIKE operator. The format you use is illustrated below:
IF A$ LIKE "ABC" THEN ...
To make your conversions from Thoroughbred easier, set the TL System Parameter ON. With this
parameter ON, the LIKE operator emulates the Thoroughbred matching of patterns.
See also: MSK( ) Scan String for Mask, p. 274(f)
SET_PARAM Set System Parameters, p. 379(d)
TL LIKE Emulates Thoroughbred, p. 559(p)

Specialty *File* Handling
Appendix: Specialty *Files*
Description:
ProvideX supports the use of a series of specialty files, listed below. These are special files ProvideX will
recognize in an OPEN directive and will deal with internally in the language at RUN time. Theyre
described in alphabetical order in the following sections to give you information on specialty file handling.
NOTE: Include the asterisks with these filenames.
Specialty File Type

*MEMORY* Memory-resident logical file. See *MEMORY* Create & Use Memory File,
p. 590 for instructions on handling this specialty file.
*VIEWER* Special device file that allows you to preview print jobs. See *VIEWER*
Device File: Print Preview, p. 591.

*WINDEV* Special device file that provides access in RAW or PASS THROUGH mode to
the WINDOWS print subsystem. See *WINDEV* Device File: RAW Mode
Printing, p. 593.

*WINPRT* Special device file that provides standard API access to the WINDOWS print
subsystem. See *WINPRT* Device File: Windows Printing, p. 596.

*MEMORY* Create & Use Memory File
Specialty File "*MEMORY*"
Formats:
1 Create Memory File OPEN (chan[,fileopt])"*MEMORY*"
Where =
chan Channel or logical file number to assign to the file.
*MEMORY* Keyword, not case-sensitive. Logical file name, enclosed in quotation marks for
your OPEN directive. (Include the asterisks in the syntax.)
fileopt File options. Valid options OPENing *MEMORY* include:
IND=record_index
KEY=key_value
DOM=statement reference when you WRITE to a memory file
BSZ=bytes. You can use an optional BSZ= assignment to specify record
size (number of bytes). The default record size is 1,024 bytes
unless you override it with the BSZ= option.
string$ or iol_ref Records value to WRITE or READ. You can use a string expression, an iolist or
a string variable for the contents of the record.
Description:
ProvideX supports a memory-resident logical file called *MEMORY* (Ver. 4.01). This file is basically a
memory-resident queue of records. ProvideX recognizes *MEMORY* at RUN time and deals with it
internally.
Once *MEMORY* is OPEN, you can gain I/O access to memory-resident records in the same manner as
you can to DIRECT files - by record index or by key, using the following I/O directives:
WRITE Add/Update Data in File, p. 477(d)
WRITE RECORD Add/Update Record in File, p. 480(d)
CLOSE Close File, p. 47(d)
MERGE Read/Append Lines from File, p. 259(d)
REMOVE Delete Record from File, p. 355(d)
NOTE: You can use the KEY( ), KEP( ), KEL( ), KEF( ), KEN( ), IND( ) and RNO( ) functions with
memory-queue files.
See also: DIRECT Create File with Keyed Access, p. 88(d)
Create *Memory* File: OPEN (chan)"*MEMORY*"[,BSZ=bytes]

Create your memory-queue file and assign your given logical file number (channel) by OPENing it.
(CLOSE (chan) to delete a *memory* file.) Note that *memory* is not case-sensitive, but the asterisks
are required, e.g. OPEN (14)"*Memory*".

*VIEWER* Device File: Print Preview
Specialty File *VIEWER*
Format:
1 OPEN for Preview OPEN (chan)*VIEWER*

2 Using WindX CALL "*windx.utl;spawn","*VIEWER* -XT=1 -ARG filename[ DELETE]"
3 Command Line <your_path>\pvx\pvxwin32.exe *VIEWER* -XT=1 -ARG filename[ DELETE]
Where =
chan Channel or logical file number, e.g. OPEN (1)"*viewer*"
*VIEWER* Keyword. Special interface filename. Include the asterisks in the syntax.
\pvx\pvxwin32.exe Command to launch ProvideX. See also: Command Line, Launching
ProvideX, p. 569
*windx.utl;spawn ProvideX utility;function. See also: Format 8: [WDX] and *WindX.utl:, p. 630.
filename$ Name of the file that the print job is stored in or being spooled to. The file must
be a SERIAL file and NOT locked. See SERIAL Create a Sequential File, p.
375(d).
Use 'LU' Lock Unnecessary: Sequential WRITE, p. 549(p) to override the

normal requirement that a SERIAL file be locked.
DELETE Optional. Use the DELETE keyword to tell ProvideX to erase the file when the
viewer closes.
Description:

The *VIEWER* is a special device file that allows you to preview reports You can view print jobs as they
spool and use the zoom capability. You can also copy reports to the CLIPBOARD.
Here are the *VIEWER*s capabilities:
captures a print job to a file
can view currently spooling print jobs, or print jobs stored on the disk
is WindX-aware and works on the local WINDOWS client
has four zoom in/out states
will GoTo: Page, First Page, Last Page, Previous Page, Next Page, Specific Page Number
can text search
allows you to copy to CLIPBOARD
allows you to view a job while its still spooling.
Format 1 OPENs for Print Preview: OPEN (chan)*VIEWER*

The example below illustrates OPENing and using the *VIEWER*.
0010 LET CHAN=UNT; OPEN (CHAN)"*VIEWER*"

0020 PRINT (CHAN)'FONT'("Courier New",-10),'DF',
0030 PRINT (CHAN)'FONT'("Arial",2),'TEXT'(@X(2),@Y(2),"Fonted Text"),
0040 PRINT (CHAN)'PICTURE'(@X(3),@Y(5),@X(43),@Y(30),"*win/nomads2"),
NOTE: Set 'BM' Begin Output of Markup Files, p. 496(m) to ON to have the *VIEWER* send
all data directly to the print file without interpretation. This allows you to send print

jobs to any Windows printer that is available on the client PC. The *VIEWER* filters
out the first and/or last page if either is blank.
Number of Columns: Example

The *VIEWER* does not return values for maximum column / line, i.e. in MXC( ) and MXL( ) functions.
The following example illustrates how to approximate the number of columns:
CHAN=UNT; OPEN (CHAN)"*WINPRT*"

POINTSZ=-10
LOOP:
PRINT (CHAN)'FONT'("Courier New",POINTSZ),'DF',
IF MXC(CHAN)<132 THEN POINTSZ+=2; GOTO LOOP
LINES=MXL(CHAN),COLS=MXC(CHAN)
PRINT (CHAN)'AB', ! <--- aborts print job
CLOSE (CHAN)
OPEN (CHAN)"*VIEWER*"
PRINT 'FONT'("Courier New",POINTSZ),'DF',mn/line)

*WINDEV* Device File: RAW Mode Printing
Specialty File *WINDEV* RAW Mode
Format:
1 OPEN Device File OPEN (chan[,fileopts])"*WINDEV*[;Q_name]"

2 OPEN for Read Only OPEN INPUT (chan[,fileopts])"*WINDEV*[;Q_name]"
3 OPEN for [WDX] OPEN [INPUT] (chan[,fileopts])"[WDX]*WINDEV*[;Q_name]"
Where =
chan Channel or logical file number, e.g. OPEN (14)"*windev*"
fileopts File options. Valid options for OPENing *WINDEV* include:
OPT=char$ File OPEN options. See About File OPEN Options, p. 300.
You can use OPT( ) Return File OPEN Options, p. 303(f) in your applications to
obtain the current OPT= value.
[WDX] *WINDEV* is specific to WINDOWS operating systems.
Under UNIX, ProvideX automatically directs *WINDEV* access to the WindX client:
OPEN (14)"*windev*" ! For the PC client from UNIX host
In a WINDOWS NT environment, you are opening the *WINDEV* printer relative to the
host unless you prefix the printer name with the [WDX] tag. For example:
OPEN (14)"*windev*" ! For the NT host
OPEN (14)"[WDX]*windev*" ! For the NT PC client
*WINDEV* Keyword. Special device filename. Include the asterisks.
Q_name Print queue to OPEN. (If you omit the queue name, a printer selection dialogue will
appear at RUN-time to let your user select the printer and its properties.) Valid
Q_name options include:
O/S name of an existing physical print queue on the local WINDOWS machine:
open(14)"*WINDEV*;HP LaserJet"
O/S name of print queue ON resource (UNC, Format: ON \\machine\resource
for any shared resource or ON LPT# for direct local access to a port):
OPEN (14)"*WINDEV*;HP LaserJet on \\Main_Server\HP
Laser"
OPEN (14)"*WINDEV*;LP on LPT1"
Or you can use one of the queue selection keywords:
ASIS Most recently selected printer and properties
DEFAULT Printer currently "Set As Default" in the system. For example,
OPEN (30,ERR=9900)"*WINDEV*;DEFAULT"
NORMAL Normal dialogue with page range (no paper size / source tray)
SETUP Setup dialogue with paper size, source tray (no page range)
The Q_name is optional. The *WINDEV* directive doesnt support setting queue
options (graphical printer properties in the WINDOWS Printer Dialogue box such as:
orientation=landscape;copies=3).
Description:

Use *WINDEV* with your OPEN and/or OPEN INPUT directives to gain access to the WINDOWS print

subsystem in RAW or PASS THROUGH mode.
You can identify the LPT for direct local access to the port or use UNCs (Universal Naming Conventions)
for transmissions to a shared resource. For both LPT and UNC use, note that you can use raw escape
sequences but graphical printing is not supported. LPT identification is not recommended under
WINDOWS NT.
Normally, you can take advantage of *WINDEV* to send data to the printer without having the driver strip
out escape codes (for instance, to pass PCL code to the printer). That is, you CAN use escape sequences
with *WINDEV*, but these must be both valid and supported by your given printer and print driver.
ProvideX recognizes *WINDEV* as a special device file in your OPEN [INPUT] directive and deals with it
internally in the language at RUN-time. ProvideX returns an Error #12: File does not exist
(or already exists) on the OPEN if no printers are installed or if the user presses the {Cancel}
button in a printer selection dialogue. (This error can also occur if no printer is "Set As Default".)
RAW Printing Behaviour

ProvideX supports RAW mode to send raw data to a WINDOWS printer (Ver. 4.10). You can control the
mode by using the RP (Raw Printing) system parameter. This parameters default is ON. When you turn
it OFF, ProvideX uses the old PASS THROUGH mode.
See also: RP *WINDEV* Raw Print (WindX / WINDOWS Only), p. 556(p)
The printer drivers shouldnt (but might) strip escape sequences from the data you send to *WINDEV*.
Support for RAW mode is printer/driver-dependent. Some drivers do "eat" certain escape sequences,
removing them from the data stream. If escape sequences disappear from your *WINDEV* print jobs,
check the sequences for validity and check printer/driver appetites with their manufacturers.
Format 1 to OPEN Device File: OPEN (chan[,fileopts])"*WINDEV*[;Q_name]"

Use this format to OPEN the *WINDEV* device file to pass print jobs through in RAW mode to the given
queue on your OPEN channel. See also: Examples: *WINPRT* / *WINDEV* Printing, p. 602.
NOTE: Some device drivers issue an extra blank page (some even hang) if an OPEN channel
is CLOSEd too quickly or if nothing is printed to the channel before its CLOSEd. You
can use an OPEN INPUT directive (described next) to bypass problems of this nature.
Format 2 for READ-Only Mode: OPEN INPUT (chan[,fileopts])"*WINDEV*[;Q_name]"

Use the OPEN INPUT directive to open *WINDEV* in read-only mode when you only want to determine
the name and properties of a printer without sending a physical job. With an OPEN INPUT directive, you
can OPEN the printer, query the printers properties and CLOSE the channel without starting a physical
job.
For example, you can use a WINPRT_SETUP READ PROPERTIES directive or MXC( ) and MXL( )
functions without generating a FormFeed:
0100 IF WDX%<>$00$ THEN OPEN INPUT (30)"*WINDEV*;ASIS"
C=MXC(30)+1 ! Zero-based. For this printer MXC(30)=79, C=80 (0-79 columns)
L=MXL(30)+1 ! Also zero-based.
WINPRT_SETUP READ PROPERTIES WHAT_PROP$
! WHAT_PROP$ returns printer-specific list (items such as COPIES=1,OFFSET=0:0)
NOTE: The FONT mnemonic works with *WINPRT* but not with any of the character-mode
printers. To control fonts on a text mode device, send raw escape sequences to the
printer using *WINDEV*, UNC (Universal Naming Conventions) or direct access to
LPT ports. Note that your choice of fonts with *WINDEV*, UNC or an LPT is limited
to the fonts supported by the given printer.

See also: WINPRT_SETUP Windows Printer Setup, p. 472(d)
MXC( ) / MXL( ) Return Maximum Column/Line, p. 283(f)
Format 3, [WDX]-Enabled: OPEN [INPUT] (chan[,fileopts])"[WDX]*WINDEV*[;Q_name]"

On an NT or PC server, if you include [WDX] in your OPEN [INPUT] directive (e.g. OPEN
(30)"[WDX]*WINDEV*"), then that signals ProvideX to direct any print jobs and dialogues to the WindX
client PC, which will in turn use its WINDOWS print subsystem to send jobs to the given printer.
If you are using *WINDEV* on an NT Server and do not use [WDX] in your OPEN directive, then:
the printer selection dialogue will appear on the server console, and
any print queue you name directly must exist on the NT server in the Control Panel printers
folder.
Reminder: You must install and use WindX to use *WINDEV* in a UNIX environment, but you
dont need the [WDX] tag on a UNIX server because ProvideX automatically directs
*WINDEV* access to your WindX client PC.
See also: Examples: *WINPRT* / *WINDEV* Printing, p. 602

*WINPRT* Device File: Windows Printing
Specialty File *WINPRT*
Format:
1 OPEN OPEN (chan[,fileopts])"*WINPRT*[;Q_name[;Q_options]]"

2 Read Only OPEN INPUT (chan[,fileopts])"*WINPRT*[;Q_name[;Q_options]]"
3 Using [WDX] OPEN [INPUT] (chan[,fileopts])"[WDX]*WINPRT*[;Q_name[;Q_options]]"
Where =
chan Channel or logical file number, e.g. OPEN (14)"*winprt*"
fileopts File options. Valid options for OPENing *WINPRT* include:
You can use the function OPT( ) Return File OPEN Options, p. 303(f) in your
applications to obtain the current OPT= value.
[WDX] *WINPRT* is specific to WINDOWS operating systems.
Under UNIX, ProvideX automatically directs *WINPRT* access to the WindX client:
OPEN (14)"*winprt*" ! For the PC client under UNIX
In a WINDOWS NT environment, you are opening the *WINPRT* printer relative to the
host unless you prefix the printer name with the [WDX] tag. For example:
OPEN (14)"*winprt*" ! For the NT host
OPEN (14)"[WDX]*winprt*" ! For the NT PC client
*WINPRT* Keyword, not case-sensitive. Special device filename. Include the asterisks.
Q_name Print queue to OPEN. String expression or keyword. (If you omit the queue name, a
printer selection dialogue will appear at RUN-time to let your user select the printer and
its properties.) Valid Q_names include:
O/S name of an existing physical print queue on the local WINDOWS machine
as in OPEN (14)"*WINPRT*;HP LaserJet"
O/S name of print queue ON resource (UNC, Format: ON \\machine\resource
for any shared resource or ON LPT# for direct local access to a port):
OPEN (14)"*WINPRT*;HP LaserJet on \\Main_Server\HP
Laser"
OPEN (14)"*WINPRT*;LP on LPT1"
OR you can use one of the queue selection keywords:
ASIS Most recently selected printer and properties
DEFAULT Printer currently "Set As Default" in the system. For example,
OPEN (30,ERR=9900)"*WINPRT*;DEFAULT"
NORMAL Normal dialogue with page range (no paper size / source tray)
SETUP Setup dialogue with paper size, source tray (no page range)
The Q_name is optional unless you want to assign or override queue properties
(Q_options, below). Then, Q_name is mandatory in your directive.
See also: Examples: Queues for *WINPRT* / *WINDEV*, p. 599.

Where =
Q_options Printer properties. String expressions. You can override printer- / driver-specific values
by assigning a new value to the queue (e.g. copies=2 instead of copies=1). Use
semicolons to separate items if you have a list.
Q_options must be preceded by a Q_name (i.e. HP LaserJet in the example below,
or a queue keyword like DEFAULT). See WINPRT_SETUP Properties, p. 472 and
*WINPRT* and *WINDEV* Properties, p. 600.
Example:
open(30)"*WINPRT*;HP LaserJet;orientation=landscape;copies=3"
Description:

Use *WINPRT* with your OPEN and/or OPEN INPUT directives to gain standard API access to the
WINDOWS print subsystem.
The device driver for your given printer interprets the data you send to the *WINPRT* channel, then sends
the output to the WINDOWS spooling subsystem for transmission to its destination. You can identify the
LPT for direct local access to the port or use UNCs (Universal Naming Conventions) for transmissions to a
shared resource. LPT identification is not recommended under WINDOWS NT.
ProvideX recognizes *WINPRT* as a special device file in your OPEN [INPUT] directive and deals with it
internally in the language at RUN-time. ProvideX returns an Error #12: File does not exist
(or already exists) on the OPEN if no printers are installed or if the user presses the CANCEL
button in a printer selection dialogue. (This error can also occur if no printer is "Set As Default".)
Some printer device drivers are unable to handle invalid Q_options (i.e., unknown property assignments
and/or syntax errors such as range=1,5 instead of the correct range=1:5). The result can be
unpredictable. The driver can even cause your ProvideX session to hang during the OPEN. If you
encounter unexpected problems, invalid Q_options for the given driver are the likely cause.
NOTE: Escape sequences are NOT allowed with *WINPRT* and may have an unpredictable
effect on the device and/or printer driver. If you need access to the print subsystem
to send PCL, escape sequences, etc., use *WINDEV* Device File: RAW Mode
Printing, p. 593.
Format 1 to OPEN Device File: OPEN (chan[,fileopts])"*WINPRT*[;Q_name[;Q_options]]"

Use this format to OPEN the *WINPRT* device file. ProvideX will recognize and deal with this special
device file at RUN time to give you access to the WINDOWS print subsystem. Then you can send print
jobs to the given queue on your OPEN channel. See also: Examples: *WINPRT* / *WINDEV* Printing, p.
602.
NOTE: Some device drivers issue an extra blank page (some even hang) if an OPEN channel
is CLOSEd too quickly or if nothing is printed to the channel before its CLOSEd. You
can use an OPEN INPUT directive (described next) to bypass problems of this nature.
Format 2 for READ-Only Mode: OPEN INPUT (chan[,fileopts])"*WINPRT*[;Q_name[;Q_options]]"

Use the OPEN INPUT directive to open *WINPRT* in read-only mode when you just want to determine
the properties (Q_options) and attributes of a printer without sending a physical job. With an OPEN INPUT
directive, you can OPEN the printer, process your queries and CLOSE the channel without starting a
physical job.

Examples:
For example, you can use a WINPRT_SETUP READ PROPERTIES directive, a FONT(LIST) graphics
mnemonic or MXC( ) and MXL( ) functions without generating a FormFeed:
IF WDX%<>$00$ THEN OPEN INPUT (30)"*WINPRT*;ASIS"
X$=FONT(LIST*,30) ! Get font list
-:?X$
System,Fixedsys,Terminal,MS Serif,MS Sans Serif,Courier,Symbol,Small Fonts,
Modern,FrameMakerSmallFont,Marlett,Arial,Courier New,Times New Roman, ... etc.
NOTE: The FONT mnemonic works with *WINPRT* but not with any of the character-mode
printers.
Maximum column and line values are zero-based. The MXC( ) value returned is 79 for 0-79 = 80 columns
in the next example:
C=MXC(30)+1 ! For this printer MXC(30) returns 79, C=80 (0-79)
L=MXL(30)+1 ! For this printer MXL(30) returns 55, L=56 (0-55)
Your string variable in READing PROPERTIES returns a printer-specific list (here, for the ASIS printer):
-:?what_prop$
-:close (30)
See also: *WINPRT* and *WINDEV* Properties, p. 600
WINPRT_SETUP Windows Printer Setup, p. 472(d)
'FONT' Define / List Fonts, p. 509(m)
MXC( ) / MXL( ) Return Maximum Column/Line, p. 283(f)
Format 3 for [WDX]: OPEN [INPUT] (chan[,fileopts])"[WDX]*WINPRT*[;Q_name[;Q_options]]"

On an NT or PC server, when you include [WDX] in your OPEN [INPUT] directive (e.g. OPEN
(30)"[WDX]*WINPRT*"), that signals ProvideX to direct any print jobs and dialogues to the WindX client
PC, which will in turn use its WINDOWS print subsystem API to send jobs to the given printer.
If you are using *WINPRT* on an NT server and do NOT use [WDX] in your OPEN directive, then:
folder.
Reminder: You must install and use WindX to use *WINPRT* in a UNIX environment, but you
dont need the [WDX] tag for a UNIX server because ProvideX automatically directs
access to *WINPRT* to your WindX client PC.
See also: [WDX] Tag: Directs Action to Client Machine, p. 626
Examples: *WINPRT* / *WINDEV* Printing, p. 602.

Examples: Queues for *WINPRT* / *WINDEV*
Specialty Files Examples
Description:
The queue information in this section applies to both *WINDEV* and *WINPRT* device files. The
examples illustrate the formats you can use to designate printer queues and (for *WINPRT* only) assign
values to a printers properties (Q_options).
Queue = Value: Using Queue Name

To select a particular printer, use the actual O/S print queue name in your OPEN directive. The Q_name
you use must match the print queues O/S name (in the Printers folder of the Control Panel on the local
WINDOWS PC, as assigned to the printer when it was installed, e.g. "Bills Desk - Canon").
Omit any mention of ports. For instance, if the Control Panel folder records the name as "HP LasertJet
on LPT1", simply use HP LaserJet as the queue name in your directive.
Examples:
In these examples, because the queue is named in the OPEN directive, the end-users will not see the
printer selection dialogue at RUN-time. (You can use this to advantage if you want to prevent users from
changing the printer and properties during the print run.)
OPEN (30)"*WINPRT*;HP LaserJet"
open (30)"*WINPRT*;Bills Desk - Canon;orientation=landscape;copies=3"
OPEN (30)"*WINDEV*;HP LaserJet;copies=2"
Queue = ASIS Keyword

Use the ASIS keyword to OPEN the most recently selected printer with ALL its settings AS IS. Again, your
users will not have access to the printer selection dialogue at RUN-time and cant alter the settings.
Warning: ALL the settings for the queue options will be identical to the previous selection. For
the examples below, the previous selection was the HP LaserJet, copies=2, so
the ASIS print jobs below are sent to the HP LaserJet using its current property
settings. (All properties, including copies=2 will be identical.)
Examples:
open (30)"*WINPRT*;ASIS"
open (30)"*WINDEV*;ASIS"
For *WINPRT* only, you can override the ASIS queue option settings in your OPEN directive. (Make sure
your properties and values are valid for the given driver.) As examples:
OPEN (30)"*WINPRT*;ASIS;copies=5;offset=500:500"
OPEN (1)"*WINPRT*;ASIS;file=hello.txt"
Queue = DEFAULT Keyword

Use the DEFAULT keyword to OPEN the printer currently "Set As Default". Your users will not have
access to the printer selection dialogue and cant alter your settings at RUN-time. For *WINPRT* only,
you can use queue options to override the current DEFAULTs properties.

Examples:
If the default printer is "Bills Desk - Canon", then the print jobs in the examples below will be sent to
that Canon printer.
open (14)"*WINPRT*;DEFAULT"
open (14)"*WINPRT*;DEFAULT;copies=5;orientation=landscape;offset=300:600"
OPEN (14)"*WINDEV*;DEFAULT"
Queue = NORMAL Keyword

Use the NORMAL keyword in your OPEN directive when you want the user to see the printer selection
dialogue including a page range option (but no paper size or source tray options) at RUN-time. Your users
can accept the current settings or alter them. The current options (including any options you set for
*WINPRT* in your OPEN directive) are displayed in the printer selection dialogue when the user sees it.
Examples:
Note that either open(30)"*WINDEV*" (omitting the queue name) or open (30)"*WINDEV*;NORMAL"
will display the dialogue box so that the user can make changes. However, a queue name (in this case,
NORMAL) is mandatory if you include queue options in a *WINPRT* command. For instance:
open (14)"*WINPRT*;NORMAL;orientation=landscape"
Queue = SETUP Keyword

Use the SETUP keyword in your OPEN directive when you want the user to see the printer selection
dialogue with paper size and source tray options (without the page range option) at RUN-time. The
current options (including any options you set in your OPEN directive for *WINPRT*) are displayed in the
printer selection dialogue when the user sees it.
Examples:
open(30)"*WINPRT*;SETUP"
open(30)"*WINDEV*;SETUP"
open(30)"*WINPRT*;SETUP;range=1:5"
*WINPRT* and *WINDEV* Properties

To retrieve a list of the properties that are valid for a given queue, use Format 2: WINPRT_SETUP READ
PROPERTIES var$, p. 475. For example:
OPEN INPUT (30)"*WINDEV*;ASIS"

-:?what_prop$
-:close (30)
With *WINPRT* only, you can use Q_options in your directive to assign values to the properties the
individual driver allows for your given queue. Most Q_options are self-explanatory, like copies=1. For
detailed information on properties, see WINPRT_SETUP Windows Printer Setup, p. 472(d).
You can obtain information on available fonts for graphics mode printing by PRINTing FONT(LIST *).
This mnemonic is not for character mode. See 'FONT' Define / List Fonts, p. 509(m).

Link Files for Queues: Example
You can use a link file, associating a device or file with a device driver. The device can be any valid device
or file name including any of the Windows printers. The device driver is a ProvideX-based program that
resides in the *DEV directory (or /PVX/LIB/_DEV directory). Link files are maintained with the ProvideX
utility *UCL (Utilities/Configuration/Linkfiles).
The name of the link file can be any valid O/S file name, for example:
Link file name: LP
Device/file name: *WINDEV*;HP Laser Jet
Device driver: HPLASER

Examples: *WINPRT* / *WINDEV* Printing
Specialty Files *WINDEV* / *WINPRT* Printing
Description:
This section gives you some general information, tips and examples for WINDOWS printing.
To Abort: Example
You can abort a print job at any time by PRINTing the mnemonic 'AB' to the printer channel, as in:
PRINT (30)AB ! To cancel the current job.
NOTE: How much data prints when you abort is determined by the printer driver, the
WINDOWS print spooling subsystem and your setting in the print spooler options
"Start Printing After the First Page" or "Start Print After the Last Page".
Look for the name (title bar caption) of your current ProvideX window to find your print job in the
WINDOWS print spooler Job Listing.
Initial Settings: Examples

Before you PRINT data to the *WINDEV* and *WINPRT* special device files, you should always set the
initial font and point size of the printer to a known state and make it the default (using DEFAULT or DF).
See also: 'DEFAULT' Define Mnemonic as Default, p. 502(m)
Example:
open(chan)"*winprt*"
print (chan)'font'("Courier New",-10),'default',
We suggest that you use negative sizes to define specific point sizes (as in PRINT
(1)font("Arial",-7),DF). All standard PRINT statement data will use the selected font, with
spacing based on logical CPI values (pitch). As a guide to equivalent measures:
Point Size = Logical LPI = Logical CPI

-12 =6 LPI =10 CPI
-10 =7.2 LPI =12 CPI
-7 =10 LPI =16 CPI
Column and row addressing are based on the default font. Switching fonts will not alter the column or row
addressing. You can use the CPI and LPI mnemonics to simplify text alignment. The following example
scales the text to allow for 200 characters across but addresses the page based on 132 characters:
0010 FONT$="Times New Roman",COLS_REQD=132,REALLY_SMALL_FONT=200
0020 CHAN=UNT; OPEN (CHAN)"*WINPRT*"
0030 PRINT (CHAN)'FONT'(FONT$,-12),'DF', ! Set base to 10 CPI
0040 CUR_COL=MXC(CHAN)+1,INCHES_WIDE=CUR_COL/10
0050 PRINT (CHAN)'FONT'(FONT$,CUR_COL/REALLY_SMALL_FONT),'DF',
0060 PRINT (CHAN)'CPI'(COLS_REQD/INCHES_WIDE),LPI(6),
0070 FOR Z=0 TO 12
0080 PRINT (CHAN)@(Z*10),"Hello World"
0090 NEXT

Text Mode, Fixed Pitch Font: Example
The example below uses a fixed-pitch font for text mode printing (e.g. for report printing). The application
adjusts the font to allow for the number of columns in COLS_REQD. The MXC( ) and MXL( ) functions
return maximum available column and line for the channel, based on the current default settings for paper
size, printable area, offset, margin, default font height, width, pitch.
0010 LOOP=0,COLS_REQD=132,FONT$="Courier New"

0030 PRINT (CHAN)'FONT'(FONT$,-12),'DF', ! Set Font to 10 CPI
0040 PRINT (CHAN)'FONT'(FONT$,MXC(CHAN)/COLS_REQD),'DF', ! Scale it
0050 IF MXC(CHAN)<COLS_REQD THEN IF LOOP++<5 THEN GOTO 0040
0060 PRINT MXC(CHAN),LOOP
This method of printing works with any WINDOWS printer, with no adjustments necessary for legacy code.
To control fonts on a text mode device, send raw escape sequences to the printer using *WINDEV*, UNC
(Universal Naming Conventions) or direct access to LPT ports. Note that your choice of fonts with
*WINDEV*, UNC or an LPT# is limited to the fonts supported by the given printer.
See also: MXC( ) / MXL( ) Return Maximum Column/Line, p. 283(f)

Mnemonics, p. 486
Text Mode, Proportional Font: Example

Proportional fonts are supported using *WINPRT* and can be scaled to fit the page.
You can print fields individually for proper alignment. That is, use the @(col) position for each element or
field. A dimensioned string like DIM X$(80); X$(1)="Customer",X$(46)=" Balance" would not
be properly aligned. ProvideX left justifies any string variable at the specified column based on the default
font. Decimal alignment is supported for the STR( ) function or format masks. Numeric variables print
right-justified with decimal alignment, provided a format mask is used.
Example:
10 LOOP=0,COLS_REQD=78,FONT$="MS Sans Serif"
30 PRINT (CHAN)'FONT'(FONT$,-12),'DF', ! Set Font to 10 CPI
40 PRINT (CHAN)'FONT'(FONT$,MXC(CHAN)/COLS_REQD),'DF', ! Scale it
50 IF MXC(CHAN)<COLS_REQD THEN IF LOOP++<5 THEN GOTO 0040
60 PRINT (CHAN)@(0),"Customer",@(45)," Balance"
70 PRINT (CHAN)@(0),"Mustangs Unlimited",@(45),19.67:"####,##0.00-"
80 PRINT (CHAN)@(0),"CJ Pony Parts Inc.",@(45),289.67:"####,##0.00-"
You can use text justification mnemonics to override the normal handling of string and numeric data.
Normally, these mnemonics are required only when the individual fields are grouped into a single variable
which is being sent to a printer using a proportionally spaced font.
'JC' Center text
'JD' Right justify, align decimal points
'JL' Left justify text
'JN' Numeric data, right justified
'JR' Right justify text
'JS' Left justify string data
You can use the +S mnemonic to automatically replace the underscore, dash and equals sign ( _ - & =)
with solid underlines. The solid line technique also only applies to fields that are printed separately.

Example:
0010 DIM A$(10,"_"),B$(10,"-"),C$(10,"=")
0020 LET CHAN=UNT; OPEN (CHAN,ERR=*END)"*winprt*"
0030 PRINT (CHAN)'FONT'("MS Sans Serif",1),'DF',
0040 PRINT (CHAN)'+S',@(0),A$,@(12),B$,@(24),C$
GUI API and Mnemonics: Example

Restriction: All access to the WINDOWS print subsystem must use standard WINDOWS print API
calls. Since only ProvideX predefined mnemonics are mapped to WINDOWS API
calls, you are limited to using ProvideX predefined mnemonics.
You can mix and match varying fonts and attributes, use graphics mnemonics (ARC, CIRCLE, FILL,
FONT, FRAME, LINE, PEN, PICTURE, PIE, POLYGON, RECTANGLE and TEXT), and include
text mode printing all on the same page. You can move line positioning (column and row) around as
desired. Printing is page-oriented rather than line-oriented. In GUI API, you can access any part of the
entire page at any time. Top to bottom ordering is not necessary. This also applies when using WindX
under UNIX. The following routine illustrates some of the available graphic mnemonics:
0010 ! Printing Graphics
0030 PRINT (CHAN)'FONT'("Times New Roman",3,"BI"),'BLUE',
0040 PRINT (CHAN)'TEXT'(@X(0),@Y(0),@X(70),@Y(5),"Printing Graphics","C"),
0050 PRINT (CHAN)'PEN'(1,2,4),'ARC'(@X(7),@Y(9.5),@X(1),1,0,180),
0060 PRINT (CHAN)'PEN'(1,3,1),'FILL'(1,4),'RECTANGLE'(@X(2),@Y(9),@X(12),@
0060:Y(13)),
0070 PRINT (CHAN)'PEN'(1,1,7),'LINE'(@X(2.5),@Y(9.5),@X(11.5),@Y(9.5),@X(1
0070:1.5),@Y(12.5),@X(2.5),@Y(12.5),@X(2.5),@Y(9.5)),
0080 PRINT (CHAN)'PEN'(1,2,4),'FILL'(7,1),'CIRCLE'(@X(54),@Y(10),@X(6),1.8),
0090 L=@X(24),R=@X(33),S=@X(4),X=@Y(6),Y=@Y(14)
0100 PRINT (CHAN)'PEN'(1,3,2),'FILL'(1,12),'POLYGON'(L-S*2,X,R+S*4,Y,L,Y,
0100:R-S,X,L,X)
0110 PRINT (CHAN)'PICTURE'(@X(0),@Y(11),@X(40),@Y(18),"*win/nomads2",2),
You can use all of the foreground and background colours with colour printers. Use the PEN & FILL
mnemonics to control the colour settings for graphics mnemonics. The following routine prints each of the
available 16 colours:
0010 ! Colour Printing
0020 FONT$="MS Sans Serif",COLS_REQD=80
0040 PRINT (CHAN)'FONT'(FONT$,-12),'DF', ! Set base to 10 CPI
0050 CUR_COL=MXC(CHAN)+1; IF CUR_COL=0 THEN CUR_COL=80
0060 INCHES_WIDE=CUR_COL/10
0070 PRINT (CHAN)'FONT'(FONT$,CUR_COL/COLS_REQD),'DF',
0080 PRINT (CHAN)'CPI'(COLS_REQD/INCHES_WIDE),'LPI'(6),
0090 FOR Z=0 TO 15
0100 INTENSITY$=TBL(Z>7,"","Light ")
0110 COLOUR$=TBL(MOD(Z,8),"Black","Red","Green","Yellow","Blue","Magenta","Cy
0110:an","White")
0120 COLOUR_MNEM$=ESC+"F"+CHR(ASC("0")+Z)
0130 PRINT (CHAN)@(0),COLOUR_MNEM$,INTENSITY$,COLOUR$
0140 NEXT

[WDX]*WINDEV* Escape Sequences: Examples
If you are opening [WDX]*WINDEV* and defining/creating mnemonics that will send escape sequences to
the printer channel, you must send the mnemonic definitions to the WindX client instead of defining them
on the server. (This is because internally there are actually two channels open: one ProvideX is using to
route printing to WindX and one WindX opens, connected to the actual port on the client. Your mnemonic
is run locally on the servers channel and not sent to WindX for the remote client.)
NOTE: As of Ver. 4.20, WindX supports the use of the MNEMONIC directive via the [WDX]
tag.
To send the mnemonic to the client in older versions of ProvideX / WindX, you can either:
create a device driver containing mnemonic definitions on the WindX client PC and then use a
CALL directive, e.g. CALL [WDX]*dev/your_driver_name or
use an EXECUTE directive from the server side for mnemonic definitions on the client, e.g.
EXECUTE "[WDX]MNEMONIC (LFO)'XX'=....".

Reminder: With *WINPRT*: Escape sequences are NOT allowed and may have an unpredictable
effect on the device and/or printer driver.
With *WINDEV*: You can use escape sequences, but both the validity of sequences
and the printers support for RAW mode (if any) are printer- / driver-dependent.
Pages and FormFeeds in PRINTing

You can access an entire page and PRINT to it. However, you can only PRINT to the current page at any
one time. To complete a page, either use a FormFeed or CLOSE the channel. For proper spooler
operation, dont include leading or trailing FormFeeds within the print job. Spoolers always assume the
paper is at top-of-form when a job begins.
NOTE: A FormFeed is automatically appended to every print job sent.

System Limits
Appendix: System Limits
The following are the preset limits in ProvideX:
System Limit For ProvideX Basic Programs:

14 Digits of accuracy
64999 Highest line number
65535 Maximum program size
32Bit ProvideX Program Sizes (Ver. 4.20)

For all platforms which support 32-bit values (not MS-DOS or Windows16-bit). The
maximum program size has increased from 64K per program to the maximum the OS
allows or 2GBs, whichever is smaller.
Note that there is still a limit of 64999 maximum line numbers. Programs created
beyond 64K will not run on 16-bit platforms.
See also: PZ Suppress Program Size Warning, p. 554(p)
'AI'=num Automatic Line-Numbering Increment, p. 539(p)

255 Longest command line argument list, increased from 80 to 255 bytes (Ver. 4.01)
127 Longest variable name
127 Longest statement label
4095 Longest single statement size
32167 Longest string size
10240 Default record limit.
As of Ver. 4.20, the default record limit has been increased from 4096 to 10240 for
composite IOLISTs when using the CHR type field definition.
1000 Longest Data Dictionary entry 1000 bytes (Ver. 4.01)
64 Megabytes of memory
3 Dimensions for an array
32767 Elements in an array in 32-bit ProvideX (Ver. 4.10). The limit in 16-bit Windows and
DOS remains 8192 elements.
-32768 Minimum array offset
32767 Maximum array offset
20000 Character limited in window (#lines x #columns)
65535 Maximum WebServer port. Integers 1 to 65535. Values below 2000 are normally
reserved for standard Internet activities.
65535 Maximum TCP socket number. Each O/S has TCP limitations:
Windows 3.11 only allows 4 TCP connections at any given time.
Windows 95 only allows 16 TCP connections at any given time.
Windows NT and UNIX allow 65535 connections at any given time (integers 1 to
65535. (For invalid values, the O/S dynamically assigns an unused valid number.)

System Limit For ProvideX Basic Programs:
50 Expanded TCP/IP address name from 20 to 50 characters, e.g. www.explorer-
software.com (Ver. 4.10).
15 Maximum KNO=value (Range is 0 to 15).
64K Maximum amount of data for MULTI_LINE, LIST_BOX, DROP_BOX.
In Win3.1 and WFW the maximum is 64K.
In Win95 and WinNT there is no limit, but we dont recommend loading a LIST_BOX
or DROP_BOX with much more than a 1000 entries.
System Limit For Data Files

2^31-1 Maximum # bytes in file. See the MB (MegaBytes) System Parameter for details
32167 Maximum record size (fixed)
32000 Maximum record size (variable length) increased from 4000 bytes.
96 Key fields, except for SORT files where the maximum key size is 127 (Ver. 4.01).
16 Keys
127 Open files (default). If 'XF' Extended File Mode, p. 563(s) is set, then the maximum
is 65000.
100 Maximum KEY IO buffers

[WDX] and Other Specialty Command [Tags]
Appendix: Special Command File_Tags
Description:
ProvideX supports the use of a series of special command file tags, enclosed in square brackets, to
simplify your development tasks. When you modify a pathname in your OPEN directive by prefixing it with
one of these tags, ProvideX recognizes it at RUN-time and deals with it internally. Following the
pathname, you can include a series of semicolon-separated parameters. Some tags are supported only in
specific operating environments.
This appendix describes the following special command tags.
Tag: See: Platform:

[DDE] [DDE] Tag: Dynamic Data Exchange, p. 609 WINDOWS only
[DLL] [DLL] Tag: Dynamic Link Library, p. 611 WINDOWS only

[OCX] [OCX] Tag: Object Component Extension, p. 612 WINDOWS only
[ODB] [ODB] Tag: Open DataBase, p. 613 WINDOWS only
[RPC] [RPC] Tag: Remote Procedure Control, p. 614 Any system except DOS
[TCP] [TCP] Tag: Transmission Control Protocol, p. 619 Any system except DOS
[VBX] [VBX] Tag: Custom VBX, p. 625 WINDOWS only
[WDX] [WDX] Tag: Directs Action to Client Machine, p. 626 Any platform if WindX is active
Note that you can only use the [WDX] specialty commands when running under WindX. You can also
prefix some (but not all) of the other specialty command tags with a [WDX] tag to direct the action to the
WindX client machine instead of the server.
WindX is our thin-client GUI screen handler. Use it when you need to:
give your users (client PC) screens a Windows GUI look with your character-based applications,
optimize your networks use of both WINDOWS and UNIX by directing tasks to the most
appropriate platform, and
do remote processing through serial and/or TCP/IP communications.

[DDE] Tag: Dynamic Data Exchange
Command File_Tag [DDE] Tag
Format:
1 OPEN for [DDE] OPEN (chan[,fileopts])"[DDE]dde_app;params"
The square brackets enclosing the DDE tag are "real" (i.e. part of the syntax).
Where =
chan Channel or logical file number to OPEN.
fileopts File OPEN options.
[DDE] File tag notifies ProvideX that youre opening an external DDE application.
dde_app Path and/or name of Dynamic Data Exchange application, e.g. Excel. String
expression.
params Optional DDE-specific parameters. Semicolon-separated arguments and/or variables
to receive returned values, etc. (Early implementations [V3.12 and before] used a
vertical bar instead of a ; semicolon as separator. Both are now acceptable)
Please refer to the documentation supplied with the individual product or application to
determine how to communicate with it using a [DDE] link.
Description:

Use the [DDE] tag as a prefix for your filename when you OPEN it to denote that ProvideX is to route all file
I/O requests to an external DDE application (like Excel). The [DDE] tag is built into the ProvideX
programming language, which recognizes the tag and deals with it internally at RUN-time.
You can associate a CTL value with an item in a DDE application to have ProvideX generate the CTL value
automatically whenever the value of the associated item changes. For example:
0010 DEFCTL (dde_fileno)"item"=ctl_event
Format 1, Excel Example: OPEN (chan[,fileopts])"[DDE]dde_app;params"

The example illustrates an export to an Excel spreadsheet. Note that the worksheet name is optional, but
the worksheet must exist if you include its name. This example also demonstrates the use of $09$ <Tab>
as the separator for Excel and makes SELECTive graphical requests to draw a pie chart, etc..
0010 OPEN (1)"[WDX][DDE]excel;existing_worksheet.wk1"

! or 0010 OPEN (1)"[wdx][dde]Excel;"
0020 OPEN (2)"SALES"
0030 LET R=0
0040 LOOP:
0050 LET DIV_ID$=KEY(2,END=DRAW_IT)
0060 READ (2,KEY=DIV_ID$)DIV_NAME$,DIV_SALES
0070 LET R=R+1 ! Bump row number
0080 LET K$="R"+STR(R)+"C1:R"+STR(R)+"C2"
0090 WRITE RECORD (1,KEY=K$)DIV_NAME$+$09$+STR(DIV_SALES)
0100 GOTO LOOP
0110 DRAW_IT:
0120 IF R=0 THEN STOP ! No divisions
0130 LET X$="R"+STR(R)

0140 WRITE RECORD (1)"[select(""R1C1:"+X$+"C2"","""+X$+"C2"")]"
0150 WRITE RECORD (1)"[new(2,1)]"
0160 WRITE RECORD (1)"[gallery.3d.pie(6)]"
0170 WRITE RECORD (1)"[window.maximize()]"
0180 WRITE RECORD (1)"[app.maximize()]"
See also: WRITE RECORD Add/Update Record in File, p. 480(d)

[DLL] Tag: Dynamic Link Library
Command File_Tag [DLL] Tag
Format:
1 OPEN [DLL clause] OPEN (chan,[fileopt])"[DLL:lib_name;fnc_name]params"

The square brackets enclosing the DLL clause are "real" (i.e. part of the syntax).
Where =
[DLL ... ] File_tag clause notifies ProvideX that youre opening a Dynamic Link Library.
lib_name Path and/or name of the free-standing Dynamic Link Library that contains the
external function you want to invoke. String expression.
fnc_name Case-sensitive name of the function. It acts as the entrypoint into the library.
String expression.
params DLL-specific parameters. Semicolon-separated arguments and/or variables to
receive returned values, etc.
Description:

Use the [DLL] tag as a prefix for your filename when you OPEN it to denote that ProvideX is to route all file
I/O requests to an external (user-defined) DLL. The [DLL] tag is built into the ProvideX programming
language, which recognizes the tag and deals with it internally at RUN-time.
A DLL is a free-standing Dynamic Link Library of C-style functions (external to ProvideX) used in
WINDOWS environments. For library names, the .DLL extension is not mandatory (other extensions, such
as .EXE are also used). Case-sensitive function names serve as entrypoints into the DLL.
Warning: You can use third-party DLLs, but make sure you have good documentation on what
youre passing and getting back. We can provide assistance on how to call a DLL,
but we dont provide support for third-party DLLs. There is no validation on what
you pass. Bad pointers can cause memory corruption and GPFs are not uncommon.
See also: DLL( ) and DLX( ) Call Windows DLL/DLX, p. 92(f)
Examples:
PROCESS SERVER "Inventory" ON "[DLL]c:\app\server.dll;Entry"
OPEN (1)"[dll:dbase2.dll;entry]cust.db"

[OCX] Tag: Object Component Extension
Command File_Tag [OCX] Tag
Format:
1 OPEN [OCX clause] OPEN (chan,[fileopt])"[OCX:lib_name;fnc_name]params"

The square brackets enclosing the OCX clause are "real" (i.e. part of the syntax).
Where =
[OCX ... ] File_tag clause notifies ProvideX that youre opening an OCX, ActiveX or COM
utility.
lib_name Path and/or name of the free-standing library that contains the external function
you want to invoke. String expression.
fnc_name Case-sensitive name of the service, function or control. It acts as the entrypoint.
String expression.
params OCX-specific parameters. Semicolon-separated arguments and/or variables to
Description:
An OCX (Object Component eXtension) is used primarily in Visual Basic and is similar to a DLL. Its a
separately compiled utility that provides a service, function or control and uses the Microsoft COM
(Common Object Module) interface. Each OCX must be registered in the system Registry under the
subkey HKEY_CLASSES_ROOT (done by the OCX / COM / ActiveX object itself.)
See also: OCX Interface Define Windows Object, p. 294(d)
NOTE: The OCX / COM / ActiveX interface (Ver. 4.20) is for use in WindX or WINDOWS only,
but is not fully supported across a WindX connection.
ALSO: ProvideX reserves CTL values -32001 through -32767 and 32001 through 32767
internally for use in OCX handling (Ver. 4.20).
Warning: Best Software Canada Ltd. does not provide support for any OCX / COM / ActiveX
objects, their use nor for their errors / problems / GPFs. We will, however provide
support for problems relating to the ProvideX interface itself (i.e. the
communications tunnel between ProvideX and the OCX / COM / ActiveX object). Use
of this interface is at your own risk. Contact your OCX / COM / ActiveX object
proprietor or supplier for documentation on the proprietary properties, usage,
arguments for methods, etc.. (Best Software Canada Ltd. does not provide these
items.)

[ODB] Tag: Open DataBase
Command File_Tag [ODB] Tag
Format:
1 OPEN ODBC database OPEN (chan[,filopt])"[ODB]filename[;USER=login;PSWD=password]"

The square brackets enclosing the [ODB] tag are "real" (i.e. part of the syntax). The square brackets
enclosing other elements above indicate that the elements are optional.
Where =
fileopt File options. Valid options:
BSZ=num Block size
REC=var Record prefix
[ODB] File tag notifies ProvideX that you are opening an external WINDOWS ODBC
database (not a ProvideX data file).
filename Path and/or name of the ODBC database file to OPEN. String expression.
login, password To specify a login and password, you can append the assignments to the filename.
Description:
NOTE: The [ODB] tag is built into the ProvideX programming language. You dont need the
ProvideX ODBC driver to use this tag, but you are limited to using the tag in
WINDOWS only. (ODBC is the Microsoft acronym for Open Database Connectivity.)
Use the [ODB] tag as a prefix for your filename when you OPEN it to denote that ProvideX is to route all file
I / O requests to an external (WINDOWS, not ProvideX) ODBC database file. Once you OPEN a channel
for [ODB] use, you can use it just like any other channel (i.e. for file I/O). It remains open until you CLOSE
it.
See also: READ Read Data from File, p. 343(d)
SELECT Select/Query From ... Where, p. 371(d)
WRITE Add/Update Data in File, p. 477(d)
NOTE: To open and read ProvideX (internal) data files using other database applications
(e.g. Excel), you would install and use the ProvideX ODBC driver instead of using the
[ODB] tag.
Example:
To read WINDOWS ODBC databases from a UNIX server, you would install and use WindX to make the
connection or use ProvideX RPC on a PC or NT server and open your ODBC databases through that
server.
OPEN (14)"[WDX][ODB]c:\your_path\your_ODBC_filename"

[RPC] Tag: Remote Procedure Control
Command File_Tag [RPC] Tag
Format:
1 Identify remote server PROCESS SERVER "server" ON "address"

2 Start remote server CALL "*rpsrvr",port
3 Terminate remote server PROCESS SERVER "server" CLOSE
4 Assign search rules PREFIX FILE "prog" or PREFIX FILE "subprog"
5 CALL remote subprogram CALL "[RPC:server]subprog[;entry]"[,ERR=stmtref][,arglist],varlist
6 OPEN remote file OPEN (chan[,fileopt])"[RPC:server]filename"
7 In Windows Command Line \PVX\PVXWIN32.EXE [RPC:server]prog [...etc.]
8 In UNIX Command Line /PVX/PVX [RPC:server]prog [...etc.]
The square brackets in the [RPC:rpc_server] clause are "real" (i.e. part of the syntax). The square
brackets enclosing other elements in all the directives above indicate that the elements are optional.
Where =
server Logical server name to identify which RPC server will handle which
CALL. Length: from 1 to 12 characters. For example,
"INVENTORY".
address Identify the servers address and/or port. A typical address, for
instance, uses the [TCP] address and port number, as in
"[tcp]192.1.1.100;15000". For other alternatives you can use,
see Server Addresses, p. 615.
*rpsrvr A Best Software Canada Ltd. application. Include the asterisk.
port Servers port, i.e., the port number in [TCP]. If you used
"[tcp]192.1.1.100;15000" as your server address, for example,
you would use 15000 as your server_port, as in:
CALL "*rpsrvr",15000
"[RPC:server]" The [RPC] clause initiates the remote CALL. (It can be defined in a
PREFIX FILE directive.) Server is your logical server name.
prog or subprog Name of the program to RUN at start_up or the subprogram for your
CALL directive. For example:
CALL "[RPC:INVENTORY]inv_alloc",a$,b,c,d
As examples, for a PREFIX FILE directive, you can use either a literal
("inv_alloc", in quotes) or a string variable, like REMOTE_FILE$.
;entry Entrypoint label. (Optional.) If you include a label, precede it with a
semicolon and append it to your subprogram name.
ERR=stmt You can include an error branch. Use a line number or label as your
stmtref.
arglist One or more arguments (comma-separated if you include a list
arg,arg...) to pass to the subprogram. Optional.
varlist One or more variables, literals, mnemonics, IOL= options, and/or
location functions, e.g. "@(5,4)". If you include a list, items must be
comma-separated.

Where =
fileopt File options. Valid options for OPEN include:
BSZ=num Block size
REC=var Record prefix
For more information, see About File OPEN Options, p. 300.
filename Name of the file to OPEN, prefixed by [RPC:server]. Use a string literal
as in OPEN (14)"[RPC:my_server]my_file"
Description:
You can use RPC (Remote Processing Control) for true distributed processing of your ProvideX
applications across a network of TCP/IP-connected machines. That is, you can distribute your
applications and files so that your processing logic is executed on the remote machine (server) where your
data files reside.
Format 1 to Identify Remote Server: PROCESS SERVER "server" ON "address"

Identify your remote server by logical name and actual address and/or port. Your logical name must be
between 1 and 12 characters in length, e.g. "INVENTORY". Your server address can take one of several
forms, depending on your circumstances. See the examples below.
Server Addresses Example:

tcp_address;port PROCESS SERVER "Inventory" ON "[tcp]192.1.1.100;15000"
LOCAL PROCESS SERVER "Inventory" ON "LOCAL"
The LOCAL keyword makes any [RPC] CALL to the given logical server a
LOCAL directive.
In UNIX only: pipe | PROCESS SERVER "Inventory" ON "|/u/sys001/inventory"
In Windows: [DLL] PROCESS SERVER "Inventory" ON "[DLL]c:\app\server.dll;Entry"
(For Entry, use the case-sensitive function name, preceded by a semicolon.)
Format 2 Starts Remote Server: CALL "*rpsrvr",port

When you call Best Software Canada Ltd.s *rpsrvr, it starts the remote server as a background task and
establish its port / server number on your system. For example, CALL "*rpsrvr",15000 will establish a
Remote Process server as port / service 15000 on your system.
Important: Assign and administer your port addresses carefully, to avoid duplication. Also,
when you define a [TCP] server address, as in "[tcp]192.1.1.100;15000" make sure
that your server_port number matches the number you pass to *rpsrvr.
Format 3 Terminates Remote Server: PROCESS SERVER "server" CLOSE

Use this Format to CLOSE your Remote Process server, as in PROCESS SERVER "INVENTORY" CLOSE.

Format 4 for Dynamic Changes: PREFIX FILE "subprog"
You can use PREFIX FILE definitions for your [RPC] subprograms to alter existing CALLs dynamically by
changing the subprograms PREFIX search rules. See the example below.
Example:
In this example, the PROCESS SERVER is defined as:
PROCESS SERVER "INVENTORY" ON "[tcp]192.1.1.100;15000"
The PREFIX FILE is defined as:
KEYED "inv_alloc",9,0,-256
PREFIX FILE "inv_alloc"
OPEN (14)"inv_alloc"
LET R_FILE$="[RPC:INVENTORY]inv_alloc"
WRITE (14,KEY="inv_alloc")R_FILE$
CLOSE (14)
With the PREFIX FILE defined for RPC, a standard CALL (e.g., CALL "inv_alloc",a$,b,c,d) from
any application will result in the [RPC] CALL. You can change your servers location dynamically for
existing CALLs simply by changing your PREFIX FILE contents.
Format 5: CALL "[RPC:server]subprog[:entry]"[,ERR=stmtref][,arglist],varlist

Use the [RPC] CALL format to tell ProvideX that your subprogram is to run (and your data resides) on a
different processor in the network, i.e. on your given remote server. You use the same syntax as you
would for a standard CALL directive, except that you include your [RPC:rpc_server] clause to designate
which remote server is to handle the CALL. Since your data isnt transferred during [RPC] CALL
processing, you can maximize both network performance and data security.
Transparent [RPC] Process

At RUN-time, ProvideX doesnt transfer data files or programs across the network for your [RPC] CALL.
Instead, ProvideX puts your CALLed [RPC] subprogram name and parameters into a TCP/IP data packet
and sends the packet to your remote server. The remote server loads and runs your subprogram, passing
it your parameters. When your subprogram EXITs, the remote server puts your parameters (as altered by
your subprogram) into a TCP/IP response packet and sends this back to your CALLing program.
See also: [RPC]s TCP Data Packets, p. 617.
Warning: When you design subprograms to run on a remote server, its risky to make
assumptions about the current environment of the remote server. While the server
can be initiated in a specific disk directory and could also have its own START_UP
procedure, you should still design your programs to check that the files they need
can be directly addressed.
NOTE: Since ProvideX [RPC] processing is true distributed processing, done as a

transparent background process, any displays during subprogram processing will
appear on the remote server. You should NOT attempt to display subprogram activity
on the CALLing machine.
Format 6 OPENs Remote File: OPEN (chan[,fileopt])"[RPC:server]filename

ProvideX supports the OPEN directive for remote files. Prefix your filename with the [RPC:rpc_server]
clause to indicate that the server is to handle file requests.

Formats 7 and 8: RUN [RPC] Program at ProvideX Startup

7 Command Line, Windows: \PVX\PVXWIN32.EXE [RPC:rpc_server]prog [parameters, etc.]
8 Command Line, UNIX: /PVX/PVX [RPC:rpc_server]program [parameters, etc.]
You can START background tasks from Command Line by naming your RPC program to run at startup.
See Command Line, Launching ProvideX, p. 569 for the rest of the syntax (parameters, arguments,
etc.) for starting ProvideX.
[RPC]s TCP Data Packets

All data packets for remote file access contain the following header:
Major_code Single character major function (Always "F" for File I/O)
Minor_code Single character minor function
Size Two-byte binary packet size
CRC Two-byte CRC-16
Data... Variable length packet data
Format of [RPC] Data Elements in Packets:

CHR One-byte character
INT Two-byte binary value
LONG 4-byte binary value
STR String of data prefixed by a two-byte binary length
If string is omitted then the size = -1
If you include a return value, ACK $06$ should be in the first character position, followed by a two-byte
return length and then the data. For errors, the first character of the return value should be NAK $15$
followed by a two-byte binary error code.
The chart which follows shows the valid data packet elements, formats and contents for commands
supported in ProvideX [RPC].
Supported Data Packet

Commands: Element - - - Format - - - - Contents
OPEN Major code - - CHAR - - - - Always F
Minor Code - CHAR - - - - O
Option - - - - CHAR - - - - OPEN option: (*=Load, I=Input, P=Purge, L=Lock,
blank=None)
Isz - - - - - - INT - - - - - - ISZ value if specified
Path - - - - - STR - - - - - Pathname from the OPEN directive
Opt= - - - - - STR - - - - - Value specified in OPT= parameter
(Return) - - - INT - - - - - - Logical file number to be used in all subsequent
requests
CLOSE Major code - - CHAR - - - - Always F
Minor code - - CHAR - - - - C
Fileno- - - - - INT - - - - - - Logical file number to close

Supported Data Packet
Commands: Element - - - Format - - - - Contents
WRITE Major code - - CHAR - - - - Always F
Minor Code - CHAR - - - - W
Fileno- - - - - INT - - - - - - Logical File Number
Sub1 - - - - - CHAR - - - - Record access option (K=KEY, I=IND, R=RNO)
Sub2 - - - - - CHAR - - - - Error Option (D=DOM specified)
Key - - - - - - STR - - - - - KEY if specified
Ind - - - - - - LONG - - - - Record IND if specified or RNO value
Data - - - - - STR - - - - - Data to write
READ Major code - - CHAR - - - - Always F
Minor Code - CHAR - - - - R
Sub2 - - - - - CHAR - - - - Blank (Not Used)
KEY - - - - - STR - - - - - KEY if specified
IND - - - - - - LONG - - - - Record IND if specified or RNO value
KNO - - - - - INT - - - - - - KEY number
(Return) - - - STR - - - - - Record Contents
REMOVE Major code - - CHAR - - - - Always F
Minor Code - CHAR - - - - Hyphen/Minus sign -
Sub2 - - - - - CHAR - - - - Blank (Not Used)
KEY( ), Major code - - CHAR - - - - Always F
Minor Code - CHAR - - - - K
IND( )
KNO( ) Sub1 - - - - - CHAR - - - - Record access option (K=KEY, I=IND, R=RNO)
Sub2 - - - - - CHAR - - - - blank' '=KEY, P=KEP, C=KEC, N=KEN, F=KEF,
Functions
L=KEL, R=RNO, I=IND
KNO - - - - - INT - - - - - - KEY number
(Return) - - - STR or LONG Returns KEY value as STR, IND/RNO as LONG

[TCP] Tag: Transmission Control Protocol
Command File_Tag [TCP] Tag
Format:
1 Open a [TCP] Channel OPEN (chan[,fileopts])"[TCP][tcp_server];socket[;tcp_opts]"

2 Forcibly REMOVE Client REMOVE (chan[,fileopts])
Note that the square brackets enclosing the [TCP] tag above are "real" (i.e. part of the syntax). The square
brackets enclosing other syntax elements indicate that such elements are optional.
See also: File I/O on an OPEN [TCP] Channel, p. 621
Where =
fileopts File options.
Valid options for OPENing a TCP channel include:
ERR={label | line_num}
BSZ=num Block size in bytes for the channel (maximum 32000).
BSZ defaults: per READ=1024, per WRITE=32000.
TIM=num Timeout value (Ver. 4.20). For example:
OPEN(chan,TIM=3)"[TCP]IP;SOCKET"
KEEPALIVE Only applies to the client side TCP/IP connections (ignored if specified on
the host style connection). Use this attribute to force the O/S to send keepalive packets
to the host,thereby keeping TCP/IP pipes open forever on TCP/IP connections which
time out due to inactivity. For example:
OPEN(chan)"[tcp]ip;socket;KEEPALIVE"
If you omit file options from your REMOVE directive, ProvideX disconnects the last
client for which there was a READ. Valid options for REMOVE include:
[TCP] File tag that tells ProvideX your channel is being OPENed for a TCP/IP connection.
tcp_server Server address. Optional. If you include it (to denote a client connection on the
channel), use either an IP address like 172.16.1.1 or a DNS (Domain Name System)
server, such as www.pvx.com. Omit it to denote a server/host connection.
socket TCP/IP socket number. For a host connection, this is the socket number where the
host listens and the client connects. For a client connection, this is the socket number
where the host listens. The valid range for [TCP] sockets is 1 to 65535. (For an invalid
socket number, <0 or >65535, the O/S dynamically assigns an unused valid number.)
See also: O/S Limits on Connections, p. 621
tcp_opts [TCP] options to override default [TCP] characteristics. If you include a list, use the
semicolon as a separator. Valid options are:
NODELAY Disables algorithm that delays transmission. Default: delay up
to 200ms., attempt to combine data into larger packets.
SINGLE For host. One client per connection. Default: multiple clients.
STREAM Sets streaming data mode. ProvideX default: block mode.
Description:
You can use [TCP] to create virtually any kind of two-way communications program. For instance, you

can use it for file transfer systems, internet mail or fax interfaces, e-commerce, remote software updating
... and more. Its used in Best Software Canada Ltd. applications, too (e.g. WindX Telnet interface, client/
server interface programs *nthost,*ntslave, the WebServer and e-mail tools).
Format 1: OPEN (chan[,fileopts])"[TCP][tcp_server];socket[;tcp_opts]"

Use the ProvideX built-in [TCP] interface as a "smart pipe" when you OPEN a channel for either type of
[TCP] connection: the server/host connection (the daemon or listener) and/or the client connection
(requesting information). In any one program, you can include many [TCP] sockets, which can be open
concurrently and are independent of each other. However, there are operating system limitations. See
also: O/S Limits on Connections, p. 621.
[TCP] Client Connection:

When you include the optional tcp_server, that tells ProvideX that you are OPENing the channel as a client
connection linked to the socket where the host is listening. That is, you open a channel to create a link to
the hosts socket number. A client can only communicate with the specific host to which its connected.
For example:
OPEN (1,BSZ=16384)"[TCP]172.16.1.1;10000"
opens a client link to a [TCP] channel, port 10000 on the server. Your client PC will use any available
socket number for its side of the communications. Note that the local machine dynamically assigns an
available socket for your program to use.
You can use KEF( ) Return First Key of File, p. 203(f) for local sockets, as in
LET MY_KEY$=KEF(CHAN)
(The data in MY_KEY$ for the example here is in IP format, "10.12.1.12;80;GORDD".)
As another example,
open (1)"[tcp]www.microsoft.com;80;nodelay"
opens a connection to Microsofts website, which is listening to socket number 80, the default. (The
example also turns off the 200ms delay packet optimization algorithm.)
[TCP] Host/Server Connection:

When you omit your tcp_server value from the syntax, you notify ProvideX that you are OPENing the chan-
nel as a host/server.
For example:
OPEN (1,BSZ=8192)"[TCP];10000"
opens a [TCP] channel as a host/server connection with a block size of 8192 bytes. A host/server can
communicate with more than one client at a time. (You can override this by using SINGLE as one of your
tcp_opts.)
[TCP] Errors during OPEN

Typical [TCP] errors during an OPEN are listed in the chart below.
Error: Explanation:
Error 10 Error #10: Illegal pathname specified
Invalid or unreachable IP address or DNS name

Error: Explanation:
Error 12 Error #12: File does not exist (or already exists)
Cant establish connection. Server is not listening to socket.
Error 15 Error #15: Operating system command failed
Cant OPEN the socket locally. Some potential causes:
Socket is in use by another application.
Socket contains pending data. (Some operating systems wont let you open a
socket if there is already data in it. The timeout can be delayed for as
much as 10 to 15 minutes before the data is cleared and the port made
available.)
The host must always open the socket before a client is allowed to connect to
the socket.
O/S Limits on Connections

Each O/S has TCP limitations:
Windows 3.11 only allows 4 TCP connections at any given time.
Windows 95 only allows 16 TCP connections at any given time.
Windows NT and UNIX allow 65535 connections at any given time.
NOTE: All operating systems limit you to a maximum of 5 pending messages in the queue
for newly-connected clients on the given host socket. The O/S will refuse further
connections by clients to the socket until there are fewer than 5 pending messages in
the given queue. READ your messages frequently to prevent refusals.
Due to a change in bitmap handling, ProvideX versions 4.14 or higher will no longer run on MS-Windows
NT version 3.51. The following Operating Systems will no longer be supported:
MS-Windows NT Version 3.51
MS-Windows 3.1 (16-Bit)
MS-DOS will only be available on request
File I/O on an OPEN [TCP] Channel

Once you OPEN a [TCP] channel, you can use it just like any other channel. It remains open until you
CLOSE it. Make sure you include ERR=options to branch for error handling.
[TCP] I/O with SIZ=option

If your file I/O directive (i.e. READ, WRITE, etc.) includes the SIZ=option, use a positive value to tell
ProvideX to read the number of bytes requested or to wait until either the SIZ=option is satisfied or an error
occurs. Use a negative value to have ProvideX return immediately with any data requested, up to the
given size. If you omit the SIZ=option in your file I/O directive, ProvideX refers to your OPEN directive and
uses your OPENing BSZ=option (or the default BSZ values) to determine the amount of data to send or
return.

[TCP] Example
OPEN (CHAN,BSZ=8192)"[TCP];80" ! LISTEN TO SOCKET 80 AS HOST
LOOP:
READ RECORD (CHAN,END=CLIENT_DISCONNECTED,ERR=LOOP)IN_DATA$
LET UNIQUE_CLIENT_ID=IND(CHAN) ! 32-BIT NUMERIC VALUE
LET CLIENT_ID$=KEY(CHAN) ! USUALLY CLIENT IP ADDRESS FORMAT AS IN "172.16.1.1"
LET MY_DATA$=KEF(CHAN)! LOCAL INFO ON SOCKET, E.G. "10.12.1.12;80;GORDD"
IF IN_DATA$="" THEN GOSUB NEW_CLIENT_CONNECTING
GOSUB PROCESS_DATA_FROM_CLIENT
GOTO LOOP
! ...
CLIENT_DISCONNECTED:
LET UNIQUE_CLIENT_ID=IND(CHAN)
GOSUB CLEAR_CLIENT_DATA
GOTO LOOP
READ to Detect Client Communications

Use READ directives to detect newly-connected clients, read the data and detect disconnections. Each
client has one buffer of incoming data (which moves in either stream or block mode and is appended to
that clients data in the buffer). At a minimum, your host receives a connection and a disconnection from
the client. In between, it receives data, if any is sent.
NOTE: Buffering affects the host only. See Designing Your Program, p. 623.
To Detect a Connection:
The READ on a new connection terminates with NULL data in the READ variables and your
IND(channel) function returns a unique connection number.
How ProvideX READs Data:

When ProvideX encounters data for your READ or READ RECORD, it retrieves all the data pending for
one client at a time, up to the SIZ= or BSZ= option you specify. There are no delimiters in the data and
your program might receive the data in one or several READs (depending on the clients packet
optimization and how fast your program reads the data from the TCP channel).
ProvideX READs the data available, then parses it by SEParators (default=$8A$) into variables on the
READ. If you have not identified the client (using either the IND=option or KEY=option), ProvideX READs
the input buffer for any data from the next client in FIFO order. For READ RECORD directives, ProvideX
reads the data in binary form. No translation is performed and no EOL (end-of-line) terminators are
expected.
To Detect a Disconnection:
When a client has disconnected, ProvideX returns an Error #2: END-OF-FILE on read or File
full on write on your READ directive and your IND(chan) returns the clients unique connection
number.
See also: READ Read Data from File, p. 343(d)

WRITE Directives
When you use a WRITE directive, ProvideX appends a SEP to the end of the WRITE. If you have not
identified the client by IND=option or KEY=option, ProvideX writes/sends data to the last client for which
there was a READ. For WRITE RECORD directives, data is sent in binary form. No translation is
performed and no EOL (end-of-line) terminators are appended.
See also: WRITE Add/Update Data in File, p. 477(d)
Designing Your Program

We recommend that you design your program with a buffer of your own for the data and parse for your
EOM (end of message) indicator. You need some way to recognize when a message ends.
You can, for instance, build your host and client using ACK / NAK styling where the client or host sends
only one message at a time and waits for a response. You can use message length, as specified in the
TCP packet header. You can create and parse for your own EOM. As well, a standard internet service
(e.g. FTP, POP3, etc.) informs you in their RFC about what commands the service accepts, their format
and their EOM.
TIPS:
Corrupt messages, service timeouts and dropped connections are common in communications. The list
below offers you tips on trouble-shooting:
You can limit the number of clients connected at a given time to one, by using the SINGLE option
in your OPEN directive.
Check your TCP channel and drain your messages often. Limit the amount of work your program
does between READ directives. This helps prevent overloads, timeouts and refused
connections.
Use tight error handling in your directives to anticipate communications problems.
If your application sends critical information, use outboxes and holding queues so that processing
can carry on even if communications are down.
To Spawn TCP/IP Server Applications

On WINDOWS NT, you can run your application as a simple console task through a shortcut, or you can
run it as a service using SERVANY.EXE from the NT Resource Kit.
On UNIX, you can run the application as a simple console task, or from /etc/inittab for automatic
starting and restarting, or from /etc/services so that its only launched when a connection is pending.
Under WINDOWS, you can run both server and client side applications on the desktop for simplified
program creation and debugging.
Security
Watch your security. You can use firewalls, proxies and other NAT (Network Address Translation) devices
to perform IP address and socket blocking. All requests made by clients with NAT are actually performed
using the IP address of the NAT device. Firewalls and proxy servers can be set up to block specific TCP
sockets or to route connection requests for a particular socket to a different machine.
To guard against hackers, if your application launches as "root", you can design your application to control
a user_ID and have operations performed under that ID.

Clients making requests might be behind firewalls even if you dont use one, for security and other
reasons. Many ISPs (Internet Service Providers) use firewalls as a solution when they dont have enough
IP addresses to handle their clients. By designing your applications so that the client always initiates the
call to the server, you can make sure that your application flows through firewalls correctly. Since a remote
clients "real" IP address might be hidden (for instance behind a firewall), dont expect your server
application to be able to call back to the client.
If you cant connect to a socket number even though youre sure a server is listening, check to see that the
socket is not being blocked either internally or by your ISP.
Format 2 Disconnects Client(s): REMOVE (chan[,fileopts])

Use a REMOVE directive with the IND= or KEY= options to identify and forcibly disconnect a specific
client. If you omit your IND= and KEY=options, a REMOVE directive disconnects the last client for which
there was a READ. Your REMOVE directive does not clear your hosts socket and data buffers.
Examples:
REMOVE (30)
REMOVE (30,KEY=KK$)
REMOVE (30,IND=I)
Note that browsers such as Netscape Navigator and Internet Explorer rely on being disconnected. (These
browsers connect with your socket, send their request for data and see the data received from you as
being complete when they are disconnected from the server.)
Warning: You can use a CLOSE directive to disconnect ALL clients, but this will also clear the
socket and data buffers.
See also: REMOVE Delete Record from File, p. 355(d)
CLOSE Close File, p. 47(d)
[TCP] Errors during File I/O

Typical errors during file I/O are listed in the chart, below:
Error: Explanation:
Error 2 Error #2: END-OF-FILE on read or File full on write
Host or client has disconnected.
Error 11 Error #11: Record not found or Duplicate key on write
Your application includes an IND=value or KEY=value for a client that is not connected.
Error 15 Error #15: Operating system command failed
General TCP failure. Check the values returned by the RET system variable and the
function MSG(-1) for a description of the error.

[VBX] Tag: Custom VBX
Command File_Tag [VBX] Tag
Format:
1 OPEN [VBX clause] OPEN (chan,[fileopt])"[VBX:lib_name;fnc_name]params"

The square brackets enclosing the VBX clause are "real" (i.e. part of the syntax).
Where =
[VBX ... ] File tag notifies ProvideX that youre opening a free-standing VBX library (external
to ProvideX).
lib_name Path and/or name of the free-standing library that contains the external function you
want to invoke. String expression.
fnc_name Case-sensitive name of the service, function or control. It acts as the entrypoint.
String expression.
params VBX-specific parameters. Semicolon-separated arguments and/or variables to
Description:
Warning: VBXes are third party / proprietary utilities used to define objects. Please make sure
you have the right to use and subsequently distribute external tools.
You can use VBXes in both WINDOWS and UNIX systems when running in graphics modes of ProvideX.
There is no text mode support since VBXes are WINDOWS programs and need a WINDOWS graphics
device.
See also: CUSTOM_VBX Create/Control VBX, p. 56(d)

[WDX] Tag: Directs Action to Client Machine
Command File_Tag [WDX] Tag
Format:
1 EXECUTE EXECUTE "[WDX]statement"

2 INVOKE INVOKE "[WDX]statement"
3 CALL Pgm CALL "[WDX]subprog_name",params
4 OPEN a file OPEN (chan[,fileopts])"[WDX]filename"
5 COM port OPEN (chan,OPT=settings$)"[WDX]port_id"
6 [tag] process OPEN (chan[,fileopts])"[WDX][tag]prog;[params]"
7 *device* OPEN [INPUT] (chan[,fileopts])"[WDX]*device*[;Q_name[;Q_options]]"
8 *WindX.utl CALL "[WDX]*WindX.utl;function",params
Note that the square brackets for specialty command tags like [WDX] are "real", i.e. part of the syntax, as
are the asterisks enclosing special device file names like *WINDEV*. Square brackets around other
syntax elements indicate that the elements are optional
Where =
[WDX] File tag notifies ProvideX that you are directing the action to the WindX client
machine instead of the server.
statement Any command supported by ProvideX (some are not) for use with EXECUTE or
INVOKE + the [WDX] tag in WindX. String expression.
subprog Name of a subprogram which exists and RUNs on the client PC. String
expression.
params Arguments and variables you pass to the subprogram or function. If you
include a list, its comma-separated.
fileopts Optional file options:
BSZ=size Block size
NBF=buffers Dedicated number of buffers
OPT=string$ File OPEN options
REC=var$ Record prefix
For more information, see About File OPEN Options, p. 300
filename Name of the file. The file must exist on the client PC. String expression. For
example:
OPEN (14)"[WDX]"+TMP$ ... or OPEN (14)"[wdx]temp_file" ...
settings$ Serial devices attributes (baud rate, etc.). String expression.
port_id System identifier for the port, e.g. COM1.
tag ProvideX special command file_tag, enclosed in square brackets, e.g. [DDE],
[OCX...] and [VBX...], etc.

Where =
prog;function Parameters for the [tag]. For instance, for [DDE] to export to Excel, you can
OPEN a worksheet using either :
"[WDX][DDE]EXCEL;existing_worksheet.WK1" or
"[WDX][DDE]EXCEL;"
In the first example, where a spreadsheet name is included, it must exist on the
client PC.
*device* Identifier and parameters for either one of the two [WDX]-supported special
device files (*WINDEV* or *WINPRT*):
;Q_name
;Q_options
*WINPRT* Device File: Windows Printing, p. 596.
function A Best Software Canada Ltd. utility / function, part of the *WindX.utl utility
program. For instance, the *WindX.utl;Spawn function initiates tasks on the
host / server and / or client.
Description:
Use the [WDX] tag to have the action occur on a remote client PC instead of on your server if your given
command could be used on either client or server and when or if the command supports using [WDX].
Restrictions:
You can use the [WDX] tag in specialty commands only when running under WindX.
NOTE: The DIR=option and the PURGE, FILE and INDEXED directives are not supported by
WindX. When you need one of these on a WindX PC, encapsulate your commands in
an EXECUTE "[WDX]..." directive or design your applications to run remotely on the
client.
ALSO: As of Ver. 4.20, WindX now supports the use of the following additional commands
via the [WDX] tag: SERIAL, KEYED, DIRECT, SORT, PROGRAM, DIRECTORY, REFILE,
LOCK, UNLOCK, MNEMONIC and ERASE. For example, you can now use SERIAL
"[WDX]somefile.ext"... instead of embedding the command in an EXECUTE
directive.
If you are running an earlier version of ProvideX on a WindX PC, you still need to
encapsulate these commands in an EXECUTE "[WDX]..." directive or design your
applications to run on the remote site.
To Detect WindX: Tip & Example

To detect whether or not youre actually working on a WindX PC in COMMAND mode, look for the special
COMMAND mode prompt -} (i.e., hyphen + curly brace). In your applications, a test for one of the
following indicators will tell you that your session is running under WindX:
DEC(MID(MSE, 22,1))>0
TCB(88)<>0 (Ver. 4.10)
See also: MSE Mouse State, p. 269(v)
Example:
You can create a global variable in your WindX set-up, and use it later to test for the presence of a WindX
client PC connection. (Then, if WindX is running the session, you can use the [WDX] tag.) For example,
the user-defined variable %WDX below is only set when WindX is running, otherwise its value is NULL.

IF MID(MSE,22,1)>$00$ AND MID(MSE,22,1)<$FF$ THEN %WDX$="[WDX]"
You can use such a global variable in a statement like OPEN (30)%WDX$+"*WINPRT*" to bypass an
Error #12: File does not exist (or already exists) when WindX isnt running.
How ProvideX Itself Detects WindX

ProvideX uses terminal type to detect a WindX session. In UNIX, ProvideX recognizes two terminal types
as potential WindX stations (TERM="winterm" for the WindX client PC and TERM="ansi"). Since most
UNIX systems and applications cant recognize or use the winterm type, the ProvideX ansi device driver
sends a special escape sequence to a terminal to test for a WindX client. If the terminal is a WindX PC, a
special response is generated. If no response is generated before a timeout occurs, ProvideX assumes
the device is ansi.
GUI Requests
Once the ProvideX session on the server recognizes the terminal as a WindX station, it changes the
internal settings to allow graphical requests to be routed correctly. (Then, graphical requests are
automatically tokenized and forwarded to WindX for processing. That is, you dont need the [WDX] tag.)
For instance, a server command to PRINT a picture in a UNIX environment would automatically be
sent to WindX for the client. ProvideX transmits standard mnemonics to WindX as an escape ($1B$)
followed by the mnemonic in native form. Traffic from the host/server is minimized because the WindX
clients ProvideX interpreter handles a lot of the functionality locally (i.e. on the client) for screen refreshing
and graphical requests.
In WindX, your instruction to PRINT is sent to the client, bundled as is. When you use mnemonics and/or
graphics like .BMPs, they must exist on the client or be accessible to the client. The next example uses a
picture that is defined and shared on a common WINDOWS server (e.g. an NT server) instead of being
stored on each individual client machine:
print picture(10,10,10,10),"\\serv_name\driveshare\your_bmps\that.bmp"
Formats 1 and 2: Initiate Remote Command

Format 1 Executes Command on Client: EXECUTE "[WDX]statement"
Format 2 Invokes Command on Client: INVOKE "[WDX]statement"
You can use the EXECUTE and INVOKE formats with the [WDX] tag to process your commands on the
WindX PC (the remote client). Common applications of the EXECUTE format are in changing the clients
local directory, setting System Parameters, altering the PREFIX and in file creation.
Examples:
The example below illustrates how you can use EXECUTE "[WDX]statement" in your application on the
host/server to define a MNEMONIC directive locally on the WindX client:
IF WDX%<>$00$ THEN EXECUTE "[WDX]MNEMONIC(LFO)5X=$1B+hex$" ELSE GOTO MY_LABEL
The next example sets 'B0' Base Zero for Level / Window, p. 539(p) on a WindX PC using a
[wdx]command from a UNIX host:
EXECUTE "[wdx]SET_PARAM 'B0'"
NOTE: If you run your application with B0 set, make sure that it is set on both the host and
the WindX PC. Otherwise, the wrong windows will be addressed. (You can set B0
either by executing it from the host, as in the example, or by using -B0 as an
argument on the WindX PCs startup command line.

Reminder: As of Ver. 4.20, WindX supports the use of the MNEMONIC directive via the [WDX]
tag. (If you are running an earlier version of ProvideX on a WindX PC, you still need
to encapsulate your command in an EXECUTE "[WDX]..." directive or design your
applications to run on the remote site.)
Warning: When you use the EXECUTE and INVOKE directives from your server to initiate
action remotely on a client, the client PC might be running a ProvideX activation with
a different set of syntax tables. As a result, your MNEMONICs might be invalid.
Format 3 for Remote Processing: CALL "[WDX]subprogram"[,parameters]

Use this format to allow the server to CALL a subprogram that exists and RUNs remotely on the client. Its
true distributed processing. The servers files and global variables are not accessible to your subprogram.
Your remote CALL passes parameters back and forth, not data files. You can pass a maximum of 20
parameters/arguments, in a comma-separated list.
For example, you can call applications like special printer device drivers you have built on the client to
handle print mnemonics:
CALL "[WDX]*dev/your_driver_name"
You can use a similar format to CALL the ProvideX *WindX.utl (utility) functions.
See also: [WDX]*WINDEV* Escape Sequences: Examples, p. 605
Format 8: [WDX] and *WindX.utl:, p. 630
Formats 4 and 5: OPEN Files, Serial Ports on Client

Format 4 OPENs File on Client OPEN (chan[,fileopts])"[WDX]str_expr"
Format 5 OPENs Client COM Port OPEN (chan,OPT="settings")"[WDX]port"
Use this format in programs running on your server when youre OPENing remote files or ports. That is,
using [WDX] as a prefix to the pathname of your file (or port, etc.) tells WindX to OPEN it remotely on the
client. WindX automatically forwards requests (i.e. your file I/O directives) for processing.
Reminder: Not all directives are not supported by WindX. When you need a statement that is not
supported on a WindX PC, encapsulate your commands in an EXECUTE "[WDX]..."
directive or design your applications to run remotely on the client.
Examples:
You can use Format 4 when OPENing files:
OPEN (1)"[WDX]CLIENT_PATH\CLIENT_FILE"
Use a similar format to OPEN a COM port for direct access to a serial device (e.g. a serial printer or weigh
scale) on the client PC without going through a spooler:
LET SETTING$="9600,n,8,1,x"
OPEN (5,OPT=SETTING$)"[WDX]COM2"
or
OPEN (5,OPT="9600,n,8,1,x",ERR=OOPS)"[WDX]COM2"
Format 6 for File Tags OPEN (chan[,fileopts])"[WDX][tag]prog_name;[params]"

You can use the [WDX] file tag in conjunction with some other file tags. For example:
0010 OPEN (1)"[WDX][DDE]excel;existing_worksheet.wk1"

Format 7 for *WINDEV* and *WINPRT*: Windows Print Subsystem on Client
*WINDEV* OPEN [INPUT] (chan[,fileopts])"[WDX]*WINDEV*[;Q_name[;Q_options]]"
*WINPRT* OPEN [INPUT] (chan[,fileopts])"[WDX]*WINPRT*[;Q_name[;Q_options]]"
ProvideX OPENs the special device files *WINPRT* and *WINDEV* on the PC/server which issues the
command. Except in UNIX (where its done automatically), use [WDX] with OPEN {INPUT] directives for
the two specialty files *WINDEV* and *WINPRT* to direct any print jobs and dialogues to the WindX
client PC, which will in turn use its WINDOWS print subsystem API to deal with the jobs and send them to
the given printer. For example:
OPEN (7,ERR=1500)"[WDX]*WINPRT*"
With a WindX client and an NT Server, if you do NOT use [WDX] in your OPEN directive, then:
folder.
See also: [WDX]*WINDEV* Escape Sequences: Examples, p. 605
Format 8: [WDX] and *WindX.utl:

Format: CALL"[WDX]*WindX.utl;function",params
Use this format to CALL Best Software Canada Ltd.s utilities/functions in the WindX.utl utility program.
For example:
call "[wdx]*windx.utl;spawn",cmdline$,inifile$,appfid$
The functions listed in the chart below are built into WindX to simplify your development tasks.
Function Returned Values and Explanations

CALL "[WDX]*WindX.utl;Get_Addr",X$ Returns the IP address of the WindX PC
CALL "[WDX]*WindX.utl;Get_ARG",X,X$ Returns the command line argument
number specified by X in X$
CALL "[WDX]*WindX.utl;Get_LPG",X$ Returns the LPG (Lead Program Name)
system value for the WindX session.
CALL "[WDX]*WindX.utl;Get_LWD",X$ Returns the local current disk directory
(Last Working Directory) for the WindX
session.
CALL "[WDX]*WindX.utl;Get_WindX",X$ Returns the absolute pathname of the
WindX program.
CALL "[WDX]*WindX.utl;Get_NewPort",X Returns the port number of an unused
TCP/IP port on the WindX station.
CALL "[WDX]*WindX.utl;Get_TCB",X Returns the value of the TCB function task
specified by X in X, i.e. X=TCB(X).
CALL "[WDX]*WindX.utl;Get_Val",X$,Y$ Evaluates and returns the value of the
string expression X$ in Y$, i.e.
Y$=EVS(X$).
CALL "[WDX]*WindX.utl;Get_Num",X$,Y Evaluates and returns the value of the
numeric expression X$ in Y (i.e.
Y=EVN(X$).

Function Returned Values and Explanations
CALL "[WDX]*WindX.utl;Spawn",X$,I$,F$ Spawns a new session of ProvideX on the
host and an associated WindX session on
the client PC. By default, if the main
session terminates, then the spawned
session terminates. The parameters are:
X$ the command line parameters
to be used on the host
I$ the pathname of INI file to be
used on the client PC
F$ the value of FID(0) for the
session
CALL "[WDX]*WindX.utl;Spawn_Nohup",X$,I$,F$ Same as Spawn but detaches the session
from the main user task. If the main task
terminates, then the spawned task
continues executing.

Reserved Words
Appendix: Reserved Words
This words on this list are reserved for internal use by ProvideX. You should not use them as variable
names (Ver. 4.20).
Reserved Words Reserved Words Reserved Words Reserved Words
ABS DATA EVS INDEXED

ACCEPT DAY EXCEPT INPUT
ACS DAY_FORMAT EXECUTE INT
ADD DEC EXIT INVOKE
ADDR DEF EXP IOL
ALL DEFAULT EXTRACT IOLIST
AND DEFCTL FFN IOR
ARG DEFPRT FI ISZ
ASC DEFTTY FIB JUL
ASN DELETE FID KEC
ATH DICTIONARY FILE KEF
ATN DIM FIN KEL
AUTO DIR FIND KEN
AUTO_LOCK DIRECT FLG KEP
BEGIN DIRECTORY FLOATING KEY
BIN DISABLE FMT KEYED
BKG DLL FN KGN
BREAK DLM FNT KNO
BSY DLX FOR LAOD
BSZ DOM FPT LCS
BUTTON DROP FROM LEN
BYE DROP_BOX GAP LET
CALL DSK GBL LFA
CASE DSZ GEP LFO
CHART DTE GET_FILE_BOX LIKE
CHECK_BOX DUMP GFN LINE_SWITCH
CHG EDIT GID LIP
CHN ELSE GO LIST
CHR ENABLE GRID LIST_BOX
CLEAR END HFN LOAD
CLIP_BOARD ENDTRACE HIDE LOCAL
CLOSE END_IF HLP LOCK
CONTINUE ENTER HSA LOG
CONTROL ENV HSH LONG_FORM
COS EOM HTA LPG
CPL EPT HWD LRC
CRC ERASE HWN LSIT
CREATE ERR H_SCROLLBAR LST
CSE ERROR_HANDLER I3E LWD
CTL ERS I86 MAX
CUSTOM_VBX ESC IF MDE
CVS ESCAPE IND MEM
CWDIR EVN INDEX MENU_BAR

Reserved Words Reserved Words Reserved Words Reserved Words
MERGE PRC SAVE TABLE

MESSAGE_LIB PRECISION SCALL TAN
MID PREFIX SECURITY_MASK TBL
MIN PREINPUT SELECT TCB
MNEMONIC PRINT SEP THEN
MNM PRM SERIAL TIM
MNU PROCEED SERVER TIP
MOD PROCESS SETCTL TME
MSE PROGRAM SETDAY TMR
MSG PROPERTIES SETDEV TMS
MSGBOX PROPERTY SETDRIVE TO
MSK PSZ SETERR TRANSLATE
MSL PTH SETESC TRISTATE_BOX
MULTI_LINE PUB SETFID TRX
MULTI_MEDIA PURGE SETMOUSE TSK
MXC QUIT SETTIME TSM
MXL QUO SETTRACE TXH
NAR RADIO_BUTTON SET_FOCUS TXW
NBF RANDOM SET_NBF UCS
NEXT RANDOMIZE SET_PARAM UID
NID RCD SGN UNLOCK
NOT RDX SHORT_FORM UNT
NUL READ SHOW UNTIL
NUM REC SID UPK
OBJ RECORD SIN USER_LEX
OBJECT REFILE SIZ VAL
OBTAIN RELEASE SORT VARDROP_BOX
OFF REM SQR VARLIST_BOX
ON REMOVE SRT VIA
OPEN RENAME SSN VIDEO_PALETTE
OPT RENUMBER SSZ VIN
OR REPEAT START VIS
OWN RESET STEP V_SCROLLBAR
PAD RESTORE STK WAIT
PASSWORD RET STOP WEND
PCK RETRY STP WHERE
PERFORM RETURN STR WHILE
PFX RND SUB WHO
PGM RNO SWAP WINDOW
PGN ROUND SWITCH WINPRT_SETUP
POINT RSZ SWP WRITE
POP RTY SYS XEQ
POPUP_MENU RUN SYSTEM_HELP XFA
POS SAME SYSTEM_JRNL XOR

Error Codes and Messages
Appendix: Error Codes
Description:
Whenever ProvideX detects an error, it sets the numeric system variable ERR to an error code (an
integer). The associated error message indicates the type of error. This section of the Language
Reference contains a listing by error number, with error messages and descriptions of the error conditions
reported by ProvideX.
ERR values greater than 255 indicate Operating System errors. In these cases, ProvideX returns the
value of the Operating System's error code (integer) plus 256.
You can use the MSG( ) function to obtain the error message associated with a specific error number:
->?msg(4)
Error #4: Device not ready
Error # Possible Reasons: Error Codes & Messages

0 Error #0: Record/file busy
Possible reasons:
1 Cannot OPEN a file that is LOCKed by another user.
2 Cannot READ, FIND, EXTRACT, or INPUT if a record is being EXTRACTed
by another user.
3 Time-out occurred on a device.
4 Permission denied.
The BSY=stmtref option allows you to trap Error #0: Record/file busy.
1 Error #1: Logical END-OF-RECORD reached
Combined length of data elements cannot exceed preset maximum record length
(as defined for your given file).
2 Error #2: END-OF-FILE on read or File full on write
Possible reasons:
1 On a read: the end of the file has been reached or
2 On a write: the file is full or has reached a preset maximum record count.
3 [TCP] disconnection
When ProvideX is processing a CLOSE directive and Error #2 is reported because of a
full disk, the error is only reported once. Then ProvideX internally trashes the pending
data and CLOSEs the channel.
3 Error #3: Input/Output error on file
A physical (hardware) error was returned from a device. If errors are recurring on
a disk drive: record and report them to your hardware maintenance supplier.
4 Error #4: Device not ready
A "not ready" status was returned from the device. If the device is a printer, see if
it's out of paper or the off-line button has been pressed.
5 Error #5: Data error on device or file
Typically reports a hardware malfunction: an error has occurred on a device
during a read or write (most often on a read, indicating that the system is
unable to read the data correctly).
6 Error #6: Directory error
Unable to re-establish a LOCK on a file.

7 Error #7: Access out of file boundaries
On a read or write: cannot use a record index which exceeds the maximum
number of records allowed for the file.
8 Error #8: Data write error
Typically reports a hardware malfunction: an error has occurred while trying to
update a data file.
9 Error #9: Unable to restore calling program
DOS only unable to reLOAD a program that was removed from memory (due to
memory limitations).
10 Error #10: Illegal pathname specified
Invalid file name on a SAVE, OPEN, LOAD, RUN, or CALL directive. (Possible
reasons: filename too long, contains invalid characters, or has invalid
syntax. A NULL string is an invalid path name.)
In [TCP], an invalid IP or DNS address.
11 Error #11: Record not found or Duplicate key on write
Non-existent record specified in KEY= or IND= option. On a READ or EXTRACT
directive (KEY= option only) index position goes to the record with the next
higher record key. Use the DOM= option to trap and process this error.
OR [TCP] file I/O includes an IND=value or KEY=value for a client that is not
connected.
12 Error #12: File does not exist (or already exists)
Possible reasons:
1 Cannot create a file (DIRECT, INDEXED, SORT, etc.) if a file of the same
given name already exists.
2 Filename does not exist: cannot ERASE, OPEN, LOAD, RUN, or CALL a
non-existent file.
3 In [TCP], cant OPEN, server is not listening.
13 Error #13: File access mode invalid
Possible reasons:
1 Cannot send output to SERIAL file unless first LOCKed.
2 Cannot receive input from an output-only device (e.g. a printer)
3 Cannot send output to an input only device
4 Cannot write given output to file without a KEY= option or not before
EXTRACTing a record.
5 Cannot DROP the only active window on a terminal.
6 O/S returned an access mode violation or a permission denied status on an
OPEN INPUT or OPEN PURGE directive for a file.
14 Error #14: Invalid I/O request for file state
Possible causes:
1 Cannot access a file that is not OPENed.
2 Cannot UNLOCK a file that is not locked.
3 Cannot OPEN a logical file number (channel) that is already open
4 On a CLOSE directive: cannot close a channel that is not open, but no
message is returned unless you used the ERR= option.)
15 Error #15: Operating system command failed
1 Returned from the Operating System. For more details PRINT MSG(-1)
One possible reason: exhaustion of .BMP handles.
2 In [TCP], cant OPEN the socket locally or general TCP failure on file I/O.

16 Error #16: File/Disc is full
Typically: either the disk is full or the user has reached an allotted limit. The file
being written to has no additional room for expansion.
17 Error #17: Invalid file type or contents
Possible reasons:
1 Cannot use a KEY= option when the file does not have a key.
2 Cannot have unequal lengths for the two parameters for an AND( ), IOR( ),
or XOR( ) function.
3 Cannot SAVE, LIST, or MERGE a file that has a key.
4 Cannot WRITE to a PROGRAM file.
18 Error #18: Program not loaded/Invalid program format
Cannot LOAD, RUN, or CALL a file which is not in the correct PROGRAM format.
19 Error #19: Program size too large
Program exceeds the 64k limit
20 Error #20: Syntax error
The program statement contains a syntax error (usually just a typing error).
21 Error #21: Statement number is invalid
Possible reasons:
1 Cannot use a line number in excess of maximum 65000.
2 Cannot EDIT/append to a non-existent line.
3 Cannot refer incorrectly to an existing line
e.g. TBL=nnnn where nnnn is not a TABLE
4 Program does not have line numbers
22 Error #22: Invalid compound statement
Directive out of position: the particular directive must be the final item in a
compound statement because it has the potential to transfer control (e.g.
GOTO, GOSUB, etc.).
23 Error #23: Missing/Invalid variable
Mandatory variable is missing from the statement's syntax.
24 Error #24: Attempt to duplicate a function name
Cannot create function of the same given name as one that already exists.
25 Error #25: Invalid call to user function (Non-existant or
recursive)
Possible reasons:
1 Cannot call non-existent user-defined function (not defined or name
misspelled)
2 Cannot exceed limit on number of recursive calls to a user defined function.
(Maximum of 10 recursive calls, ten levels deep.)
26 Error #26: Variable type invalid
Possible reasons:
1 Cannot use numeric value in string variable.
2 Cannot use string value in numeric variable.

27 Error #27: Unexpected or incorrect WEND, RETURN, or NEXT
Cannot execute NEXT, WEND, RETURN, or UNTIL if there is no corresponding
entry at the top of the stack (applies to WHILE/WEND, GOSUB/RETURN,
FOR/NEXT,or REPEAT/UNTIL stack).
28 Error #28: No corresponding FOR for NEXT
The variable name for the NEXT directive does not match the variable name
given for the current FOR directive.
29 Error #29: Invalid Mnemonic or position specification
Possible reasons:
1 Unrecognized or invalid mnemonic (undefined or misspelled, etc.) on a
PRINT or INPUT statement (only generated if you have already set the 'EG'
mnemonic).
2 Invalid position in @( ) function (outside of current window/scroll region
boundaries).
30 Error #30: Statement too complex -- cannot compile
Expression cannot exceed 249 parentheses.
31 Error #31: Memory limits reached -- Increase '-SZ' option
Cannot exceed preset maximum size for user workspace (set either using a -SZ
option or in the START directive). Free some of the workspace (delete
unused variables, arrays, etc.) or increase the memory limits.
32 Error #32: Invalid or redundant Input/Output option
Invalid or duplicate option used on the Input/Output directive.
33 Error #33: Insufficent memory available in system -- try later
The Operating System has denied a request for additional memory. Either the
amount of memory being requested exceeds system capacity or the
memory is in use.
34 Error #34: Directive not allowed from COMMAND mode
The particular directive cannot be executed from COMMAND mode. The FOR
directive is one example.
35 Error #35: Invalid date/time specified
An invalid date or time has been specified on a SETDAY or SETTIME directive.
36 Error #36: ENTER parameters don't match those of the CALL
The parameters in an ENTER directive do not match the parameters in the
corresponding CALL directive. The number and type (numeric or string)
must be the same in both directives.
37 Error #37: Directive can only execute in subprogram
Cannot execute an ENTER or EXIT directive except in subprogram.
38 Error #38: Directive cannot be used within CALLed program
The particular directive cannot be used in a subprogram.
39 Error #39: Invalid record definition
This message applies to ODBC data.

40 Error #40: Divide check or numeric overflow
1 Cannot divide by zero. (To return zero for divide by zero errors, set the D0
parameter ON.)
2 Cannot exceed the machine's limits on the result of an arithmetic operation.
41 Error #41: Invalid integer encountered (range error or non-
integer)
Either the value specified is not an integer or it exceeds the range allowed for the
type of operation being performed.
For example:
1 Cannot use logical file number (channel) outside of permitted range.
2 Cannot set PRECISION to value outside of range -1 to +14
3 Cannot exceed 32767 elements in an array.
4 Cannot use line or column position @...( ) function outside of preset window
or screen boundaries
5 Cannot return function value outside of existing range, for instance, a non-
existent TSK( ) number
42 Error #42: Subscript out of range/Invalid subscript
The value of the subscript is beyond the minimum/maximum settings defined for
the array.
43 Error #43: Format mask invalid
The format mask in a PRINT statement or a STR( ) function is not large enough
to contain the numeric value. Use the 'FI' parameter to suppress the
message.
44 Error #44: Invalid step value
Cannot use zero (0) for the STEP value in a FOR directive.
45 Error #45: Referenced statement invalid
Incorrect reference to existing statement (e.g. IOL=nnnn where nnnn does not
contain an IOLIST or TBL=nnnn where nnnn does not contain a TABLE
directive).
46 Error #46: Length of string invalid
Possible reasons:
1 Length of the string in the KEY= option cannot exceed the key length for the
given file.
2 Cannot execute the ASC( ) function on a null string.
47 Error #47: Substring reference out of string
Possible reasons:
1 Substring does not exist in string variable or
2 Substring exceeds the capacity of the variable.
48 Error #48: Invalid input -- Try again
This error occurs when data input is checked against a validation list. It indicates
one of the following:
1 Value for numeric variable is not in the range specified or has too many
decimals.
2 Value for a string variable exceeds the maximum length allowed.

49 Error #49: <*> Internal program format error <*>
The compiled statement contains invalid data and cannot be processed or
decompiled. This is either because of an internal ProvideX error or because
the program code has been modified externally. Possible reasons:
The program on disk has been damaged.
The program was created using a feature from a newer version of ProvideX
which is not supported by the version you are using.
A new version of ProvideX was installed without the correct Lex tables (/pvx/
lib/_lex*.*)
50 Error #50: Memory Parity error
51 Error #51: Invalid VFU/key load

The VFU is not loaded because the mnemonic sequence is incorrect or other
than numeric data has been inserted between the 'SL' and 'EL' printer
mnemonics.
52 Error #52: Program is password protected
The current program has been saved with a PASSWORD.
1 Cannot change or list the program without using the PASSWORD directive.
2 Cannot save a passworded program to a SERIAL file.
53 Error #53: Invalid password
The password entered does not match the password recorded for the program.
(ProvideX Technologies can recover a program if the password is unknown.)
54 Error #54: Unable to load device
55 Error #55: Cannot locate statement label

Non-existent or misspelled statement label during program execution. (If the
label is missing during a SAVE operation, the program is saved without a
reported error but the program may not function properly.)
56 Error #56: Duplicate statement label
This error is only generated by the SAVE command. It warns that a statement
label has been defined twice. The SAVE operation is completed without
error, but the program may not function properly.
57 Error #57: No such window defined
Possible reasons:
1 Non-existent window number: cannot locate for a 'DROP'/'GOTO'
2 Cannot exceed window number 248 in creating new Window.
58 Error #58: Line(s) in GOSUB/FOR/WHILE stack
One of the program lines you are trying to edit is currently in the stack. You must
RESET or END the program before making the change.
59 Error #59: Invalid directive in multi-line function
In a multi line function, cannot include a directive which could reset the stack or
return to program COMMAND mode.

60 Error #60: Invalid control argument value
61 Error #61: Authorization failure

Cannot run an unauthorized program or system function. Contact your dealer to
obtain the proper activation keys.
62 Error #62: Not a development system
Cannot create (or change access to) a secured program. Only developers can
perform this task.
63 Error #63: Not activated for this ID
Cannot SAVE a program using a package id without an activation key.
64 Error #64: No valid LEX table loaded
65 Error #65: Window element does not exist or already exists

Cannot reference non-existent window or GUI object that has not yet been
drawn.
66 Warning #66: Program size approaching 64K limit
Providex issues this warning when you SAVE a program that is getting close to
the 64k limit.
67 Error #67: VBX processor reported a failure
The VBX Processor reported back with an error.
68 Error #68: RPC (Remote Process Call) name not found
Cannot issue a call to a remote system that has not yet been defined.
69 Error #69: No Journalization file open
File marked to be journalized but no journal file is open.
70 Error #70: EDIT command syntax error
The EDIT directive was incorrectly entered. No changes will be made to the
program.
71 Error #71: String not found
The string given (enclosed in square brackets) has not been found.
72 Error #72: Replacement string will not fit
The length of the string following an EDIT 'R' directive exceeds the number of
characters remaining in the original line. The complete EDIT command is
rejected.
73 Error #73: No current string defined
Cannot reference the current string using [ ] because no current string has been
defined.
74 Error #74: RENUMBER rejected -- Line numbers too large
Cannot RENUMBER if the result will generate statements exceeding maximum
65000. Change the RENUMBER directive to reduce the highest line
number used.

75 Error #75: Invalid Hex string
Cannot use characters other than 0 to 9 or A to F in a Hex string.
76 Error #76: LINE_SWITCH failure - Terminal cannot be switched
The system cannot properly switch file 0 (zero) to the specified file (cannot switch
to a file that is not a terminal).
77 Error #77: Edit generates no line number
On EDIT directive, the resultant string does not contain a valid leading line
number.
78 Error #78: Invalid MSK specification
Possible reasons:
1 The mask specified in the MSK( ) function is invalid.
2 Cannot reuse as current mask if no previous mask already available.
79 Error #79: Invalid FORMAT specification
The IOLIST contains an invalid format specification.
80 Error #80: Invalid key definition
Possible reasons:
1 Invalid key definition on a KEYED directive
2 Invalid key number referenced
81 Error #81: Invalid IOLIST specification
The IOLIST contains an invalid specification.
82 Error #82: File must be 'LOCKED' before being 'PURGED'
File must be LOCKed before using a PURGE directive to erase all data.
83 Error #83: Invalid statement number range
Cannot have invalid range of statement numbers (e.g. an ending statement
number less than the starting statement number).
84 Error #84: No DICTIONARY exists on OPENed file
No internal data dictionary exists but the file Input/Output directive is looking for
one.
85 Error #85: Program does not support line numbers..
Returned if trying to use line numbers when system parameter 'NN' set to prohibit
line numbers
86 Error #86: Transmission error to device
A communications problem is reported between a host and a WindX client
(usually when the client does not respond quickly).
87 Error #87: MENUBAR definition invalid
Syntax error in a menubar definition
88 Error #88 Invalid/unknown property name
89 Error #89 to Error #96

to
Reserved for future use.
96

97 Error #97: Directive requires use of '-TB' option
98 Error #98: Feature not yet implemented

Cannot use the particular function or directive because it isn't implemented in this
release of ProvideX.
99 Error #99: Feature not supported
Cannot use the particular function or directive because it's not implemented or
available on this hardware platform.
100 Error #100: No driver for terminal type or library missing
During initialization: ProvideX could not locate the device driver module for the
type of terminal you are using (as defined in the TERM environment
variable). This error may also result because the system cannot find the
ProvideX library.
101 Error:101 to Error 102
to
No message. Reserved for future use.
102
103 Error #103: Control Interval (CI) error
104 Error #104: Disk I/O error
For Errors NOTE: Errors 105 to 114 (below) signal a logical error in the format of the
105 to 114, KEYED file being referenced. Try to recover the file if possible, either
below by restoring it from a backup or by running the *UFAR File Recovery
utility.
105 Error #105: Keyed file error (Short key block)
Reported whenever a key/data block is read from the file and the O/S reports that
the data read is less than was expected. Normally this indicates a truncated
file caused by O/S failure.
106 Error #106: Keyed file error (Bad key block hdr)
The key/data block read has an invalid header. The first byte of the data block
which indicates the type of data stored within the block is incorrect.
107 Error #107: Keyed file error (Wrong key block addr)
The logical address field within the key/data block (offset 2,4) does not match the
address that was expected.
108 Error #108: Keyed file error (Record length invalid)
A data record read from the file has an invalid record length field. The record
length must not exceed the maximum record length for the file.
109 Error #109: Keyed file error (Deleted record chain bad)
The deleted record chain on a fixed record length keyed file is corrupted. Each
record on this chain should have a deleted record flag set.
110 Error #110: Keyed file error (No EOF flag found)
The key structure has become corrupted as there is no logical EOF key entry.

111 Error #111: Keyed file error (Record data unreadable)
The system was unable to read a record from a fixed record length keyed file.
The operating system is indicating that the data is not available, usually due
to file truncation.
112 Error #112: Keyed file error (Record key size invalid)
A data record read from the file has an invalid external key size length. The
external key size must not exceed the maximum defined for the file.
113 Error #113: Keyed file error (Variable record offset bad)
An offset within a data block is invalid. The offset which indicates where within
the data block the physical record starts must contain a positive value not
exceeding the size of the data block.
114 Error #114: Keyed file error (Physical record address bad)
A logical record address in a variable length record file is incorrect. A logical address
consists of a block address plus a one-byte record index within the block. The record
index must be between 1 and 255. This error is reported if the index is zero.
115 Error #115: File I/O Verification Error
116 Error #116: Invalid field descriptor byte
117 Error #117: Invalid segment number
118 Error:118 to Error 119
to
119
120 Error #120: Internal system logic error
Contact ProvideX Technologies for technical support.
121 Error #121: Invalid program format
122 Error:122
123 Warning #123: The following statement labels cannot be located
This warning appears when a non-existent label is referenced in a program.
124 Warning #124: The following statement labels occur more than once
This warning apprears when the same label is defined more than once in a
program.
125 Error #125: Memory Parity error
126 Error #126: Forced termination - No valid activation file

Please contact ProvideX Technologies
127 Error #127: Break key depressed
An internal error generated when either the user hits the BREAK key or an
ESCAPE directive is encountered.

256 OPERATING SYSTEM ERRORS
and
Any error message over 255 is a reported Operating System error. ProvideX
>256
reports O/S errors by taking the actual O/S error number and adding 256.
You can use the following requests to determine what these errors are:
PRINT MSG(error# )
or
PRINT MSG(RET)

Providex Reference Lenguaje

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Providex Reference Lenguaje

Uploaded by

Copyright:

Available Formats

Welcome to the

ProvideX Language Reference Version 4.20x

If Youre New to ProvideX:

NOTE: Some Operating Systems are no longer supported.

NOTE that this is a BETA release of the ProvideX Language

1 ProvideX Language Reference (Ver. 4.20x) 10/10/01 1

Common Syntax Elements

Syntax Element What to Use

2 ProvideX Language Reference (Ver. 4.20x) 10/10/01 2

Exception: ProvideX verifies the existence of an IOLIST and stmtref for

See also: Operators Supported in ProvideX, p. 587.

3 ProvideX Language Reference (Ver. 4.20x) 10/10/01 3

4 ProvideX Language Reference (Ver. 4.20x) 10/10/01 4

Topic Types & Locations

Symbol Cross Reference Is To A

If Youre New to ProvideX See If Youre New to ProvideX, p. 8

Directives: See Directives, System Functions and Variables, p. 10

System Functions: See Directives, System Functions and Variables, p. 10

5 ProvideX Language Reference (Ver. 4.20x) 10/10/01 5

FID( ), FIB( ), FIN( ) See Directives, System Functions and Variables, p. 10

See also: FIB( ), FID( ) and FIN( ) File Information, p. 141(f)

FIB( ) Return File Information Block, p. 142(f)

FID( ) Return File Information Descriptor, p. 145(f)

FIN( ) Return File Information, p. 149(f)

System Variables: See Directives, System Functions and Variables, p. 10

Mnemonics: Mnemonics, p. 486

See also: MNEMONIC Define File Command Sequence, p. 265(d)

PRM Current ProvideX Parameter Settings, p. 324(v)

PRM( ) Return Parameter Value, p. 325(f)

System Parameters: System Parameters, p. 537

6 ProvideX Language Reference (Ver. 4.20x) 10/10/01 6

Special Files: Specialty *File* Handling, p. 589

7 ProvideX Language Reference (Ver. 4.20x) 10/10/01 7

ProvideX Punctuation/Syntax Conventions

8 ProvideX Language Reference (Ver. 4.20x) 10/10/01 8

9 ProvideX Language Reference (Ver. 4.20x) 10/10/01 9

10 ProvideX Language Reference (Ver. 4.20x) 10/10/01 10

1 Return Column Position @X(col[,chan][,ERR=stmtref])

->PRINT 'TEXT'(A,B),"X MARKS THE SPOT" ! Starts at column 1, line 2

11 ProvideX Language Reference (Ver. 4.20x) 10/10/01 11

Return Absolute Value ABS(num[,ERR=stmtref])

Returns: Numeric, absolute value of expression. Always positive or zero.

12 ProvideX Language Reference (Ver. 4.20x) 10/10/01 12

Read a Keystroke ACCEPT (chan[,fileopt])char$

See also: INPUT Get Input from Terminal, p. 192(d)

OBTAIN Get Hidden Terminal Input, p. 293(d)

13 ProvideX Language Reference (Ver. 4.20x) 10/10/01 13

Return Arc-Cosine ACS(num[,ERR=stmtref])

Returns: Numeric value between 0 (zero) and (pi=3.14159...)

14 ProvideX Language Reference (Ver. 4.20x) 10/10/01 14

Load Program in Memory ADDR prog_name$[, ERR=stmtref]

See also: DROP Removes Program from Memory, p. 98(d)

START Restart ProvideX, p. 404(d)

15 ProvideX Language Reference (Ver. 4.20x) 10/10/01 15

Logical AND AND(string_1$,string_2$[,ERR=stmtref])

Returns: String result of bit-wise logical AND comparison

Examples: AND(A$,B$) HEX Equivalent Binary

0140 READ (1,END=1000)F$

16 ProvideX Language Reference (Ver. 4.20x) 10/10/01 16

Return Argument Value ARG(position[,ERR=stmtref])

Returns: String, value of start up argument

Given PVX -SZ=20 -ARG TOM JONES:

See also: NAR Number of Arguments, Start Providex, p. 284(v)

17 ProvideX Language Reference (Ver. 4.20x) 10/10/01 17

Special Files: Specialty File Handling, p. 589