Basic Udt

UniBasic Commands
Reference
S
A O F T W A R E
P R O D U C T S
T
A
D
I
N
U
UniData
Relational Database Management System
®
for UNIX
DATA MANAGEMENT THAT WORKS.

All rights to this publication are reserved. No part of this document may be reproduced, transmitted, tran-
scribed, stored in a retrieval system, or translated into any language, in any form or by any means, without
prior written permission from Unidata, Inc. If you are a licensed user of this product, however, Unidata
grants you a limited, nontransferable license to reproduce this particular document. This is limited to pho-
tocopy reproduction of a Unidata-supplied master copy. Copies must include all pages contained in the
master copy (including this page) and must be intended strictly for internal distribution and use by the lic-
ensee, its employees, and assigns. Reproduced copies may not be transferred, in whole or in part, to any
party outside the licensee’s place(s) of business.
Copyright © 1994 Unidata, Inc.

All Rights Reserved
UniData Release 3.3 for UNIX
Documentation D33-0015
Rev. 111594
Unidata, Inc., reserves the right to make changes to this document and the software described herein at any
time and without notice. No warranty is expressed or implied other than that contained in the terms and
conditions of sale, and in no case is Unidata, Inc., liable for more than the purchase price of the product.
Unidata, Inc.
1099 18th Street, Suite 2200
Denver, Colorado 80202
Phone: (303) 294-0800
Fax: (303) 293-8880
Principal Technical Writer

Bryan Justice, Steven J. Owens
Product Information Group

Lisa Booth, Bryan Justice, Kathleen Kennedy, Steven J. Owens, Peggy Simmons, Jim Vênis
Contributors and Technical Reviewers

Doug Armatage, Jackie Burhans, Li Chen, James Crowder, Claire Gustafson, Jan Magid, Doug Ray, David
Seagle, Wally Terhune
Unidata and UniData are registered trademarks of Unidata, Inc. UniDesktop and UniServer are trademarks of Unidata, Inc. Pick is
a registered trademark of Pick Systems. Unidata is not a licensee of Pick Systems. SYBASE is a registered trademark, and DB-
Library, Net Library, Open Client, Open Server, and SYBASE Server Library are trademarks of Sybase, Inc. UNIX is a registered
trademark of UNIX System Laboratories, Inc. VMS is a trademark of Digital Equipment Corporation. Other trademarks and regis-
tered trademarks are the property of the respective trademark holders.
Contents SOFTWARE PRODUCTS
Reference UniBasic Commands and Functions ....................... 14

Elements of Syntax Statements .....................................................15
@ ...................................................................................................16
[ ] ...................................................................................................21
{ } or CALCULATE .....................................................................23
$BASICTYPE ...............................................................................25
$DEFINE ......................................................................................26
$IFDEF .........................................................................................27
$IFNDEF ......................................................................................29
$INCLUDE ...................................................................................31
$UNDEFINE ................................................................................33
ABORT .........................................................................................34
ABS ...............................................................................................36
ACOS ............................................................................................37
ALPHA .........................................................................................38
ASCII ............................................................................................39
ASIN .............................................................................................40
ASSIGN ........................................................................................41
ATAN ...........................................................................................42
BITAND .......................................................................................43
BITOR ..........................................................................................44
BITNOT ........................................................................................45
3
Contents
BITXOR ........................................................................................46
BPIOCP ........................................................................................47
BREAK .........................................................................................49
CALCULATE ...............................................................................51
CALL ............................................................................................52
CALLC .........................................................................................56
CASE ............................................................................................57
CAT ..............................................................................................60
CATS ............................................................................................61
CHAIN ..........................................................................................62
CHANGE ......................................................................................63
CHAR ...........................................................................................64
CHARS .........................................................................................65
CHECKSUM ................................................................................66
CLEAR .........................................................................................67
CLEARCOMMON .......................................................................68
CLEARDATA ..............................................................................69
CLEARFILE .................................................................................70
CLEARINPUT ..............................................................................72
CLEARSELECT ...........................................................................73
CLEARSQL ..................................................................................75
CLOSE ..........................................................................................76
CLOSESEQ ..................................................................................78
COL1 ............................................................................................80
COL2 ............................................................................................81
Comment .......................................................................................82
COMMON ....................................................................................83
CONNECT ....................................................................................87
CONTINUE ..................................................................................89
CONVERT ....................................................................................90
CONVERT ....................................................................................92
4
Contents
COS ...............................................................................................94
COUNT .........................................................................................95
COUNTS ......................................................................................97
CRT ...............................................................................................99
DATA .........................................................................................100
DATE ..........................................................................................101
DCOUNT ....................................................................................102
DEBUG .......................................................................................104
DEFFUN .....................................................................................106
DEL .............................................................................................108
DELETE .....................................................................................110
DELETE .....................................................................................112
DELETELIST .............................................................................114
DELETEU ..................................................................................115
DIMENSION ..............................................................................117
DIR ..............................................................................................120
DISCONNECT ...........................................................................121
DOWNCASE ..............................................................................122
DQUOTE ....................................................................................123
DROUND ...................................................................................124
EBCDIC ......................................................................................125
ECHO ..........................................................................................126
END ............................................................................................127
ENTER ........................................................................................128
EQ ...............................................................................................130
EQS .............................................................................................131
EQUATE ....................................................................................132
EXECUTE ..................................................................................134
EXECUTESQL ...........................................................................135
EXIT ...........................................................................................138
EXP .............................................................................................139
5
Contents
EXTRACT ..................................................................................140
FIELD .........................................................................................142
FIELDSTORE ............................................................................144
FILEINFO ...................................................................................146
FILELOCK .................................................................................149
FILEUNLOCK ...........................................................................151
FIND ...........................................................................................153
FINDSTR ....................................................................................155
FLUSH ........................................................................................157
FMT ............................................................................................158
FOOTING ...................................................................................161
FORMLIST .................................................................................163
FOR/NEXT .................................................................................164
FUNCTION ................................................................................166
GARBAGECOLLECT ...............................................................167
GE ...............................................................................................168
GES .............................................................................................169
GET .............................................................................................170
GETCOLUMNDATA ................................................................173
GETCOLUMNNAME ................................................................175
GETENV ....................................................................................177
GETERRMSG ............................................................................178
GETLIST ....................................................................................179
GETNEXTTUPLE ......................................................................181
GETPTR .....................................................................................183
GETPU ........................................................................................185
GETREADU ...............................................................................186
GETUSERNAME .......................................................................187
GETUSERGROUP .....................................................................188
GOSUB .......................................................................................189
GOTO .........................................................................................191
6
Contents
GROUP .......................................................................................193
GROUPSTORE ..........................................................................195
GT ...............................................................................................198
GTS .............................................................................................199
HASH ..........................................................................................200
HEADING ..................................................................................201
HUSH ..........................................................................................204
ICONV ........................................................................................205
IF/THEN/ELSE ..........................................................................215
IN ................................................................................................217
INDEX ........................................................................................218
INDICES .....................................................................................220
INMAT .......................................................................................222
INPUT .........................................................................................223
INPUT @ ....................................................................................227
INPUTERR .................................................................................229
INPUTIF .....................................................................................230
INPUTNULL ..............................................................................231
INPUTTRAP ..............................................................................232
INS ..............................................................................................234
INSERT ......................................................................................236
INT ..............................................................................................238
ITYPE .........................................................................................239
LE ................................................................................................241
LES .............................................................................................242
LEN .............................................................................................243
LENS ..........................................................................................244
LN ...............................................................................................245
LOCATE .....................................................................................246
LOCK ..........................................................................................250
LOOP/REPEAT ..........................................................................253
7
Contents
LOWER ......................................................................................256
LT ................................................................................................257
LTS .............................................................................................258
MAT ............................................................................................259
MATBUILD ...............................................................................261
MATCH
MATCHES .................................................................................264
MATCHFIELD ...........................................................................266
MATPARSE ...............................................................................268
MATREAD .................................................................................271
MATREADL ..............................................................................274
MATREADU ..............................................................................277
MATWRITE ...............................................................................280
MATWRITEU ............................................................................282
MAXIMUM ................................................................................284
MDPERFORM ...........................................................................285
MINIMUM .................................................................................290
MOD or REM .............................................................................291
NE ...............................................................................................292
NES .............................................................................................293
NEG ............................................................................................294
NEXT ..........................................................................................295
NOCONVERT ............................................................................296
NOT ............................................................................................298
NOTS ..........................................................................................299
NULL ..........................................................................................300
NUM ...........................................................................................301
NUMS .........................................................................................302
OCONV ......................................................................................303
OCONV Date (D) .......................................................................305
OCONV Group (G) ....................................................................309
8
Contents
OCONV Length (L) ....................................................................310

OCONV Masked Character (MC) ..............................................311
OCONV Masked Decimal (MD) ................................................313
OCONV Left Justify (ML) .........................................................315
OCONV Packed Decimal (MP) ..................................................317
OCONV Packed Decimal (MP1) ................................................318
OCONV Right Justify (MR) .......................................................319
OCONV Time (MT) ...................................................................321
OCONV Hex (MX), Octal (MO), Binary (MB) .........................322
OCONV Pattern Match (P) .........................................................324
OCONV Range (R) .....................................................................325
OCONV (S) ................................................................................326
OCONV Text Extraction (T) ......................................................327
OCONV File Translation (Tfile) ................................................328
OCONVS ....................................................................................330
ON/GOSUB ................................................................................331
ON/GOTO ..................................................................................333
OPEN ..........................................................................................335
OPENSEQ ..................................................................................339
OSBREAD ..................................................................................343
OSBWRITE ................................................................................346
OSCLOSE ...................................................................................348
OSDELETE ................................................................................349
OSOPEN .....................................................................................351
OSREAD ....................................................................................354
OSWRITE ...................................................................................357
PAGE ..........................................................................................359
PCPERFORM .............................................................................361
PERFORM ..................................................................................363
PRECISION ................................................................................368
PRINT .........................................................................................370
9
Contents
PRINTER ....................................................................................372
PRINTER CLOSE ......................................................................373
PRINTERR .................................................................................374
PROCREAD ...............................................................................377
PROCWRITE .............................................................................379
PROGRAM .................................................................................380
PROMPT ....................................................................................381
PWR ............................................................................................382
QUOTE .......................................................................................383
RAISE .........................................................................................384
READ ..........................................................................................385
READBCK .................................................................................388
READBCKL ...............................................................................390
READBCKU ..............................................................................392
READFWD .................................................................................394
READFWDL ..............................................................................396
READFWDU ..............................................................................398
READL .......................................................................................400
READLIST .................................................................................403
READNEXT ...............................................................................406
READNEXTTUPLE ..................................................................409
READSELECT ...........................................................................411
READSEQ ..................................................................................412
READT .......................................................................................414
READU .......................................................................................418
READV .......................................................................................421
READVL ....................................................................................424
READVU ....................................................................................427
READXFWD ..............................................................................430
READXBCK ..............................................................................432
RECORDLOCKED( ) ................................................................434
10
Contents
RECORDLOCKL .......................................................................436
RECORDLOCKU ......................................................................438
RELEASE ...................................................................................440
REMOVE ....................................................................................442
REMOVE ....................................................................................446
REPLACE ...................................................................................448
RESIZET ....................................................................................451
RETURN ....................................................................................453
REUSE ........................................................................................454
REWIND ....................................................................................455
RND ............................................................................................457
RNDSEED ..................................................................................458
SADD ..........................................................................................459
SCMP ..........................................................................................460
SDIV ...........................................................................................461
SELECT ......................................................................................462
SELECTINDEX .........................................................................465
SELECTINFO ............................................................................467
SEND ..........................................................................................468
SEQ .............................................................................................470
SEQS ...........................................................................................471
SETINDEX .................................................................................472
SETTABLE ................................................................................475
SETROW ....................................................................................477
SIN ..............................................................................................479
SLEEP .........................................................................................480
SMUL .........................................................................................482
SOUNDEX .................................................................................483
SPACE ........................................................................................485
SPACES ......................................................................................486
SPLICE .......................................................................................487
11
Contents
SQUOTE .....................................................................................488
SQRT ..........................................................................................489
SSUB ..........................................................................................490
STATUS .....................................................................................491
STOP ...........................................................................................492
STR .............................................................................................494
STRS ...........................................................................................495
SUBROUTINE ...........................................................................496
SUBSTRINGS ............................................................................498
SUM ............................................................................................499
SWAP .........................................................................................501
SYSTEM .....................................................................................503
TAN ............................................................................................506
TIME ...........................................................................................507
TIMEDATE ................................................................................508
TRANSACTION ABORT ..........................................................509
TRANSACTION COMMIT .......................................................511
TRANSACTION START ...........................................................513
TRIM ..........................................................................................515
TRIMB ........................................................................................517
TRIMF ........................................................................................518
TRIMS ........................................................................................519
UDTEXECUTE ..........................................................................520
UNASSIGNED ...........................................................................522
UNLOCK ....................................................................................523
UPCASE .....................................................................................524
USE .............................................................................................525
WAIT ..........................................................................................527
WEOF .........................................................................................529
WEOFSEQ ..................................................................................532
WRITE ........................................................................................534
12
Contents
WRITELIST ...............................................................................536
WRITESEQ ................................................................................537
WRITESEQF ..............................................................................539
WRITET .....................................................................................541
WRITEU .....................................................................................544
WRITEV .....................................................................................546
WRITEVU ..................................................................................548
XLATE .......................................................................................550
Appendix A ASCII Character Codes ........................................... 552

Appendix B @variables................................................................ 563
@Variables .................................................................................564
Compiler @variables ..................................................................569
@SYSTEM.RETURN.CODE Values ........................................570
Index
13
Reference SOFTWARE PRODUCTS
UniBasic Commands and

Functions
This section contains a detailed alphabetic listing with descriptions and working
examples of all UniBasic commands and functions.
Functions perform specialized operations that augment and enhance commands. You
always use functions as expressions or in expressions following a command.
14
Elements of Syntax Statements
Elements of Syntax Statements

This reference manual uses a common method for stating syntax for UniData com-
mands. The syntax statement includes the command name, required arguments, and
options that you can use with the command. Italics represents a variable that you can
replace with any valid option. The following figure illustrates the elements of a syntax
statement:
command names square brackets indicate

appear in boldface an optional argument
no brackets or braces a vertical line indicates that

indicates a required you may choose between
argument the given arguments
COMMAND required [option] [option1 | option2]

{option1 | option2} required... "string" quotation marks
must enclose a
literal string
braces indicate that you an ellipsis indicates that
must choose between you may enter more than
the given arguments one argument
15
@
Syntax
@(col.expr [,row.expr])
@ (-num.expr)
Description
The UniBasic @ function positions the cursor on the video screen. In the first form,
the system positions the cursor at the column and row you specify.
In the second form, you may specify various terminal functions by num.expr.
An easy way to control screen attributes is to assign the required @ function

Tip to a variable. Assigning an @ function to a variable is more efficient if you
expect to use the @ function more than once.
Note Any reference to @ functions turns off automatic screen pagination.
Parameters
The following table describes each parameter of the syntax:
Parameter Description
col.expr Specifies the column position at which the

cursor will be placed.
May be either a literal value or a variable.
Must be a positive value.
Value 0 is the left edge of the screen. For most
terminals, this value may range from 0 to 79
(the right-hand side of the screen).
[,row.expr] Specifies the row at which the cursor will be
placed. Defaults to the current row.
May be either a literal value or a variable.
Must be a positive value.
Value 0 is the top edge of the screen. For most
terminals, this value may range from 0 to 23
(the last row on the screen).
@ Parameters
16
@
-num.expr Specifies a @ terminal function. Refer to the

next table for the possible range of @ terminal
functions and their effects.
@ Parameters (continued)
@ Terminal Functions
The following table describes the valid @ terminal functions:
Function Description
-1 Clear screen, home cursor

-2 Home cursor
-3 Clear from cursor to end of screen
-4 Clear from cursor to end of line
-5 Enter blink mode
-6 Stop blink mode
-7 Enter protected mode
-8 Stop protected mode
-9 Backspace one character
-10 Move cursor up one line
-11 Enter half-intensity mode
-12 Stop half-intensity mode
-13 Enter reverse video mode
-14 Stop reverse video mode
-15 Enter underlining mode
-16 Stop underlining mode
-17 Down one line
-18 Non-destructive space (cursor right)
@ Terminal Functions
17
@
-19 Audible signal (bell)

-20 Delete character
-21 Insert character
-22 Delete line
-23 Add new blank line
-24 Turn on the printer
-25 Turn off the printer
-26 Print contents of the screen
-27 Start alternate character set
-28 End alternate character set
-29 to -49 Reserved for color combinations
-50 Sent by the backspace key
-51 Sent by the clear screen or erase key
-52 Sent by the delete character key
-53 Sent by the insert character key
-54 Sent by the delete line key
-55 Sent by the insert line key
-56 Sent by the home key
-57 Sent by the left arrow key
-58 Sent by the up arrow key
-59 Sent by the down arrow key
-60 Sent by the right arrow key
-61 Sent by the clear-to-end-of-line key
-62 Sent by the clear-to-end-of-screen key
-63 Sent by function key F0
@ Terminal Functions (continued)
18
@

-74 Sent by the next-page key
-75 Sent by the previous-page key
-76 Sent by the scroll forward/down key
-77 Sent by the scroll backward/up key
-78 Sent by the set-tab key
-79 Sent by the terminal up arrow key
-80 Out of “keypad transmit” key
-81 Turn bold on
-82 Turn bold off
-83 Turn standout on
-84 Turn standout off
@ Terminal Functions (continued)
Examples
In the following example, the statement prints the message HI in the fifth column from
the left of the screen and the tenth row down from the top:
PRINT @(5,10):"HI"
19
@
In the next example, the program segment prints two messages at different points on
the screen:
ROW = 0 ; COL = 0
PRINT @(COL,ROW):"TOP":@(COL,ROW+21):"BOTTOM"
In the next example, the program segment starts reverse video mode, prints a prompt,
then stops reverse video mode:
PRINT @(-13)
PRINT "ENTER NAME:":
PRINT @(-14)
In the next example, the program segment clears the screen and places the cursor in
the home position:
CLS = @(-1)
PRINT CLS
Related Topics
@variables
For information on @variables, refer to Appendix B @variables.
Terminal and Printer Input/Output

For information on terminal and printer input/output, refer to Developing UniBasic
Applications.
REUSE.ROW
The ECL REUSE.ROW command changes the way the cursor moves on a terminal
when the cursor positioning is controlled by the @ function. For information on
REUSE.ROW, refer to UniData Commands Reference.
20
[]
[]
Syntax
string.expr [num.expr1,num.expr2] = expr
expr = string.expr [num.expr1, num.expr2]
Description
The UniBasic [ ] “square brackets” function either extracts or replaces strings.
BASICTYPE In BASICTYPE M, the [ ] “square brackets” function can remove a substring

to null and remove elements of the substring, but does not replace the null
with spaces.
Parameters
string.expr In the first form, the function replaces part or

all of string.expr. In the second form, the
function extracts part or all of string.expr.
num.expr1 Indicates the starting position for the operation.
It refers to the character position where the
replacement or extraction operation occurs.
num.expr2 Indicates the number of characters involved in
the operation. If the system performs an extrac-
tion, it returns that number of characters. If the
system performs a replacement, it replaces that
number of characters.
[ ] Parameters
Examples
In the following example, the program segment extracts the first character of the vari-
able LAST.NAME, in this case an S:
LAST.NAME = ’Smith’
L.INITIAL = LAST.NAME[1,1]
21
[]
In the next example, the program segment changes the first letter of the word Bind in
the variable TITLE to W. The resulting string is “Gone with the Wind”.
TITLE = ’Gone with the Bind’
TITLE[15,1] = ’W’
In the next example, the program segment changes the substring 234 to nulls. In
BASICTYPE M, A will be “15.” In all other BASICTYPES, a will be “1 5.”
A = "12345"
A[2,3] = ""
Related Topics
String Manipulation and Extraction
For information on string manipulation and extraction, refer to Developing UniBasic
Applications.
22
{ } CALCULATE
{}
CALCULATE
Syntax
{dictionary.item}
CALCULATE(dictionary.item)
Description
The UniBasic { } “braces” or CALCULATE function executes and captures the
results of a virtual attribute. These functions, working with the @variables, @DICT
and @RECORD, permit this operation. The dictionary.item must be a valid virtual
attribute within the dictionary previously opened to the @DICT variable with an
OPEN statement. In the {} form, the dictionary.item must be the literal dictionary
name, with no quotes. In the CALCULATE() form, the dictionary.item may be a
quoted string or a UniBasic variable. The expression uses the data from the current
@RECORD during the evaluation process.
You must open a dictionary to @DICT and read the data record into @RECORD for
the function to work properly.
If these functions are successful, they update the values in the @CONV, @FORMAT,
and @HEADER. The dictionary virtual attribute has values for conversion, format-
ting, and column headings. These values are placed in the @CONV, @FORMAT, and
@HEADER variables after the first execution of the braces function. You may then
use them in other UniBasic functions, such as ICONV, OCONV, and FMT.
Examples
In the following example, the program segment opens the CUSTOMER file to the
variable CUSTOMER and the dictionary of the CUSTOMER file to the special
@DICT variable. After selecting the CUSTOMER file, the program reads the value of
each record ID into @ID, reads the value of the customer record into @RECORD,
then uses the { } “braces” function to evaluate the current balance (storing the total in
TOTAL.DUE). The braces function updates the @CONV, @HEADER and @FOR-
MAT variables. The system uses these variables in subsequent statements to output
the value with a heading and correct format.
OPEN ’’,’CUSTOMER’ TO CUSTOMER ELSE
STOP ’NO CUSTOMER’
END
OPEN ’DICT’,’CUSTOMER’ TO @DICT ELSE
STOP ’NO DICTIONARY FOR CUSTOMER’
END
TOTAL.DUE = 0
23
{ } CALCULATE
SELECT CUSTOMER
MORE = 1
LOOP
READNEXT @ID ELSE MORE = 0
UNTIL NOT(MORE) DO
READ @RECORD FROM CUSTOMER,@ID ELSE
@RECORD = ’’
END
TOTAL.DUE += {BALANCE}
PRINT @HEADER:’’:OCONV({BALANCE},@CONV)
REPEAT
TOTAL.DUE = OCONV(TOTAL.DUE,@CONV)
PRINT "Total Due ":FMT(TOTAL.DUE,@FORMAT)
END
Related Topics
ITYPE
The UniBasic ITYPE function allows a BASIC program to access a UniData virtual
attribute from the dictionary of a UniData file.
24
$BASICTYPE
$BASICTYPE
Syntax
$BASICTYPE “param”
Description
The UniBasic $BASICTYPE command compiles data in a specified BASICTYPE.
The $BASICTYPE statement must be the first non-comment statement.
If you do not specify a $BASICTYPE, the system compiles the program in the
BASICTYPE you specify in the ECL BASICTYPE command. The default type is U.
Note The BASICTYPE param must be in quotes.
Parameters
The following table describes the available parameters:
U UniBasic
P Pick® Basic
R R/Basic
M McDonnell Douglas
$BASICTYPE Parameters
Related Topics
BASICTYPE
For information on the ECL BASICTYPE command, refer to UniData Commands
Reference.
25
$DEFINE
$DEFINE
Syntax
$DEFINE var
Description
The UniBasic $DEFINE command defines a control variable that you can later use to
direct the compilation.
If the $DEFINE statements are kept in a separate INCLUDE file, it is a minor

Tip task to recompile programs with different definitions.
Examples
In the following example, since you define SMALL, when you compile the program
segment, the system defines array1 as a 10-element array and initialized with 0.
$DEFINE SMALL
$IFDEF SMALL
DIM array1(10)
MAT array1 = 0
$ENDIF
Related Topics
$UNDEFINE
The UniBasic $UNDEFINE command deletes the definition of var, previously
defined by $DEFINE.
EQUATE
The UniBasic EQUATE command causes all occurrences of a variable to be replaced
with a variable that you designate during the compilation of a program.
26
$IFDEF
$IFDEF
Syntax
$IFDEF var statements1 [$ELSE statements2] $ENDIF
Description
The UniBasic $IFDEF command compiles one statement or another, depending upon
whether or not the variable var currently has a definition defined by a $DEFINE.
Parameters
var Specifies variable to check to determine whether to

compile statements1 or statements2.
statements1 Specifies statements to compile if var is defined.
statements2 Specifies optional statements to compile if var is not
defined.
$IFDEF Parameters
Examples
In the following example, when you compile the program segment, the system defines
array1 as a 10-element array and initialized with 0:
$DEFINE SMALL
$IFDEF SMALL
DIM array1(10)
MAT array1 = 0
$ENDIF
In the next example, when you compile the program segment, the system defines
array1 as a 100-element array and initializes it with 1:
$UNDEFINE SMALL
$IFDEF SMALL
PRINT ’SMALL was defined’
$ELSE
DIM array1(100)
MAT array1 = 1
$ENDIF
27
$IFDEF
Related Topics
$DEFINE
$IFNDEF
The UniBasic $IFNDEF command checks if a variable is currently undefined. If so,
the system compiles the specified statements. If not, the system compiles other speci-
fied statements.
28
$IFNDEF
$IFNDEF
Syntax
$IFNDEF var statements1 [$ELSE statements2] $ENDIF
Description
The UniBasic $IFNDEF command compiles one statement or another, depending
upon whether or not the variable var is currently undefined by $DEFINE.
Parameters
var Specifies variable to check to determine whether to

compile statements1 or statements2.
statements1 Specifies statements to compile if var is not defined.
statements2 Specifies optional statements to compile if var is
defined.
$IFNDEF Parameters
Examples
In the following example, the program segment nests the $IFDEF and $IFNDEF state-
ments. Upon compilation of this program, the size of array A might be 1000, 10, or
100 depending on whether LARGE or SMALL is defined. If both are undefined, the
size of A is 100 elements, and the initialized value of array A might be 1 or 0, depend-
ing on whether ONE is defined. If the $DEFINE statements are kept in a separate
INCLUDE file, it is a minor task to recompile programs with different definitions.
$IFDEF LARGE
DIM A(1000)
$IFDEF ONE
MAT A = 1
$ELSE
MAT A = 0
$ENDIF
$ELSE
$IFNDEF SMALL
DIM A(100)
$ELSE
29
$IFNDEF
DIM A(10)
$ENDIF
$IFDEF ONE
MAT A = 1
$ELSE
MAT A = 0
$ENDIF
$ENDIF
Related Topics
$DEFINE
$IFDEF
The UniBasic $IFDEF command checks if a variable is currently defined. If so, the
system compiles the specified statements. If not, the system compiles other specified
statements.
30
$INCLUDE
$INCLUDE
Syntax
$INCLUDE record [FROM [DICT] filename]
$INSERT record [FROM [DICT] filename]
$INCLUDE filename {, | | > } record
$INSERT filename {, | > } record
$INCLUDE [pathname {, | | > }] seq.filename
$INSERT [pathname {, | | >}] seq.filename
Description
The UniBasic $INCLUDE and $INSERT commands insert UniBasic source code
from the file you specify into the program being compiled.
The fifth and sixth forms of the $INCLUDE statement insert code from a UNIX or
VMS sequential file.
Parameters
record Specifies the record, including the code you

want to insert.
filename Specifies the name of a UniData directory level
file containing the record, including the code
you want to insert. If you do not specify
filename, the system searches for record in the
current file where the program being compiled
resides.
$INCLUDE Parameters
31
$INCLUDE
pathname Specifies the directory containing seq.file-

name. If you do not specify pathname, the sys-
tem searches for seq.filename in the current file
where the program being compiled resides.
The delimiter between the path and the file or
record, can be a space, comma (,) or a greater
than sign (>).
seq.filename Specifies the name of a UNIX or VMS
sequential file.
$INCLUDE Parameters (continued)
Note The filename can identify a remote file as determined by the VOC entry. The
code to be inserted can also contain $INCLUDE or $INSERT statements.
Examples
In the following example, the program statement inserts the code contained in record
code_seg1 in file BP into the program being compiled:
$INCLUDE code_seg1 FROM BP
In the next example, the program statement inserts the code contained in sequential
file my_code in directory /usr/ud/mydir into the program being compiled:
$INCLUDE /usr/ud/mydir/my_code
32
$UNDEFINE
$UNDEFINE
Syntax
$UNDEFINE var
Description
The UniBasic $UNDEFINE command deletes the definition of var previously
defined by $DEFINE.
Related Topics
$DEFINE
EQUATE
The UniBasic EQUATE command causes all occurrences of a specified variable to be
replaced with a specified variable during the compilation of a program.
33
ABORT
ABORT
Syntax
ABORT [expr]
Description
The UniBasic ABORT command terminates the program or subroutine in progress,
returning the user to the UniData system level. ABORT returns the user to the Uni-
Data prompt, whether the aborted program was called by another program or executed
through a UniData menu or paragraph. ABORT may include an optional string expr to
display when the program aborts. The expression may contain variables, functions,
and arithmetic or string operators.
BASICTYPE The ABORT command in BASICTYPE P provides additional functions.

ABORT prints either a user-defined message specified by the string expr, or
an error message in the system ERRMSG file based on the message-id.
ABORT [message-id]
ABORT [expr,...]
In the first form, the message-id must be a variable which evaluates to a key
contained in the ERRMSG file when compiled in BASICTYPE P. In the sec-
ond form of the ABORT statement, you can specify more than one expr when
compiled in BASICTYPE P.
Tip You may use the ECL ON.ABORT command so that ABORT does not termi-
nate the process. For information on the ECL ON.ABORT command, refer to
UniData Commands Reference.
Examples
In the following example, the program segment attempts to read a record from a file.
If the record does not exist, the program aborts, clears the terminal screen, and prints
the message RECORD IS MISSING at line 10, column 10 on the terminal.
CUST.ID = 1234
OPEN ’’, ’CUSTOMER’ READONLY TO CUSTOMER ELSE STOP "Cannot Open"
READ REC FROM CUSTOMER, CUST.ID ELSE
ABORT @(10,10):’RECORD IS MISSING’
END
In the next example, the segment prints a prompt if an error flag ERR.FLAG has been
set and reads the user’s input into the variable ANS. If ANS equals “Y,” the program
aborts.
34
ABORT
ERR.FLAG = 1
IF ERR.FLAG THEN
PRINT "ABORT PROGRAM?"
INPUT ANS
IF ANS = "Y" THEN ABORT
END
In the next example, in BASICTYPE P, an error message prints and the program ter-
minates when DATAFILE_1 cannot be opened:
EID = "USER-ERROR"
ERR_MSG = "CAN’T OPEN FILE"
OPEN "", "DATAFILE_1" TO DFILE ELSE
ABORT ERR_MSG, EID
END
In the next example, in BASICTYPE P, the program segment prints and the error mes-
sage from record 10075 in the ERRMSG FILE prints if the program aborts:
If A < 0 THEN ABORT 10075
Related Topics
PRINTERR
The UniBasic PRINTERR command prints error messages stored in the system error
message file (ERRMSG).
STOP
The UniBasic STOP command stops execution of a program, but returns control to the
calling program, subroutine, menu, or paragraph, if any.
ON.ABORT
The ECL ON.ABORT command executes a user specified command if a subsequent
UniBasic program aborts. For information on ON.ABORT, refer to UniData
Commands Reference.
CLEAR.ONABORT
The ECL CLEAR.ONABORT command clears the setting of an ON.ABORT com-
mand. For information on CLEAR.ONABORT, refer to UniData Commands
Reference.
Error Message File

For more information on the error message file (ERRMSG), refer to Administering
UniData on UNIX.
35
ABS
ABS
Syntax
ABS(expr)
Description
The UniBasic ABS function returns the positive numeric value (absolute value) of the
argument. expr may be any numeric expression, negative or positive.
Examples
In the following example, the program segment prints the absolute value of the vari-
able NUM. This results in 999 printing.
NUM = -999
PRINT ABS(NUM)
In the next example, the program statement replaces the variable NUM with its abso-
lute value:
NUM = ABS(NUM)
36
ACOS
ACOS
Syntax
ACOS(expr)
Description
The UniBasic ACOS function returns the trigonometric arc cosine (inverse cosine) of
a numeric expression in degrees. expr must be a value between -1 and +1. ACOS
returns a value expressed as the degree of the arc cosine of the input, which ranges
from 0 to 180. If expr evaluates to a value outside the range of -1 and +1, the system
displays an error message and returns 0 as the result.
Examples
In the following example, the program statement assigns 60, the value of arc cosine of
0.5, to ARCCOS:
ARCCOS = ACOS(0.5)
In the next example, the program statement prints out the arc cosine of -0.5, which is
120:
PRINT ACOS(-0.5)
37
ALPHA
ALPHA
Syntax
ALPHA(“str.expr”)
Description
The UniBasic ALPHA function tests a string to see if it is composed entirely of alpha-
betic characters. If str.expr is made entirely of alphabetic characters, spaces, punctua-
tion characters, escape sequences, etc., the function returns a one. If numeric
characters are present in str.expr, or if str.expr evaluates to a null, the function returns
a zero.
Examples
In the following example, the program statement prints a 0 since the literal string con-
tains the numeric character 2:
PRINT ALPHA("ABCDEFGHIJK2")
In the next example, the program segment prints a 1 since the string ALPHA contains
only alphabetic characters:
ALPHA.T=ALPHA("CORONA")
PRINT ALPHA.T
In the next example, the program statement prints a 0 since the string does not contain
any characters. A null value is not considered an alphabetic character.
PRINT ALPHA("")
38
ASCII
ASCII
Syntax
ASCII(expr)
Description
The UniBasic ASCII function (American Standard Code for Information Interchange)
converts a string in EBCDIC format (Extended Binary Coded Decimal Information
Code) to the corresponding ASCII values. While the ASCII function works with data
in any format, its results are only meaningful when it is applied to EBCDIC data.
For more information on ASCII character codes, refer to Appendix A ASCII Character
Codes.
Examples
In the following example, the program statement converts the EBCDIC data in the
variable E.VAR to ASCII format and assigns the value to the variable A.VAR:
A.VAR=ASCII(E.VAR)
Related Topics
EBCDIC
The UniBasic EBCDIC function converts a string in ASCII format to the correspond-
ing EBCDIC values.
39
ASIN
ASIN
Syntax
ASIN(expr)
Description
The UniBasic ASIN function returns the trigonometric arc sine (inverse sine) of a
numeric expression in degrees. expr must be a value between -1 and +1. ASIN returns
a value expressed as the degree of the arc sine of the input, which ranges from -90 to
+90. If expr evaluates to a value outside the range of -1 and +1, the system displays an
error message and returns 0 as the result.
Examples
In the following example, the program statement assigns 30, the value of arc sine of
0.5, to ARCSIN.
ARCSIN = ASIN(0.5)
In the next example, the program statement prints -30, the arc sine of -0.5.
PRINT ASIN(-0.5)
40
ASSIGN
ASSIGN
Syntax
ASSIGN expr TO SYSTEM(option)
Description
The UniBasic ASSIGN command redefines some of the system-level parameters. The
value in option changes to the value you specify with expr.
Parameters
The following table describes the valid ASSIGN parameters:
2 Page width
3 Page length
5 Page number
7 Terminal type
ASSIGN Parameters
For parameters 2, 3, and 5, expr should evaluate to a numeric value; for parameter 7,
expr should evaluate to a string representing a valid terminal type and be enclosed in
quotes.
Examples
In the following example, the program resets the page width to 40, page length to 30,
and terminal type to vt100.
ASSIGN 40 TO SYSTEM(2)
ASSIGN 30 TO SYSTEM(3)
ASSIGN "vt100" TO SYSTEM(7)
Related Topics
TERM
The ECL TERM command sets your terminal type and other terminal characteristics.
For information on TERM, refer to UniData Commands Reference.
41
ATAN
ATAN
Syntax
ATAN(expr)
Description
The UniBasic ATAN function returns the trigonometric arc tangent (inverse tangent)
of a numeric expression expr in degrees.
Examples
In the following example, the program segment prints the arc tangent of the variable
VAL which is 45.
VAL = 1
PRINT ATAN(VAL)
42
BITAND
BITAND
Syntax
BITAND(num.expr1,num.expr2)
Description
The UniBasic BITAND function performs the bit-wise AND logical function on the
arguments num.expr1 and num.expr2.
The following table illustrates the resulting value of the BITAND function.
num.expr1 num.expr2 Result
0 0 0
0 1 0
1 0 0
1 1 1
3 9 1
23 87 23
BITAND Function Operation Results
Examples
In the following example, the program statement prints a 0.
PRINT BITAND(0,1)
43
BITOR
BITOR
Syntax
BITOR(num.expr1,num.expr2)
Description
The UniBasic BITOR function performs the bit-wise OR logical function on the argu-
ments num.expr1 and num.expr2.
The following table illustrates the resulting value of the BITOR function.
0 0 0
0 1 1
1 0 1
1 1 1
3 9 11
23 87 87
BITOR Function Operation Results
Examples
PRINT BITOR(0,1)
44
BITNOT
BITNOT
Syntax
BITNOT(num.expr)
Description
The UniBasic BITNOT function performs the bit-wise NOT logical function on the
argument num.expr.
The following table illustrates the correct use and resulting value of the BITNOT
function.
num.expr Result
0 1
1 0
BITNOT Function Operation Results
Examples
PRINT BITNOT(0)
45
BITXOR
BITXOR
Syntax
BITXOR(num.expr1,num.expr2)
Description
The UniBasic BITXOR function performs the bit-wise XOR logical function on the
arguments num.expr1 and num.expr2.
The following table illustrates resulting value of the BITXOR function.
0 0 0
0 1 1
1 0 1
1 1 0
3 9 10
23 87 64
BITXOR Function Operation Results
Examples
PRINT BITXOR(0,1)
46
BPIOCP
BPIOCP
Syntax
BPIOCP
Description
The UniBasic BPIOCP command resets the terminal pagination. Whenever a UniBa-
sic program is printing to a terminal (without using cursor addressing), and the print
statements reach the bottom of the screen, this prompt appears:
Enter <New Line> to continue...
Parameters
There are three valid parameters for this prompt:
New Line Pressing Return on the keyboard displays another screen

of data.
N Continues the display process and disables the display of
the new line prompt.
Q Quits the current process and returns to the previous
process.
BPIOCP Parameters
The page control process is automatically disabled if the UniBasic program uses the
@ function cursor control in any way. For example, the following disables terminal
pagination:
PRINT @(1)
CRT @(2)
VARIABLE = @(3)
Under this circumstance, UniData assumes that the program will control the paging of
data. To turn automatic pagination on from within a UniBasic program, use the BPI-
OCP statement. This enables page handling and the use of the new line prompt.
47
BPIOCP
Examples
In the following example, the program prints the first 30 records of the CUSTOMER
file without any pagination prompt. The second loop will print 22 lines and then give
you the pagination prompt “Enter <New Line> to continue...”.
JUNK = @(0,0)
OPEN ’’,’CUSTOMER’ READONLY ELSE NULL
FOR CUST.ID = 1 TO 30
READ REC FROM CUST.ID THEN
PRINT CUST.ID
END ELSE
PRINT CUST.ID: "DOES NOT EXIST."
END
NEXT
BPIOCP
FOR CUST.ID = 1 TO 30
READ REC FROM CUST.ID THEN
PRINT CUST.ID
END ELSE
PRINT CUST.ID: "DOES NOT EXIST."
END
NEXT
48
BREAK
BREAK
Syntax
BREAK [KEY] {ON | OFF | expr }
Description
The UniBasic BREAK command enables or disables the break key to exit a program
to the ‘!’ debugger prompt and display the current program line number.
The system increments a counter each time BREAK OFF executes and decrements
that same counter when BREAK ON executes. Until the system counter is less than or
equal to zero (more BREAK ON statements executed than BREAK OFF statements),
the break key will be non-operational. This status continues even if you exit a program
with the BREAK key disabled.
Parameters
The following table describes the valid BREAK parameters:
[KEY] KEY is optional and has no effect; it is included for com-

patibility purposes only.
ON Enables the terminal break key to stop the execution of a
UniBasic program and enters the UniBasic debugger.
OFF Disables the break key. Pressing the break key has no
effect on program execution.
expr Enables the terminal break key to stop the execution of a
UniBasic program and enter the UniBasic debugger if the
expression is valid.
BREAK Parameters
Examples
In the following example, the program statement decrements the system counter and
enables the break key if the counter is less than or equal to zero.
BREAK ON
49
BREAK
In the next example, a numeric expression decides whether to enable the break key. If
X is greater than 0, then the system enables the break key.
BREAK X > 0
Related Topics
PTERM
For information on the ECL PTERM command, refer to UniData Commands
Reference.
50
CALCULATE
CALCULATE
The UniBasic { } “braces” or CALCULATE function executes and captures the
results of a virtual attribute. Refer to the {} entry for further information.
51
CALL
CALL
Syntax
CALL *sub.name [[(argument1[,argument2][MAT matrix1 [,MAT matrix2]]...)]
[ASYNC | SYNC] [ON connection]
CALL @var [[(argument1[,argument2][MAT matrix1 [,MAT matrix2]]...)]
CALL sub.name [[(argument1[,argument2][MAT matrix1 [,MAT matrix2]]...)]
Description
The UniBasic CALL command transfers program control to an external subroutine,
either from the main program or from another subroutine.
• The first CALL statement calls a globally cataloged subroutine.
• The second CALL statement calls a subroutine named in a variable.
• The third CALL statement calls a subroutine directly.
Control returns to the calling program or subroutine by a RETURN statement within
the called subroutine.
Note You must catalog subroutines before using them in a UniBasic CALL state-
ment.
You must separate individual arguments by commas and surround the set of argu-
ments with parentheses. You may place arguments on multiple lines as long as each
line ends with a comma. Regardless of their placement, the number and type of argu-
ments in the CALL statement must match the number and type of arguments in the
SUBROUTINE statement at the top of the external subroutine. Matrices and singl-
evalued arguments can pass in the same CALL statement.
You may pass variables that appear in a COMMON statement to subroutines. If both
the program and subroutine have a COMMON statement, the variables are accessible
in both without being passed as arguments. A variable or matrix name in a subroutine
cannot appear in both the SUBROUTINE arguments and in the subroutine’s COM-
MON variables list. You may not call matrices that appear in a COMMON statement.
CALL is very efficient for passing large amounts of data to a subroutine.

Tip
52
CALL
Parameters
sub.name The name of a subroutine to call.

@var A UniBasic @variable which contains the
name of the subroutine to call.
argument1, argument2 Any valid argument to pass to the subroutine.
MAT matrix1, Any valid matrix to pass to the subroutine.
MAT matrix2
[ASYNC | SYNC] ASYNC performs an asynchronous execution
and returns control to the program immedi-
ately, without waiting to get the results of the
CALL statement. To get the results, use the
WAIT command. SYNC performs a synchro-
nous execution and waits for the results of the
command and returns them before continuing
with the program. You can use these parame-
ters when developing UniDesktop/Open
Client applications. For information on devel-
oping these applications, refer to Developing
UniDesktop/Open Client Applications.
[ON connection] Specifies the handle to a server you specified
with the CONNECT command. You can use
this parameter when developing UniDesktop/
Open Client applications. For information on
developing these applications, refer to
DevelopingUniDesktop/Open Client
Applications.
CALL Parameters
Examples
In the following example, the program statement calls the subroutine VID, passing the
variables TITLE and ST.
CALL VID(TITLE,ST)
53
CALL
In the next example, the program segment calls the subroutine MONTHTOTAL by
calling the @variable @VID that holds the string “MONTHTOTAL.” Note that the
subroutine arguments follow the @variable and are not stored in the variable itself.
VID = "MONTHTOTAL"
CALL @VID(TOTAL)
In the next example, the program segment calls the contents of cell (1.12) in the
matrix cells, thus calling the subroutine RECEIPTS with the argument “MON1_12”.
In the use of @matrices, you may select the matrix element by the use of an index (a
variable within the dimensions of the matrix).
"SUBROUTINE MONTHTOTAL(TOTAL)"
SALES(1,12) = "RECEIPTS"
CALL @SALES(1,12)(MON1_12)
In the next example, the program statement calls the globally cataloged subroutine
PROMPT.ROUTINE.
CALL *PROMPT.ROUTINE
In the following example, the CALL statement is invalid since subroutine SUBS has a
different number of arguments than the CALL statement. Called routines must pass
the same number of parameters.
CALL SUBS(X,Y,Z)
Called subroutine:
SUBROUTINE SUBS(X)
Related Topics
COMMON
The UniBasic COMMON command makes the named variables available to all pro-
grams and subroutines that use the same COMMON statement.
DIMENSION
The UniBasic DIMENSION command declares the name and dimensions of matrices.
RETURN
The UniBasic RETURN command transfers program control from a subroutine back
to the calling program or subroutine.
SUBROUTINE
The UniBasic SUBROUTINE command determines the beginning of an external
subroutine.
54
CALL
CATALOG
The ECL CATALOG command copies the compiled object code of a UniBasic pro-
gram into the system catalog. For information on CATALOG, refer to UniData
Commands Reference.
55
CALLC
CALLC
Syntax
CALLC c.sub.name [(argument1[,argument2]...)]
CALLC @var [(argument1[,argument2]...)]
Description
The UniBasic CALLC command transfers program control to an external C subrou-
tine, either from the main program or from another subroutine. The second form calls
an external C subroutine stored in an @variable. The arguments are optional. The
CALLC statement is similar to the normal CALL subroutine statement, except that
matrices may not be passed as arguments. The CALLC subroutine can pass back a
value called the return value to a variable. CALLC arguments can be simple variables
or complex expressions.
CALLC may also be used as a function; it is placed on the right side of an assignment
operator and its value is then assigned to the variable on the left side of the statement.
Calling a C Subroutine in UNIX

You must interface a C subroutine in UNIX with UniData before calling it from a Uni-
Basic program. For information on interfacing with a C program, refer to Developing
UniBasic Applications.
Examples
In the following example, the C subroutine called draws a circle with its center at the
12th row and 12th column and a radius of 3.
RADIUS = 3
CENTER = "12,12"
CALLC DRAW.CIRCLE(RADIUS,CENTER)
In the next example, the subroutine name is stored in the variable @SUB.NAME.
SUB.NAME = DRAW.CIRCLE
CALLC @SUB.NAME(RADIUS,CENTER)
In the next example, CALLC is used as a function, allowing the return value of the C
subroutine PROGRAM.STATUS to be assigned to the variable RESULT.
RESULT = CALLC PROGRAM.STATUS
56
CASE
CASE
Syntax
BEGIN CASE
CASE expression1
statements1
CASE expression2
statements2
.
.
.
{CASE 1
statements}
END CASE
Description
The UniBasic CASE command creates a series of branches based on conditional
expressions. Case structures must always begin with BEGIN CASE and terminate
with END CASE.
The number of CASE commands within the BEGIN CASE and END CASE state-
ments is unlimited. The number of statements within each CASE branch is unlimited.
CASE statements may be nested.
The CASE command tests each of the expressions in sequence. If an expression eval-
uates as true, the system executes the statements that follow it. Once one of the CASE
expressions is found to be true, the system does not test any subsequent expressions. If
none of the conditions are true, the system does not execute any statements.
Parameters
CASE expression1 Specifies any UniBasic expression. If the

expression is true, execute statements1.
statements1 Specifies the UniBasic statements to execute if
expression1 is true.
CASE Parameters
57
CASE
CASE expression2 Specifies any UniBasic expression. If the

expression is true, execute statements2.
statements2 Specifies the UniBasic statements to execute if
expression2 is true.
{CASE 1 This expression always evaluates as true. By
statements} placing it at the end of the CASE statement,
you can specify a set of statements to execute if
all previous statements evaluate as false.
CASE Parameters (continued)
Examples
In the following example, if the variable DUE.DATE is greater than the system date,
the program calls the subroutine PRINT.OVERDUE. (Notice that both dates are in
‘internal’ format.) If DUE.DATE is less than or equal to the system date, the program
prints the message “Okay” on your display terminal.
BEGIN CASE
CASE DUE.DATE > DATE()
GOSUB PRINT.OVERDUE:
CASE DUE.DATE <= DATE()
PRINT "Okay"
END CASE
The multiline indented statement layout shown in these examples is not required.
Tip However, this format is clearer and easier to read.
In the next example, the program segment transfers program control to either
“CHARGE:” or “CHECK:” based on the value of the variable VAL. If VAL is neither
one nor two, the program executes the statements after the CASE 1 clause.
PRINT "Option number?" ; INPUT VAL
BEGIN CASE
CASE VAL = 1
GOSUB CHARGE:
CASE VAL = 2
GOSUB CHECK:
CASE 1
PRINT "Answer 1 or 2 only"
END CASE
In the following example, the statement is invalid, since the evaluation expression
should not appear on the BEGIN CASE line.
BEGIN CASE VAR 1
58
CASE
In the next example, the statement is invalid, since BEGIN CASE must appear first.
CASE VAL
59
CAT
CAT
Syntax
expr1 CAT expr2
Description
The UniBasic CAT function concatenates expr1 to expr2.
Examples
In the following example, the program segment concatenates A to B and prints
123456.
A = "123"
B = "456"
C = A CAT B
PRINT C
Related Topics
String Manipulation
For information on string manipulation, refer to Developing UniBasic Applications.
60
CATS
CATS
Syntax
CATS(array1,array2)
Description
The UniBasic CATS function concatenates array1 to array2. Each element of array2
is concatenated to its corresponding element in array1.
Examples
In the following example, the program segment concatenates array A to array B and
prints 300A}400B}401C}402D}100E.
A = 300:@VM:400:@VM:401:@VM:402:@VM:100
B = "A":@VM:"B":@VM:"C":@VM:"D":@VM:"E"
C = CATS(A,B)
PRINT C
Related Topics
String Manipulation
61
CHAIN
CHAIN
Syntax
CHAIN “str.expr”
Description
The UniBasic CHAIN command terminates the current UniBasic program and exe-
cutes the ECL command str.expr. CHAIN performs a function similar to the EXE-
CUTE statement, except that control is not returned to the original program. The
system treats str.expr as a command you type at the ECL colon ( : ) prompt, and there-
fore the system references the VOC file for the meaning of str.expr.
Use this command to avoid system-imposed limitations on program size by

Tip moving from program to program.
BASICTYPE The CHAIN statement performs differently with BASICTYPE P and M. If

one program executes another program, (i.e., with the EXECUTE statement),
and a second program chains to a third program, the system does not pass the
unnamed common.
Examples
In the following example, the current program terminates and the system executes the
ECL command “RUN BP FORMLET”, where FORMLET is a compiled UniBasic
program. Control will not return to the original program when FORMLET terminates.
CHAIN "RUN BP FORMLET"
In the next example, the current program terminates and the paragraph
RUN.ACCOUNTS executes.
CHAIN "RUN.ACCOUNTS"
62
CHANGE
CHANGE
Syntax
CHANGE(string, old.substring, new.substring)
Description
The UniBasic CHANGE function replaces all occurrences of old.substring in string
with new.substring. If old.substring is null, the system does not change string.
Parameters
string Specifies the original text string.

old.substring Specifies the text string to replace with
new.substring.
new.substring Specifies the text string with which to replace
old.substring.
CHANGE Parameters
Examples
In the following example, the program segment will print “UniBasic Release 3.1.0”
STRA = "UniBasic Release 2.3.2"
OLDRELEASE = "2.3.2"
NEWRELEASE = "3.1.0"
STRB = CHANGE(STRA,OLDRELEASE,NEWRELEASE)
PRINT STRB
In the next example, the program segment will print

“NEW STRC = A23A24A25A26.”
STRC = "123124125126"
PRINT "NEW STRC =":CHANGE(STRC,"1","A")
63
CHAR
CHAR
Syntax
CHAR(expr)
Description
The UniBasic CHAR function changes a numeric expression to its ASCII (American
Standard Code for Information Interchange) character string equivalent. ASCII is a
system for representing all characters in terms of numbers: A = 65, B = 66, etc. expr
may be a constant, variable, numeric function, or any combination of these, and must
evaluate to a positive number from zero to 255, (the range of ASCII character codes).
Note Not all ASCII codes are printable. Some represent terminal controls, and oth-
ers are reserved for special uses. For more information on ASCII character
codes, refer to Appendix A ASCII Character Codes.
Examples
In the following example, the program segment assigns the ASCII string equivalent of
the numeric expression VAL to the variable VSTRING. The final numeric value of
the argument is 90, so VSTRING becomes Z, the character equivalent of 90 in the
ASCII code system.
VAL=90
VSTRING=CHAR(VAL)
In the next example, the program statement sends the ASCII code 12 to the current
print device. In ASCII, this is a form feed.
PRINT CHAR(12)
64
CHARS
CHARS
Syntax
CHARS(array)
Description
The UniBasic CHARS function changes a numeric value in array to its ASCII
(American Standard Code for Information Interchange) character string equivalent.
ASCII is a system for representing all characters in terms of numbers: A = 65, B = 66,
etc. array elements may contain a constant, variable, numeric function, or any combi-
nation of these, and must evaluate to a positive number from zero to 255, (the range of
ASCII character codes).
Note Not all ASCII codes are printable. Some represent terminal controls, and oth-
ers are reserved for special uses. For more information on ASCII character
codes, refer to Appendix A ASCII Character Codes.
Examples
In the following example, the program segment assigns the ASCII string equivalent of
the elements of array VAL to the variable VARRAY. VARRAY now contains
W}X}Y}Z, the character equivalent of 87,88,89, and 90 in the ASCII code system.
VAL = 87:@VM:88:@VM:89:@VM:90
VARRAY = CHARS(VAL)
65
CHECKSUM
CHECKSUM
Syntax
CHECKSUM(str.expr)
Description
The UniBasic CHECKSUM function computes the positional checksum of the string
str.expr you specify. The positional checksum is the sum of the ASCII value of each
character in the string, multiplied by the position of the character in the string.
Tip You can use the CHECKSUM function to check that data was copied cor-
rectly, or information processed properly, by comparing the CHECKSUM of
the original data with the CHECKSUM of the copy.
Examples
In the following example, the program statement prints out 2445, the checksum of
string “123456789.”
PRINT CHECKSUM("123456789")
66
CLEAR
CLEAR
Syntax
CLEAR
Description
The UniBasic CLEAR command sets the values of the variables stored in all local
memory to zero. This includes all matrix elements. Any variables assigned by named
or unnamed COMMON statements are not affected.
Tip CLEAR may at any point within a program, initialize or reinitialize variables.
CLEAR performs differently with BASICTYPE P. All variables in unnamed

BASICTYPE
COMMON are also set to 0.
Examples
In the following example, the program statement clears all variables not held in com-
mon if the variable INITIALIZE is true and BASICTYPE is U. The variable INI-
TIALIZE will also be set to zero (false) if the variable is not held in COMMON.
IF INITIALIZE THEN CLEAR
In the next example, the program segment sets X, Y, and all elements in NAME, to
zero in BASICTYPE P.
COMMON NAME(100)
X = 4
Y = X - 1
CLEAR
Related Topics
COMMON
grams and subroutines that use the same COMMON statement.
CLEARCOMMON
The UniBasic CLEARCOMMON command sets the variables in the named common
you specify to zero.
67
CLEARCOMMON
CLEARCOMMON
Syntax
CLEARCOMMON /common.label/
CLEAR COMMON /common.label/
CLEARCOM /common.label/
CLEAR COM /common.label/
Description
The UniBasic CLEARCOMMON command sets all variables you specify in a
named COMMON statement to zero. If you do not specify common.label,
CLEARCOMMON sets all variables specified in the unnamed COMMON statements
of a program to zero.
Examples
In the following example, the program statement sets to zero all variables named in
COM_1.
CLEARCOMMON /COM_1/
In the next example, the program statement sets to zero all variables held in COM-
MON statements if the variable INITIALIZE.COMMON is true.
IF INITIALIZE.COMMON THEN CLEAR COMMON
Related Topics
CLEAR
The UniBasic CLEAR command clears the values stored in all local memory vari-
ables.
COMMON
grams and subroutines that use the same COMMON statement. Named COMMON
allows for different common statements between subroutines and programs.
68
CLEARDATA
CLEARDATA
Syntax
CLEARDATA
Description
The UniBasic CLEARDATA command clears remaining data from any previously
executed DATA statements. Any subsequent INPUT statements will request data
from the keyboard rather than accepting data remaining in the input queue.
Examples
In the following example, a DATA statement sets up a list of values to be read. An
INPUT statement then reads the first number into the variable VAL. If the value of
VAL is 100, a CLEARDATA statement executes and clears the remaining list of data
items. The last INPUT statement then requests information from the keyboard rather
than getting it from the DATA statement. If the first value was not 100, the value of
VAL2 is 120 because it is assigned by the second item in the DATA list.
DATA 100,120,105,54,120
INPUT VAL
IF VAL = 100 THEN CLEARDATA
PRINT "VALUE": ; INPUT VAL2
Related Topics
DATA
The UniBasic DATA command creates a data queue to be read by subsequent INPUT
statements.
INPUT
The UniBasic INPUT command requests data from the keyboard or a data statement
during program execution.
69
CLEARFILE
CLEARFILE
Syntax
CLEARFILE [file.var] [ON ERROR statements]
Description
The UniBasic CLEARFILE command clears all records from a file but does not
delete the file itself. You may only clear one file at a time with a CLEARFILE
statement.
Tip The CLEARFILE statement clears any of the files that you can open, even if
they reside in a remote account.
Parameters
[file.var] Specifies a dictionary or data file to clear.

The file must have been opened previously
with an OPEN statement.
Defaults to the most recently opened file.
[ON ERROR statements] Specifies statements to execute if a fatal error
occurs because the file is not open or is read-
only.
If you do not specify the ON ERROR clause,
the program terminates under such fatal error
conditions.
CLEARFILE Parameters
Examples
In the following example, the program statement removes all records from the file
referred to by the file variable PASTDUE. The dictionary remains unchanged after the
execution of this statement.
CLEARFILE PASTDUE
70
CLEARFILE
Related Topics
OPEN
The UniBasic OPEN command opens the dictionary or data file that you specify. You
can then read, write to, or delete the file.
OPENSEQ
The UniBasic OPENSEQ command opens an ASCII sequential file.
OSOPEN
The UniBasic OSOPEN command opens a UNIX sequential file.
CLEAR.FILE
The ECL CLEAR.FILE command clears the data and/or dictionary files. For informa-
tion on CLEAR.FILE, refer to UniData Commands Reference.
71
CLEARINPUT
CLEARINPUT
Syntax
CLEARINPUT
INPUTCLEAR
Description
The UniBasic CLEARINPUT command deletes all terminal type ahead characters so
the next INPUT statement forces a response from the user.
Examples
In the following example, the CLEARINPUT statement deletes all terminal type
ahead characters so the user must input whether or not to delete a file.
CLEARINPUT
PRINT "DO YOU WANT TO DELETE THIS FILE?(Y OR N)"; INPUT X,1
Related Topics
CLEARDATA
The UniBasic CLEARDATA command clears the remaining data from any previ-
ously executed DATA statements.

For more information on terminal and printer input/output, refer to Developing
UniBasic Applications.
72
CLEARSELECT
CLEARSELECT
Syntax
CLEARSELECT [num.expr] [ALL]
Description
The UniBasic CLEARSELECT command clears active select lists. You can specify
a particular ID list, where num.expr can be 0 through 9. ALL clears all active select
lists. If you do not specify a parameter, the system clears the default ID list (zero). If
you specify an ID list outside the valid range, a run-time error occurs.
You generally create active lists by the execution of the ECL SELECT, SSELECT or
GET.LIST commands, or the UniBasic SELECT or GETLIST commands. These
commands report or process a specific subset of IDs within a file. Since multiple
select lists can be active at one time, the CLEARSELECT statement may clear one or
all of the currently active lists.
Examples
In the following example, the program segment clears active select list 1, which is the
value stored in the variable ID.LIST.
ID.LIST=1
CLEARSELECT ID.LIST
In the next example, the program statement clears the default list zero.
CLEARSELECT
Related Topics
SELECT
The UniBasic SELECT command compiles a list of all record IDs in a file.
GETLIST
The UniBasic GETLIST command generates an active list from a saved list created by
the ECL SELECT and SSELECT commands or the UniBasic SELECT command, and
saved by the SAVE.LIST command or by the UniBasic WRITELIST statement.
73
CLEARSELECT
SELECT
The UniQuery SELECT command creates an active list of record IDs that you may
use with other UniQuery commands or a user-defined process. For information on
SELECT, refer to Using UniQuery.
SSELECT
The UniQuery SSELECT command creates an active list of record IDs (or keys) in ID
order. For information on SSELECT, refer to Using UniQuery.
GET.LIST
The UniQuery GET.LIST command retrieves the records stored by a previous
SAVE.LIST statement or a user process to use in another query statement or UniBasic
program. For information on GET.LIST, refer to Using UniQuery.
Select Lists
For information on select lists, refer to Using UniQuery.
74
CLEARSQL
CLEARSQL
Syntax
CLEARSQL [file.name.expr]
Description
The UniBasic CLEARSQL command clears all active temporary tables that were cre-
ated during the current session (i.e., created with the EXECUTESQL command with a
corresponding INTO clause). If you do not specify file.name.expr, CLEARSQL clears
all the SQL file variables created during this UniBasic session.
Note When a program returns to the UniData prompt, whether or not you execute a
CLEARSQL statement, the system clears all SQL file variables.
Related Topics
EXECUTESQL
The UniBasic EXECUTESQL command passes an SQL statement directly to the
UniData SQL processor.
75
CLOSE
CLOSE
Syntax
CLOSE [file.var] [ON ERROR statements]
Description
The UniBasic CLOSE command closes a dictionary or data file opened as file.var.
Note UniData allows you to OPEN virtually an unlimited number of files in a sin-
gle process. Limitations occur if the total number of files opened across
numerous processes and users exceeds the number of files available to the
UNIX or VMS operating system.
Parameters
[file.var] Specifies a dictionary or data file to close.

with an OPEN statement.
occurs because the file is not open.
conditions.
CLOSE Parameters
Examples
In the following example, the program segment opens and closes the file INVEN-
TORY.
OPEN ’’,’INVENTORY.FILE’ TO INVENTORY ELSE ABORT
CLOSE INVENTORY
76
CLOSE
Related Topics
OPEN
The UniBasic OPEN command opens the dictionary or data file you specify. You may
then read from, write to, or delete the file.
77
CLOSESEQ
CLOSESEQ
Syntax
CLOSESEQ seq.file.var [ON ERROR statements]
Description
The UniBasic CLOSESEQ command closes an open sequential access type file. The
CLOSESEQ command releases the exclusive file lock set by the OPENSEQ com-
mand, allowing other users to access it. If any new lines (sequential records) were
added to the file prior to closing, the system writes a new end-of-file mark to the file
after the new lines.
Parameters
seq.file.var Specifies a sequential access file to close.

with an OPENSEQ statement.
occurs because the file is not open.
conditions.
CLOSESEQ Parameters
Examples
In the following example, the statement closes the sequential file referred to by the file
variable DATA.59.
CLOSESEQ DATA.59
78
CLOSESEQ
Related Topics
OPENSEQ
The UniBasic OPENSEQ command opens an ASCII sequential file.
READSEQ
The UniBasic READSEQ command assigns the next record from a previously opened
sequential file to a variable.
WRITESEQ
The UniBasic WRITESEQ command writes an expression at the end of a sequential
file.
WRITESEQF
The UniBasic WRITESEQF command writes an expression at the end of a sequential
file and forces the system to write the data to disk.
Sequential File Input/Output

For information on sequential file input/output, refer to Developing UniBasic
Applications.
79
COL1
COL1
Syntax
COL1( )
Description
The UniBasic COL1 function returns the column position before a substring found by
the execution of the FIELD function. The COL1 function has no arguments. If you do
not execute the FIELD function prior to the COL1 function, the function returns a
zero.
The FIELD function examines a string for a particular delimiter and returns the sub-
string marked by the specified occurrence of that delimiter. While the FIELD function
returns the substring itself, the COL1 function returns the position immediately before
the substring within the string sent to the FIELD function.
Examples
In the following example, the program segment uses the FIELD function to search the
string STRING for the third occurrence of the delimiter “,”. FIELD marks the sub-
string “10”, and assigns it to the variable SSTR. The COL1 function assigns column 6,
the column position of the character before “10”, to the variable SPOS.
STRING = "11,20,10,15,20,15"
SSTR = FIELD(STRING,",",3)
SPOS = COL1()
Related Topics
COL2
The UniBasic COL2 function returns the column position after a substring found by
using the FIELD function.
FIELD
The UniBasic FIELD function returns a substring or group of substrings in a larger
string that is delimited by any ASCII character.
80
COL2
COL2
Syntax
COL2( )
Description
using the FIELD function. The COL2 function has no arguments. If you do not exe-
cute the FIELD prior to the COL2 function, the function returns a zero.
The FIELD function examines a string for a particular delimiter and returns the sub-
string marked by the specified occurrence of that delimiter. While the FIELD function
returns the substring itself, the COL2 function returns the position immediately after
the substring within the string sent to the FIELD function.
Examples
In the following example, the program segment uses the FIELD function to search the
string STRING for the third occurrence of the delimiter “,”. FIELD marks the sub-
string “10”, and assigns it to the variable SSTR. The COL1 function assigns column 9,
the column position of the character after “10”, to the variable SPOS2.
STRING = "11,20,10,15,20,15"
SSTR = FIELD(STRING,",",3)
SPOS2 = COL2()
Related Topics
COL1
the execution of the FIELD function.
FIELD
81
Comment
Comment
Syntax
* [comment text]
! [comment text]
REM [comment text]
Description
The UniBasic comment commands place remarks in a program by starting the com-
ment line with any of the above symbols. A comment may appear anywhere within a
program, either on a line by itself or following program statements on the same line.
You may also place comments at the end of each line of a multiline statement. If a
comment appears on the same line as another statement, the comment must follow a
semi-colon.
Note Program code may not follow comments on the same line.
Examples
In the following example, the comment commands are used to identify what a pro-
gram is doing.
! Subroutine to test user input validity.
SUBROUTINE TEST
COMMON N,DATA.IN,VAL,SCORE(10)
BEGIN CASE
CASE DATA.IN=VAL; ** answer correct, then
SCORE(N)=1 REM add one to SCORE(N)
PRINT "Got it right!";! print message.
CASE IN <> VAL

SCORE(N)=0
PRINT "Incorrect, try again."
END CASE
RETURN
REM end of error check subroutine.
82
COMMON
COMMON
Syntax
COMMON [/common.name/] var1 [,var2][MAT1]...
COM [/common.name/] var1 [,var2][MAT1]...
Description
The UniBasic COMMON command declares variables that can be accessed from
multiple subroutines and programs.
Normally, variables and the values stored in them are only available locally (across
the execution of the routine in which they are declared). When you declare variables
with a COMMON statement, UniData stores the data in such a way that it can be com-
monly available to other routines.
To use COMMON variables, declare the variables with the COMMON command.
UniData initializes the variables with a value of 0. Set up the values as appropriate.
COMMON variables may be normal variables and matrices. Do not declare matrices
with a DIMENSION statement. Matrices in a COMMON statement cannot be dynam-
ically redimensioned.
In later programs or subroutines, where you want to access COMMON variables,
declare the variables with a COMMON statement at the beginning of the routine. (The
values will be in COMMON, but until they are declared, the routine won’t be able to
access them.) Once the variables are declared, they are available to the program or
routine as if they were local variables.
You can declare the variables with different names in later routines. The variables will
be in COMMON in the order in which they were declared in the first COMMON
statement. The order of the names in the later declaration will determine which names
go with which values.
If you declare variables with a COMMON statement that does not include a com-
mon.name, you place the data in “unnamed COMMON.” There is a single unnamed
COMMON that persists across a single chain of execution—from when the variables
are declared until the last program ends and you return to the ECL prompt. When you
return to the ECL prompt, unnamed COMMON is cleared.
If you declare variables with a COMMON statement that includes a common.name,
you place the data in a “named COMMON”. You can have multiple named
COMMONs that persist across a single UniData session. You can run a program,
return to the ECL prompt, run another program, and so forth, and the named
COMMON variables will remain. When you exit that UniData session, the named
COMMON variables are cleared.
83
COMMON
You may enter a COMMON statement on several lines by using a comma at the end
of each line.
The number of variables that a COMMON statement may contain depends on the vir-
tual memory of your system. For information on virtual memory, refer to
Administering UniData on UNIX.
COMMON BASICTYPE
BASICTYPE
With BASICTYPE U and R, UniData uses a single area for unnamed
COMMON and separate areas for each named COMMON. The variables you
declare for the same common area must be the same type and in the same
order in all programs accessing that common area. Once you establish the
variable type for a common element, you cannot change it. Other programs
may declare more or fewer variables, and may even change the name of the
variable. You cannot change a non-dimensioned variable to a dimensioned
variable; you cannot change a two-dimensioned variable to a single-dimen-
sioned variable; declaring a dimensioned size for a variable determines that
variable’s size in all subsequent programs. The system does not allow any
change, including changing the size of the array. CLEARCOMMON sets the
common variable to 0 only (its initial state).
With BASICTYPE M and P, UniData is more flexible because COMMON

BASICTYPE
does not maintain the concepts of zero or one- and two-dimensioned arrays.
BASICTYPE P and BASICTYPE M consider all elements as zero-dimen-
sioned arrays; that is, a conflict does not exist in COMMON between two pro-
grams that declare COMMON as A,B(5) in the first program and U,V,W, X,
Y, Z in the second. You may reference elements set in the first program as the
corresponding elements in the second program. If A = 4 and B(3) = 5, then
U = 4 and X = 5 in the second program. A program may declare as many or as
few of the common elements (and in any dimensional grouping), as needed.
BASICTYPE P does not include a zero element in an array, so the mapping
from a dimensioned to a non-dimensioned array is straightforward.
COMMON and ECL Commands

PASSCOM Option
Prior to release 3.1, when you executed UniData Environment Control Language
(ECL) commands from a program, you did not have access to named common unless
you used the PASSCOM option. In release 3.1 or later, if you execute a command like
LIST or SELECT, and the command references a virtual attribute that calls a subrou-
tine that uses named COMMON, you no longer need to use the PASSCOM option
with the ECL command. You may still use the PASSCOM option for compatibility
purposes.
84
COMMON
If a program aborts, the named COMMON does not clear.

Note
STACKCOMMON Command
The ECL STACKCOMMON command extends COMMON flexibility (although
using STACKCOMMON requires additional memory). If STACKCOMMON is OFF
when one program executes another program, the unnamed common is passed to the
executed program and any changes are passed back to the executing program. If
STACKCOMMON is ON when one program executes another program, unnamed
common is not passed to the program you execute. Instead the program’s unnamed
common is pushed onto a stack and the executed program’s unlabeled common is ini-
tialized to zero. When the program is called back, the system moves the executing lev-
els and returns to the original value of the program. Unnamed common is never passed
to a phantom program.
Note STACKCOMMON is always ON in BASICTYPE P and M.

STACKCOMMON defaults to OFF in BASICTYPE R and in the standard
BASICTYPE U.
Parameters
[/common.name/] Specifies a name for a “named COMMON.” If

common.name is omitted, the COMMON is
unnamed, by default.
common.name may have any valid variable
name no longer than 7 characters.
var1 A variable to place in the named or unnamed
COMMON.
[,var2] A second variable to place in the named or
unnamed COMMON.
[MAT1] A matrix to place in the named or unnamed
common.
COMMON Parameters
Examples
In the following example, the program statement uses an unnamed COMMON state-
ment to declare the matrices, NAME and DATES, as well as the variable DCHANGE.
85
COMMON
COMMON NAME(100),DATES(100,2),DCHANGE
In the next example, the program segment creates two named COMMON areas. The
second COMMON statement continues on a second line with the comma ( , ) continu-
ation character.
COMMON /MENU/ X,Y,XDIM,YDIM,S.CHAR
COMMON /CALC/ RATE(10),AMOUNT(10),DATE1,
DATE2,LATE
In the following example, the program segment in invalid since the COMMON state-
ment must appear first. You cannot redefine a variable in the COMMON statement
after it has been assigned. UniData requires one-to-one correspondence between main
line and subprograms.
VALUE = 253
COMMON VALUE,SUBVALUE,ATTRIBUTE
Related Topics
EXECUTE
The UniBasic EXECUTE command executes an ECL command from within a UniBa-
sic program.
CLEARCOMMON
The UniBasic CLEARCOMMON command sets the variables in the named common
you specify to zero. If you do not specify a named common, the variables listed in the
unnamed common are set to zero
STACKCOMMON
The ECL STACKCOMMON command allows you to control the stack common
areas. For information on STACKCOMMON, refer to UniData Commands
Reference.
CLEAR
The UniBasic CLEAR command clears the values stored in all local memory vari-
ables.
86
CONNECT
CONNECT
Syntax
CONNECT server WITH usr_name, password, application TO connection
[ON ERROR statement]
Description
The UniBasic CONNECT command connects you to server so that you can access
UniData files on another platform on your network.
This command is used to develop UniDesktop/Open Client applications. For informa-
tion on how to develop UniDesktop/Open Client applications, refer to Developing
STATUS
After the execution of the CONNECT statement, STATUS is set to one of the follow-
ing values:
Status Value Description
0 Success
1 The log file cannot be opened
2 User name could not be found or password is incorrect
3 You have exceeded the maximum number of
UniServer users
4 Unused
5 Unused
6 Other error
7 UniDesktop is not licensed
8 All connections for the user are already allocated
9 Server is not in interfaces file
10 Server is not running
CONNECT Status Values
87
CONNECT
Parameters
server The name of the server in which to use on the server

machine. You specify this name when setting up a
server in us_admin. For more information on setting up
a server, refer to Administering UniServer.
usr_name The user name that will be used to log onto the server
platform. It must be a character string that represents a
valid login name of the user on the host where the server
resides.
password The password for the user that will be logging onto the
server platform.
application The application name used to help in identifying a client
process.
connection The handle to the connection. If this call is successful,
this will be a unique identifier of the connection. This
identifier will be used in all subsequent calls to this
server until you close the connection.
[ ON ERROR The ON ERROR clause allows the program to continue
statements] to perform if the CONNECT statement fails, it then exe-
cutes the statements you specify.
CONNECT Parameters
Example
In the following example, the CONNECT statement connects to the demo server. The
statement will log onto the remote platform using the user name “ubj01”, uses the
password “secret”, specifies to use “unidata” as the application, and names this con-
nection “remote.demo”. If the statement fails to make a connection, the program will
abort and an error message will print out the status.
CONNECT "demo" WITH "ubj01", "secret", "unidata" TO
remote.demo ON ERROR ABORT "CONNECT failed: ":STATUS()
88
CONTINUE
CONTINUE
Syntax
CONTINUE
Description
The UniBasic CONTINUE command transfers control to the next iteration of a FOR/
NEXT or LOOP/REPEAT statement.
Use CONTINUE to improve the structure of your programs.

Tip
Generally, the statements within a FOR/NEXT or LOOP/REPEAT structure execute
one by one. If you want to break the sequence to begin the next iteration, without a
CONTINUE statement, you could use the GOTO statement. However, this is gener-
ally regarded as poor programming practice. By using CONTINUE, you can clearly
express the program logic without degrading program structure.
Examples
In the following example, the program segment prints the value of I until I reaches
eight. When I is equal to eight, the CONTINUE statement drops you out of the FOR/
NEXT loop, and the next statement in the program executes.
FOR I = 1 TO 10
IF I < 8 THEN CONTINUE
PRINT "I = ":I
NEXT I
Related Topics
EXIT
The UniBasic EXIT command terminates the operation of a FOR/NEXT or LOOP/
REPEAT structure and transfers control to the first statement following the structure.
89
CONVERT
CONVERT
Syntax
CONVERT expr1 TO expr2 IN var
Description
The UniBasic CONVERT command changes all occurrences of the substring expr1
in var to the string expr2. The system compares each character of the replacement
string expr2 and, if necessary, replaces each character of the target string expr1 on an
individual basis; the system does not compare and insert strings as a whole.
Note CONVERT may delete characters from a string expression, but it cannot
insert more characters than it replaces. The length of the replacement sub-
string expr2 must be less than or equal to length of thethe substring it replaces,
expr1.
Parameters
expr1 Specifies the target string to replace with expr2.

expr2 Specifies the string with which to replace expr1.
var Specifies the string to search for expr1.
CONVERT Parameters
Examples
In the following example, the program segment converts all occurrences of 1 to 3 and
all occurrences of 2 to 4. The new contents of NSTRING is now 34,0,03,35,44.
NSTRING = "12,0,01,15,22"
CONVERT "12" TO "34" IN NSTRING
In the next example, the program segment converts all occurrences of AC to X. The
new contents of NSTRING is now XBDEFG. The C is changed to null (deleted).
NSTRING = "ABCDEFG"
CONVERT "AC" TO "X" IN NSTRING
90
CONVERT
In the following example, the statement is invalid. The program segment has a null
effect; the replacement string of “A,B” is longer than the string it is intended to
replace.
NSTRING = "A,C,D,E"
CONVERT "A" TO "A,B" IN NSTRING
Related Topics
String Manipulation
CONVERT
The CONVERT function performs the same as the CONVERT command.
91
CONVERT
CONVERT
Syntax
CONVERT(expr1, expr2, expr3)
Description
The UniBasic CONVERT function changes all occurrences of the substring expr1 in
expr3 to the string expr2. The system compares each character of the replacement
string expr2 and, if necessary, replaces each character of the target string expr1 on an
individual basis; the system does not compare and insert strings as a whole.
CONVERT may delete characters from a string expression, but it cannot insert char-
acters other than the characters it replaces. The length of the replacement substring
expr2 must be less than or equal to the length of the substring it replaces, expr1.
Parameters
expr1 Specifies the target string to replace with expr2.

expr2 Specifies the string with which to replace expr1.
expr3 Specifies the string to search for expr1.
CONVERT Parameters
Examples
In the following example, the program segment changes OLDSTR to NEWSTR
which now contains “868,848,838,808.”
OLDSTR = "767,747,737,707"
NEWSTR = CONVERT("7","8",OLDSTR)
In the next example, the program segment displays 1AA33BB667. Note that the fives
in X are dropped since you do not specify any corresponding substitute.
X = "122334455667"
PRINT CONVERT("245","AB",X)
In the following example the statement is invalid. The program segment tries to con-
vert “s” to “st”. Z has the same contents as Y, since S2 is longer than S1.
92
CONVERT
Y = "sasasasasa"
S1 = "s"
S2 = "st"
Z = CONVERT(S1,S2,Y)
93
COS
COS
Syntax
COS(expr)
Description
The UniBasic COS function returns the trigonometric cosine of a numeric expression.
Examples
In the following example, the program statement assigns the cosine of a 60-degree
angle to the variable COSINE. COSINE is assigned the value of .5.
COSINE = COS(60)
In the next example, the program statement prints the cosine of the variable VAL plus
ten.
PRINT COS(VAL+10)
94
COUNT
COUNT
Syntax
COUNT(str.expr1, str.expr2)
Description
The UniBasic COUNT function returns the number of times a substring appears
within a string. The string you want to search, str.expr1, must be longer than the sub-
string str.expr2. After str.expr2 is found, the system searches the string again with the
new starting point after the entire first occurrence of str.expr2. If the str.expr2 is not
found, the COUNT function returns a zero.
In BASICTYPE P, after str.expr2 is found, the system searches the string

BASICTYPE
again with the new starting point after the first character of the first occur-
rence of str.expr2. Overlapping character strings may be found.
Parameters
str.expr1 Specifies the string to search. This string must

be longer than str.expr2.
str.expr2 Specifies the target string to search for and
count occurrences of in str.expr1.
COUNT Parameters
Examples
In the following example, the program segment searches the string STRING for the
number of occurrences of the substring “II” and assigns this number “2” to the vari-
able IC.
STRING = "JAWSII,ROCKYIII,STARTREKIV"
IC = COUNT(STRING,"II")
In the next example, the same program segment compiled under BASICTYPE P,
searches the string STRING for the number of occurrences of the substring II and
assigns the number 3 to the variable IC. The COUNT function in BASICTYPE P,
counts III as 2 occurrences of the substring II.
95
COUNT
$BASICTYPE "P"
STRING = "JAWSII,ROCKYIII,STARTREKIV"
IC = COUNT(STRING,"II")
96
COUNTS
COUNTS
Syntax
COUNTS(expr,str.expr)
Description
The UniBasic COUNTS function returns the number of times a substring appears
within each element of an array. The elements in the array you want to search, expr1,
must be longer than the substring str.expr. After str.expr is found, the system searches
the array again with the new starting point after the entire first occurrence of str.expr.
If str.expr2 is not found, the COUNT function returns a zero.
In BASICTYPE P, after str.expr is found, the system searches the string again
BASICTYPE
with the new starting point after the first character of the first occurrence of
str.expr. Overlapping character strings may be found.
Parameters
expr Specifies the array to search. The elements of

this array must be longer than str.expr.
str.expr Specifies the target string to search for and
count occurrences of in elements of expr.
COUNTS Parameters
Examples
In the following example, the program segment searches the array ARR for the num-
ber of occurrences of the substring “I” and assigns the values to the variable IC. IC
now contains 2}3}1.
ARR = "JAWSII":@VM:"ROCKYIII":@VM:"STARTREKIV"
IC = COUNTS(STRING,"I")
In the next example, the same program segment compiled under BASICTYPE P,
searches the array ARR for the number of occurrences of the substring “II” and
assigns the values to the variable IC. IC now contains 1}2}0.
97
COUNTS
$BASICTYPE "P"
ARR = "JAWSII":@VM:"ROCKYIII":@VM:"STARTREKIV"
IC = COUNTS(STRING,"II")
98
CRT
CRT
Syntax
CRT [print.expr]
DISPLAY [print.expr]
Description
The UniBasic CRT command sends output to the display terminal regardless of the
use of the PRINTER ON/OFF command. print.expr may consist of either:
• String data
• Any number of strings or numeric variables
• UniBasic functions
• Any valid combination of the above
Examples
In the following example, the program segment uses the CRT command to print to the
display terminal. Notice in the latter case that even though a PRINTER ON statement
is issued, the system still directs the output from the CRT command to the display ter-
minal.
CRT "Turn your printer on and press Return to continue"
INPUT GO.ON
PRINTER ON
CRT "Process will take at least 2 hours to complete"
99
DATA
DATA
Syntax
DATA expr1 [,expr2]...
Description
The UniBasic DATA command holds data to be read by subsequent INPUT state-
ments. The expressions (expr1 and expr2) may be literal strings or variables. At the
time of execution of the DATA statements the system determines the specific position
of a value in the data queue. If expr1 is a variable or a complex expression resulting
from an operation (X*Y, for instance), and the you later change the value of the vari-
able (i.e., X changes from 10 to 20), or elements of the expression change, the con-
tents of the data stack remain the same.
The system places DATA statements in the queue in order of execution, whether by a
UniData command or within a UniBasic program. The queue processes on a first-in,
first-out basis. The DATA queue clears when control is returned to the UniData ECL
prompt (:). The DATA queue remains active through programs containing the CHAIN
command and through the use of PERFORM or EXECUTE when running additional
UniBasic programs.
You can load in-line prompts for paragraphs with the DATA command from a
Tip UniBasic program.
The first INPUT statement reads the first value in the DATA queue. Any following
INPUT statements continue to read subsequent values until reaching the end of the
DATA queue. If the system encounters a new DATA statement before the current
DATA queue is empty, the system places the new data values at the end of the queue.
If INPUT statements continue after the DATA statement is empty, the system requests
input information.
Note You may continue DATA statements over several lines by placing a comma
after each line (except for the last line).
Examples
In the following example, the program segment executes a DATA statement contain-
ing variables and constants of both string and numeric types. The first value, 10, is
read by a subsequent input statement and assigns the value to the variable COUNT.
DATA 10,"William","James",TESTVAL,135,
"Test Run"
INPUT COUNT
100
DATE
DATE
Syntax
DATE( )
Description
The UniBasic DATE function returns the current system date in internal format. The
internal format is the number of days after the system starting date of December 31,
1967.
Examples
In the following example, the program statement prints the current system date in the
internal format. If the date is December 31, 1967, the statement prints zero. If the date
is January 1, 1968, the statement prints 1, if the date is January 1, 1987, the statement
prints 6941, if the date is February 15, 1955, the system prints -4702.
PRINT DATE()
Related Topics
ICONV
The UniBasic ICONV function converts string or numeric data to an internal repre-
sentation format based on conversion codes.
OCONV
The UniBasic OCONV function converts string or numeric data from an internal rep-
resentation format to a format based on conversion codes.
TIMEDATE
The UniBasic TIMEDATE function returns a string representation of the current sys-
tem time and date in external format.
101
DCOUNT
DCOUNT
Syntax
DCOUNT(str,delim)
Description
The UniBasic DCOUNT function returns the number of substrings delimited by delim
in a string. If str is null, the system returns a 0. It str has data but does not have a
delimiter, the system returns a 1.
Parameters
str Specifies the string to search for occurences of

substrings delimited by delim.
delim Specifies the delimiter to use in searching str.
DCOUNT Parameters
Examples
In the following example, the program segment finds three occurrences of the value
mark and prints 3.
STR = 123:@VM:456:@VM:789
SUBS = DCOUNT(STR,@VM)
PRINT SUBS
In the next example, the program segment prints a 1. Even though there is not a delim-
iter as part of the string, there is a value the DCOUNT function recognizes.
STR = 123
DCOUNT(STR,@VM)
PRINT SUBS
102
DCOUNT
Related Topics
COUNT
The UniBasic COUNT function returns the number of times a substring occurs in a
string.
103
DEBUG
DEBUG
Syntax
DEBUG
Description
The UniBasic DEBUG command turns control over to the interactive UniBasic
debugger at the location of the statement. Pressing the BREAK key on your system
(ask your system administrator for its location) also gives control to the debugger.
To use the DEBUG command to display the contents of variables, you must compile
the program with the D option.
When you enter the debugger, the following message displays:
DEBUGGER called before line 1 of program BP/TEST
Related Topics
ABORT
The UniBasic ABORT command terminates the program in progress, and returns the
user to the UniData system level.
UniBasic Debugger
For information on the UniBasic Debugger, refer to Developing UniBasic
Applications.
BASIC
The ECL BASIC command compiles the UniBasic source code program into com-
piled interpretive code to use with the UniData Basic interpreter. The -D option cre-
ates a cross reference table for use with the UniBasic debugger. For information on
BASIC, refer to UniData Commands Reference.
DEBUG.FLAG
The ECL DEBUG.FLAG command invokes or suppresses debug statements within a
UniBasic program. For information on DEBUG.FLAG, refer to UniData Commands
Reference.
104
DEBUG
DEBUGLINE.ATT
The ECL DEBUGLINE.ATT command attaches another terminal for dual-terminal
debugging with the UniBasic debugger. For information on DEBUGLINE.ATT, refer
to UniData Commands Reference.
DEBUGLINE.DET
The ECL DEBUGLINE.DET command terminates dual-terminal debugging with the
UniBasic debugger. For information on DEBUGLINE.DET, refer to UniData
Commands Reference.
ON.ABORT
The ECL ON.ABORT command executes a command you specify if a subsequent
UniBasic program aborts. For information on ON.ABORT, refer to UniData
Commands Reference.
RUN
The ECL RUN command executes a compiled UniBasic program. The -D option
invokes the UniBasic debugger when a program encounters a run-time error. For
information on RUN, refer to UniData Commands Reference.
SETDEBUGLINE
The ECL SETDEBUGLINE command makes a terminal port attachable for dual ter-
minal debugging with the UniBasic debugger. For information on SETDEBUGLINE,
refer to UniData Commands Reference.
UNSETDEBUGLINE
The ECL UNSETDEBUGLINE command releases the debug terminal back to the
system when you are using dual terminal debugging in the UniBasic debugger. For
information on UNSETDEBUGLINE, refer to UniData Commands Reference.
UDT.OPTIONS
The setting of UDT.OPTIONS 14 determines where to return control after exiting a
UniBasic program when you are using the UniBasic debugger and enter ABORT or
END. For information on UDT.OPTIONS, refer to UniData Commands Reference.
105
DEFFUN
DEFFUN
Syntax
DEFFUN function.name [(MAT] arg.1[,[MAT]arg.2]...)] [CALLING catalog.name]
Description
The UniBasic command DEFFUN allows you to call a user-written function. You
must define a function with the UniBasic FUNCTION command within a UniBasic
program before you can call it with DEFFUN.
Parameters
function.name Specifies the name of the user-written

function.
[(MAT]arg.1 Specifies the arguments, if any, to be passed
[,[MAT]arg.2]...)] into the function. If arguments are used, they
must be enclosed in parentheses. Multiple
arguments must be separated by commas.
[CALLING catalog.name] Specifies the function to call if function.name
is not in the catalog file.
DEFFUN Parameters
Examples
The following example sets up a user-written function named CALC.SALES.TAX:
PRINT @(-1)
DEFFUN CALC.SALES.TAX(arg.1,arg.2)
PROMPT"
PRINT ‘Enter county name’:;INPUT COUNTY.NAME
PRINT ‘Enter sales amount ‘:;INPUT SALES.AMT
TAX.AMT=0
TAX.AMT=CALC.SALES.TAX(COUNTY.NAME,SALES.AMT)
PRINT ‘County name =’:COUNTY.NAME
PRINT ‘Sales amount =’:SALES.AMT
PRINT ‘Tax amount =’:TAX.AMT
END
106
DEFFUN
Related Topics
FUNCTION
The UniBasic FUNCTION command defines a user-written function and the argu-
ments that the calling program will pass to it.
107
DEL
DEL
Syntax
DEL dyn.array.var <attrib.expr[,val.expr [,subval.expr]]>
Description
The UniBasic DEL command deletes an attribute, value, or subvalue from a dynamic
array along with the corresponding delimiter.
DEL destroys the data within files and removes the corresponding delimiters.
Warning You must use caution when using DEL.
Parameters
dyn.array.var Specifies the dynamic array to perform the

delete operation on.
<attrib.expr> Specifies which attribute of the dynamic array
to delete. If the value expression is omitted,
DEL deletes the entire attribute, including
values and subvalues.
[,val.expr ] Specifies which value of the dynamic array
attribute to delete. If the subvalue expression is
omitted, DEL deletes the entire value,
including the subvalues.
[,subval.expr] Specifies which subvalue of the dynamic array
attribute value to delete.
DEL Parameters
Examples
In the following example, the program segment deletes the third attribute of the
dynamic array ARRAY1, which is Anne.
108
DEL
ARRAY1 = ’#543’:@AM:’Dorothy’:@AM:’Anne’:@AM:’Parker’
DEL ARRAY1<3>
In the following example, the statement is invalid. The DEL statement has more
parameters than ARRAY1.
ARRAY1 = ’#543’:@AM:’Dorothy’:@AM:’Anne’:@AM:’Parker’
DEL ARRAY<13,0,1,4>
Related Topics
DELETE
The UniBasic DELETE function deletes the contents and associated delimiter of an
attribute, value, or subvalue from a dynamic array.
Dynamic Arrays
For information on dynamic arrays, refer to Developing UniBasic Applications.
109
DELETE
DELETE
Syntax
DELETE [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic DELETE command deletes a record from a UniData file.
The DELETE statement releases any locks on the record you specify that have been
set by previous MATREADU, READL, READU, or READVU statements. This is the
only difference between the DELETE and DELETEU statements.
DELETE destroys the data within files. You must use caution when using
Warning DELETE.
Parameters
[file.var,] Specifies the file from which to delete the

record. Defaults to the most recently opened
file.
record.ID.expr Specifies the record to delete.
[ON ERROR statements] Specifies UniBasic statements to execute if
the DELETE statement fails with the follow-
ing fatal error conditions: the system cannot
find the file, or a default file is not open. If
you do not specify the ON ERROR clause,
the program terminates.
DELETE Parameters
Examples
In the following example, the program statement eliminates the record with the ID
PEANUT from the most recently opened default file.
DELETE "PEANUT"
110
DELETE
In the next example, the program segment deletes the record whose ID is specified by
the variable DEL_ID from the file previously opened to the PARTS variable.
DEL_ID = "HOOK"
DELETE PARTS, DEL_ID
In the following example the statement is invalid. The program segment is invalid,
since the filename must be opened to a file variable before the system can delete an
item. Here the CUSTOMER file is opened to the variable CUST, but the DELETE
statement attempts to delete CUSTOMER, not CUST. If a default file is not open, you
must specify a file variable.
OPEN ’’ ,’CUSTOMER’ TO CUST ELSE STOP ’NO CUST’
DELETE CUSTOMER, C.ID
Related Topics
DELETEU
The UniBasic DELETEU command deletes the record you specify from a UniData
file while maintaining an existing record lock.
111
DELETE
DELETE
Syntax
DELETE(dyn.array,attrib.expr{,val.expr{,subval.expr}})
Description
The UniBasic DELETE function deletes the contents of an attribute, value, or sub-
value (including the delimiter, if it is at the end of an array) from a dynamic array.
Parameters
dyn.array.var Specifies the dynamic array to perform the

delete operation on.
attrib.expr Specifies which attribute of the dynamic array
to delete. If the value expression is omitted,
DEL deletes the entire attribute, including
values and subvalues.
{,val.expr} Specifies which value of the dynamic array
attribute to delete. If the subvalue expression is
omitted, DEL deletes the entire value,
including the subvalues.
{,subval.expr} Specifies which subvalue of the dynamic array
attribute value to delete.
DELETE Parameters
Examples
In the first example, the program segment deletes the first attribute (125), and the
attribute mark, from the dynamic array ARRAY.
ARRAY = 125:@AM:1:@VM:62:@VM:3:@AM:132:@VM:4:@VM:5:@SM:1
ARRAY=DELETE(ARRAY,1,0,0)
In the next example, the program statement removes the first subvalue of the first
value of the second attribute in the array ARRAY. The new array is assigned to the
dynamic array ARRAY2.
112
DELETE
ARRAY2=DELETE(ARRAY,2,1,1)
In the next example, the program segment deletes the third attribute, which would
delete the A, B, and C.
ARRAY = 1:@AM:2:@AM:’A’:@VM:’B’:@VM:’C’
ARRAY = DELETE(ARRAY,3,0,0)
Related Topics
DELETE
The UniBasic DELETE command deletes the record you specify from a UniData file.
Dynamic Arrays
For more information on dynamic arrays, refer to Developing UniBasic Applications.
113
DELETELIST
DELETELIST
Syntax
DELETELIST list.name.expr
Description
The UniBasic DELETELIST command deletes a saved list created by either the
UniQuery SAVE.LIST command or by the UniBasic WRITELIST command.
list.name.expr is an expression specifying the saved list to delete.
If the list you specify cannot be found, the system displays an error message and takes
no action.
DELETELIST destroys the data within saved lists. You must use caution
Warning when using DELETELIST.
Examples
In the following example, the program statement eliminates the saved list CUST in the
current account.
DELETELIST "CUST"
114
DELETEU
DELETEU
Syntax
DELETEU [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic DELETEU command deletes the specified record record.ID.expr from
a UniData file.
The DELETEU command does not affect any record locks that were set by the user.
This allows the system to delete a record and re-create that same record while still
reserving a lock on that record for the current user.
DELETEU destroys the data within files. You must use caution when using
Warning DELETEU.
Parameters
[file.var,] Specifies the file from which to delete the

record. Defaults to the most recently opened
file.
record.ID.expr Specifies the record to delete.
[ON ERROR statements] Specifies UniBasic statements to execute if
the DELETE statement fails with the follow-
ing fatal error conditions: the system cannot
find the file, or a default file is not open. If
you do not specify the ON ERROR clause,
the program terminates.
DELETEU Parameters
Examples
In the following example, the program statement eliminates the record with the record
ID “JONES” from the most recently opened default file.
DELETEU "JONES"
115
DELETEU
In the next example, the program segment deletes the record, where the record ID is
stored in the variable DEL_ID, in the file previously opened to the variable DIS-
COUNT. If the record you delete is locked, it remains locked after the system deletes
it.
DEL_ID = "ACTION_FILMS"
DELETEU DISCOUNT, DEL_ID
Related Topics
DELETE
The UniBasic DELETE command deletes a record from a UniData file.
RELEASE
The UniBasic RELEASE command unlocks records.
116
DIMENSION
DIMENSION
Syntax
DIMENSION name1(rows[,cols]) [,name2(rows[,cols])]...
DIM name1(rows[,cols]) [,name2(rows[,cols])]...
Description
The UniBasic DIMENSION command creates and dimensions matrices. You may
specify matrices with as many as two dimensions (rows, cols). You must dimension
any matrices before you reference them from within a program. Standard UniBasic
(BASICTYPE U) also retains a zero element for each matrix.
The maximum number of elements you can specify is based on the total amount of
virtual memory available on your system.
Note Refer to Administering UniData on UNIX for information on system config-

uration.
After you execute a DIMENSION statement, the UniBasic INMAT function is set to
zero (0) if the matrices were successfully dimensioned and one (1) if there was insuf-
ficient memory. If sufficient memory is not present, the system prints an error mes-
sage and program execution continues.
The DIMENSION command will not perform a dimension in a subroutine when it is
called to the main program, instead the subroutine assumes the dimensions of the main
program when it is called.
In a two-dimensional matrix, there is an element 0,0. Elements such as 0,5 or 1,0 do
not exist. If a matrix is assigned using a MATREAD, MATWRITE, or MATPARSE
statement and more data is available than the matrix can contain, the excess data is
assigned to the 0,0 element.
Note MATREAD, MATWRITE, and MATPARSE load and empty an array from
left to right and from top to bottom.
117
DIMENSION
Parameters
name1 Specifies the name of the array.

rows Specifies the number of rows in the array.
[,cols] Specifies the number of columns in the array.
The cols parameter is optional. If cols is
omitted the array is one-dimensional.
DIMENSION Parameters
Resizing Arrays
You can also use the DIMENSION statement to dynamically re-dimension existing
arrays without losing any data if only the dimensions change without changing the
size of the matrix. When you resize a matrix, the system reshuffles the data with the
old elements being placed from left to right and from top to bottom.
While you may change the size of a matrix during program execution, its configura-
tion may not change, (i.e., a two-dimensional matrix may not be changed to a one-
dimensional matrix and vice versa). Also, matrices you pass as arguments to a subrou-
tine may not be re-dimensioned within the subroutine.
Examples
In the following example, the program statement creates three matrices: one-dimen-
sional NAME and TITLES, and the two-dimensional DATES.
DIMENSION NAME(100),TITLES(100),DATES(100,2)
In the next example, these two DIMENSION statements are perfectly legal in the
same program. After the execution of the second DIMENSION statement, the array
has the dimension of 100 by 10. The data in the matrix is reshuffled to fill the new
matrix. Some data is lost, since the new matrix is smaller than the original.
DIMENSION WAGES(50,100)
DIMENSION WAGES(100,10)
In the next example, the program statement creates the matrix TEST with the use of a
variable. The DIMENSION statement declares TEST as a one-dimensional array of
30 elements.
A = 30
DIMENSION TEST (A)
118
DIMENSION
In the following example the statement is invalid. The program statement is invalid
because a matrix size is declared with a non-numeric variable.
fffff TEST = "(10,5)"
DIMENSION TEST
Related Topics
MATREAD
The UniBasic MATREAD command assigns the values found in successive fields of a
record to corresponding elements of a matrix.
MATPARSE
The UniBasic MATPARSE command distributes portions of string to consecutive ele-
ments of a matrix based on a specified delimiter, which is found within the string.
MATWRITE
The UniBasic MATWRITE command writes successive elements of a matrix into cor-
responding attributes of a record.
INMAT
The UniBasic INMAT function displays the status of statements that you have exe-
cuted.
119
DIR
DIR
Syntax
DIR(file.expr)
Description
The UniBasic DIR function returns the file size (in bytes), the last date and time (in
internal format) the file was modified, and the file privileges of the file. The system
stores these values in the first four attributes of the value that returns. file.expr must
evaluate to a UNIX or VMS file name. If you do not specify a path name, the system
searches the current directory.
Examples
In the following example, the program segment retrieves the file statistics of the Uni-
Data file stored in the subdirectory /usr/accounting/gl. The first attribute contains the
file size in bytes; the second attribute contains the date the file was last updated; and
the third attribute contains the time the file was last updated. The system stores the
second and third attributes in the internal format, and the example converts them to the
external format.
FILESTAT = DIR("/usr/accounting/gl")
SIZE = FILESTAT <1>
DATE.MOD = OCONV(FILESTAT<2>,’D2/’)
TIME.MOD = OCONV(FILESTAT<2>,’MT’)
PRINT ’The gl file is ’:SIZE
PRINT ’And was last modified: ’:DATE.MOD,TIME.MOD
120
DISCONNECT
DISCONNECT
Syntax
DISCONNECT connection [ON ERROR statements]
Description
The UniBasic DISCONNECT command disconnects the program from a server.
STATUS
After the execution of the DISCONNECT statement, STATUS is set to one of the fol-
lowing:
0 Success
1 The server is not connected
2 Other errors
DISCONNECT Status Values
Parameters
connection The handle of the connection to the server.

[ON ERROR The ON ERROR clause allows the program to continue to
statements] perform if the DISCONNECT statement fails. It then
executes the statements you specify.
DISCONNECT Parameters
121
DOWNCASE
DOWNCASE
Syntax
DOWNCASE(str.expr)
Description
The UniBasic DOWNCASE function converts all characters in a string str.expr to
lower case.
Examples
In the following example, the program segment converts the contents of the variable
USTRING to lower case letters.
USTRING = "WHY am I HAPPY?"
DSTRING = DOWNCASE(USTRING)
DSTRING now contains “why am i happy?”
Related Topics
UPCASE
The UniBasic UPCASE function converts all characters in a string expression to
upper case.
122
DQUOTE
DQUOTE
Syntax
DQUOTE(str.expr)
Description
The UniBasic DQUOTE function encloses the string you specify within double
quotes. The string may contain any type of character.
Examples
In the following example, the program statement prints “This is “a” test”.
PRINT DQUOTE (’This is "a" test’)
In the next example, the program segment prints “‘This is another test’”.
X = "’This is another test’"
PRINT DQUOTE(X)
Related Topics
QUOTE
The UniBasic QUOTE function encloses an expression with quotes.
SQUOTE
The UniBasic SQUOTE function encloses a string with single quotes.
123
DROUND
DROUND
Syntax
DROUND(val.expr [,precision.expr])
Description
The UniBasic DROUND function performs double-precision rounding on a value.
Note DROUND affects the internal representation of the numeric value. It performs
the rounding without conversion to and from string variables. This increases
the speed of calculation.
Parameters
val.expr Specifies the value to round.

[,precision.expr] Specfies the precision for the rounding. The
valid range is 0 to 14. Default precision is four
places.
DROUND Parameters
Examples
In the following example, the program statement stores the result in A as a value with
8 digits to the right of the decimal point.
A = DROUND(3.14159265 * R * R,8)
Related Topics
PRECISION
The UniBasic PRECISION command sets the number of places past the decimal point
where you want to truncate a numeric variable.
124
EBCDIC
EBCDIC
Syntax
EBCDIC(expr)
Description
The UniBasic EBCDIC (Extended Binary Coded Decimal Information Code) func-
tion converts the ASCII (American Standard Code for Information Interchange) data
in expr to its corresponding EBCDIC values.
Reminder The standard application converts data to EBCDIC format before the data is
written to tape.
Examples
In the following example, the program statement first prints a message, then prints the
EBCDIC equivalent of the ASCII variable VAL.
PRINT "EBCDIC equivalent":EBCDIC(VAL)
Related Topics
ASCII
The UniBasic ASCII function converts a string from EBCDIC to the corresponding
ASCII values.
125
ECHO
ECHO
Syntax
ECHO {ON | OFF | expr}
Description
The UniBasic ECHO command controls the character display on the display terminal
as characters are entered from the keyboard.
Use ECHO for security purposes where the entry of an ID or password should
Tip not display on the display terminal.
Parameters
The following table describes the valid parameters:
ON Enables the display of characters as you type them on the

keyboard.
OFF Disables the display of characters as you type them on the
keyboard.
expr When the evaluation of expr results in zero, ECHO is set
to OFF. When expr evaluates to a non-zero value, ECHO
is set to ON. expr must evaluate to a numeric expression.
ECHO Parameters
Examples
In the following example, the program segment enables echoing, since the expression
A+B evaluates to a non-zero value.
A = 1
B = 3
ECHO A+B
126
END
END
Syntax
END
Description
The UniBasic END command declares the end of a program or a block of statements.
Note UniBasic does not require you to use END at the end of a program.
Examples
In the following example, the END command declares the end of the program seg-
ment.
IF X > 0 THEN
PRINT "Incrementing"
A = A + 1
END ELSE
PRINT "Decrementing"
A = A - 1
END
Related Topic
Program Constructs
For more information on program constructs, refer to Developing UniBasic
Applications.
127
ENTER
ENTER
Syntax
ENTER filename
ENTER @variable
Description
The UniBasic ENTER command passes control to a program you specify.
Note Control does not return to the original program.
The ENTER command terminates the program that is passing control and
executes the cataloged program. All variables passed between programs must
be included in a COMMON statement in both programs. All other variables
are initialized when you enter the new program.
The ENTER command processes faster than the CHAIN command.

Tip
Examples
In the following example, the program statement transfers control to cataloged pro-
gram CHECK_1.
ENTER CHECK_1
In the next example, the program segment transfers control to cataloged program
CHECK_2.
NO = 2
PROG = "CHECK_":NO
ENTER @PROG
Related Topics
CHAIN
The UniBasic CHAIN command terminates the UniBasic program in progress and
executes a specified terminal-level command.
128
ENTER
COMMON
grams and subroutines that use the same COMMON statement. Naming COMMON
allows for different common statements between subroutines and programs.
CATALOG
For more information on the ECL CATALOG command, refer to UniData
Commands Reference.
129
EQ
EQ
Syntax
variable EQ expr
Description
The UniBasic EQ function assigns or compares the contents of an expression to a
variable. expr can be a value, string, expression, or variable.
Parameters
variable Specifies the variable to which to assign the

contents of expr.
expr Specifies a value, string, expression, or
variable the value of which variable is
assigned to.
EQ Parameters
Examples
In the following example, the program statement assigns the value of 60 to the vari-
able PAGELENGTH.
PAGELENGHT EQ 60
In the next example, the program segment tests if A is equal to B. In this case, the
message “NOT EQUAL” prints.
A = 24
B = 23
IF A EQ B THEN
PRINT "EQUAL"
END ELSE
PRINT "NOT EQUAL"
END
130
EQS
EQS
Syntax
EQS(array1,array2)
Description
The UniBasic EQS function compares each value in array1 to its corresponding value
in array2. The system returns an array with a one in each position where values are
equal, and a zero in each position for values that are not equal.
Examples
In the following example, the program segment compares ARRAY1 to ARRAY 2 and
returns ARRAY3. ARRAY3 now contains 1}1}1}0}0.
ARRAY1 = ’11’:@VM:’12’:@VM:’13’:@VM:’20’:@VM:’21’
ARRAY2 = ’11’:@VM:’12’:@VM:’13’:@VM:’19’:@VM:’22’
ARRAY3 = EQS(ARRAY1,ARRAY2)
131
EQUATE
EQUATE
Syntax
EQUATE constant1 TO value1 [[,constant2 TO value2]...]
EQUATE constant1 LITERALLY string1 [[,constant2 LITERALLY string2]...]]
EQU constant1 TO value1 [[,constant2 TO value2]...]
EQU constant1 LIT string2 [[,constant2 LIT string2]...]
Description
The UniBasic EQUATE command replaces a constant with a string, value, or vari-
able name at compile time.
The TO form can take any legal UniBasic variable name as a value. If you specify a
string enclosed in quotation marks, at compile time the system replaces all occur-
rences of the constant with the string, including the quotation marks.
If you use the LITERALLY form of the EQUATE statement, at compile time the sys-
tem replaces all occurrences of the constant with a literal string, excluding quotation
marks. You must use quotation marks when you define the literal string in the
EQUATE statement, but the quotation marks will not be inserted at compile time.
Reminder UniBasic’s variable literal string limit is 2048 characters. EQUATE has the
same limit.
You may use variables, matrices, functions, numbers, and strings in the EQUATE
statement. You can use the LITERALLY form of the EQUATE statement to insert
expressions at compile time.
The EQUATE statements allow programmers to use longer, more meaningful

Tip names as they write code; these names are then replaced with the actual value
at compile time. The EQUATE also allows you to equate a control character
to a meaningful name. In addition, the system does not use memory for a con-
stant symbol, since the replacement takes place during compilation.
After the execution of an EQUATE statement, you may use the constant symbols
interchangeably at all levels of the program.
Note Before UniData 3.3, EQUATE variables were not stored in the object file and
were invisible to the UniBasic debugger. EQUATE variables are now avail-
able from within the UniBasic debugger.
132
EQUATE
Parameters
constant1 Specifies the constant to be replaced with

value1 at compile time.
value1 Specifies the value to replace the constant
constant1 with at compile time.
string1 Specifies a literal string, in quotes, to replace
the constant constant1 with at compile time.
EQUATE Parameters
Examples
In the following example, all occurrences of the constant BS are replaced with the
value CHAR(8) (clear screen) during program compilation.
EQUATE BS TO CHAR(8)
In the next example, during compilation, the program statement replaces every occur-
rence of the constant TITLE with the string ALGONQUIN.
EQUATE TITLE LITERALLY "ALGONQUIN"
In the next example, during compilation the program statement replaces every occur-
rence of the constant TRUE with the value 1, and every occurence of the constant
FALSE with the value 0.
EQUATE TRUE to 1, FALSE to 0
IF TRUE
PRINT "Income less than target figure."
END
IF FALSE
PRINT "Income equal to or greater than target!"
END
In the next example, during compilation the program statement replaces every occur-
rence of the constant FULLNAME with the expression in the example.
EQUATE FULLNAME LITERALLY "FIRST_NAME:’ ‘:LAST_NAME"
FIRST_NAME = "Mary"
LAST_NAME = "Jones"
PRINT FULLNAME
At compile time, the print statement in this example would be changed to look like
this:
PRINT FIRST_NAME:’ ‘:LAST_NAME
133
EXECUTE
EXECUTE
The UniBasic EXECUTE and PERFORM commands execute ECL commands
(UniData or UniQuery commands), sentences, or paragraphs. Refer to the entry on the
UniBasic PERFORM command for further information.
134
EXECUTESQL
EXECUTESQL
Syntax
EXECUTESQL str.expr [ASYNC | SYNC] [ON connection]
Description
The UniBasic EXECUTESQL command executes an SQL statement.
If the SQL statement includes a SELECT statement with the intent to process items
internal to the program, the SELECT statement must contain an INTO clause with a
resulting file name. Otherwise, the system displays the result of the statement. If you
select only the @ID attribute, the system select lists are used, if available. If the SQL
statement includes an INTO clause, the data is stored in the resulting file and is then
available to the UniBasic program via the READNEXTTUPLE statement.
Parameters
str.expr Specifies a valid SQL statement for the

system to execute.
[ASYNC | SYNC] ASYNC performs an asynchronous execution
and returns control to the program immedi-
ately, without waiting to get the results of the
EXECUTESQL statement. To get the results,
use the WAIT command. SYNC performs a
synchronous execution and waits for the
results of the EXECUTESQL command and
returns them before continuing with the pro-
gram. You can use these parameters when
developing UniDesktop/Open Client applica-
tions. For information on developing these
applications, refer to Developing UniDesktop/
Open Client Applications.
EXECUTESQL Parameters
135
EXECUTESQL
[ON connection] Specifies the handle to a server you specified

with the CONNECT command. You can use
this parameter when developing UniDesktop/
Open Client applications. For information on
developing these applications, refer to
Developing UniDesktop/Open Client Appli-
cations.
EXECUTESQL Parameters (continued)
Examples
In the following example, the program segment executes an SQL command. The
resulting output displays on the display terminal.
OUT.COMMAND = "SELECT NAME, ADDRESS, CITY"
OUT.COMMAND := "FROM CUSTOMER;"
EXECUTESQL OUT.COMMAND
In the next example, the program segment executes the same SQL command with an
INTO clause that stores the SQL output in a file that you can access using the READ-
NEXTRECORD statement.
OUT.COMMAND := " FROM CUSTOMER INTO SQL_INPUT;"
DONE = 0
LOOP
READNEXTRECORD CUST.REC FROM SQL_INPUT
ELSE DONE =1
UNTIL DONE DO
CONVERT @AM TO " " IN CUST.REC
PRINT CUST.REC
REPEAT
In the next example, the SQL statement selects an @ID only. The system uses a select
list instead of storing the output. In this case, the SQL command does not require an
INTO clause, and the standard UniBasic READNEXT statement processes the IDs
selected.
OUT.COMMAND = "SELECT @ID"
OUT.COMMAND := "FROM CUSTOMER"
OUT.COMMAND := "WHERE STATUS = ‘OPEN’;"
DONE = 0
LOOP
READNEXT @ID ELSE DONE = 1
UNTIL DONE DO
GOSUB PROCESS.RECS:
REPEAT
136
EXECUTESQL
Related Topics
READNEXT
The UniBasic READNEXT command assigns the next record ID from a list of IDs to
a variable.
READNEXTTUPLE
The UniBasic READNEXTTUPLE command assigns an entire record from an SQL
statement (with attributes separated by attribute marks) to a variable.
137
EXIT
EXIT
Syntax
EXIT
Description
The UniBasic EXIT command terminates a FOR/NEXT or LOOP/REPEAT structure
and transfers control to the first statement after the preceding structure. As with the
CONTINUE statement, EXIT forms well-structured programs.
Tip Use EXIT to avoid poorly formed conditions or awkward code segments.
Examples
In the following example, the program segment exits the FOR/NEXT loop when I is
greater than 8.
FOR I = 1 TO 10
IF I > 8 THEN EXIT
PRINT "I = ":I
NEXT I
Related Topics
CONTINUE
The UniBasic CONTINUE command transfers control to the next iteration of a FOR/
NEXT or LOOP/REPEAT statement.
FOR/NEXT
The UniBasic FOR/NEXT command executes statements repeatedly while a variable,
beginning at a specified value, is incremented. The loop continues until the variable
reaches a specified value or the condition in the WHILE or UNTIL clause is reached.
LOOP/REPEAT
The UniBasic LOOP/REPEAT command repeats any contained statements WHILE or
UNTIL a specified condition is met.
138
EXP
EXP
Syntax
EXP(expr)
Description
The UniBasic EXP function raises e to the power of expr.
Reminder e is important because the function ex is its own derivative. If y = ex, then x is
the natural logarithm of y. e has a value of approximately 2.7183.
Examples
In the following example, the program statement raises e to the power of 2, and
assigns this value, 7.3891, to the variable ETOX.
ETOX = EXP(2)
Related Topics
LN
The UniBasic LN function returns the natural base logarithm of a numeric expression.
139
EXTRACT
EXTRACT
Syntax
EXTRACT(dyn.array.expr, attrib.expr,{val.expr [,subval.expr]})
dyn.array.expr <attrib.expr,{val.expr [,subval.expr]}>
Description
The UniBasic EXTRACT function extracts data from an attribute, value, or subvalue
in a dynamic array. The dynamic array itself remains unchanged.
Parameters
dyn.array.expr Specifies a dynamic array from which to

extract the data.
attrib.expr Specifies an attribute of the dynamic array
from which to extract the data. If attrib.expr is
less than 1, then the system assumes a 1.
val.expr Specifies a value of attrib.expr from which to
extract the data. If the val.expr and subval.expr
evaluate to zero, the system extracts an
attribute.
subval.expr Specifies a subvalue of the value specified by
val.expr in the attribute specified by
attrib.expr, from which to extract data.
If the val.expr and subval.expr evaluate to zero,
the system extracts an attribute. If subval.expr
evaluates to zero, the system extracts a value.
EXTRACT Parameters
Examples
In the following example, the program segment assigns the string Joan to the variable
MID, which is the second attribute in the dynamic array ARR. The value and subvalue
expressions are zero, resulting in the extraction of an attribute.
140
EXTRACT
ARR = "#543":@AM:"Joan":@AM:"D’Arc"
MID = EXTRACT(ARR,2,0,0)
In the next example, the program segment assigns the string Dagny, the second value
of the third attribute, to the variable MID.
ARRAY = "#143":@AM:"Gustav":@AM:"Mahler":@VM:"Dagny":@VM:"Jens"
MID = EXTRACT(ARRAY,3,2)
In the next example, the program statement demonstrates the short form of the previ-
ous EXTRACT statement.
MID = ARRAY<3,2>
141
FIELD
FIELD
Syntax
FIELD(string.expr,delim.expr,field.expr [,rep.expr])
Description
The UniBasic FIELD function treats a string as an array, with fields delimited by any
specified ASCII character (for example, spaces, commas, or periods), and returns a
substring or group of substrings.
Parameters
string.expr Specifies the string expression to return the

field from.
delim.expr Specifies the field delimiter.
field.expr Specifies the field to start returning from.
[,rep.expr] Specifies the number of fields to return. If you
do not specify rep.expr, or it is less than 1, the
system returns a default of 1 substring.
FIELD Parameters
Examples
In the following example, the program segment assigns the second value (“Guy”) in
the array ARR to the array NARRAY.
ARR = "#999":@AM:"Charlemagne":@VM:"Guy":@VM:"Pierre"
NARRAY = FIELD(ARR,CHAR(253),2,1)
In the next example, the program segment assigns the two fields following the third
occurrence of the delimiter “,” in the variable ARR to NARRAY. The system stores
the value “8,7” in NARRAY.
ARR = "10,10,5,8,7,12,15,8"
NARRAY = FIELD(ARR,",",3,2)
142
FIELD
In the next example, the program segment assigns the second group of characters in a
string delimited by spaces in the variable NAME to LNAME. The system stores the
value Smith in LNAME.
NAME = "Harry Smith"
LNAME = FIELD(NAME," ",2)
Related Topics
COL1
COL2
143
FIELDSTORE
FIELDSTORE
Syntax
FIELDSTORE(str.expr,delimiter,b.pos,option,replace.expr)
Description
The UniBasic FIELDSTORE function inserts an expression into a string.
Parameters
str.expr Specifies the string to insert replace.expr into.

delimiter Specifies the character that delimits fields in
the string str.expr.
b.pos Specifies the field at which to insert.
If the number of delimiters is less than b.pos,
the system inserts the appropriate number of
null substrings and delimiters.
option Specifies whether FIELDSTORE will insert
before, insert after, or replace the field at b.pos.
Refer to the Options table for further details.
replace.expr Specifies the expression (with its associated
delimiter) to insert before or after the specified
attribute, value or subvalue mark.
FIELDSTORE Parameters
144
FIELDSTORE
Options
The value of option changes which operation takes place with the replace.expr. The
following table describes these values and their results.
Value Description
If option > 0 The system replaces the number of substrings equal to the
absolute value of option with the equivalent number of
substrings in replace.expr.
If option = 0 The system inserts the entire replace.expr at the substring
position indicated by the value of b.pos.
If option < 0 The system deletes the number of substrings equal to the
value of option and inserts replace.expr at the substring
location indicated by b.pos.
FIELDSTORE Options
Examples
In the following example, the program segment inserts Arkansas (“AR”) in the string
ASTATES. ASTATES now contains the string “AL:AK:AR:AZ.”
ASTATES = ’AL:AK:AZ’
ASTATES = FIELDSTORE(ASTATES,’:’,3,0,’AR’)
In the next example, the program segment specifies that processing begins at the fifth
value (ugly), that this value is deleted (the -1 option), and that the replace.expr
(orange,black) is to be inserted in the same position. COLORS now contains the string
“yellow,blue,red,green,orange,black,white.”
COLORS = ’yellow,blue,red,green,ugly,white’
COLORS = FIELDSTORE(COLORS,’,’,5,-1,’orange,black’)
145
FILEINFO
FILEINFO
Syntax
FILEINFO(file.var, code)
Description
The FILEINFO function returns information about a file’s configuration.
Parameters
file.var Specifies the file about which to return

information.
file.var is the file variable previously used in an
OPEN or OPENSEQ statement.
code Specifies the type of information to return.
FILEINFO Parameters
FILEINFO Codes
code is a number indicating the information required. The following table describes
the codes and the return values of the function:
Information
Code File Type Returned Value
Requested
0 Is file open ALL 1= Open

0= Not open
2 Full path name of file ALL Pathname of file
3 File type HASHED 2
DYNAMIC 3
DIRECTORY 4
SEQUENTIAL 5
OS 8
FILEINFO File Information Codes
146
FILEINFO
Information
Requested
4 Hashing file type HASH & DYN Hashtype (0 or 1)

OTHERS Null
5 Modulus of file HASH Modulus
DIRECTORY 0
DYNAMIC Current modulus
OTHERS Null
6 Minimum modulus of DYNAMIC Minimum modulus
file
7 Group size of file HASH & DYN (Block size/1024)-1
OTHERS Null
8 Block size of file HASH & DYN Block size
OTHERS Null
9 Merge factor DYNAMIC Merge factor
percentage OTHERS Null
10 Split factor percentage DYNAMIC Split factor
OTHERS Null
11 Current load DYNAMIC Percent result of the
percentage OTHERS formula:
(keyspace(grp)
*100)/blksize
Null
13 Does file contain HASH & DYN 1= yes; 2 = no
alternate key indices? OTHERS Null
14 Next line number to SEQUENTIAL Next line number
read or write OTHERS Null
17 Filename HASH & DIR VOC entry name
& DYNAMIC
OTHERS Null
18 Block size of file HASH & DIR Block size
& DYNAMIC
OTHERS Null
FILEINFO File Information Codes (continued)
147
FILEINFO
Information
Requested
19 Access permissions ALL Permissions the

person running the
program has
expressed as total
UNIX values
(r=4,w=2,x=1, so
rw= 6)
20 Index to which the last ALL VOC entry name
SETINDEX statement
was applied.
21 Index record read by ALL Key Value
last browsing
statement, including
READFWD,
READBCK, etc.
FILEINFO File Information Codes (continued)
148
FILELOCK
FILELOCK
Syntax
FILELOCK [file.var] [ON ERROR statements] LOCKED statements
Description
The UniBasic FILELOCK command locks the dictionary or data portion of a file
against access by READL, READU, READVU, MATREADL, MATREADU, MAT-
WRITEU, WRITEU, and WRITEVU statements. Other file input/output commands
ignore FILELOCK.
Parameters
[file.var] Specifies the file to lock. If you do not

specify a file.var, the system locks the most
recently opened default file.
[ON ERROR statements] Specifies statements to perform if the
FILELOCK statement fails with a fatal
error condition because the file is not open.
If you do not specify the ON ERROR
clause, the program terminates.
LOCKED statements Specifies statements to execute if the file is
already locked.
FILELOCK Parameters
Examples
In the following example, the FILELOCK statement locks the file STAT, preventing
lock-checking commands from accessing this file.
FILELOCK STAT LOCKED STOP
149
FILELOCK
Related Topics
FILEUNLOCK
The UniBasic FILEUNLOCK command unlocks a file previously locked with the
FILELOCK command.
150
FILEUNLOCK
FILEUNLOCK
Syntax
FILEUNLOCK [file.var] [ON ERROR statements]
Description
The UniBasic FILEUNLOCK command unlocks a file previously locked with a
FILELOCK command.
Parameters
[file.var] Specifies the file to unlock. If you do not

specify a file.var, the system unlocks the
most recently opened default file.
[ON ERROR statements] Specifies statements to perform if the
FILEUNLOCK statement fails with a fatal
error condition because the file is not open.
If you do not specify the ON ERROR
clause, the program terminates.
FILEUNLOCK Parameters
Examples
In the following example, the FILEUNLOCK statement unlocks the file referred to by
the file variable TAPES.
FILEUNLOCK TAPES
Related Topics
FILELOCK
The UniBasic FILELOCK command locks a file against access by other users using
READL, READU, READVU, and MATREADU statements.
151
FILEUNLOCK
STATUS
The UniBasic STATUS function returns the validity of the previous operation.
152
FIND
FIND
Syntax
FIND expr IN dyn.array[,occur] SETTING f [,v[,s]] {[THEN statements] |
[ELSE statements]}
Description
The UniBasic FIND command determines the position of the given expression in a
dynamic array.
Parameters
expr Specifies the expression to find. expr must

evaluate to either a numeric or a string value.
dyn.array Specifies the dynamic array in which to find
expr.
[,occur] Specifies which occurrence of expr in the array
you want to find. The default for occur is 1 (the
first occurrence).
f [,v[,s]] Specifies variables in which to place the posi-
tion of expr. The location of the attribute is
assigned to f, value to v, and subvalue to s.
If the attribute found has neither multivalues
nor subvalues, then v and s, if specified, are set
to zero. If only multivalues are present, s is set
to zero. If only subvalues exist, v is also set to
zero.
[THEN statements] Specifies statements to execute if the expr is
found in the array. Either a THEN or an ELSE
statement is required.
[ELSE statements] Specifies statements to execute if the expr is
not found in the array. Either a THEN or an
ELSE statement is required.
FIND Parameters
153
FIND
Examples
In the following example, the program segment searches for 31 in the string DA. This
results in F=3, V=1, S=0, since 31 is found in the third attribute as the first multivalue,
and this attribute has no subvalues.
DA = 1:@AM:2:@AM:31:@VM:32:@VM:41:@VM:41:@VM:42:@VM:43
FIND 31 IN DA SETTING F,V,S ELSE PRINT "NOT FOUND"
In the next example, the program segment searches for second occurrence of 41 in the
string DA. This results in F=3, V=4, S=0, since the second occurrence of 41 is found
in the third attribute as the 4 multivalue, and this attribute has no subvalues.
FIND 41 IN DA,2 SETTING F,V,S ELSE PRINT "NOT FOUND"
Related Topics
FINDSTR
The UniBasic FINDSTR command determines the position of a specified substring
within a dynamic array element.
154
FINDSTR
FINDSTR
Syntax
FINDSTR substr IN dyn.array[,occur] SETTING f[,v[,s]] {[THEN statements1] |
[ELSE statements2]}
Description
The UniBasic FINDSTR command determines the position of a given substring in a
dynamic array.
Parameters
substr Specifies the substring to find. substr must

evaluate to either a numeric or a string value.
dyn.array Specifies the dynamic array in which to find
substr.
[,occur] Specifies which occurrence of substr you want
to find in the array. The default for occur is 1
(the first occurrence).
f [,v[,s]] Specifies variables in which to place the posi-
tion of substr. The location of the attribute is
assigned to f, value to v, and subvalue to s.
If the attribute found has neither multivalues
nor subvalues, then v and s, if specified, are set
to zero. If only multivalues are present, s is set
to zero. If only subvalues exist, v is also set to
zero.
[THEN statements] Specifies statements to execute if the substr is
found in the array. Either a THEN or an ELSE
statement is required.
[ELSE statements] Specifies statements to execute if the substr is
not found in the array. Either a THEN or an
ELSE statement is required.
FINDSTR Parameters
155
FINDSTR
Examples
In the following example, the program segment searches for 3 in the string DA. This
results in F=3, V=1, S=0, since 3 is found in the third attribute as the first multivalue,
and this attribute has no subvalues.
FINDSTR 3 IN DA SETTING F,V,S ELSE PRINT "NOT FOUND"
In the next example, the program segment searches for the second occurrence of 4 in
the string DA. This results in F=3, V=4, S=0, since the second occurrence of 4 is
found in the third attribute as the 4 multivalue, and this attribute has no subvalues.
FINDSTR 4 IN DA,2 SETTING F,V,S ELSE PRINT "NOT FOUND"
Related Topics
FIND
The UniBasic FIND command determines the position of an expression in a dynamic
array.
156
FLUSH
FLUSH
Syntax
FLUSH
The FLUSH command flushes output to the terminal when UDT.OPTIONS 46 is ON.
Note For more information on the ECL command UDT.OPTIONS 46, refer to the
157
FMT
FMT
Syntax
FMT(expr, “len [ f.char] [L | R | T | C] [n] [$] [,] [Z] [mask]”)
FMT(expr, pattern.var)
FMT(expr, “[L | R | T | C] # len [f.char] [n] [$] [,] [Z] [mask]”)
expr “[L | R | T | C] # len [f.char] [n] [$] [,] [Z] [mask]”
Description
The UniBasic FMT function formats data in an expression expr through a specific
format mask for display purposes.
In the second form, you can express the pattern format through a variable pattern.var.
In the first form, the FMT statement must contain a L, R, C, or T and a len expression;
additional expressions are optional.
In the third form, the justification is the first element, followed by a pound sign (#) to
truncate data, and the len expression. All other values are the same.
In the fourth form, you do not have to explicitly state FMT, but it follows the same
format pattern syntax.
Note A FMT statement can be no longer than 2046 characters.
The FMT function sets the STATUS function to 0, 1, or 2. If the format is successful,
the value is set to 0. If the string expression is invalid or exceeds the allowable string
size, the value is set to 1. If the conversion code is invalid, the value is set to 2.
Note The UniBasic FMTS function formats a multivalued array.
158
FMT
Parameters
The following table describes each of the syntax elements.
len Specifies the total number of characters to appear in the

output string.
[f.char] Specifies a character to be used to fill the formatted string,
if necessary; the default is a space. Since the f.char follows
the len expression and both may be numeric, you may pre-
fix a numeric f.char with a ‘\’ to indicate it is the fill
character.
[L] Specifies left-justification. If the text is longer than a
length expression (if any), the text is broken in len
intervals.
[R] Specifies right-justification in a field of len spaces.
[C] Specifies centered text in the column of width len.
[T] Specifies text justification. If data must be broken to fit in
a column, a space justification occurs on a word basis
(from space-to-space).
[n] Specifies the maximum number of decimal places
allowed, rounding as necessary. If n = 0, the number is
rounded to an integer.
[$] Prints a dollar sign at the head of the formatted string.
Valid for numeric data only. {,}prints numbers with com-
mas separating each level of thousands. Valid for numeric
data only.
[Z] Specifies the suppression of any leading zeros in the
string.
[mask] Specifies a pattern mask composed of numbers and other
characters. Numeric data is placed sequentially in the
mask before justification.
FMT Parameters
159
FMT
Examples
In the following example, the program segment prints the variable SS.NUM as a for-
matted string using a pattern mask. The result printed is a string with 11 characters,
left-justified: “543-70-4128.”
SS.NUM=543704128
PRINT FMT(SS.NUM,"11L###-##-####")
In the next example, the program segment prints the variable NUM as a 12 character-
wide, right-justified number with two decimal places, preceded by a dollar sign and
composed with commas. The segment prints the value “$16,526.00”
NUM = 16526
PRINT FMT(NUM, "12R2$,")
In the next example, the program segment formats the string OUT.STRING with 0 as
the fill character, right-justified, and in a column of four spaces. The segment prints
0044.
OUT.STRING = 44
OUT.STRING = FMT(OUT.STRING,"4\0R")
PRINT OUT.STRING
In the next example, the program statement saves the variable STR as a right-justified,
eight column string.
STR = STR "R#8"
In the next example, the program segment uses a variable to specify the pattern for-
mat. The system formats the string STR according to the variable PATTERN.
PATTERN = "12R2$,"
STR = STR PATTERN
160
FOOTING
FOOTING
Syntax
FOOTING [ON num.expr] {str.expr [‘option‘]...}
Description
The UniBasic FOOTING command causes the specified string to display at the bot-
tom of every page of a report.
The PRINTER command directs the output of a FOOTING command not sent to a
print file. The execution of PRINTER OFF causes a report, together with its footings,
to appear on the user’s terminal. A PRINTER ON command causes all subsequent
footings, headings, and PRINT output to be sent to the destination specified by the
current SETPTR setting.
The code or codes must be surrounded by one pair of single quotes. You can place
codes anywhere in the footing expression.
Parameters
[ON num.expr] Specifies a particular print file to which to

direct the footing, where num.expr is the num-
ber of the desired print file between 0 and 254.
{str.expr} Specifies the string to display at the bottom of
every page.
[option]... A footing string may contain special codes
controlling paging characteristics and can
insert the current time, date, or page number in
the footing.
FOOTING Parameters
161
FOOTING
Options
The following table describes the valid options.
Option Description
P or S Prints current page number.

N Suppresses the CR after each page.
L Advances one line. Used for multiline footings.
D Prints date in MM-DD-YY format.
T Prints time/date in MM-DD-YY HH:MM:SS format.
C Centers the footing text.
G Forces the line to fill the width of the page.
FOOTING Options
Examples
In the following example, the program statement produces a footing using a character
string.
FOOTING "Copyright 1987, Genius, Inc."
In the next example, the program statement prints “Page,” and the current page num-
ber, it advances one line and then prints the string Paul’s Produce. Notice the double
apostrophe in the middle of the strings; which is necessary to print a single apostrophe
in the footer as it will appear on the screen or printer. The ON 2 clause sends the foot-
ing to the print file 2.
FOOTING ON 2 "Page ‘PL’Paul’’s Produce"
Related Topics
SETPTR
For information on the ECL SETPTR command, refer to UniData Commands
Reference.
Device Input/Output
For information on device input/output, refer to Developing UniBasic Applications.
162
FORMLIST
FORMLIST
Syntax
FORMLIST dynamic.array.var [TO list.num.expr]
Description
The UniBasic FORMLIST command creates an active select list from a dynamic
array. FORMLIST uses the attribute marks in dynamic.array.var to create an active
select list that you can use with READNEXT statements or other list processing com-
mands such as external LIST statements.
Parameters
dynamic.array.var Specifies a dynamic array from which to create

an active select list.
[TO list.num.expr] Specifies which list, 0 through 9, you want the
list sent to. 0 is the default list.
FORMLIST Parameters
Examples
In the following example, the program segment creates a select list and then uses that
list to print the first five records of the CUSTOMER file.
ARRAY.LIST = 1:@AM:2:@AM:3:@AM:4:@AM:5
FORMLIST ARRAY.LIST TO 0
PRINT "PROCESSING THE FOLLOWING ITEMS:"
PERFORM "LIST CUSTOMER"
END
Related Topics
READLIST
The UniBasic READLIST command assigns the values in an active select list to a
dynamic array.
163
FOR/NEXT
FOR/NEXT
Syntax
FOR var = val1 TO
val2 [STEP val3]
[statements]
[{UNTIL |
WHILE}expr]
statements
NEXT [var]
Description
The UniBasic FOR/NEXT command executes statements repeatedly while increment-
ing a variable over a range until it reaches the end of the range, or until the condition
in the WHILE or UNTIL clause is ended or reached.
You may nest FOR/NEXT constructions. Each FOR statement must be associ-
Tip ated with one NEXT statement.
Parameters
var Specifies the variable to increment.

val1 Specifies the beginning of the range to incre-
ment var over.
val2 Specifies the end of the range to increment var
over.
[STEP val3] Specifies the change to use in incrementing
var. The increment can be negative or positive,
making the variable decrease or increase.
[statements] Specifies the statements to carry out for each
loop.
FOR/NEXT Parameters
164
FOR/NEXT
[{UNTIL | WHILE}expr] Specifies a condition, expr, to test after each

statements loop. If the UNTIL keyword is used, the loop
continues as long as expr is not true. If the
WHILE keyword is used, the loop continues as
long as expr is true. In either case, when the
loop stops, the statements are executed before
the program continues.
NEXT [var] The NEXT statement defines the end of the
block of statements to be repeated. var is the
same variable as in the beginning of the FOR/
NEXT statement.
FOR/NEXT Parameters (continued)
Examples
In the following example, the program segment prints the string “10,8,6,4,2,”. The
loop terminates before printing 0, since the FOR/NEXT statement specifies that when
the variable “I” falls below 1 the loop terminates.
FOR I = 10 TO 1 STEP -2
PRINT I:",":
NEXT I
In the next example, the optional WHILE expression clause creates a secondary con-
dition for the termination of the FOR/NEXT structure. While a normal FOR/NEXT
loop repeats the contained statements 10 times, the WHILE clause results in this
example stopping after only three repetitions. This occurs because the value read from
the DATA statement by the INPUT command exceeds the value of “I” on the third
iteration. The WHILE clause with the same statements results in the loop terminating
after one iteration. After the iteration, variable “I” is less than “K”, satisfying the con-
dition and causing the loop to stop.
K=50
DATA 3,4,2,51,8,10,15,3,2,8
FOR I = 1 TO 10 WHILE I < K
INPUT K
PRINT I,K
NEXT I
165
FUNCTION
FUNCTION
SYNTAX
FUNCTION function.name [([MAT] arg.1[, [MAT] arg.2]...)]
DESCRIPTION
The UniBasic command FUNCTION defines a user-written function and accepts the
arguments that the calling program passes to it. A user-written statement can contain
only one FUNCTION statement, and the FUNCTION statement must be the first non-
comment line.
Parameters
function.name Specifies the name of the user-written function.

[([MAT] arg.1 Specifies the arguments the user-written
[, [MAT] arg.2]...)] function accepts.
FUNCTION Parameters
RELATED TOPICS
DEFFUN
The UniBasic DEFFUN command calls a user-written function.
166
GARBAGECOLLECT
GARBAGECOLLECT
Syntax
GARBAGECOLLECT
Description
The UniBasic GARBAGECOLLECT command releases all reserved but non-active
portions of memory space allocated for UniBasic variables.
167
GE
GE
Syntax
expr1 GE expr2
Description
The UniBasic GE function tests whether the expression expr1 is greater than or equal
to expr2. The expressions may be any valid UniBasic expression, variable, or string.
Examples
In the following example, the program segment tests whether A is greater than or
equal to B. Since A is greater than B, the message “Greater Than or Equal To” prints.
A = 24
B = 22
IF A GE B THEN
PRINT "Greater Than Or Equal To"
END ELSE
PRINT "Less Than"
END
168
GES
GES
Syntax
GES(array1,array2)
Description
The UniBasic GES function compares each value in array1 to its corresponding value
in array2. The system returns an array with a one in each position where the value in
array1 is greater than or equal to the value in the corresponding position in array2.
The system returns a zero in each position for values that are less than array2.
Examples
In the following example, the program segment compares ARRAY1 to ARRAY2 and
ARRAY1 = 10:@VM:20:@VM:30@VM:40:@VM:50
ARRAY2 = 9:@VM:10:@VM:30:@VM:50:@VM:60
ARRAY3 = GES(ARRAY1,ARRAY2)
169
GET
GET
Syntax
GET[X] var[,length] [SETTING count.var] FROM line.expr [UNTIL term.expr]
[RETURNING term.var] [WAITING seconds] [{THEN | ELSE} statements]
Description
The UniBasic GET command receives unprompted input from an attached line. A
prompt does not display, and the system accepts all control characters, including the
carriage return and line feed as input characters.
The way that the GET statement performs varies according to the termination condi-
tions specified, and whether the THEN or ELSE clauses are specified.
You can terminate input from the attached line in four ways:
• When the system reads the number of expected characters.
• When you do not specify the number of characters and do not use an
UNTIL clause. The system accepts only one character. (The only time
GET does not have a maximum amount of characters is when you use the
UNTIL clause without explicitly specifying a length.)
• When any one of the characters you specify by the UNTIL clause is also
in the input. When the system reads one of the specified characters from
the attached line, the GET statement terminates and the system assigns
characters up to the terminating character to the variable var. If you use
the RETURNING clause, the system assigns the terminating character to
the variable term.var.
• When the system reads the record mark character, CHAR(255) and you
specify a number of seconds with the WAITING clause, and none of the
conditions listed above has been met before the number of seconds has
elapsed.
If you use the UNTIL clause without a WAITING clause or an expected length, the
program waits indefinitely until it reads a termination character. After this process, the
system executes the THEN clause.
Note The system never performs an ELSE clause if you use the UNTIL clause
without a WAITING clause or an expected length.
If you use the WAITING clause, the system performs the ELSE clause only if the
number of seconds for time-out elapses. If the input is terminated for any other reason,
the system performs the THEN clause. In either case, whatever data is read from the
attached line is placed in var.
170
GET
In special cases, the system performs the ELSE clause if the line has not been attached
before executing the GET statement.
Parameters
[X] Specifies that GET should return an exploded

ASCII hexadecimal representation string of the
input data. This feature allows binary data to
contain a 255 value (hexadecimal FF). For
instance, if a user enters HELLO, the input
data variable contains 48454C4C4F.
var Specifies a variable to receive input.
[,length] Specifies an expression of the number of char-
acters to wait for input from the attached line.
The default is one character, unless you use
UNTIL in the statement.
[SETTING count.var] The SETTING clause assigns the variable
count.var to the number of characters from the
attached line.
FROM line.expr FROM line.expr is an expression evaluating to
the attached line receiving input.
[UNTIL term.expr] UNTIL term.expr is an expression of a string
of characters. The system accepts any of the
characters as a terminating character for the
accepted input. The terminating character does
not appear in the returned text variable. If you
use UNTIL and do not explicitly specify a
term.expr, there is no limit to the number of
characters.
Characters often used for the UNTIL clause are
carriage return (CHAR(13)) and line feed
(CHAR(10)).
GET Parameters
171
GET
[RETURNING term.var] The RETURNING clause assigns the character

which terminates the input to the variable
term.var. The input terminates due to: reaching
the maximum number of characters, a time-out
condition, or if the system reads a record mark
(CHAR(255)). If the system reads a record
mark, the variable term.var contains the null
string.
[WAITING seconds] The WAITING clause specifies the number of
seconds to wait before the system times out.
[{THEN | ELSE} If the line is not attached, the system performs
statements] the ELSE clause. If the line is not attached and
there is not an ELSE clause. A runtime error
displays and you enter the UniBasic debugger.
GET Parameters (continued)
Examples
In the following example, the program segment waits 15 seconds for ten characters of
input from line 0. If time expires before you enter the ten characters, the system
returns the input up to that point and performs the ELSE clause.
GET TMP,10 FROM 0 WAITING 15
ELSE PRINT "Input time has expired"
Related Topics
SEND
The UniBasic SEND command sends output data to a specified line.
PROTOCOL
The ECL PROTOCOL command sets data line transmission characteristics and proto-
cols for a specified line. For information on PROTOCOL, refer to UniData
Commands Reference.
172
GETCOLUMNDATA
GETCOLUMNDATA
Syntax
GETCOLUMNDATA var FROM connection, col.no [ON ERROR statements]
Description
The UniBasic GETCOLUMNDATA statement retrieves the data in the specified col-
umn in the current row of the current result table.
STATUS
After the execution of the GETCOLUMNDATA statement, STATUS is set to one of
the following:
0 Success
2 The position is out of bounds
3 Other error
GETCOLUMNDATA Command STATUS Values
Parameters
var The variable name in which to store the data.

FROM connection Specifies the handle to a server you specified with
the CONNECT command.
GETCOLUMNDATA Parameters
173
GETCOLUMNDATA
col.no The column number of the current table to retrieve

data from.
[ON ERROR The ON ERROR clause allows the program to con-
statements] tinue to perform if the GETCOLUMNDATA state-
ment fails. It then executes the statements you
specify.
GETCOLUMNDATA Parameters (continued)
174
GETCOLUMNNAME
GETCOLUMNNAME
Syntax
GETCOLUMNNAME var FROM connection, col.no [ON ERROR statements]
Description
The UniBasic GETCOLUMNNAME statement retrieves the column name for the
specified column of the result table.
STATUS
After the execution of the GETCOLUMNNAME statement, STATUS is set to one of
the following:
0 Success
2 The position is out of bounds
3 Other error
GETCOLUMNNAME Command STATUS Values
Parameters
var The variable name in which to store the column

name.
FROM connection Specifies the handle to a server you specified with the
CONNECT command.
GETCOLUMNDNAME Parameters
175
GETCOLUMNNAME
col.no The column number of the current table to retrieve the

column name from.
statements] tinue to perform if the GETCOLUMNNAME state-
specify.
GETCOLUMNDNAME Parameters (continued)
176
GETENV
GETENV
Syntax
GETENV(var | “envir.var”)
Description
The UniBasic GETENV function returns the contents of the UNIX environmental
variable or VMS logical name. If the environmental variable appears explicitly, you
must enclose it in quotation marks.
Examples
In the following example, the program statement retrieves the value in UDTBIN into
the variable X.
X = GETENV("UDTBIN")
In the next example, the program retrieves the value in UDTBIN into variable X using
a variable to define UDTBIN.
VAR = "UDTBIN"
X = GETENV(VAR)
177
GETERRMSG
GETERRMSG
Syntax
GETERRMSG()
Description
The UniBasic GETERRMSG function returns the error message from the server
when a UniBasic statement fails. When a UniBasic statement that is part of a remote
execution fails, the GETERRMSG function returns the complete text of the error mes-
sage from various sources, depending on the error.
178
GETLIST
GETLIST
Syntax
GETLIST list.name [,acct.name] [TO list.num]
[SETTING count.var] {{THEN | ELSE} statements [END]}
Description
The UniBasic GETLIST command creates an active select list from a saved list cre-
ated either by an ECL SAVE.LIST command or the UniBasic WRITELIST com-
mand.
Use GETLIST to access a list without having to issue multiple SELECT or

Tip SSELECT commands.
GETLIST requires a THEN or an ELSE clause. The system requires an END state-
ment when you use THEN or ELSE with multiple lines.
Parameters
list.name Specifies the source list.

acct.name Specifies a full UNIX or VMS path name of a
directory where the list resides, if list.name is
not in the current account.
TO list.num Specifies the active list you generate. list.num
can be 0 through 9. The default list is zero.
[SETTING count.var] Specifies a variable to contain the number of
elements the GETLIST command generates.
{THEN | ELSE} Specifies statements to execute if the command
statements succeeds (THEN) or fails (ELSE).
GETLIST Parameters
179
GETLIST
Examples
In the following example, the program segment retrieves the previously saved list
CS_STAFF and assigns it to active list 2. If the list isn’t found, the program aborts and
displays an error message.
GETLIST "CS_STAFF" TO 2 ELSE
ABORT "NO CS_STAFF saved list found."
In the next example, the program segment retrieves the saved list CUST to active list 0
(the default). The number of elements in CUST is assigned to the count variable
LIST.CNT. The program then uses the IDs in list 0 to retrieve the records in the
CUSTOMER file.
OPEN ’’, "CUSTOMER" TO CUST ELSE ABORT
X = "CUST"
GETLIST X SETTING LIST.CNT
ELSE PRINT X:" CAN NOT BE FOUND";STOP
FOR I = 1 TO LIST.CNT
READNEXT ID ELSE EXIT
READ REC FROM CUST, ID THEN
PRINT REC
END ELSE
PRINT "CANNOT FIND RECORD":ID
END
NEXT I
END
180
GETNEXTTUPLE
GETNEXTTUPLE
Syntax
GETNEXTTUPLE var FROM connection [{THEN | ELSE} statements]
[ON ERROR statements]
Description
The UniBasic GETNEXTTUPLE command retrieves the current row (tuple) of the
result table. When you retrieve a row, your position in the table is changed to the next
row.
STATUS
After the execution of the GETNEXTTUPLE statement, STATUS is set to one of the
following:
0 Success
2 Other error
GETNEXTTUPLE Command STATUS Values
Parameters
var The variable name in which to store the row.

FROM connection Specifies the handle to a server you specified with the
CONNECT command.
GETNEXTTUPLE Parameters
181
GETNEXTTUPLE
[{THEN | ELSE} Specifies statements to execute if the command suc-

statements] ceeds (THEN) or fails (ELSE).
statements] tinue to perform if the GETNEXTTUPLE statement
fails. It then executes the statements you specify.
GETNEXTTUPLE Parameters (continued)
182
GETPTR
GETPTR
Syntax
GETPTR(unit.no)
Description
The UniBasic GETPTR function returns a string variable containing the values of the
current printer settings for the unit.no specified.
GETPTR can store the values associated with a print unit so those values can
Tip be reset to their initial values at the end of a process.
The GETPTR function returns a string containing the same set of values as specified
in the SETPTR function, including the print unit and the options:
unit,line,page,top.mar,bot.mar,mode,options.
STATUS
The following table describes the value the STATUS function returns after the GET-
NEXTTUPLE statement executes.
Value Description
0 If success.
1 If there are no more rows.
2 Other error.
GETNEXTTUPPLE Command STATUS Values
Examples
In the following example, the program segment assigns the printer settings to the vari-
able PRINTER.STRING.
PRINTER.STRING = GETPTR(1)
183
GETPTR
Related Topics
SETPTR
The ECL SETPTR command sets the options for a logical printer. For information on
SETPTR, refer to UniData Commands Reference.
184
GETPU
GETPU
Syntax
GETPU(unit.number)
Description
The UniBasic GETPU function returns the full path of the current print or hold file ID
you just created. unit.number is the number of the logical printer unit.
Use the ECL SETPTR command to determine the current printer unit of your
Tip system.
Related Topics
SETPTR
The ECL command SETPTR sets options for the logical printer unit. For more infor-
mation on SETPTR, refer to UniData Commands Reference.
185
GETREADU
GETREADU
SYNTAX
GETREADU( )
DESCRIPTION
The UniBasic function GETREADU returns a dynamic array containing information
about all records that have been locked by any UniBasic command or ECL command
that updates any record.
This command delivers the same information—but, in a different format—that the
ECL command LIST.READU delivers. A value mark separates these pieces of infor-
mation. An attribute mark separates the information about different locks. The number
of locks is returned in @SYSTEM.RETURN.CODE.
The following table describes the values GETREADU returns:
Value Description
UDTNO The UniData number of the UniData process

that locked the file.
USERNBR The user number of the user who ran the
UniData application that locked the file.
UID The user ID of the user who ran the UniData
apllication that locked the file.
USERNAME The user name of the user who ran the UniData
apllication that locked the file.
TTY The terminal of the user who ran the UniData
application that locked the file.
FILE NAME The name of the locked file.
INBR The inode number used by the locked file.
DNBR The device number used by the locked file.
RECORD ID The ID of the record in the file that is being
updated.
MODE The mode of the command that locked the file.
Values Returned by GETREADU
186
GETUSERNAME
GETUSERNAME
Syntax
GETUSERNAME(uid)
Description
The UniBasic GETUSERNAME function returns the UNIX or VMS user name for
the user ID you specify by uid. Use the UniBasic @UID variable to obtain the UNIX
user ID or enter “id” at the UNIX level. Once you obtain the UNIX user ID, you can
specify the user ID explicitly by using the GETUSERNAME function.
Examples
In the following example, the program statement assigns the user name in variable X.
X = GETUSERNAME(@UID)
In the next example, the program statement assigns the user name for 1023 in variable
X.
X = GETUSERNAME(1023)
Related Topics
GETUSERGROUP
The UniBasic GETUSERGROUP function returns the UNIX or VMS group number
for the user ID you specify.
@variables
187
GETUSERGROUP
GETUSERGROUP
Syntax
GETUSERGROUP(uid)
Description
The UniBasic GETUSERGROUP function returns the UNIX or VMS group number
for the user ID you specify by uid.
Examples
In the following example, the program statement assigns the user group in variable X.
X = GETUSERNAME(@UID)
In the next example, the program statement assigns the user group for 1023 in variable
X.
X = GETUSERNAME(1023)
Related Topics
GETUSERNAME
The UniBasic GETUSERNAME function returns the UNIX or VMS user name for
the user ID you specify.
@variables
188
GOSUB
GOSUB
Syntax
GOSUB label[:]
Description
The UniBasic GOSUB command transfers program control to an internal subroutine.
The system requires a valid statement label. Control returns to the main program by a
RETURN statement in the subroutine.
Note You must terminate all non-numeric statement labels with a colon ( : ). This
differentiates non-numeric labels from variables.
Examples
In the following example, the program statement transfers program control to the sub-
routine starting at label YESNO:.
GOSUB YESNO:
In the next example, the program segment prints “Now we go to the subroutine.”,
“Now in subroutine BRANCHOUT.”, and finally, “Back from subroutine BRAN-
CHOUT.”
PRINT "Now we go to the subroutine."
GOSUB BRANCHOUT:
PRINT "Back from subroutine BRANCHOUT."
STOP
BRANCHOUT:
PRINT "Now in subroutine BRANCHOUT."
RETURN
END
Related Topics
ON/GOSUB
The UniBasic ON/GOSUB command transfers program control to a subroutine based
on a numeric expression.
RETURN
189
GOSUB
Program Constructs
For more information on program constructs, refer to Developing UniBasic
Applications.
190
GOTO
GOTO
Syntax
GOTO label [:]
GO label [:]
Description
The UniBasic GOTO command branches unconditionally to a statement label within
a program or subroutine. A statement label must exist in the program or subroutine. If
the label you specify does not exist, the compiler generates an error message and the
program aborts. Once a program executes a GOTO, it does not keep track of the point
of departure, but simply moves to the new statement and begins executing there.
Note You may not use the UniBasic RETURN command in conjunction with a
GOTO statement.
Examples
In the following example, the program statement transfers program control to the
statement label 2510.
GOTO 2510
In the next example, the program statement transfers control to the statement label
“START:”, if the variable RETRY is true.
IF RETRY GOTO START:
Related Topics
GOSUB
The UniBasic GOSUB command transfers program control to a specified internal sub-
routine.
ON/GOTO
ON/GOSUB
191
GOTO
Program Constructs
For information on program constructs, refer to Developing UniBasic Applications.
192
GROUP
GROUP
Syntax
GROUP(str, delim, start, rtn.num)
Description
The UniBasic GROUP function extracts a number of continuous groups you specify
from the given string.
GROUP functions similar to option G of the OCONV function (group extraction con-
version), but allows any single character, including a system delimiter, numeric, or
minus sign (-) as a delimiter. Another difference is the start parameter of the GROUP
function specifies the starting group to return, while OCONV specifies the number of
leading groups to skip.
Parameters
str Specifies the string from which to extract

groups.
delim Specifies any ASCII character that delimits
groups in the string.
start Specifies the first of the groups to return.
rtn.num Specifies the number of continuous groups
included in the result.
If the rtn.num is greater than the number of
groups remaining in the string, the function fin-
ishes after the whole remaining string is
exhausted.
GROUP Parameters
Examples
In the following example, the program statement assigns “1231” to the variable A.
A = GROUP("123124125126","2",1,2)
193
GROUP
In the next example, the program segment prints “Boulder” since it is the second
group separated by ‘:’ and only one group is required to be returned.
ST = "Denver:Boulder:Aurora:Littleton"
PRINT GROUP(ST,‘:’,2,1)
Related Topics
FIELD
OCONV
The UniBasic OCONV function converts string or numeric data from internal repre-
sentation format to output format based on conversion codes.
194
GROUPSTORE
GROUPSTORE
Syntax
GROUPSTORE substr IN str USING start.num,replace.num [,delim]
Description
The UniBasic GROUPSTORE command inserts a given substring, or a portion of a
substring into a string replacing all, part, or none of the string. The unit of replacement
is called an “element.” This may be delimited by the single character delimiter.
Parameters
substr Specifies the string you want to insert into the

string. substr can contain a combination of any
number of numeric, alphabetic, or special
characters.
str Specifies the string into which to insert substr.
start.num Specifies the position from which to begin
replacing elements of the string. start.num
must at least be one. If it is less than one,
UniBasic defaults to one. If start.num is nega-
tive and replace.num is not negative, UniBasic
uses the absolute value of start.num.
If start.num is greater than the number of ele-
ments in the string, UniBasic appends the
substr to the end of the string with the appro-
priate number of delimiters in between.
replace.num Specifies the number of elements in the string
you want to replace with elements of substr.
Refer to the next table for values replace.num
can have.
GROUPSTORE Parameters
195
GROUPSTORE
[,delim] Specifies a single ASCI I character to use as a

delimiter. If you do not specify delim, the
default delimiter is @AM. If you specify more
than one character for delim, UniBasic only
recognizes the first character.
GROUPSTORE Parameters (continued)
The replace.num option controls whether GROUPSTORE replaces all, part, or none
of the substring. The following table describes these options:
Value Description
>0 The first replace.num elements of the substr replace ele-

ments of the string starting from the position specified by
start#. If the string contains fewer than replace.num ele-
ments starting from start.num, the replacement stops after
the string is exhausted.
0 The whole substr inserts before the start.num position in
the string.
<0 replace.num elements of substr delete starting at start#,
and the entire substr inserts at this position.
If both start.num and replace.num are less than zero,
replacement takes does not take place; only replace.num
elements in the string delete starting at start.num.
GROUPTSTORE Replace Number Values
Examples
In the following example, the program segment assigns the value of SUB in the string
A. Since the starting number is 2 and you do not specify a delimiter, the system uses
the attribute mark (@VM) as the delimiter.
A = "123":@AM:"ABC":@AM:"456":@VM:"DEF":@AM:"012":@VM:"GHI"
SUB = "***"
GROUPSTORE SUB IN A USING 2,1
This results in:

A = "123":@AM:"***":@AM:"456":@VM:"DEF":@AM:"012":@VM:"GHI"
196
GROUPSTORE
In the next example, the program segment replaces the third attribute in A, which
includes two values, with SUB. Though the replace number is 2, the system replaces
only one attribute since there is only one element in SUB.
SUB = "###"
This results in:

A = "123":@AM:"ABC":@AM:"###":@AM:"012":@VM:"GHI"
In the next example, the program segment inserts SUB before position 1 in A.
SUB = "begin"
This results in:

A = "begin":@AM:"123":@AM:"ABC":@AM:"456":@VM:"DEF":
@AM:"012":@VM:"GHI"
In the next example, the program segment replaces the first two attributes and their
associated subvalues with SUB using @VM as the delimiter.
SUB = "mv1":@VM:"sub1":@SM:"sub2":@VM:"mv2"
GROUPSTORE SUB IN A USING 1,2,@VM
This results in:

A = "mv1":@AM:"sub1":@AM:"sub2":@VM:"GHI"
197
GT
GT
Syntax
expr1 GT expr2
Description
The UniBasic GT function tests whether the expression expr1 is greater than expr2.
expr1 and expr2 may be any valid expression, variable, or string.
Examples
In the following example, the program segment tests whether A is greater than B.
Since A is greater than B, the message “Greater Than” prints.
A = 24
B = 22
IF A GT B THEN
PRINT "Greater Than"
END ELSE
PRINT "Less Than"
END
198
GTS
GTS
Syntax
GTS(array1,array2)
Description
The UniBasic GTS function compares each value in array1 to its corresponding value
array1 is greater than the value in the corresponding position in array2, and a zero in
each position for values that are less than array2.
Examples
ARRAY1 = 10:@VM:20:@VM:30@VM:40:@VM:50
ARRAY2 = 9:@VM:10:@VM:30:@VM:50:@VM:60
ARRAY3 = GTS(ARRAY1,ARRAY2)
199
HASH
HASH
Syntax
HASH(rec.key,modulo,type)
Description
The UniBasic HASH function determines to which group a particular key is hashed
depending on the modulos and the type of the file. HASH returns the group number in
which a record with a key of rec.key is stored. HASH includes a file type parameter.
When rec.key, modulo, and type are passed to the function, it returns the group num-
ber to which the record key will hash.
Parameters
rec.key Specifies the record key to hash.

modulo Specifies the file modulo, the number of
groups specified when the file was created.
type Specifies the hash type specified when the file
was created.
HASH Parameters
Related Topics
CREATE.FILE
For more information on CREATE.FILE, refer to UniData Commands Reference.
200
HEADING
HEADING
Syntax
HEADING [ON expr] str.expr [“W”]
Description
The UniBasic HEADING command prints a string you specify at the top of all report
pages on the current print device.
Note The HEADING command clears the screen before displaying a report.
Parameters
[ON expr] Specifies to send the output to a print file expr.

As many as three print files may be active at
any one time with values between 0 and 254.
str.expr Specifies a string to print at the top of all report
pages.
[“W”] The W option causes a page to fill completely
before page breaking and printing the heading
when the HEADING statement is first encoun-
tered. If you do not specify W, the system cre-
ates a new page break when the system first
encounters the HEADING statement.
HEADING Parameters
HEADING Expressions
A heading string str.expr may contain codes that control paging characteristics and
insert the current time, date, or page number in the heading. The following table
describes these codes.
201
HEADING
Code Description
P or S Prints current page number.

N Suppresses the carriage return after each page of a screen
report.
L Advances one line (in multiline headings.)
D Prints date in MM-DD-YY format.
T Prints time/date in MM-DD-YY HH:MM:SS format.
C Centers the heading text.
G Forces the line to fill the width of the page.
HEADING Expressions Options
The code or codes must be surrounded by one pair of single quotes. You can place
codes anywhere in the heading expression.
You can use special characters, such as unmatched single and double quotes in
str.expr.
Examples
In the following example, the program statement sends a heading, “Shareholders
Report” with the current page number on the left and the current date on the right, to
print file 3.
HEADING ON 3 "’P’ Shareholders Report ’D’"
In the next example, the program statement prints the current page number and the
current date and time on the top of the default print device. The N code causes the
report to print continuously, not requiring a carriage return after each page.
HEADING "’PTN’"
This results in the following heading;

1207-21-91 12:13:00
202
HEADING
Related Topics
FOOTING
The UniBasic FOOTING command prints a string you specify at the bottom of all
report pages on the current print device.
203
HUSH
HUSH
Syntax
HUSH {ON | OFF | expr} [SETTING pre.status.var]
Description
The UniBasic HUSH command enables or disables terminal output.
Parameters
The following table describes the valid parameters:
{ON} Disables the terminal output.

{OFF} Enables the terminal output.
{expr} Disables the terminal output if expr evaluates to a non-zero
value. Enables the terminal output if expr evaluates to zero.
expr must evaluate to a numeric value.
[SETTING The SETTING clause sets the previous terminal status (1
pre.status.var] for ON and 0 for OFF) to pre.status.var.
HUSH Parameters
Examples
In the following example, the program segment prints 1 and -1 on the terminal screen
since the HUSH command enables the terminal (A + B evaluates to zero). The second
PRINT statement produces nothing on the screen since HUSH ON is set. The third
PRINT command prints C = 1 on the screen since the terminal output is enabled.
A = 1; B = -1
HUSH A + B
PRINT A,B
HUSH ON
PRINT A + B
HUSH OFF SETTING C
PRINT "C = ":C
204
ICONV
ICONV
Syntax
ICONV(expr,conv.code.expr)
Description
The UniBasic ICONV function converts string or numeric data to an internal repre-
sentation format based on conversion codes.
Parameters
expr Specifies the expression, a string or numeric

data, to convert.
conv.code.expr Specifies which internal representation format
to which to convert expr.
ICONV Parameters
The following table summarizes the valid conversion codes. Detailed discussions fol-
low under separate headings.
Code Format
D System date
MB Binary
MC Masked character
MD Masked decimal
ML Left justify
MP Packed decimal
MO Octal
ICONV Codes
205
ICONV
Code Format
MR Right justify
MT System time
MX Hexadecimal (also HEX)
ICONV Codes
ICONV D System date

The date (D) code converts external representations of dates into a simple integer
internal format. The conv.code.expr takes the following form:
D {y} {c} {E}
D indicates a date conversion. The ICONV function does not use y and c but they are
accepted to maintain consistency with the OCONV function. E indicates an interna-
tional format (DD,MM,YY) instead of the standard format (MM,DD,YY).
The internal form of the date takes the number 0 as December 31, 1967, and increases
by one for each day thereafter. Dates prior to this date are negative numbers.
Dates take many different formats:
mm dd yy or month day, year
The space between digits may be any delimiter symbol (slash, period, comma, aster-
isk, etc.). In the written format, month can be either a three-digit abbreviation (DEC)
or the month as a word. Day is the day of the month. Year can be either two or four
digits.
ICONV supports a more flexible type of date conversion. ICONV allows you to input
one or two digits to indicate the first day of the month of the current year. You may
also input three to four digits to indicate a certain day of a certain month.
Any year you enter before “30” will be considered for the next century. For example,
12/31/29 will be 12/31/2029.
Common Date Conversions

The following table describes common date conversions and their results.
Value Code Result
09/15/85 D 6468
206
ICONV
Value Code Result
12/31/67 D 0
December 31, 1967 D 0
31/12/67 DE 0
01/29/1988 D 7334
ICONV MB Binary, MO Octal, and MX Hexadecimal (also HEX)

The hex (MX), octal (MO), and binary conversion codes converts data in different
bases into decimal format for internal representation. The following table describes
the different conv.code.expr.
Conversion Code Description
MX or HEX {0C} Hex (base 16) conversion

MO {0C} Octal (base 8) conversion
MB {0C} Binary (base 2) conversion
ICONV Base Conversion Codes
The MX, MO, and MB are the conversion codes you use with the appropriate str.expr.
The optional 0C indicates that you want the input data to be converted to an ASCII
code format. Using the 0C option may result in more than one ASCII character. Using
0C with binary results in taking each group of eight characters and converting to
ASCII. With octal, the system converts each group of three characters. With hex, the
system converts each group of two characters.
Input data must fall into the domain of the appropriate base. The following table
describes each domain.
Domain
Base
Numbers Letters
Hex 0-9 A-F

Octal 0-7
Base Domain
207
ICONV
Domain
Base
Numbers Letters
Binary 0-1
Base Domain
Note The system produces a run-time error message if either the value to be con-
verted or the conversion code is invalid.
ICONV MC Masked character

The masked character (MC) code has a variety of codes that provide many conversion
functions. The following table describes these codes.
Code Description
MCA Extracts only alphabetic values from the input string.

MC/A Extracts only non-alphabetic values from the input string.
MCB Extracts just the alphabetic and numeric values from the
input string.
MC/B Extracts just the characters that are neither alphabetic nor
numeric.
MCC;x;y Converts all occurrences of substring x to substring y in the
input string.
MCD[x] Converts the input hex value to its equivalent decimal
value.
MCL Converts data to lowercase characters.
MCN Extracts only the numeric values from the input string.
MC/N Extracts only the non-numeric values from the input string.
MCP Converts all non-printable characters in the input string to
tildes (~).
ICONV Masked Character Codes
208
ICONV
Code Description
MCT Converts all uppercase characters to lowercase starting

from the second character in each word. Changes the first
character of a word from lowercase to uppercase, if
necessary.
MCU Converts data to uppercase characters.
MCX[D] Converts the input decimal value to its equivalent
hexadecimal value.
ICONV Masked Character Codes (continued)
ICONV MD Masked decimal

The masked decimal (MD) code converts a decimal number to an integer. The str.expr
can be any numeric value with or without a decimal. The conv.code.expr has the fol-
lowing syntax:
MDn {f}
MDn is required and indicates a masked decimal conversion with n places past the
decimal point. n can be a number between 0 and 9. f is an optional scaling factor
between 0 and 9. If you do not specify f, the system assumes f is equal to n. The inter-
nal format produced is a simple integer number. If n is less than the number of digits
right of the decimal point, the resulting value is rounded before truncating excess dig-
its.
If the conversion to internal format is unsuccessful, the system returns the original
value.
ICONV ML Left justify

The left justify (ML) code left justifies text or a number. str.expr can be any valid text
or a numeric value with or without a decimal. The conv.code.expr has the following
syntax:
MLn {f}
MLn is required and indicates a left justify conversion of n places. n can be a number
between 0 and 9. f is an optional scaling factor between 0 and 9. If you do not specify
f, the system assumes f is equal to n. The internal format produced is a simple integer
number. If n is less than the number of digits right of the decimal point, the resulting
value is rounded before truncating excess digits.
value.
209
ICONV
ICONV MP Packed decimal

The packed decimal (MP) conversion code transforms an integer into a packed deci-
mal representation by compressing two digits of the integer into just one byte.
Use this function to save space.

Tip
ICONV MR Right justify
The right justify (MR) code right justifies a decimal number. str.expr can be any
numeric value with or without a decimal. The conv.code.expr has the following syn-
tax:
MRn {f}
MRn is required and indicates a right justify conversion of n places. n can be a number
between 0 and 9. f is an optional scaling factor between 0 and 9. If you do not specify
f, the system assumes f is equal to n. The internal format produced is a simple integer
number. If n is less than the number of digits right of the decimal point, the resulting
value is rounded before truncating excess digits.
value.
ICONV MT System time

The time (MT) code converts the time of day from an external format into an internal
format. The conv.code.expr follows the following format:
MT {H} {S} {c}
MT is required to indicate a time conversion. The remaining options are ignored but
are allowed to maintain consistency with the OCONV function. Time is assumed to be
in the following form:
HH MM SS
MM and SS are not required and if you do not specify them, UniData assumes the
value to be zero. The character separating each unit (HH, MM, SS) may be any non-
numeric character. The suffixes AM, PM, A, and P are also accepted at the end of the
string. The system hours are the same as standard hours, with 12PM as noon and
12AM as 00:00 or midnight. The value of the internal format is the number of seconds
since midnight, with 00:00:01 as 1 and 24 or 12PM as 86400.
ICONV Tfile File Translation

The file translation (Tfile) retrieves attributes from another file. The conv.code.expr
has the following syntax:
T{DICT} [filename;cn;I-Attribute;O-Attribute]
210
ICONV
where id.expr evaluates to an ID in the filename.

The following table describes the conversion code syntax:
Elements Description
T Code name.
DICT Translates to the dictionary of the file indicated by
filename.
filename Name of the file where the translation is directed (any
valid UniData file in your VOC file containing the
required attribute or data).
c One of the following translate subcodes:
V If the record does not exist or if the attribute is null,
returns a null value and prints an error message.
C If the record does not exist or attribute is null, it substi-
tutes id.epr for value of the function.
X If the record does not exist or the attribute is null, the
system returns a null.
n If an attribute is retrieved from a translated attribute and is
multivalued, it indicates which value to retrieve. If n is not
indicated, the system retrieves all values of the attribute.
I-Attribute Decimal number of the attribute to be retrieved during
input conversion (ICONV). If I-Attribute is omitted, 0 is
assumed and record ID is retrieved.
O-Attribute Decimal number of attribute to be retrieved during output
conversion (OCONV). If the O-Attribute is omitted, 0 is
assumed and the record ID is retrieved.
ICONV File Translation Conversion Code Elements
211
ICONV
Examples
ICONV D System date
In the following example, the program segment will print the converted date.
INPUT IN_DATE
INTERNAL = ICONV(IN_DATE,"D")
OUTPUT = OCONV(INTERNAL, "D4/")
PRINT IN_DATE,INTERNAL,OUTPUT
The following table describes various dates you can input in the previous program and
their conversions.
In_Date Internal Output
1 8402 01/01/1991
11 8706 11/01/1991
011 8402 01/01/1991
12 8736 12/01/1991
121 8736 12/01/1991
110389 8709 11/03/1989
1/1 8402 01/01/1991
1/1/89 8402 01/01/1989
1/1/02 12420 01/01/2002
Example Date Conversions
ICONV MB Binary, MO Octal, and MX Hexadecimal (also HEX)

The following table describes ICONV MX, MO, and MB conversion codes and their
results.
Input Code Result
123123123 MO0C SSS

171 MO0C y
D1E1F4 MX0C Qat
ICONV Hex, Octal, and Binary Examples
212
ICONV
Input Code Result
11010101 MB0C U
100 MX or HEX 256
101 MB 5
101010 MO 33288
ICONV Hex, Octal, and Binary Examples (continued)
ICONV MD Masked decimal

In the following example, the system converts the value 12.339 to 1234 based on the
MD3 internal conversion.
INTERNAL.VAL = ICONV("12.339","MD3")
ICONV ML Left justify

ML3 internal conversion.
INTERNAL.VAL = ICONV("12.339","ML3")
ICONV MR Right justify

MR3 internal conversion.
INTERNAL.NUM = ICONV("12.339","MR3")
ICONV MT System time

The following table describes the time conversion code and the resulting value.
Code
Value Result
Specification
12:30 MT 45000
12AM MT 0
12PM MT 43200
ICONV Time Examples
213
ICONV
Related Topics
OCONV
sentation format to output format based on conversion codes.
ICONV D System date and DATE.FORMAT

For information on the ECL DATE.FORMAT command, refer to UniData
Commands Reference.
ICONV D System date and STATUS

The STATUS function will be set for the date conversion. A value of 0 indicates a
successful conversion of a valid date, 1 indicates an invalid input date, 2 indicates an
invalid conversion specification, and 3 indicates a successful conversion of a possible
invalid date. For example, 12/31/67 converted with code “DE” returns a value of 563
and a STATUS of 3.
ICONV MP Packed decimal and OCONV

sentation format to output format based on conversion codes. The OCONV function
has an MP code that converts a packed decimal to an integer.
214
IF/THEN/ELSE
IF/THEN/ELSE
Syntax
IF expr THEN statements [ELSE statements]
IF expr THEN
statements...
END [ELSE
statements...
END]
IF expr ELSE statements
IF expr ELSE
statements
END
Description
The UniBasic IF/THEN/ELSE command executes one of two blocks of statements
based on a conditional expression. If expr is true, the system executes the first group
of statements. If the expression is false, the system executes the second group of state-
ments.
An IF/THEN/ELSE structure may occupy either a single line or several lines. In the
multi-line form, blocks of statements within the THEN and ELSE clauses are defined
by the use of END. In both cases, the ELSE clauses are optional. The THEN statement
must appear on the same line with the IF expression, however, the END ELSE state-
ment may appear on the same or subsequent lines.
The single line form does not require an END statement before the ELSE statements.
Each branch of an IF/THEN/ELSE structure must contain at least one statement. If
you do not want any action for a particular logical branch, you can use the NULL
statement. Each line of the statement may be followed by a comment.
Note The END statement may appear on the same line as the last statement of a IF
or THEN block of statements. It must be separated with a semi-colon.
Tip IF/THEN/ELSE statements may be nested; however it is usually preferable to

use a CASE statement.
215
IF/THEN/ELSE
Examples
In the following example, the program statement tests if the variable SUPPLY is less
than the variable DEMAND. If the comparison is true, program control is transferred
to the statement labeled REORDER.
IF SUPPLY < DEMAND THEN GOTO REORDER
In the next example, the program segment compares INCOME to TARGET; the sys-
tem executes the first branch if the comparison is true or executes the second group of
statements if the comparison is false.
IF INCOME < TARGET THEN
PRINT "Income less than target figure."
END ELSE
PRINT "Income equal to or greater than target!"
END
Related Topics
CASE
The UniBasic CASE command creates a series of conditional branches based on a
selection expression.
NULL
The UniBasic NULL command acts as a dummy statement, performing no actions.
216
IN
IN
Syntax
IN( )
Description
The UniBasic IN function captures raw data from the user’s terminal or from a data
queue.
IN may capture function, arrow, and other special keys from the keyboard.
Tip
Examples
In the following example, the program segment assigns the value of “y” to ANSWER.
DATA y
ANSWER = IN()
Related Topics
INPUT
The UniBasic INPUT command requests data fro the terminal or a data statement dur-
ing program execution.
217
INDEX
INDEX
Syntax
INDEX(str.expr1,str.expr2,num.expr)
Description
The UniBasic INDEX function returns the starting position of the num.expr occur-
rence of str.expr2 within str.expr1.
Parameters
str.expr1 Specifies the string to search.

str.expr2 Specifies the string for which to search in
str.expr1.
num.expr Specifies which occurrence of str.expr2 to
return.
INDEX Parameters
Examples
In the following example, the program segment searches STR.VAR for the second
occurrence of the letter “t” and returns that location, assigning it to the variable LOC.
In this example, the value that it returns is eight.
STR.VAR = "It was the best of times"
LOC = INDEX(STR.VAR,"t",2)
In the next example, the INDEX function operates like the COL() functions used in
conjunction with the FIELD function. It returns the beginning position of the string
“212” within the string variable STR. The result stored in the variable NY.STR is 15.
STR = "303-433-3199, 212-999-1212"
NY.STR = INDEX(STR,"212",1)
218
INDEX
Related Topics
COL1
COL2
219
INDICES
INDICES
Syntax
INDICES(file.var[, index.name.expr])
Description
The UniBasic INDICES function returns either the names of alternate key indices, or
returns information about a particular alternate key index.
Retrieving Alternate Key Indices Names

If you only specify file.var, the INDICES function returns a dynamic array containing
the alternate key index names for all indices in the file you specify. The index names
do not return in any particular order and index names are separated by attribute marks.
Note If the index you specify does not exist, the function returns a null string.
Retrieving Information About Indices

When you specify the name of an alternate key index (indexname.expr), the INDICES
function returns information about that index in a dynamic array.
The dynamic array generally consists of six attributes:
• Attribute 1 consists of four values representing the following information
(in the order given: type of key (I or D); build required (1 or null); (the
third value has no meaning); and automatic update enabled (1 or null).
• Attribute 2 indicates the location of the alternate key in the record.
• Attributes 3 contains an ASCII string with the timestamp of the last time
the index was built (updated by BUILD.INDEX).
• Attributes 4 and 5 are empty.
• Attribute 6 contains “S” for singlevalued attributes or “M” for multival-
ued attributes and “MS” for multi-subvalued attributes.
220
INDICES
Parameters
file.var Specifies the file about which to return indice

information.
[, index.name.expr] Specifies a specific alternate key index about
which to return information.
INDICES Parameters
221
INMAT
INMAT
Syntax
INMAT( )
INMAT(matrix.name)
Description
The UniBasic INMAT function, in the first form, returns the number of elements in a
matrix. The second form returns the current dimension of matrix.name. If the array
has two dimensions, the bounds are separated by value marks.
After you open a file, the value of INMAT is set to the modulos of the file. Subsequent
file operations using matrix commands changes the value of INMAT.
INMAT is automatically set by the matrix-oriented commands DIMENSION,
MATREAD, MATREADU, MATPARSE, SELECT and, OPEN statements.
Examples
In the following example, the program segment fills the matrix MAIN.MAT with val-
ues from REC. If there are enough elements in the matrix, the value of INMAT is set
to the number of elements filled. If the number of values exceeds the number of ele-
ments, and the 0 value of the matrix is filled (MAIN.MAT(0)), the value of INMAT is
set to 0.
MATPARSE MAIN.MAT FROM REC, @VM
PRINT INMAT()
In the next example, the program segment dimensions two arrays and then prints the
dimensions using the PRINT statement and INMAT function.
DIM LARGE.ARRAY(23,14)
DIM SMALL.ARRAY(9)
PRINT INMAT(LARGE.ARRAY)
PRINT INMAT(SMALL.ARRAY)
This results in:

23}14
9
222
INPUT
INPUT
Syntax
INPUT var [,expr [ _ ]] [:] [[FOR | WAITING time.expr] [UNFILTERED]
[{THEN | ELSE} statements]
INPUT var [,-l] [[FOR | WAITING time.expr] [UNFILTERED]
[{THEN | ELSE}statements]
Description
The UniBasic INPUT command requests data from a user or a DATA queue.
Only one variable can be read by each INPUT statement. If you enter Return only, the
variable is assigned a null value.
You can display a message to prompt the user for information by using a
Tip PRINT statement before an INPUT statement.
@SYSTEM.RETURN.CODE is set to -1 if an INPUT statement times out.
Parameters
var Specifies a variable to which to assign the

input. In the first form, if data (established by a
DATA statement) is present in a data queue,
INPUT assigns the next value to the variable
var. If a DATA statement was not executed,
INPUT prompts you to enter the named
variable at the terminal.
INPUT Parameters
223
INPUT
[,expr [ _ ]] Specifies the maximum length of user input.

This value limits the number of characters that
will be assigned to the variable var. If the expr
is followed by an underscore (_), the program
waits for the user to enter a Return before pro-
cessing the information. If the underscore does
not follow the expr parameter, the system per-
forms an automatic Return when the specified
number of characters is entered.
[:] Normally when an INPUT statement displays a
prompt and the user types something and
presses Enter, UniData issues a linefeed. The :
parameter inhibits this line feed.
[,-l] If you use the -1 parameter, the system checks
if there are characters in the type ahead buffer.
If characters are present in the input buffer, the
value one (1) is assigned to var.
[[FOR | WAITING Specifies a time to wait for input. If the input is
time.expr] not completed by the time time.expr expires,
var is not changed and INPUT executes the
ELSE clause.
[UNFILTERED] The UNFILTERED parameter sets INPUT to
return raw characters (i.e., backspace, up
arrow, down arrow, Return, etc.) from the
keyboard.
[{THEN | ELSE} Specifies statements to execute if there is no
statements] input by the time specified by the
FOR|WAITING clause.
INPUT Parameters (continued)
Use the underscore parameter to allow the user to use the backspace key even
Tip when the maximum specified input length is reached, (i.e., if you specify
“INPUT X,5_” and the users has entered five characters, the user can use the
backspace key to modify the entry).
Use the -1 parameter when you want to periodically check for a command an
Tip application should act upon, in an application which runs continuously.
224
INPUT
Examples
In the following example, the program segment reads the first value established by the
DATA statement and assigns it to the variable TEST, in this case, the value 10.
DATA 10,20,30,40,50
INPUT TEST
In the next example, the program statement prints the prompt, “Enter name:”. The
INPUT statement then allows the user to enter any number of characters, stopping
only when the user presses Return. The first ten characters that the user enters are
assigned to the variable NAME.
PRINT "Enter name: "; INPUT NAME,10_
In the next example, the program segment tests if the terminal type ahead buffer con-
tains any characters. If the variable S.FLAG is assigned the value zero, the buffer is
empty; if it is assigned one, the buffer contains characters. In this case, if characters
have been entered, the system prints the current value of RECS.PROCESSED. The
variable S.FLAG does not contain the characters echoed at the terminal, only a 0
or a 1.
INPUT S.FLAG,-1
IF S.FLAG THEN PRINT RECS.PROCESSED
In the next example, the user has 30 seconds to input data, otherwise the program
prints, “No input within 30 seconds.”
INPUT ANSWER FOR 30
ELSE PRINT "No input within 30 seconds."
Related Topics
INPUT @
The UniBasic INPUT @ command requests data from the terminal or a data statement
at a specific location on the screen.
INPUTERR
The UniBasic INPUTERR command displays a specified error message at the bottom
line of a user’s terminal.
INPUTTRAP
The UniBasic INPUTTRAP command checks for a particular character or characters
in the input, and then branches according to the specified criteria.
225
INPUT
INPUTNULL
The UniBasic INPUTNULL command defines a single character as the null character
in an INPUT @ statement.
DATA
The UniBasic DATA command creates a data queue to be read by subsequent INPUT
statements.
SYSTEM(14)
The SYSTEM(14) function returns the number of type ahead characters in the buffer.
IN
The UniBasic IN function captures raw data from a keyboard or data queue.
226
INPUT @
INPUT @
Syntax
INPUT @ (col,row) [ , | : ] var [,length] [ _ ] [mask]
[{THEN | ELSE} statements ]
Description
The UniBasic INPUT @ command requests data from a user or a DATA queue and
determines the characteristics and location of the input data.
@SYSTEM.RETURN.CODE is set to -1 if an INPUT statement times out.
Parameters
col Specifies the column on the screen where the data is

input.
row Specifies the row on the screen where the data is
input.
[:] Normally when an INPUT statement displays a
prompt and the user types someting and presses
Enter, UniData issues a linefeed. The : parameter
inhibits this lne feed.
var Specifies a variable to which to assign the input data.
[,length] Specifies the maximum length of the input charac-
ters.
[_] An underscore ( _ ) confirms the input length before
returning to the next statement.
[mask] Specifies a format or conversion mask.
INPUT @ Parameters
227
INPUT @
[{THEN | ELSE} Specifies statements to perform if the ECL TIME-

statements] OUT command is invoked during the input process.
If there is no ELSE clause in the statement, the user
is logged out to the system level.
Use THEN if the input variable contains at least one
character. Use ELSE if the input variable contains a
null string.
INPUT @ Parameters (continued)
Related Topics
INPUT
The UniBasic INPUT command requests data from the terminal or a data statement
TIMEOUT
For information on the ECL TIMEOUT command, refer to UniData Commands
Reference.
228
INPUTERR
INPUTERR
Syntax
INPUTERR error.expr
Description
The UniBasic INPUTERR command displays an error message at the bottom line of
the user’s terminal. error.expr can be any valid UniBasic statement including a literal
string enclosed in quotation marks.
Tip You can use INPUTERR to prompt for errors when entering data with an
INPUT statement.
You may erase any previous error messages printed on the bottom line of the screen
created by the INPUTERR statement when you execute another INPUT statement.
The user program must control the movement of the cursor so that it does not enter the
bottom line.
Note INPUTERR sends output to the screen regardless of the PRINTER on/off sta-
tus.
Examples
In the following example, the program segment prints an error message at the bottom
of the screen if you do not input the data correctly.
PRINT @(-1)
PRINT @(5,5):’Hourly Wage’
LOOP
PRINT @(16,5)
INPUT HOURLY.WAGE
UNTIL HOURLY.WAGE MATCHES ’1NON.2N’
INPUTERR ’Hourly wage must be entered as x.xx’
REPEAT
PRINT @(5,7):’Accepted.’
END
Related Topics
INPUT
The UniBasic INPUT command requests data from the terminal or a data statement
229
INPUTIF
INPUTIF
Syntax
INPUTIF var [[THEN | ELSE] statements]
Description
The UniBasic INPUTIF command retrieves input from the type ahead buffer and
assigns the input to a variable.
Parameters
var Specifies the variable to which to assign the

input data.
[[THEN | ELSE] Specifies statements to perform if there is no
statements] data in the type ahead buffer and the variable is
not assigned (ELSE) or if there is data in the
type ahead buffer (THEN).
INPUTIF Parameters
230
INPUTNULL
INPUTNULL
Syntax
INPUTNULL ‘expr’
Description
The UniBasic INPUTNULL command defines a single character as the null character
in an INPUT @ statement. expr specifies any character as a null character and must be
enclosed with single quotation marks. The default null character is an underscore ( _ ).
Examples
In the following example, the pound sign (#) is set as the new null character.
INPUTNULL ’#’
231
INPUTTRAP
INPUTTRAP
Syntax
INPUTTRAP string.expr GOTO label [:] [,label [:]]
INPUTTRAP string.expr GOSUB label [:] [,label [:]]
Description
The UniBasic INPUTTRAP command sets a trap for a particular character or charac-
ters in a program. INPUTTRAP allows you to specify characters which, if entered at
an INPUT @ statement, will branch to another statement label. For information about
the GOTO and GOSUB commands, refer to the entries in this manual.
To set a trap for an uppercase and a lowercase character, use the following:
Tip
INPUTTRAP ’Aa’ GOTO 10,10
Parameters
string.expr Specifies the expression upon which to branch

to another statement label.
label Specifies the GOTO or GOSUB label to which
to branch.
INPUTTRAP Parameters
Examples
In the following example, the program statement will branch to label ASUB if you
enter H or the statement will branch to label BSUB if you enter B.
INPUTTRAP ’HB’ GOTO ASUB,BSUB
INPUT@ (10,10) VALUE
232
INPUTTRAP
Related Topics
INPUT@
The UniBasic INPUT @ command requests data from the terminal or a data statement
at a specified location on the screen.
233
INS
INS
Syntax
INS expr BEFORE dyn.array<attrib.expr[,val.expr [,subval.expr]]>
Description
The UniBasic INS command inserts an expression, with the appropriate delimiter,
before the attribute, value or subvalue mark you specify in a dynamic array.
Parameters
expr Specifies an expression to insert.

dyn.array Specifies a dynamic array and attribute, value,
<attrib.expr or subvalue of that dynamic array, at which to
[, val.expr insert the expression. If any one of the
[,subval.expr]]> attribute, value, or subvalue expressions evalu-
ates to -1, the system inserts the expr as the last
element in the array position.
INS Parameters
Examples
In the following example, the program segment inserts Zelda with a new attribute
mark before the second attribute.
ARRAY = "H.L. Mencken":@AM:"John":@AM:"Mary"
INS "Zelda" BEFORE ARRAY<2>
This results in:

ARRAY = "H.L. Mencken":@AM:"Zelda":@AM:"John":@AM:"Mary"
In the next example, the program segment inserts Stephen at the end of the array since
val.expr is -1.
ARRAY = "Carmen":@AM:"Sally":@AM:"Billy":@AM:"Mark"
INS "Stephen" BEFORE ARRAY<-1>
234
INS
This results in:

ARRAY="Carmen":@AM:"Sally":@AM:"Billy":@AM:"Mark":@AM:"Stephen"
235
INSERT
INSERT
Syntax
INSERT(dyn.array.expr,attrib.expr,val.expr, subval.expr, insert.expr)
Description
The UniBasic INSERT function inserts an expression (with its delimiter), before or
after the specified attribute, value, or subvalue mark in a dynamic array.
There is no short form for the INSERT function; however, you may append
Tip data using the short version of the REPLACE function.
Parameters
dyn.array.expr, Specifies a dynamic array and attribute, value, or sub-

attrib.expr, value of that dynamic array, at which to insert the
val.expr, expression. If any one of the attribute, value, or sub-
subval.expr, value expressions evaluates to -1, the system inserts the
string after the position you indicate. If the value or sub-
value expressions are 0, the system inserts the string at
the next highest delimiter level (at the attribute level if
val.expr is 0 or at the value level if subval.expr is 0). If
the location expressions are positive, the system inserts
the string before any other data.
insert.expr Specifies the string you want to insert.
INSERT Parameters
Examples
In the following example, the program statement inserts HARRY at the end of the val-
ues in attribute 2.
STR = INSERT(STR,2,-1,0,’HARRY’)
In the next example, the program statement inserts HARRY in the first value of
attribute 2.
STR = INSERT(STR,2,1,0,’HARRY’)
236
INSERT
In the next example, the program statement inserts HARRY in the first subvalue of the
first value of attribute 2.
STR = INSERT(STR,2,1,1,’HARRY’)
In the next example, the program segment inserts Alias in the second attribute posi-
tion.
ARRAY = "#111":@AM:"Jones":@AM:"Smith"
ARRAY2 = INSERT(ARRAY,2,0,0,"Alias")
After the execution of the above example:

ARRAY2 = "#111":@AM:"Alias":@AM:"Jones":@AM:"Smith"
Related Topics
Dynamic Arrays
For information on dynamic arrays, refer to Developing UniBasic Applications.
DELETE
The UniBasic DELETE command deletes a record from a file.
INS
The UniBasic INS command inserts data before a attribute, value, or subvalue mark in
a dynamic array.
FIELDSTORE
The UniBasic FIELDSTORE function replaces, inserts, or deletes substrings within a
character string.
237
INT
INT
Syntax
INT(num.expr)
Description
The UniBasic INT function returns the integer value of numeric expression num.expr.
Note This function does not round num.expr, but truncates the argument to its inte-
ger part.
Examples
In the following example, the program segment prints 1, the integer part of the number
1.734.
A = 1.734
PRINT INT(A)
238
ITYPE
ITYPE
Syntax
ITYPE(itype.expr)
Description
The UniBasic ITYPE function allows a UniBasic program to access a UniData virtual
attribute from the dictionary of a UniData file. You must compile the function using
the COMPILE.DICT command. The value of the function is the same as if it were run
using UniQuery or UniData SQL.
ITYPE generally requires that both the dictionary and data portion of the file are open.
The @ID and @RECORD variables must also be assigned. These variables resolve
the value of the ITYPE function. If neither the ID of the file nor data from the record
are used in the ITYPE, you do not need to assign them.
Note Conversion or formatting codes in the dictionary record of the virtual attribute
you are using does not affect the value ITYPE returns.
Examples
The following virtual attribute exists in the dictionary file of UniData’s CUSTOMER
file.
YTD.SALES:
V
SUM(MONTHLY.SALES)
MD2
Annual Sales
12R2,$
M
The following program segment opens both the CUSTOMER file and the dictionary
of the CUSTOMER file, then reads the compiled virtual attribute into a value called
YTD.SALES. After prompting for a customer ID and reading the record, you can then
evaluate the virtual attribute by using the ITYPE function (in this case it performs a
summation on the value of MONTHLY.SALES in the @RECORD). Note that an
internal OCONV function converts the amount to an output format for display pur-
poses. The conversion and format functions in the dictionary item will not work.
239
ITYPE
OPEN ",‘CUSTOMER’ TO CUSTOMER ELSE STOP ‘NO CUST’

OPEN ‘DICT’,‘CUSTOMER’ TO DICT.CUST ELSE STOP ‘NO DICT’
READ YTD.SALES FROM DICT.CUST,‘YTD.SALES’ ELSE
PRINT ‘DICTIONARY ITEM YTD.SALES NOT FOUND’
STOP
END
LOOP
PRINT ‘Enter the Customer Number ’:
INPUT CUST.ID
WHILE CUST.ID DO
@ID = CUST.ID
READ @RECORD FROM CUSTOMER,CUST.ID ELSE
PRINT ’CUSTOMER NOT FOUND’
@RECORD = ’’
END
IF @RECORD THEN
TOT.AMT = ITYPE(YTD.SALES)
TOT.AMT = OCONV(TOT.AMT,‘MD2,$’)
PRINT "Customer’s annual sales are ":TOT.AMT
END
REPEAT
Related Topics
Virtual Attributes
For information on virtual attributes, refer to Using UniData.
@variables
240
LE
LE
Syntax
expr1 LE expr2
Description
The UniBasic LE function tests whether the expression expr1 is less than or equal to
expr2.
expr1 and expr2 may be any valid UniBasic expression, variable or string.
Examples
In the following example, the program segment tests whether A is less than or equal to
B. Since A is less than B, the message “Less Than or Equal To” prints.
A = 21
B = 22
IF A LE B THEN
PRINT "Less Than Or Equal To"
END ELSE
END
241
LES
LES
Syntax
LES(array1,array2)
Description
The UniBasic LES function compares each value in array1 to its corresponding value
array1 is less than or equal to the value in the corresponding position in array2, and a
zero in each position for values that are greater than array2.
Examples
ARRAY1 = 9:@VM:10:@VM:30:@VM:50:@VM:60
ARRAY2 = 10:@VM:20:@VM:30@VM:40:@VM:50
ARRAY3 = LES(ARRAY1,ARRAY2)
242
LEN
LEN
Syntax
LEN(str.expr)
Description
The UniBasic LEN function returns the length of character expression str.expr.
Examples
In the following example, the program segment displays 14, the length of the string
NAME.
NAME = "Arthur Fiedler"
PRINT LEN(NAME)
Related Topics
Applications.
243
LENS
LENS
Syntax
LENS(dyn.array)
Description
The UniBasic LENS function returns the length of the values within each element of
the dynamic array dyn.array in characters.
Examples
In the following example, the program segment creates a new array ARRAY1, which
contains the length of each element of ARRAY.
ARRAY = ’1’:@VM:’22’:@VM:’333’:@VM:’4444’:@VM:’55555’
ARRAY1 = LENS(ARRAY)
ARRAY1 now contains 1}2}3}4}5.
Related Topics
Applications.
244
LN
LN
Syntax
LN(num.expr)
Description
The UniBasic LN function returns the natural base logarithm of numeric expression
num.expr. This function is the inverse of the EXP function.
Examples
In the following example, the program statement assigns the natural logarithm of 12 to
the variable VAL. The result is 2.4849.
VAL = LN(12)
Related Topics
EXP
The UniBasic EXP function returns a value in exponential form.
245
LOCATE
LOCATE
Syntax
LOCATE expr IN dyn.array<attribute.expr [,val.expr [,subval.expr]]> [BY key.expr]
SETTING var [THEN statements END] ELSE statements END
Description
The UniBasic LOCATE command locates an expression within a dynamic array.
Note If you use the INSERT function to update sorted arrays, use the BY clause
with caution. The LOCATE statement using a BY clause in an unsorted array
can cause unpredictable results. For example, the following array:
"A":@VM:"B":@VM:"C"
causes the LOCATE statement to return an index value of 3 for inserting a ’D’.
Parameters
expr Specifies the expression you want to search for.

expr may be a variable, matrix element, function,
or literal string.
dyn.array Specifies a dynamic array and attribute, value, or
<attrib.expr subvalue of that dynamic array to search for the
[, val.expr expression.
[, subval.expr]]> If you do not specify a value or subvalue position,
the search starts at the lowest specified delimiter.
If the attribute number you specify is zero, the sys-
tem searches the entire array for the expression,
attribute by attribute.
If any of the search variables are negative, the sys-
tem assumes the values to be zero; except for
attributes where the system assumes a value of
one.
LOCATE Parameters
246
LOCATE
dyn.array If any search value is zero but is followed by a

<attrib.expr search value greater than zero, the previous value
[, val.expr changes to one (array<1,0,2> searches as if the
[, subval.expr]]> values were array<1,1,2>).
(continued) If the attribute, value, or subvalue numbers exceed
the range of the dynamic array, the ELSE clause
automatically executes.
[BY key.expr] Specifies the search order.
If the search expression is not found, the location
where expr would logically be in the sorted array
is assigned that location to var.
If you use the BY clause, you must specify an
ascending or descending order. The BY clause
assumes that you have already sorted the data and
that the sort was correct.
SETTING Specifies that if the expression is not found, var
will be set to a position after the last value in the
array.
var Specifies a variable in which to return the key
location of the expression.
[THEN statements Specifies statements to execute if the expression is
END] or is not found.
ELSE statements If the expression is not found, the system executes
END the statements after the ELSE clause.
If the search is successful, the system performs the
THEN clause if specified; otherwise, the system
performs the required ELSE clause.
Using multiple lines with THEN or ELSE requires
an END statement.
LOCATE Parameters (continued)
Sorting Keys
Normally, a search proceeds in the physical order of the array elements. You can alter
the search order by using the optional BY clause. The order in which the system
searches the array elements is determined by the type of sort clause you specify. The
247
LOCATE
elements are not physically rearranged, but are examined according to the sort key you
specify. The following table describes the valid sort keys.
Key Expression Search Order
DL Descending, contents left-justified.

DR Descending, contents right-justified.
AL Ascending, contents left-justified.
AR Ascending, contents right-justified.
LOCATE Sorting Keys
Note Using the LOCATE command on a dynamic array does not alter the array in
any way.
LOCATE functions differently under BASICTYPE P. LOCATE has the fol-

BASICTYPE
lowing syntax in BASICTYPE P:
LOCATE(expr,dyn.array [,attrib[,val]];index [;key.expr])

[THEN statements] [END] ELSE statements
The BASICTYPE P form locates expr in dyn.array within the search parameters of
attrib and val. The location of the item, if found, is placed in index. If you do not spec-
ify an attribute or value position, the search occurs at the attribute level. If you specify
an attribute, the search occurs at the value level. If you specify both, the search occurs
at the subvalue level. key.exp determines how the array is sorted and searched.
LOCATE functions differently under BASICTYPE R. LOCATE has the fol-

BASICTYPE
lowing syntax in BASICTYPE R:
LOCATE expr IN dyn.array <attrib.expr[,val.expr[,subval.expr]]>

[BY key.expr] USING delim.expr SETTING var [THEN statement END]
ELSE statements
The BASICTYPE R syntax contains an addition USING clause that differentiates if

the standard UniBasic (BASICTYPE U) LOCATE statement. You can set the delim-
iter you use for the search, which means an array delimited by any ASCII value may
be searched. In BASICTYPE R, the search parameters (attribute, value and subvalue)
are implemented differently than the standard UniBasic form (BASICTYPE U).
248
LOCATE
Examples
In the following example, the program statement searches the entire array FILMS,
attribute by attribute, for the literal string “HUD”. If the search is successful, the
attribute index of the string is assigned to the variable NDX. if the string is not found,
NDX is set to the last value plus one, and the system executes the STOP command.
The search is performed on the attribute level and if an attribute has the value HUD1,
the ELSE clause still executes because the LOCATE statement compares the entire
attribute.
LOCATE "HUD" IN FILMS<1> SETTING NDX ELSE STOP
In the next example, the program segment results in “HUD IS IN POSITION 2 IN

THE ARRAY” printing.
FILMS = "CARMEN":@VM:"HUD":@VM:"JAWS"
LOCATE "HUD" IN FILMS<1,1> SETTING NDX ELSE
PRINT "NOT FOUND"
STOP
END
PRINT "HUD IS IN POSITION ":NDX:" IN THE ARRAY"
In the next example, the program segment searches the array FILMS, starting at
attribute 5, value 2, subvalue 1, for the contents of the variable TITLE. Array elements
are examined in ascending order, and comparisons are left-justified. If the value in
TITLE is found, the system executes the first PRINT statement; otherwise, the system
executes the second PRINT statement.
LOCATE TITLE IN FILMS<5,2,1> BY "AL" SETTING NDX THEN
PRINT "THIS TITLTE IS IN THE LIBRARY"
END ELSE
PRINT "TITLE NOT FOUND, TRY AGAIN."
END
Related Topics
FIND
The UniBasic FIND command determines the position of an expression in a dynamic
array.
FINDSTR
The UniBasic FINSTR command determines the position of a substring within a
dynamic array.
249
LOCK
LOCK
Syntax
LOCK expr [THEN statements END] [ELSE statements END]
Description
The UniBasic LOCK command reserves a computer resource for the current UniBa-
sic program.
Use LOCK to reserve system printers or other resources for specific use by a
Tip single program.
Reminder It is your responsibility to assign the resource numbers and ensure there are no
conflicts in assignment. Resources are not automatically unlocked by the ter-
mination of the locking program. They must be released by using the
UNLOCK command. The ECL QUIT command unlocks resources reserved
by programs during a user session. Resources can also be released by execut-
ing the ECL CLEAR.LOCKS command at the system level.
Parameters
expr Specifies a number that refers to an associ-

ated resource. Each resource must be asso-
ciated with a number before it can be
reserved by a LOCK statement. expr may
range from 0 to 63.
[THEN statements END] Specifies statements to execute if the
resource is available and the LOCK
statement locks it.
LOCK Parameters
250
LOCK
[ELSE statements END] Specifies statements to execute if the

resource is reserved by another user and the
LOCK statement fails to lock it.
If you do not specify an ELSE clause and
the requested resource has already been
locked, the current program suspends exe-
cution and waits until that resource is
released.
LOCK Parameters (continued)
Examples
In the following example, the program statement reserves resource 12 if another pro-
gram is not using it. If resource 12 is already in use, the current program suspends exe-
cution and waits until resource 12 is unlocked.
LOCK 12
In the next example, the program segment locks resource 44 if it is available. If it has
already been locked, the program attempts to lock resource 45. If both resources are
unavailable, the program stops.
T1 = 44; T2 = 45
LOCK T1 ELSE LOCK T2 ELSE STOP
Related Topics
CLEAR.LOCKS
For information on the ECL CLEAR.LOCKS command, refer to UniData Commands
Reference.
LIST.LOCKS
For information on the ECL LIST.LOCKS command, refer to UniData Commands
Reference.
UNLOCK
The UniBasic UNLOCK command unlocks computer resources reserved by the
LOCK statement.
251
LOCK
QUIT
For information on the ECL QUIT command, refer to UniData Commands
Reference.
252
LOOP/REPEAT
LOOP/REPEAT
Syntax
LOOP
[statements]
[UNTIL expr [DO]
until_statements]
[WHILE expr [DO]
while_statements]
REPEAT
LOOP {WHILE | UNTIL} expr DO
statements
REPEAT
LOOP
statements
{WHILE | UNTIL} expr DO REPEAT
Description
The UniBasic LOOP/REPEAT command repeats any contained statements WHILE
or UNTIL a specified condition is met, depending on the clause you use. statements
can precede and/or follow the test condition. The structure may be written on one line,
space permitting, or it may extend over as many lines as necessary. REPEAT is
required and finishes the LOOP operation.
The first set of statements are executed on the first entry into the loop, then the
WHILE or UNTIL clause is evaluated. If expr is true (using the WHILE keyword) or
false (using the UNTIL keyword), then the system executes the second set of state-
ments. If you have statements after a WHILE or UNTIL clause, the DO clause is
required; otherwise it is optional. When REPEAT is reached, the program execution
returns to the first set of statements.
Tip Loops should be constructed so that termination occurs based on the WHILE
or UNTIL condition. The LOOP statement is flexible enough that almost any
logical progression can be incorporated.
253
LOOP/REPEAT
Parameters
expr Specifies an expression to check to for the

UNTL or WHILE clause.
expr may be any valid statement including a
READNEXT statement or LOCATE statement
statements Specifies statements to execute each time the
loop statement repeats.
while_statements Specifies statements to execute if the
expression in the WHILE clause is true.
until_statements Specifies statements to execute if the
expression in the UNTIL clause is false.
LOOP/REPEAT Parameters
Examples
In the following example, the program segment prints and increments POS until POS
reaches the value of 10.
POS=0
LOOP WHILE POS < 10 DO
PRINT POS
POS +=1
REPEAT
In the next example, the program segment prints “Counting” and then increments C. It
then evaluates C to see if it is less than eight, and if so, executes the second statement.
On the eighth iteration, the top statement is executed and the loop stops because the
condition (C > 8) is met. The program continues execution at the statement following
REPEAT. The second statement is not executed on the final iteration.
C = 0
PRINT "Counting:"
LOOP
C = C+1
UNTIL C > 8 DO
PRINT "C = ":C
REPEAT
254
LOOP/REPEAT
The result of this program:

Counting:
C = 1
C = 2
C = 3
C = 4
C = 5
C = 6
C = 7
C = 8
Related Topics
FOR/NEXT
reaches a specified value or the condition in the WHILE clause is reached.
255
LOWER
LOWER
Syntax
LOWER(dyn.array.expr)
Description
The UniBasic LOWER function converts all attribute marks to value marks and all
value marks to subvalue marks in a dynamic array.
Examples
In the following example, the program segment lowers the dynamic array D.STR.
D.STR = "A":@AM:"B":@AM:"C":@VM:"D"
D.STR = LOWER(D.STR)
The dynamic array D.STR now contains the string:

D.STR = "A":@VM:"B":@VM:"C":@SM:"D"
Related Topics
RAISE
The UniBasic RAISE function raises all delimiters in a dynamic array to the next
level.
256
LT
LT
Syntax
expr1 LT expr2
Description
The UniBasic LT function tests whether the expression expr1 is less than expr2.
expr1 and expr2 may be any valid UniBasic expression, variable or string.
Examples
In the following example, the program segment tests whether A is less than B. Since A
is less than B, the message “Less Than” prints.
A = 21
B = 22
IF A LT B THEN
PRINT "Less Than"
END ELSE
END
257
LTS
LTS
Syntax
LTS(array1,array2)
Description
The UniBasic LTS function compares each value in array1 to its corresponding value
array1 is less than the value in the corresponding position in array2, and a zero in
each position for values that are greater than array2.
Examples
ARRAY1 = 9:@VM:10:@VM:30:@VM:50:@VM:60
ARRAY2 = 10:@VM:20:@VM:30@VM:40:@VM:50
ARRAY3 = LTS(ARRAY1,ARRAY2)
258
MAT
MAT
Syntax
MAT matrix = expr
MAT matrix = MAT matrix2
Description
The UniBasic MAT command assigns new values to all elements of a matrix based on
an expression. The second form assigns the contents of one matrix to another matrix.
If a matrix is assigned the values of a second matrix, the assignment proceeds from
element to element in consecutive order. That is, the first element of the first array is
assigned to the first element of the second array, the second element is assigned to the
second element, etc. The two matrices do not have to contain the same dimensions,
but must contain the same number of elements. The system does not alter the second
matrix by the assignment process.
You must dimension all matrices before assignment. You may place MAT in any
looping structure and assign the elements with a variable or function.
Parameters
matrix Specifies a matrix to which to assign new

values.
expr Specifies an expression to evaluate to deter-
mine the value to assign to the matrix element.
expr may be a null, a formula, single value,
literal string, or function.
matrix2 Specifies a matrix from which to assign values
to the first matrix, matrix.
MAT Parameter
259
MAT
Examples
In the following example, the program segment assigns 1.5 to all elements of the array
FEES.
DIM FEES(100,100)
MAT FEES = 1.5
In the next example, the program segment assigns the values in matrix FEE2 to the
matrix FEE1. Note the differing dimensions but the same number of elements in the
two matrices.
DIM FEE1(2,4),FEE2(4,2)
MAT FEE1 = MAT FEE2
If the matrices contain the following values before the assignment:
Matrix FEE1 Matrix FEE2
1 2 3 4 10 11
5 6 7 8 12 13
14 15
16 17
Matrix FEE1 and Matrix FEE2
The values assigned to FEE1 would be:
Matrix FEE1
10 11 12 13
14 15 16 17
New Matrix FEE1
Note how the elements are assigned: from left to right, top to bottom, element by ele-
ment. The system maintains all values in matrix FEE2. The positions are shifted to fit
the dimensions of matrix FEE1.
Related Topics
DIMENSION, DIM
The UniBasic DIMENSION or DIM command declares the name and dimensions of
matrices.
260
MATBUILD
MATBUILD
Syntax
MATBUILD dyn.array FROM matrix [, start.num [, end.num [USING delim]]]
Description
The UniBasic MATBUILD command generates a dynamic array from a dimensioned
matrix based on specified starting and ending positions and the delimiter given. The
matrix can be multidimensional. The statement retrieves elements from the multidi-
mensional matrix according to the order in which its elements are stored.
Parameters
dyn.array Specifies the target string to be generated.

FROM matrix Specifies the source from which to build the
dynamic array.
[,start.num] Specifies the starting position of the matrix
where the dynamic array is generated. If
start.num is less than or equal to zero, it
defaults to 1. The dynamic array is not
generated if the start.num is greater than the
end.num.
[,end.num] Specifies the ending position of the matrix
where the dynamic array is generated.
If end.num is less than or equal to zero or
passes the end of the matrix, the system gener-
ates the dynamic array through the end of the
matrix.
MATBUILD Parameter
261
MATBUILD
[USING delim] The USING clause specifies the delimiter

delim in the dyn.array generation. If you do not
specify delim or if you specify a null, it
defaults to @AM (attribute mark). If you spec-
ify more than one character, only the first one
is used. The system inserts the delim between
consecutive elements of the matrix to form the
dyn.array.
MATBUILD Parameter (continued)
Examples
In the following example, A is a matrix with 5 elements:
A(1)=11, A(2)=22, A(3)=33, A(4)=44, and A(5)=55
The following program statement:
MATBUILD SUBSTR FROM A ,2,4
generates the following dynamic array.

SUBSTR = "22":@AM:"33":@AM:"44"
The next program statement:

MATBUILD SUBSTR FROM A ,1 USING ’,’
generates the following dynamic array:

SUBSTR = "11":@AM:"22":@AM:"33":@AM:"44":@AM:"55"
Related Topics
DIMENSION, DIM
The UniBasic DIMENSION or DIM commands declare the name and dimensions of
matrices.
MAT
The UniBasic MAT command assigns new values to all elements of a matrix based on
an expression.
262
MATBUILD
MATPARSE
The UniBasic MATPARSE command distributes portions of a string to consecutive
elements of a named matrix based on a specified delimiter.
263
MATCH MATCHES
MATCH
MATCHES
Syntax
var MATCH "[~] {len [X, A ,N]} [text]"
var MATCHES "[~] {len [X, A, N]} [text]"
Description
The UniBasic MATCH or MATCHES functions determine if a variable matches a
specific pattern of characters or numbers you specify. If the var matches the pat-
tern.expr, MATCH returns a one. If the var does not match the pattern.expr, MATCH
returns a zero.
The text string must match exactly. The codes and a text string may be mixed to
search for specific patterns separated by characters.
Parameters
var Specifies the variable to compare with the

match expression.
~ Specifies to inverse the following pattern.
Thus, if a “4N” pattern requires four numeric
characters to match, a “~4N” pattern matches
on four characters that are not all numeric.
len Specifies a number of characters to match.
X Specifies that the characters to match may be
any character type.
A Specifies that the pattern match only alphabetic
characters.
N Specifies that the pattern match only numeric
characters.
MATCH Parameters
264
MATCH MATCHES
text Specifies a literal string for the pattern to

match.
MATCH Parameters (continued)
Examples
In the following example, the program segment determines if the variable SSN is a
valid social security number.
SSN = "522-13-5124"
SSNTEST = SSN MATCH "3N’-’2N’-’4N"
265
MATCHFIELD
MATCHFIELD
Syntax
MATCHFIELD(str.expr,"[~] {len [X, A, N]} [text]", field.expr)
Description
The UniBasic MATCHFIELD function returns a portion of a string that matches a
search substring. The string being compared must match entirely the format specified.
If there is no match, the system returns a null string.
The text string must match exactly. The codes and a text string may be mixed to
search for specific patterns separated by characters.
Parameters
str.expr Specifies the string to compare with the match

pattern.
[~] Specifies to inverse the following pattern.
Thus, if a “4N” pattern requires four numeric
characters to match, a “~4N” pattern matches
on four characters that are not all numeric.
[len] Specifies a number of characters to match.
[X] Specifies that the characters to match may be
any character type.
[A] Specifies that the pattern match only alphabetic
characters.
[N] Specifies that the pattern match only numeric
characters.
[text] Specifies a literal string for the pattern to
match.
MATCHFIELD Parameters
266
MATCHFIELD
[field.expr] Specifies which portion of the match.expr is

the value to be returned. Each code segment is
considered to be a field for the purposes of
field.expr.
MATCHFIELD Parameters (continued)
Examples
In the following example, the program segment returns the value 56 because the entire
string matches the specified criteria and the third field is the middle two numbers.
SSN = "534-56-5565"
MID = MATCHFIELD(SSN,"3N’-’2N’-’4N",3)
In the next example, the program segment searches the string and returns the second
and fourth fields and prints “99922”.
STRING = "ALL999WERE22ABSENT"
NUM1 = MATCHFIELD(STRING,’3A3N4A2N6A’,2)
NUM2 = MATCHFIELD(STRING,’3A3N4A2N6A’,4)
PRINT NUM1:NUM2
267
MATPARSE
MATPARSE
Syntax
MATPARSE matrix FROM str.expr, delim.expr
Description
The UniBasic MATPARSE command distributes portions of the delimited string to
consecutive elements of the named matrix, based on a delimiter found within the
string.
If there are more elements in the string being parsed than are available in the matrix,
the system places the portion of the string that cannot be parsed in the zero element of
the array. The INMAT function is used to determine if the array being parsed is too
large for the matrix. If the value of INMAT is equal to 0, the zero element contains an
assigned value. If the value of INMAT is equal to a positive number, this number rep-
resents the number of elements of the array that were assigned values.
BASICTYPE P and R do not support the 0,0 element.

BASICTYPE
Parameters
matrix Specifies the matrix to which to distribute por-

tions of the delimited string.
str.expr Specifies a delimited string to distribute to the
matrix.
delim.expr Specifies the delimiter to use in the string
expression.
You may use any delimiter in the array (any
ASCII character including commas or spaces).
In general, use an array delimited by attribute,
value, or subvalue marks. You must specify a
delimiter, even if it is a null string.
MATPARSE Parameters
268
MATPARSE
The length of the delimiter affects the function of the MATPARSE statement. The fol-
lowing table describes the length of the delimiter and its effect.
Length Effect
null Assigns successive single characters of the string to con-

secutive elements of the matrix.
1 char Assigns all characters found between successive delimiters
in the string to the next matrix element. If delimiters are
found side-by-side in the string, the corresponding matrix
elements are assigned a null value.
>1 char The system treats each character in the delimiter string as a
potential delimiter. When a delimiter is found, the charac-
ters being delimited are placed in the first matrix element
and the delimiter(s) are placed in the second element. Thus,
each successive pair of matrix elements contain the delim-
ited attribute and the delimiter that defined it.
MATPARSE Delimiter Length Effects
Examples
In the following example, the program segment fills the matrix ALPHA with consecu-
tive characters from a literal string. A null delimiter is given, causing one character to
be assigned to each matrix cell. In this case, the value of the INMAT function is 7.
DIM ALPHA(7)
MATPARSE ALPHA FROM "ABCDEFG",""
Resulting matrix:
ALPHA(1) = "A"
.
.
.
ALPHA(7) = "G"
In the next example, the program segment dimensions the matrix T and then fills it
with data from a dynamic array. The delimiter specified is the attribute mark, so each
attribute is assigned to consecutive elements of the array. Note that the string “ITEM”
has five elements but the matrix is dimensioned with four elements. After the MAT-
PARSE command, the INMAT function is 0 and the value of the zero element, T(0) is
443.
DIM T(4)
ITEM = "123:@AM:33:@AM:199:@AM:821:@AM:443"
MATPARSE T FROM ITEM, CHAR(254)
269
MATPARSE
Resulting matrix:
T(1) = 123
T(2) = 33
T(3) = 199
T(4) = 821
In the next example, the program segment fills the first column of the array with the
contents of the attributes (as defined by the delimiters), while the second column of
the matrix contains the delimiters that defined that attribute. Delimiters are user-
defined.
DIM R(4,2)
ITEM = "2,5.3;9,,5"
MATPARSE R FROM ITEM, ",."
Resulting matrix:
R(1,1) = 2
R(1,2) = ,
R(2,1) = 5
R(2,2) = .
R(3,1) = 3;9
R(3,2) = ,,
R(4,1) = 5
R(4,2) = null
Related Topics
MAT
The UniBasic MAT command assigns new values to all elements of a matrix.
INMAT
The UniBasic INMAT function displays the status of statements that you have exe-
cuted.
270
MATREAD
MATREAD
Syntax
MATREAD matrix FROM [file.var,] record.ID.expr [ON ERROR statements]
{THEN | ELSE} statements [END]
Description
The UniBasic MATREAD command assigns the values found in successive attributes
of a record to corresponding elements of a matrix.
If there are fewer attributes in the record than elements in the matrix, the system fills
the remaining matrix elements with null values. If the matrix cannot hold all the
attributes of the record, the system stores the remaining information in the zero ele-
ment of the matrix. The value of the INMAT function is set to the number of attributes
in the record, unless the number of attributes exceeds the dimensions of the matrix. In
that case, the system sets INMAT to 0 (and the remaining attributes assigned to the
zero element).
Note You must name and dimension matrices before a MATREAD statement is
executed.
After the execution of a MATREAD statement, the system sets the INMAT function
the number of attributes that were loaded. If there are more attributes in the record
than elements in the array, the system assigns a value of zero to INMAT.

BASICTYPE
Parameters
matrix Specifies the matrix to which to assign the val-

ues read from the successive attributes of the
record record.ID.expr.
MATREAD Parameters
271
MATREAD
FROM [file.var,] Specifies the file from which to read the

record. If you do not specify a file variable, the
system accesses the most recently opened
default file.
record.ID.expr Specifies the record from which to read the
attributes.
[ON ERROR statements] Specifies statements to execute if the
MATREAD statement fails with a fatal error
condition because the file is not open or an I/O
error occurs in the read accessing process, or if
the system cannot find the specified file
variable.
If you do not specify the ON ERROR clause
and a fatal error occurs, the program
terminates.
{THEN | ELSE} Specifies statements to execute if you specify
statements [END] the ON ERROR clause and record.\ID.expr
does not exist (ELSE) or if the read is success-
ful (THEN). The system requires an END
statement when you use THEN or ELSE with
multiple lines.
MATREAD Parameters (continued)
Examples
In the following example, the program segment reads the record with ID NAMES
from the default file and assigns the successive attributes to the matrix TEST. If there
is not a default file or the record is not found, the program assigns the value 0 to the
variable FOUND.
DIM TEST(10,10)
MATREAD TEST FROM "NAMES" ELSE FOUND = 0
In the next example, the program segment reads the record with ID NAMES and
assigns the data in the file CUSTFILE to the matrix TEST.
OPEN "","CUSTFILE" TO CF ELSE STOP "NO CUSTFILE"
MATREAD TEST FROM CF,"NAMES" ELSE FOUND = 0
272
MATREAD
In the next example, the MATREAD statement uses a THEN clause and an ELSE
clause.
FILE.ERR = 0
DIM CUST.ITEM(22)
MATREAD CUST.ITEM FROM CUST.FILE,CUST.ID THEN
GOSUB PROCESS.CUSTOMER:
END ELSE
MAT CUST.ITEM = "
FILE.ERR = 1
END
Related Topics
MATREADL
The UniBasic MATREADL command assigns the values found in successive
attributes of a record to corresponding elements of a matrix while placing a read-only
lock on the specified record, allowing other users to read the record while preventing
them from updating the record.
MATREADU
The UniBasic MATREADU command writes successive elements of a matrix into
corresponding attributes of a record but will not release any locks set by the READU,
READVU, or MATREADU commands.

For information on sequential file input/output, refer to Developing UniBasic
Applications.
273
MATREADL
MATREADL
Syntax
MATREADL matrix FROM [file.var,] record.ID.expr [ON ERROR statements]
[LOCKED statements] {THEN | ELSE} statements [END]
Description
attributes of a record to corresponding elements of a matrix and sets a read-only lock
on the specified record, allowing other users to read the record while preventing them
from updating the record.
The system respects locks set by MATREADL with READU, MATREADU,
READVU, WRITEU, MATWRITEU, or WRITEVU commands. If you use the
READ, MATREAD, READV, WRITE, MATWRITE, or WRITEV commands
(which do not check locks), the lock has no effect on the record you access.

BASICTYPE
Parameters

default file.
attributes.
MATREADL Parameters
274
MATREADL

MATREADL statement fails with a fatal error
variable.
If you do not specify the ON ERROR clause
and a fatal error occurs, the program
terminates.
[LOCKED statements] Specifies statements to execute if you specify a
record that is locked by another user. If you do
not specify a LOCKED clause, the program
waits until the lock on the record is released.
statements [END] the ON ERROR clause and record.ID.expr
multiple lines.
You are only required to use a THEN or an
ELSE clause. If you use THEN, you do not
have to use ELSE.
MATREADL Parameters (continued)
Examples
In the following example, the program segment reads a tape record with the ID speci-
fied in TAPE.ID from the TAPES.FILE. If the record is found, control transfers to the
subroutine TAPE.PROCESS; otherwise, the program displays a message and aborts.
If the record is locked, the program displays a message.
MATREADL TAPE.REC FROM TAPES.FILE,TAPE.ID THEN
GOSUB TAPE.PROCESS:
PRINT "TAPE PROCESSED:":TAPE.ID
END
LOCKED PRINT "RECORD LOCKED"
ELSE PRINT "RECORD NOT FOUND:":TAPE.ID; ABORT
275
MATREADL
Related Topics
MATREAD
MATREADU
The UniBasic MATREADU command assigns the values found in successive fields
of a record to corresponding elements of a matrix while placing an exclusive lock on
the record, allowing other users to read the record while preventing them from updat-
ing the record.
LIST.READU
For information on LIST.READU, refer to UniData Commands Reference.

For more information on sequential file input/output, refer to Developing UniBasic
Applications.
276
MATREADU
MATREADU
Syntax
MATREADU matrix FROM [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic MATREADU command assigns the values found in successive
attributes of a record to corresponding elements of a matrix and sets an exclusive lock
on the record you specify with record.ID.expr, prohibiting outside access until the
update is complete.
MATREADU is specifically designed to use in conjunction with the READU,

Tip MATREADU, and READVU statements. If the non-locking commands are
used (READ, MATREAD, or READV), the system ignores the record lock
set by MATREADU.
The MATREADU statement sets the INMAT function. INMAT returns a zero if data
is stored in the zero element (0,0) because the number of attributes read exceeded the
matrix size; otherwise it returns the number of elements assigned to the matrix.
A record that you lock with the MATREADU statement remains locked until you exe-
cute one of the following statements: MATWRITE, WRITE, WRITEV, RELEASE,
or STOP. The system releases all locks when the program (but not a called subroutine)
containing the MATREADU terminates.

BASICTYPE
Parameters

MATREADU Parameters
277
MATREADU

default file.
attributes.
MATREADU statement fails with a fatal error
variable. If you do not specify the ON ERROR
clause and a fatal error occurs, the program
terminates.
[LOCKED statements] Specifies statements to execute if you specify a
record that is locked by another user. If you do
not specify a LOCKED clause, the program
waits until the lock on the record is released.
You may place the LOCKED clause after the
FROM clause.
statements [END] the ON ERROR clause and record.ID.expr
multiple lines. You are only required to use a
THEN or an ELSE clause. If you use THEN,
you do not have to use ELSE.
MATREADU Parameters (continued)
Examples
In the following example, the program segment reads the record with ID “NAMES”
from the default file. The record is locked, preventing access by another program until
the record is updated or released.
DIM TEST(10,10)
MATREADU TEST FROM "NAMES" ELSE GOSUB 105
278
MATREADU
In the next example, the program segment reads the record with the ID CUST.ID and
assigns each attribute to successive elements in the matrix CUST.REC. If the record is
found, the system executes the optional THEN clause; if the record is locked, the sys-
tem displays RECORD LOCKED. If the record is not found, the system displays a
message to that effect.
MATREADU CUST.REC FROM CUSTFILE,CUST.ID THEN
PRINT "PROCESSING CUSTOMER: ":CUST.ID
GOSUB PROCESS.CUSTOMER:
END LOCKED
PRINT ’RECORD LOCKED ’
END ELSE
PRINT ’RECORD NOT FOUND FOR CUSTOMER ’:CUST.ID
END
Related Topics
MATREAD
MATREADL
attributes of a record to corresponding elements of a matrix while placing a read-only
lock on the record, allowing other users to read the record while preventing them from
updating the record.
LIST.READU
For information on LIST.READU, refer to UniData Commands Reference.
279
MATWRITE
MATWRITE
Syntax
MATWRITE matrix {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic MATWRITE command writes successive elements of a matrix to the
corresponding attributes of the record record.ID.expr.
MATWRITE writes successive elements from the array to the record you specify. The
first element in the array is written to the first attribute in the record, and so on. If the
matrix contains trailing nulls (the matrix size exceeds the virtual record being stored
in the matrix), the trailing nulls are not written. If the zero element is not null, its con-
tents are written subsequent to the final element in the array; i.e., as element N+1.
The MATWRITE statement releases any locks set on a record by the MATREADU,
READL, READU or READVU statements.
Use the MATWRITEU statements to ensure that a record remains locked

Tip after being written to.
Note After the execution of a MATWRITE statement, the STATUS function is set
to zero if the record accessed was locked prior to being written to. If the STA-
TUS function returns -2, the record accessed is not locked.
Parameters
matrix Specifies the matrix from which to assign the

values read to the successive attributes of the
You must name and dimension a matrix before
using it in the MATWRITE statement.
MATWRITE Parameters
280
MATWRITE
[ON | TO] [file.var,] Specifies the file to which to write the record.
You must specify an ON or TO clause. If you
do not specify a file variable, the system
accesses the most recently opened default file.
record.ID.expr Specifies the record to which to write the
attributes.
MATWRITE statement fails with a fatal error
condition because the file is not open, if the file
is a read-only file, or if the file contains another
write error. If you do not specify the ON
ERROR clause and a fatal error occurs, the
program terminates.
MATWRITE Parameters (continued)
Examples
In the following example, the program segment writes the matrix RECEIPTS to the
file REC87, as a record with ID “RENTALS.”
COMMON RECEIPTS(12)
MATWRITE RECEIPTS ON REC87,"RENTALS"
Related Topics
MATWRITEU
The UniBasic MATRWRITEU command writes successive elements of a matrix into
corresponding attributes of a record without releasing a record lock.
281
MATWRITEU
MATWRITEU
Syntax
MATWRITEU matrix {ON | TO} [file.var,] record.ID.expr
Description
The UniBasic MATWRITEU command writes successive elements of a matrix to the
corresponding attributes of a specified record but does not release any locks set by
READU, READVU, or MATREADU statements.
Note After the execution of a MATWRITE statement, the STATUS function is set
to zero if the record accessed was locked prior to being written to. If the STA-
TUS function returns -2, the record accessed is not locked.
Parameters
matrix Specifies the matrix from which to assign the

values read to the successive attributes of the
You must name and dimension a matrix before
using it in the MATWRITE statement.
[ON | TO] [file.var,] Specifies the file to which to write the record.
You must specify an ON or TO clause. If you
do not specify a file variable, the system
accesses the most recently opened default file.
record.ID.exp Specifies the record to which to write the
attributes.
MATWRITEU Parameters
282
MATWRITEU

MATWRITEU statement fails with a fatal
error condition because the file is not open, if
the file is a read-only file, or if the file contains
another write error. If you do not specify the
ON ERROR clause and a fatal error occurs, the
program terminates.
MATWRITEU Parameters (continued)
Examples
In the following example, the program statement writes the matrix NEW.CLIENTS to
the file CLIENTS as a record with an ID of ‘050887’. If the record is locked, the sys-
tem maintains the lock.
MATWRITEU NEW.CLIENTS TO CLIENTS,’050887’
Related Topics
MATWRITE
The UniBasic MATWRITE command writes successive elements of a matrix into cor-
responding attribute of a record and releases a record lock.
283
MAXIMUM
MAXIMUM
Syntax
MAXIMUM(dyn.array.var)
Description
The UniBasic MAXIMUM function returns the maximum numeric element found in
the dynamic array you specified with dyn.array.var. This function ignores non-
numeric elements. If the array you specify contains only non-numeric elements,
MAXIMUM returns a null value. If there is a null element in the array, the system
treats it as zero.
The system treats all system marks (attribute, value, and subvalue marks) indiscrimi-
nately; that is, any value between two marks, no matter what the mark, is taken as an
element with respect to this function.
Examples
In the following example, the program segment prints 22 on screen.
X = "12":@VM:"2":@FM:"dd":@FM:"9":@FM:"22"
PRINT MAXIMUM(X)
In the next example, the program segment prints 0 since the string W contains a
NULL element and no other numeric elements.
W = "A":@FM:"B":@VM:"":@SM:"C"
PRINT MAXIMUM(W)
Related Topics
The UniBasic MINIMUM function returns the minimum numeric element found in a
dynamic array.
284
MDPERFORM
MDPERFORM
Syntax
MDPERFORM str.expr [CAPTURING, dyn.arrry.var]
[RETURNING, dyn.array.var] [RTNLIST int.expr] [PASSLIST int.expr]
[PASSCOM]
MDPERFORM str.expr [RETURNING, dyn.array.var]
[CAPTURING, dyn.arrry.var] [RTNLIST int.expr] [PASSLIST int.expr]
[PASSCOM]
Description
The UniBasic MDPERFORM command executes various UniData commands, sen-
tences, or paragraphs within a UniBasic program while transferring lists to and from
the executed commands.
Note MDPERFORM does not pass and return select lists unless you explicitly
specify them. In this way, there is full control and protection over the
resource.
STACKCOMMON
using STACKCOMMON requires additional memory).
If STACKCOMMON is OFF when one program executes another program, the
unnamed common is passed to the executed program and any changes are passed back
to the executing program.
If STACKCOMMON is ON when one program executes another program, unnamed
common is not passed to the program you execute, instead the program’s unnamed
common is pushed onto a stack and the executed program’s unnamed common is ini-
to an phantom program.
STACKCOMMON is always ON in BASICTYPE P and M.

BASICTYPE
BASICTYPE U.
285
MDPERFORM
Parameters
str.expr Specifies a literal string or an expression that evaluates

to a UniData command with appropriate parameters.
You may concatenate strings with appropriate opera-
tors. If you pass a filename to a MDPERFORM com-
mand, the filename must be the name of a file in the
current account, not a file variable that is the result of a
UniBasic OPEN statement.
[CAPTURING, The CAPTURING clause creates a dynamic array with
dyn.arrry.var] the output, which otherwise would appear on the dis-
play terminal. Each line of the text becomes an
attribute in the array. Output you direct to the printer is
not affected by this clause and is still sent to the
printer.
You can nest CAPTURING clauses. For example, in
program A an MDPERFORM statement, which has a
“CAPTURING var1,” invokes program B and in B
there is another MDPERFORM statement that also has
[CAPTURING, a “CAPTURING var2” clause. The output of pro-
dyn.arrry.var] grams A and B are then sent to var1 and var2,
(continued) respectively.
Currently the embedded level is set to 2. You can use
the udtconfig file variable MAX_CAPT_LEVEL to set
it to a higher number system-wide, or the environment
variable MAX_CAPT_LEVEL to set it higher on an
individual basis.
MDPERFORM Parameters
286
MDPERFORM
[RETURNING, The RETURNING clause captures the error messages

dyn.array.var] from the command you execute with MDPERFORM
into a string variable. This variable is a string of error
message numbers separated by spaces. If the command
you execute creates a spooler hold file, the system also
enters the hold file entry number into the returning
variable.
Currently, the embedded level is set to 2.
You can use the udtconfig file variable
MAX_RETN_LEVEL to set it to a higher number sys-
tem-wide, or the environment variable
MAX_RETN_LEVEL to set it higher on an individual
basis.
[RTNLIST The RTNLIST clause specifies an expression that must
int.expr] evaluate to an integer 0 - 9, designating the list to
return back to the calling program. You can use the
resulting list with subsequent READNEXT statements
or in the PASSLIST clause of a MDPERFORM state-
ment. If an expression is not given after RTNLIST, the
generated list replaces the contents of list 0. If the
RTNLIST clause is not specified, then a list does not
return.
[PASSLIST The PASSLIST clause specifies an expression that
int.expr] must evaluate to an integer 0, 1 or 2, designating the
select list to be sent to the called processor. The passed
list can be the result of previous SELECT or GETLIST
commands or the RTNLIST clause of an
MDPERFORM statement. If you do not specify
int.expr, list 0 is assumed.
Only the specified list is passed to the performed com-
mand, the other lists in UniBasic environment are not
passed.
[PASSCOM] This option is for backward compatibility for releases
prior to 3.1.
MDPERFORM Parameters (continued)
Examples
In the following example, the program segment lists all the items in the VOC file and
returns the result in select list 2.
287
MDPERFORM
list_var = 2
MDPERFORM "list dict VOC all" RTNLIST list_var
In the next example, the program segment first performs a selection on the CUS-
TOMER file and passes the result back in select list 1, then sorts the result.
list_var = 1
cmd1 = "select CUSTOMER with @ID = ’200’"
cmd2 = "sort CUSTOMER by DATE_OUT"
MDPERFORM cmd1 RTNLIST list_var
MDPERFORM cmd2 PASSLIST list_var
In the next example, the program segment builds different commands based on condi-
tions generated by MDPERFORM. According to the value of input_var, three differ-
ent UniQuery commands are executed.
list_var = 1
frg1 = "select CUSTOMER with "
frg2 = " NAME like ’...Jones...’ "
frg3 = " DATE_DUE > ’04/22/87’ "
frg4 = " AMT_DUE < 30"
frg5 = " by NAME"
BEGIN CASE
CASE input_var = 1
MDPERFORM frg1:frg2:frg5 RTNLIST list_var
CASE input_var = 2
CASE input_var = 3
END CASE
In the next example, the program segment performs the command in cmd3, using the
passed list specified by list_var and sends output to a dynamic array cpt_var.
MDPERFORM cmd3 PASSLIST list_var CAPTURING cpt_var
Related Topics
EXECUTE
The UniBasic EXECUTE command executes a UniData or UniQuery command from
within a UniBasic program.
EXECUTESQL
The UniBasic EXECUTESQL command passes an SQL statement directly to the Uni-
Data SQL processor.
PERFORM
The UniBasic PERFORM command executes a UniData command, sentence, or para-
graph from within a UniBasic program.
288
MDPERFORM
PCPERFORM
The UniBasic PCPERFORM command executes a UNIX or VMS command from
UDTEXECUTE
The UniBasic UDTEXECUTE command executes a command to perform in
ECLTYPE U, regardless of the BASICTYPE of the program.
289
MINIMUM
MINIMUM
Syntax
MINIMUM(dyn.array.var)
Description
The UniBasic MINIMUM function returns the minimum numeric element found in a
dynamic array.
The system ignores non-numeric elements with this function. If dyn.array.var con-
tains only non-numeric elements, the function returns a null value. If there is a null
element in the array, it is treated as a numeric zero.
All system marks (attribute, value, and subvalue marks) are treated indiscriminately;
that is, any value between two marks, no matter what the mark is, is taken as an ele-
ment.
Examples
In the following example, the program segment prints 2 on the screen.
X = "12":@VM:"2":@AM:"dd":@AM:"9":@AM:"22"
PRINT MINIMUM(X)
In the next example, the program segment assigns U a null value since V contains only
non-numeric elements.
V = "Null":@AM:"assignment":@AM:"test"
U = MINIMUM(V)
Related Topics
MAXIMUM
The UniBasic MAXIMUM function returns the maximum numeric element found in a
dynamic array.
290
MOD REM
MOD
REM
Syntax
MOD(num.expr1, num.expr2)
REM(num.expr1, num.expr2)
Description
The UniBasic MOD and REM functions returns the remainder of the division of
num.expr2 into num.expr1. These functions handle integers and decimals. The sign of
the result is the same as that of num.expr1.
The formula used by MOD and REM is:
MOD(x,y) = x - (INT(x/y) * y)
where x and y stand for numeric expressions. The first expression x is divided by y and
the integer function INT truncates the result. The system multiplies the resulting inte-
ger by y, and finally subtracts the result from the value of the first expression x.
Note The value of num.expr2 cannot evaluate to zero.
Examples
In the following example, the program segment assigns the variable Z the remainder
of the division of Y into X. The remainder in this case is 2.
X = 12 ; Y = 5
Z = MOD(X,Y)
291
NE
NE
Syntax
expr1 NE expr2
Description
The UniBasic NE function tests whether the expression expr1 is not equal to expr2.
expr1 and expr2 may be any valid expression, variable or string.
Examples
In the following example, the program segment tests whether A is not equal to B.
Since A is greater than B, the message “Not Equal” prints.
A = 24
B = 22
IF A NE B THEN
PRINT "Not Equal"
END ELSE
PRINT "Equal"
END
292
NES
NES
Syntax
NES(array1, array2)
Description
The UniBasic NES function compares each value in array1 to its corresponding value
array1 is not equal to the value in the corresponding position in array2, and a zero in
each position for values that are equal to array2.
Examples
ARRAY1 = 10:@VM:20:@VM:30@VM:40:@VM:50
ARRAY2 = 10:@VM:20:@VM:30:@VM:50:@VM:60
ARRAY3 = NES(ARRAY1,ARRAY2)
293
NEG
NEG
Syntax
NEG(expr)
Description
The UniBasic NEG function changes the value of expr to its opposite sign. If the
value of expr is positive, NEG returns a negative value. If the value of expr is nega-
tive, NEG returns a positive value.
Examples
In the following example, the program segment changes the value of variable A to a
negative number and prints -1.
A = 1
A = NEG(A)
PRINT A
294
NEXT
NEXT
Syntax
NEXT [var]
Description
The UniBasic NEXT command defines the end of a FOR/NEXT structure. var is the
variable being incremented. This variable serves as documentation only; a program
functions identically with or without this variable.
Related Topics
FOR/NEXT
reaches a certain value or the system reaches the condition in the WHILE clause.
LOOP
The UniBasic LOOP/REPEAT command repeats any contained statements while or
until a condition is met.
295
NOCONVERT
NOCONVERT
Syntax
NOCONVERT {OFF | ON}
Description
The UniBasic NOCONVERT command controls the conversion of the special char-
acter CHAR(0). Generally, any UniData commands covering non-UniData files or
tape input/output, converts CHAR(0) to CHAR(128) on an input read and converts
CHAR(128) to CHAR(0) on an output write. This may cause problems under some
circumstances, especially if you use the character CHAR(128) in an application or is
stored data. NOCONVERT provides a way of switching the conversion OFF or ON.
The default is OFF.
The following table describes the UniBasic commands that NOCONVERT effects.
Affected Commands
READT OSWRITE
WRITET OSBREAD
OSREAD OSBWRITE
NOCONVERT Affected Commands
Reminder The PRINT and CRT functions don’t work with strings that contain a
CHAR(0).
The following table describes the functions that work with strings containing
CHAR(0), regardless of the NOCONVERT status.
Functions
Assignment (X = Y) Bracket function ([ ])

Substring Assignment String Concatenation (A:B)
(A = B[1,3])
CHAR CONVERT
Functions That Work with CHAR(0)
296
NOCONVERT
Functions
COUNT DCOUNT
INDEX LEN
SEQ SWAP
Functions That Work with CHAR(0) (continued)
297
NOT
NOT
Syntax
NOT(expr)
Description
The UniBasic NOT function inverts the logical result of the argument expr. If the
expression is true, the function returns a 0 (false); if the expression is not true, the
function returns 1 (true).
Examples
In the following example, the program segment compares X to Y (false, since X is not
greater than Y) and inverts the result, evaluating to true instead. The THEN statement
then executes, sending program control to the label specified by RETRY:
X = 1 ; Y = 2
IF NOT(X > Y) THEN GOTO RETRY:
298
NOTS
NOTS
Syntax
NOTS(dyn.array)
Description
The UniBasic NOTS function inverts the logical result of each element of a dynamic
array. If the element is true, the function returns a 0 (false) in the corresponding posi-
tion of the new array. If the expression is not true, the function returns 1 (true) in the
corresponding position of the new array.
Examples
In the following example, the program segment evaluates the dynamic array A, inverts
each result of the evaluation, and returns the results in a corresponding array. B now
contains 0}1}0}0.
A = 1:@FM:0:@FM:1:@FM:30
B = NOTS(A)
299
NULL
NULL
Syntax
NULL
Description
The UniBasic NULL command acts as a dummy statement. You may use the NULL
statement anywhere a statement is required.
Use NULL when a statement or command clause is mandatory but you do not
Tip want any action to occur.
Examples
In the following example, if the length of the variable NAME$ is zero, nothing is
printed.
PRINT "NAME: ": ; INPUT NAME$
BEGIN CASE
CASE LEN(NAME$) = 0
NULL
CASE LEN(NAME$) > 0
PRINT "HI, ":NAME$
END CASE
In the next example, if the CUSTR.REC is found, the program branches to the subrou-
tine PROCESS.CUST. If the record is not found, action is not taken.
READ CUST.REC FROM CUSTOMER,CUST.ID THEN
GOSUB PROCESS.CUST:
END ELSE NULL
300
NUM
NUM
Syntax
NUM(expr)
Description
The UniBasic NUM function determines if an expression is numeric. If expr is
numeric, NUM returns a one; otherwise, it returns a zero. expr can be any valid Uni-
Basic expression.
The NUM function accepts some non-numeric characters and still returns a 1. The fol-
lowing table describes these characters.
Character Description
+ Plus sign
- Negative sign
. Decimal point
NUM Function Accepted Non-Numeric Characters
Examples
In the following example, the program segment prints zero since VAR contains alpha-
betic characters.
VAR = ’ABC’
PRINT NUM(VAR)
In the next example, the program segment prints a 1 since VAR contains an integer.
VAR = -123
PRINT NUM(VAR)
301
NUMS
NUMS
Syntax
NUMS(dyn.array)
Description
The UniBasic NUMS function determines if each element of an array is numeric. If
the element is numeric, NUM returns a 1 in the corresponding position of the new
array; otherwise, it returns a 0.
The NUMS function accepts some non-numeric characters and still returns a 1. The
following table describes these characters.
Character Description
+ Plus sign
- Negative sign
. Decimal point
NUMS Function Accepted Non-Numeric Characters
Examples
In the following example, the program segment determines if each element of array
CHARACTERS is numeric. The resulting array B contains 1}1}1}0}0.
CHARACTERS = 123:@FM:456:@FM:-789:@FM:"ABC":@FM:"CDE"
B = NUMS(CHARACTERS)
302
OCONV
OCONV
Syntax
OCONV(str.expr, conv.code.expr)
Description
The UniBasic OCONV function converts string or numeric data from internal format
to output format based on conversion codes.
Parameters
str.expr Specifies the string expression to convert.

conv.code.expr Specifies the conversion code to use.
OCONV Parameters
The following table describes the valid codes.
Code Format
D System date
G Extracts one or more strings separated by a delimiter
L Length
MB Binary
MC Masked character
MD Masked decimal
ML Left justify
MP Packed decimal
MP1 Converts data without truncating at the first null '\0' char-
acter or altering the null character
OCONV Codes
303
OCONV
Code Format
MO Octal
MR Right justify
MT System time
MX Hexadecimal (also HEX)
S SOUNDEX conversion
OCONV Codes (continued)
304
OCONV Date (D)
OCONV Date (D)
Syntax
Description
The date (D) code converts an integer into a corresponding date. The conv.code.expr
takes the following form:
D {y} {c} {fmt} {[f1, f2, f3]}{Month}
D indicates a date. y is a digit from 1 to 4 indicating the number of digits for the year,
the default value is 4. c is the separation character.
The internal form of the date takes the number 0 as December 31, 1967 and increases
by one for each day thereafter. Dates previous to this date are negative. Dates are out-
put in the following forms:
mm dd yy{yy}
day month year
The space between digits can be replaced with any delimiter symbol (slash, period,
comma, asterisk, etc.).
Note The UniData ECL UDT.OPTIONS 4 ON converts the text of dates to upper
case letters. For instance, May 13, is converted to MAY 13.
The fmt variable allows you to specify an output format. The following table describes
the valid output format codes.
Code Description
D Specifies the day of the month (used with M and Y options).

E Indicates the date being converted is in international format
(day, month, year) instead of the standard format (month,
day, year).
I Converts to an internal date format.
J Specifies Julian format, printing out the number of days
since the beginning of the year (used only with the Y option
specified below).
OCONV Date Output Format Codes
305
OCONV Date (D)
Code Description
M Specifies the month. Can be used with one of the fmt modi-
fiers to specify an alphabetic month.
Q Converts to quarter numeric format.
QA Converts to quarter alphanumeric format.
W Converts to weekday numeric format.
WA Converts to weekday alphanumeric format.
Y Specifies the year.
OCONV Date Output Format Codes (continued)
Note Following SMA-Standards, UniBasic treats Monday as the first day of the
week (1). The UniData ECL UDT.OPTIONS 29 ON converts Sunday to 7
instead of 0.
The fmt option can be used with one of the above format modifiers to alter the output
of the converted date. The options can consist of A,Z and/or a value between 1 and 32.
The number and letter used indicate to the system an alphabetic month. If A is used
with a 3 (A3) the month is be printed with a three-digit abbreviation (JUN); otherwise,
the entire month name is printed. Z suppresses leading zeros (if day is 01 it prints 1). Z
can also be used with a numeric value; if the value is 0, the item is suppressed.
fmt values (F1, F2, F3) must be specified with a corresponding MDY indicator.
Note If the output string is invalid or if the conversion code is invalid, the system
produces a run-time error.
Examples
In the following example, the program statement prints a three-character month name,
zero-suppresses the numeric day, and prints a four-digit year, (suppressing zeros if
necessary).
MDYA3,Z,Z4
306
OCONV Date (D)
In the next example, some sample format codes are applied to values and the results
are shown.
Value Code Result
6468 D 12 Sep 1985

6468 D2/ 09/15/85
0 D2* 12*31*67
0 D4/ 12/31/1967
7334 D 29 Jan 1988
7334 DDMY,A,Z4 29 January 1988
7334 DDMY,A3 29 Jan 1988
7334 DDMY 29 01 1988
7334 DD 29
7334 DM 01
01/29/88 DI 7334
7334 DW 5
7334 DWA Friday
7334 DQ 1
7334 DQA Winter
OCONV Date Examples
Related Topics
STATUS
The UniBasic STATUS function will be set for the date conversion. A value of 0 indi-
cates a successful conversion of a valid date; 1 indicates an invalid input date and 2
indicates an invalid conversion specification. A date conversion on a null returns a
STATUS of 1.
UDT.OPTIONS
The ECL UDT.OPTIONS 29 ON command converts Sunday to 7 instead of 0. For
information on UDT.OPTIONS, refer to UniData Commands Reference.
307
OCONV Date (D)
The UniData ECL UDT.OPTIONS 4 ON converts the text of dates to upper case let-
ters. For instance, May 13, is converted to MAY 13.
308
OCONV Group (G)
OCONV Group (G)
Syntax
Description
The group (G) code extracts one or more strings separated by a delimiter. The
conv.code.expr takes the following form:
G{m}*n
The following table describes each option of the conversion code.
Option Description
G Group extraction code.

m Indicates the number of strings to skip. If m is omitted no
strings are skipped (optional).
* Any single non-numeric character that is the strings sepa-
rator, or any system delimiter except a minus sign (-)
n The number of strings to be extracted.
OCONV Group Conversion Code Options
Examples
In the following example, the program segment prints “(303)”.
X = "(303)+555+0988"
PRINT OCONV(X,"G0+1")
309
OCONV Length (L)
OCONV Length (L)
Syntax
Description
The length (L) code places constraints on the length of the type of data that is returned.
The conv.code.expr takes the following form:
Ln{,m}
The following table describes each option of the conversion code.
Option Description
L Length conversion code.

n By itself, used as the exact number of characters the
defined attribute data value must match. When “m” is
present, “n” equals the minimum length parameter of a
length range.
m Equals the maximum data length parameter when present.
OCONV Length Conversion Code Options
Examples
In the following example, the program segment prints “123” and a null since X is less
than five characters and greater than 3. A null prints since Y is longer than five charac-
ters.
X = 123; Y = 456789
PRINT OCONV(X,"L3,5")
PRINT OCONV(Y,"L3,5")
310
OCONV Masked Character (MC)
Syntax
Description
The mask character (MC) code converts alphabetic characters to upper or lowercase,
or extracts alphabetic or numeric characters from strings.
The following table describes the valid masked character format code.
Code Function
MCA Extracts and prints all alphabetic characters, deletes non-

alphabetic characters.
MC/A Extracts all non-alphabetic characters from the data and
deletes all other characters.
MCB Extracts just the alphabetic and numeric values from the
input string.
MC/B Extracts just the characters that are neither alphabetic nor
numeric.
MCC;x;y Converts all occurrences of substring x to substring y in the
input string.
MCDX or Converts the decimal value to its equivalent hex value.
MCX
MCL Converts data to lower case.
MCN Extracts all numeric characters (0-9) from the data and
deletes all other characters.
MC/N Extracts all non-numeric characters and deletes all numeric
characters.
MCP Converts all non-printable characters in the input string to
tildes (~).
OCONV Masked Character Format Codes
311
Code Function
MCT Converts all uppercase characters to lowercase starting

from the second character in each word. Changes the first
character of a word from lowercase to uppercase.
MCU Converts data to uppercase.
MCXD or Converts the hex value to its decimal equivalent.
MCD
OCONV Masked Character Format Codes (continued)
312
OCONV Masked Decimal (MD)
Syntax
Description
The masked decimal (MD) code outputs a decimal string based on the conv.code.expr.
The str.expr can be any numeric value with related numeric formatting codes. Minus
signs, brackets (indicating a negative value), dollar signs, commas, decimal points and
the two special suffixes CR and DB (indicating negative or positive value) are
allowed.
The masked decimal (MD
BASICTYPE
The conv.code.expr has the following syntax:
MDn {f} {,} {$} [- | < | E | C | D] {P} {Z} {T} {xc} {E}
The MDn is required and indicates a Masked Decimal conversion with n places past
the decimal point. n can be a number between 0 and 9. f is an optional scaling factor
between 0 and 9. If you do not specify f, it is assumed to be equal to n (if the P option
is used, neither f nor n is used). The following table describes the optional OCONV
masked decimal codes.
Code Description
, Inserts commas to separate thousands, millions, etc.

$ Prefixes the output with a dollar sign ($).
- Specifies the negative sign (for negative data) trails the number.
< or E Specifies negative data is surrounded by brackets.
C Specifies negative data is followed by a ‘CR’ (indicating a credit).
D Specifies negative data is followed by a ‘DB’ (indicating a debit).
P Specifies that no scaling is performed. Data is assumed to contain
a decimal point (causes the ‘f’ and ‘n’ codes to be ignored).
Z Specifies that numeric 0 be output as null (zero suppress).
T Specifies data being output is truncated, not rounded.
OCONV Masked Decimal Format Codes
313
Code Description
xc Specifies the character ‘c’ is used to mask any spaces left after the
data has been formatted for output. The ‘x’ indicates the size of
the mask. If a dollar sign is present it appears in the left most posi-
tion of the attribute before the mask.
OCONV Masked Decimal Format Codes (continued)
If the conversion is unsuccessful, or if the input value is null, the returned value is
null.
Examples
The following table describes some OCONV masked decimal conversion codes and
their results.
Input Code Result
1234 MD2,$ $12.34

-912391 MD2$,- $9,123.91-
912391 MD2$,D $9,123.91DB
456789 MD2$,11* $**4,567.89
OCONV Masked Decimal Examples
314
OCONV Left Justify (ML)
Syntax
Description
The left justify (ML) justifies text or a number. str.expr can be any valid text or a
numeric value with or without a decimal. The conv.code.expr has the following syn-
tax:
MLn {f} {,} {$} {C} {Z} [(format.code)]
ML is required and indicates a left justify conversion. n can be a number between 0
and 9. f is an optional scaling factor between 0 and 9. If you do not specify f, the sys-
tem assumes f is equal to n. The internal format produced is a simple integer number.
If n is less than the number of digits right of the decimal point, the resulting value is
rounded before truncating excess digits. The following table describes the optional
OCONV left justify codes.
Code Description

C Specifies negative data is followed by a ‘CR’ (indicating a
credit).
OCONV Left Justify Format Codes
If the conversion to external format is unsuccessful, the system returns the original
value.
Examples
In the following example, the system converts the value 123456789 to 123-45-6789.
OUTPUT.VAL = OCONV("123456789","ML(###-##-####)")
315
Related Topics
ICONV
The UniBasic ICONV function converts string or numeric data from external format
to internal format based on conversion codes.
316
OCONV Packed Decimal (MP)
OCONV Packed Decimal (MP)
Syntax
OCONV(expr, MP)
Description
The packed decimal (MP) code converts an integer in packed decimal representation
into its external format. The ICONV function also has an MP code, which performs
the input conversion.
317
OCONV Packed Decimal (MP1)
OCONV Packed Decimal (MP1)
Syntax
OCONV(expr, MP1)
Description
The packed decimal (MP1) code converts an integer in packed decimal representation
into its external format without truncating at the first null ‘\0’ character nor altering
the null character.
318
OCONV Right Justify (MR)
Syntax
Description
The right justify (ML) justifies text or a number. str.expr can be any valid text or a
numeric value with or without a decimal. the conv.code.expr has the following syntax:
MRn {f} {,} {$} {C} {Z} [(format.code)]
MR is required and indicates a right justify conversion. n can be a number between 0
and 9. f is an optional scaling factor between 0 and 9. If you do not specify f, the sys-
tem assumes f is equal to n. The internal format produced is a simple integer number.
If n is less than the number of digits right of the decimal point, the resulting value is
rounded before truncating excess digits. The following table describes the optional
OCONV right justify codes.
Code Description

C Specifies negative data is followed by a ‘CR’ (indicating a
credit).
OCONV Right Justify Format Codes
If the conversion to external format is unsuccessful, the system returns the original
value.
Examples
In the following example, the system converts the value 123456 to 1,234.56.
OUTPUT.VAL = OCONV("123456","MR2$,")
319
Related Topics
ICONV
The UniBasic ICONV function converts string or numeric data from external format
to internal format based on conversion codes.
320
OCONV Time (MT)
OCONV Time (MT)
Syntax
Description
The time (MT) code converts the internal time of day from an integer between 0 and
86400 (the number of seconds in a day) to the format you specify. The conv.code.expr
follows the following format:
MT {H} {S} {c}
The MT is required to indicate a time conversion. The optional values are H, which
indicates a 12-hour format with AM or PM suffixes; S indicates that seconds are to be
included in the output and c is the separation character. The default separation charac-
ter is the colon (:). Time is output in the following form:
HH MM {SS}
If an invalid string is input to the MT conversion, a run-time error message will be
produced. The UniBasic STATUS function will be set to 1 if the input string contains
any invalid characters.
Examples
The following table describes some OCONV Time codes and their results.
Value Code Result
4500 MT 01:15
4500 MTS, 01:15:00
4500 MTS, 01,15,00
OCONV Time Examples
321
OCONV Hex (MX), Octal (MO), Binary (MB)
Syntax
Description
The hex (MX), octal (MO), and binary (MB) conversion codes convert data from dec-
imal into different bases. The conv.code.expr takes the following forms:
Conversion Code Description
MX or HEX {0C} Hex (base 16) conversion

MO {0C} Octal (base 8) conversion
MB {0C} Binary (base 2) conversion
OCONV Base Conversion Codes
The MX (or HEX), MO, and MB are the conversion codes used with the appropriate
str.expr. The optional 0C indicates you want the input data to be converted to an
ASCII code format. Using the 0C option may result in more than one ASCII character.
Using 0C with binary results in taking each group of eight characters and converting
to ASCII. With octal, each group of three characters is converted. With hex, each
group of two characters is converted.
The system produces a run-time error message if the conversion code is invalid.
Examples
The following table describes some OCONV MX, MO, and MB conversion codes and
their results.
Input Code Result
SSS MO0C 123123123

y MO0C 171
256 MX 100
5 MB 00000101
OCONV Hex, Octal, and Binary Examples
322
Input Code Result
33288 MO 101010
Qat MX0C 516174
U MB0C 01010101
OCONV Hex, Octal, and Binary Examples (continued)
323
OCONV Pattern Match (P)
OCONV Pattern Match (P)
Syntax
Description
The pattern match (P) code returns only those data values that match a specified pat-
tern. If data does not match exactly the stipulated pattern, null is returned. The
P(op){;(op).....}
The following table describes the elements of the OCONV pattern match conversion
code.
Option Description
P PATTERN MATCH code.

op Literal or pattern match operator.
OCONV Pattern Match Conversion Code Elements
The following table describes the valid pattern match operators. Any combination of
the following pattern match operators are allowed.
Operator Description
#N Integer followed by letter “N”, testing for that number of

numeric characters.
#A Integer followed by letter “A”, testing for that number of
alpha characters.
#X Integer followed by the letter “X,” testing for that number
of alphanumeric characters.
“LITERAL” Literal string, testing for that literal string.
Pattern Match Operators
324
OCONV Range (R)
OCONV Range (R)
Syntax
Description
The range (R) code returns only those data values that fall within specified ranges.The
Rn,m{;n,m.....}
The following table describes the OCONV range valid conversion code options.
Option Description
n Minimum range parameter.

m Maximum range parameter.
OCONV Range Conversion Code Options
When implementing negative ranges, you must specify the highest negative number
must first. Any delimiter (such as a semicolon or comma), except system delimiters,
can be used to separate the numbers in a range. The minus sign (-) should not be used
as a delimiter since it might refer to a negative number in the range. If range specifica-
tions are not met, the system returns a null.
Examples
In the following example, the program segment prints “123” and a null since X is
within the range and Y is not.
X = 123; Y = 456789
PRINT OCONV(X,"R100,200")
PRINT OCONV(Y,"R100,200")
325
OCONV (S)
OCONV (S)
Syntax
Description
The SOUNDEX (S) code converts string or numeric data from internal representation
format to a phonetic output format based on SOUNDEX conversion codes. The S con-
version code may be used in an OCONV virtual attribute formula to convert alpha-
betic characters to their SOUNDEX equivalent.
Note For more information on SOUNDEX conversion codes, refer to the

SOUNDEX command.
Examples
In the following example, the virtual attribute SDX_LNAME has the following for-
mula that converts LNAME to its SOUNDEX expression:
OCONV(LNAME,"S")
326
OCONV Text Extraction (T)
OCONV Text Extraction (T)
Syntax
Description
The text extraction (T) code extracts a fixed attribute from an attribute value. The
“T{m,}n”
When this conversion is applied to a string, the OCONV function extracts a contigu-
ous string of characters of length n, starting from character m.
If “Tn” is indicated, n characters are extracted from left to right. If “Tm,n” is indi-
cated, n characters starting at column m are extracted.
Examples
The following table describes some OCONV Text Extraction codes and their results.
Input Code Result
QRSTUV “T3” QRS

DAMN THE TORPEDOES “T3,5” MN TH
CONVERSION IS THE KEY “T1,9” CONVERSIO
457 COLORADO BLVD “T3,7” COLORA
OCONV Text Extraction Examples
327
OCONV File Translation (Tfile)
Syntax
OCONV(id.expr, conv.code.expr)
Description
The file translation (Tfile) allows you to retrieve attributes from another file. The
conv.code.expr has the following syntax:
T{DICT} [filename;cn;I-Attribute;O-Attribute]
where id.expr evaluates to an ID in the file (i.e., filename)
The following table describes the elements of the conversion code expression.
T Code name.
DICT Translates to the dictionary of the file indicated by its
filename.
filename Name of the file where the translation is directed (any
valid UniData file in your VOC file containing the
required attribute or data).
c One of the following translate subcodes:
VIf the record does not exist or if the attribute is null,
returns a null value and prints an error message.
CIf the record does not exist or attribute is null, it substi-
tutes id.expr for the value of the function.
XIf the record does not exist or the attribute is null, the
system returns a null.
n If an attribute is retrieved from a translated attribute and is
multivalued, it indicates which value to retrieve. If n is not
indicated, the system retrieves all values of the attribute.
I-Attribute Decimal number of the attribute to be retrieved during
input conversion (ICONV). If I-Attribute is omitted, the
system assumes 0 and retrieves the record ID.
OCONV File Translation Conversion Code Elements
328
O-Attribute Decimal number of attribute to be retrieved during output

conversion (OCONV). If the O-Attribute is omitted, the
system assumes 0 and retrieves the record ID.
OCONV File Translation Conversion Code Elements (continued)
Examples
In the following example, the program statement translates the TAPE_ID to the
TAPES file and returns the name of the tape.
TAPE_ID = CUSTOMER.REC<7,X>
TAPE_NAME = OCONV("TAPE_ID","TTAPES;X;;1")
329
OCONVS
OCONVS
Syntax
OCONVS(dyn.array.expr, conv.code.expr)
Description
The UniBasic OCONVS function converts string or numeric data from internal format
to output format based on a conversion code, for each element of a dynamic array.
Note OCONVS conversion codes are the same as OCONV conversion codes. For
information on conversion codes, refer to “OCONV”.
Parameters
dyn.array.expr Specifies a dynamic array, each element of

which to convert.
conv.code.expr Specifies a conversion code to use in convert-
ing each element of the dynamic array.
OCONVS Parameters
Examples
In the following example, the program segment converts each element of ARR1 to an
output format.
ARR1 = 1234:@VM:5678:@VM:9876
ARR2 = OCONVS(ARR1,MR2$)
ARR2 now contains:

ARR2 = $12.34$:@VM:56.78:@VM:$98.76
330
ON/GOSUB
ON/GOSUB
Syntax
ON expr GOSUB label[:][, label[:]...]
Description
The UniBasic ON/GOSUB command transfers program control to one of a list of sub-
routine labels, based on a numeric expression.
ON GOSUB may appear on one line, or may be spread over as many successive lines
as necessary. Labels that appear must be separated by commas.
When the program encounters a RETURN statement in the called subroutine, the sys-
tem transfers control back to the statement immediately following the ON GOSUB
statement. If the subroutine contains a RETURN TO label statement, control resumes
at the label you specify in the RETURN statement.
Parameters
expr Specifies a numeric value, indicating which

label to transfer program control to.
The system evaluates the expression and then
truncates it to an integer with the following
rules.
• If the resulting number is less than or equal to
one, the system transfers program control to
the subroutine starting at the first label in the
list. If the expression evaluates to two, the sys-
tem transfers control to the subroutine starting
at the second label, and so forth.
• If the number is higher than the number of
labels, the system transfers control to the last
label in the list.
• If the value of the expr is non-numeric, con-
trol branches to the first label.
ON/GOSUB Parameters
331
ON/GOSUB
label Specifies a label to which to transfer program

control, depending upon expr.
ON/GOSUB Parameters (continued)
In BASICTYPE P or M, if expr is non-numeric or less than one, the system

BASICTYPE
bypasses the GOSUB clause and the next program statement executes.
Examples
In the following example, the program segment divides the variable BALANCE by
100. If the result is less than or equal to one, the program transfers control to subrou-
tine U100. If the value is two, it transfers control to U200, etc. If the value is greater
than or equal to four, then the system transfers control to subroutine U400.
ON BALANCE/100 GOSUB U100,U200,U300,U400
In the next example, the program segment transfers control to a subroutine after
prompting the user for a screen item to modify. In this case, depending on the number
the user enters, the system transfers control to one of the five subroutines in the
GOSUB clause. If the data the user enters is non-numeric or less than 1, the system
transfers control to the first subroutine. If the user enters a value greater than 5, the
system transfers control to the last subroutine (500).
GOSUB DISPLAY.SCREEN:
PRINT "Enter Item number to modify (1-5): ":
INPUT ACTION
ON ACTION GOSUB 100,200,300,400,500
Related Topics
GOSUB
ON/GOTO
The UniBasic ON/GOTO command transfers program control to a statement label.
332
ON/GOTO
ON/GOTO
Syntax
ON expr GOTO label1[:] [, label2[:] ...]
Description
The UniBasic ON/GOTO command transfers program control to a statement label
based on a numeric expression.
The ON GOTO statement, like the GOTO statement, is a one-way transfer of program
control within the main program. If you use an ON GOTO statement to transfer con-
trol to a subroutine with a RETURN statement, the subroutine’s RETURN statement
only works if a previous GOSUB statement is still waiting for a RETURN in the sub-
routine, otherwise the program aborts with a run-time error.
Parameters
expr Specifies a numeric value, indicating which

label to transfer program control to.
The system evaluates the expression, then trun-
cates it to an integer with the following rules:
• If the resulting number is less than or equal to
one, the system transfers program control to
the first label in the list. If the expression eval-
uates to two, the system transfers program con-
trol to the second label, and so forth.
• If the value of the expression is higher than
the number of labels, the system transfers con-
trol to the last label in the list.
• If the value of expr is non-numeric, the sys-
tem transfers control to the first statement
label.
ON/GOTO Parameters
333
ON/GOTO
label Specifies a label to which to transfer program

control, depending upon expr.
Any label in an ON GOTO statement that does
not exist as a statement label causes an error
during program compilation.
ON/GOTO Parameters (continued)
In BASICTYPE P or M, if expr is non-numeric or less than one, the system

BASICTYPE
bypasses the GOTO clause and the next program statement executes.
Examples
In the following example, the program statement transfers program control to the
statement label TEST if the variable X is less than or equal to 1. If X is 2, the system
transfers control to statement label 2500. If X is greater than or equal to 3, the system
transfers control to statement label YESNO.
ON X GOTO TEST,2500, YESNO:
Related Topics
ON/GOSUB
The UniBasic ON/GOSUB command transfers program control to a subroutine.
334
OPEN
OPEN
Syntax
OPEN “expr”, “filename” [READONLY] [TO file.var] [ON ERROR statements]
Description
The UniBasic OPEN command opens a file, allowing you to read, write, or delete the
file.
Tip Use OPEN to open UniData hashed files to be read with the READ command
and written to with the WRITE command.
The INMAT function returns the file modulos after the execution of an OPEN state-
ment. If the file is a directory or DIR type, INMAT returns 0.
Parameters
“expr” expr must evaluate to either DICT or null (“”). If expr

evaluates to null, it opens a data file. If expr evaluates
to DICT, it open a dictionary file.
“filename” Specifies the name of the file to open.
[READONLY] If you use the READONLY keyword, the system
opens the file for reading only. The system does not
permit any write statements of any sort on the file. If
you attempt a WRITE statement, the system displays
a run-time error message and does not update the file.
You should not use the READONLY option if the
user wishes to modify the file. READONLY is pro-
vided in conjunction with the UniData security sys-
tem. For information on security procedures, refer to
Administering UniData on UNIX.
OPEN Parameters
335
OPEN
[TO file.var] Specifies a file variable in which to place the opened

file. If you do not specify a TO clause with a file vari-
able file.var, the file you open becomes the current
default file. Until you open another file without a file
variable, the system performs all default file state-
ments (read, write, clear, or delete) on this file. If you
open a subsequent file using a file variable name, the
file you originally opened remains the default file.
Default files are specific to the program or subroutine
[TO file.var] that executes the OPEN statement. If a main program
(continued) opens a file (as the default file), and then calls an
external subroutine that also opens a different default
file, the system restores the original default when
returning to the main program. Additionally, when
you call a subroutine without an OPEN statement, the
default file remains unassigned within the subroutine.
[ON ERROR The ON ERROR clause allows the program after the
statements] OPEN statement to continue to perform under the fol-
lowing fatal error conditions: if the file is not open, if
the file is a UniData hashed file, if the file contains an
open index error, or if the file description is incorrect.
If you do not specify the ON ERROR clause, the pro-
gram terminates under such fatal error conditions. If
you specify the ON ERROR clause and the file does
not exist in the VOC file, or the file description in the
VOC file is incorrect, or the file permission is inade-
quate, the system performs the ELSE clause.
OPEN Parameters (continued)
336
OPEN
{THEN | ELSE} You only need a THEN or an ELSE clause. If you use
statements THEN, you do not have to use ELSE. The system
[END] requires an END statement when you use THEN or
ELSE with multiple lines.
The system executes the ELSE clause statements if
the following conditions exist: if you specify a file
variable and that file cannot be found; if you do not
specify a file and if there is no default file. UniBasic
allows you to open an unlimited number of files in
any given program. For information on file perfor-
mance, refer to Administering UniData on UNIX.
Multiple statements may appear after THEN, ELSE,
or LOCKED. If the statements are placed on multiple
lines, an END at the end of the statement is required.
The statements can also be placed on the same line
with the appropriate keyword, separated by semi-
colon(s), without using END.
OPEN Parameters (continued)
Examples
In the following example, the program statement opens the data file ACCREC as a
read-only file. Since you do not specify a file variable, ACCREC becomes the current
default file.
OPEN ’’, ’ACCREC’ READONLY ELSE STOP ’Cannot open ACCREC’
In the next example, the program statement opens the dictionary file ACCPAY,
assigning it to the file variable AP. If the system does not find the file, “File Not
Found” displays.
OPEN ’DICT’, ’ACCPAY’ TO AP ELSE PRINT ’File Not Found’
In the next example, the program segment opens the CUSTOMER file to the file vari-
able CUST. If it is not found, the system executes the ELSE statements, printing an
error and setting a flag to 1.
OPEN ’’, CUSTOMER’ TO CUST ELSE
PRINT ‘NO CUSTOMER’
OPEN.ABORT = 1
END
IF OPEN.ABORT THEN PRINT ’Aborting on open error’;STOP
337
OPEN
Related Topics
CLOSE
The UniBasic CLOSE command closes a file that has been opened with the OPEN
command.
INMAT
The UniBasic INMAT function displays the status of statements that were executed.
338
OPENSEQ
OPENSEQ
Syntax
OPENSEQ seq.filename, record.id [READONLY] TO seq.file.var
[ON ERROR statements] [LOCKED statements] {THEN | ELSE} statements [END]
Description
The UniBasic OPENSEQ command opens a sequential file for access, starting at the
record you specify. Once you open a record, you can read it using the READSEQ
command.
Use OPENSEQ to open files that use CHAR(10) as a delimiter. You can then
Tip use READSEQ to read the next line delimited by CHAR(10) and WRITESEQ
to write a line delimited by CHAR(10).
The STATUS function is set to the following values after you execute an OPENSEQ
statement.
• 0 if the record in the file you specify does not exist.
• 1 if the file you specify is not a sequential-access file.
• 2 if the file does not exist.
• 3 if you use the READONLY clause and the record does not exist.
• 4 if you use the STATUS function after OPENSEQ, indicating an
unknown error (such as having too many files open or permission prob-
lems).
Parameters
seq.filename Specifies a UniData directory type file name.

record.id Specifies a record in the sequential file at
which to start accessing.
OPENSEQ Parameters
339
OPENSEQ
[READONLY] Specifies that the system open the file for

reading only.
The system does not permit any write state-
ments of any sort on the file. If you attempt a
WRITE statement, the system displays a run-
time error message and does not update the
file. You should not use the READONLY
option if the user wishes to modify the file.
READONLY is provided in conjunction with
the UniData security system. For information
on security procedures, refer to Administering
UniData on UNIX.
TO seq.file.var Specifies a file variable to use to reference the
file you open.
[ON ERROR Specifies statements to execute in the event of
statements] a fatal error condition ( if the existing sequen-
tial file is not open, or if the number of sequen-
tial files exceeds 150).
the program terminates under any fatal error
conditions. If you specify the ON ERROR
clause and the system cannot open the existing
sequential file, or if the record.id does not
exist, the system performs the ELSE clause.
[LOCKED statements] Specifies statements to execute if the file is
locked by another user.
OPENSEQ Parameters (continued)
340
OPENSEQ
{THEN | ELSE} Specifies statements to execute if the file does

statements [END] not exist.
You only need a THEN or an ELSE clause. If
you use THEN, you do not have to use ELSE.
The system requires an END statement when
you use THEN or ELSE with multiple lines.
Multiple statements may appear after THEN,
ELSE, or LOCKED. If the statements are
placed on multiple lines, an END at the end of
the statement is required. The statements can
also be placed on the same line with the appro-
priate keyword, separated by semi-colon(s),
without using END.
OPENSEQ Parameters (continued)
Examples
In the following example, the program statement opens the sequential file FILMS in
the directory DAYLOG, assigning it the file variable FILM.LOG.
OPENSEQ ‘DAYLOG’,‘FILMS’ TO FILM.LOG ELSE GOTO CLOSED:
Related Topics
READSEQ
The UniBasic READSEQ command assigns the next record from a previously opened
sequential file to a variable.
WRITESEQ
file.
WRITESEQF
file and forces the system to physically write the data to the disk.
File Input/Output
For information on file input/output, refer to Developing UniBasic Applications.
341
OPENSEQ
STATUS
342
OSBREAD
OSBREAD
Syntax
OSBREAD var FROM file.var AT byte.expr LENGTH length.expr
Description
The UniBasic OSBREAD command reads data from a file starting at a byte location
for a certain length of bytes, assigning the data to a variable. OSBREAD performs an
operating system block read on a UNIX or VMS file. The OSBREAD command
allows you to read a specified block for processing.
Reminder You must first open the file using the OSOPEN command.
Note UniData uses the ASCII 0 character (CHAR(0)) as a string-end delimiter.

Therefore, ASCII 0 cannot be used in any string variable within UniBasic.
OSBREAD converts CHAR(0) to CHAR(128) when reading a block of char-
acters.
The STATUS function is set to the following values after you execute an OSBREAD
statement.
• 0 if the read is successful.
• 1 for an invalid filename.
• 2 if access is denied by the operating system.
• 5 for any other undefined error.
Parameters
var Specifies a variable to which to assign the data

read.
OSBREAD Parameters
343
OSBREAD
FROM file.var Specifies a file from which to read the data.

AT byte.expr Specifies a location in the file from which to
read the data.
If byte.expr is 0, the read begins at the
beginning of the file.
LENGTH length.expr Specifies a length of data to read from the file,
starting at byte.expr.
length.expr may not be longer than the maxi-
mum string length determined by your system
configuration.
occurs (if the file is not open, or if the file is a
read-only file). If you do not specify the ON
ERROR clause, the program terminates under
such fatal error conditions.
OSBREAD Parameters (continued)
Examples
In the following example, the program statement reads 10,000 bytes of the file RFILE
starting from the beginning of the file and assigns that data to the variable TEST.
OSBREAD TEST FROM ’RFILE’ AT 0 LENGTH 10000
In the next example, the program segment reads 15000 bytes from a UNIX or VMS
file, starting at the first byte. It then converts ASCII value 10 (a line feed) to a value
mark and processes each line sequentially.
OSBREAD BLOCK FROM INPUT.DIR AT 0 LENGTH 15000
CONVERT CHAR(10) TO @FM IN BLOCK
LOOP
REMOVE REC FROM BLOCK SETTING MORE.RECS
GOSUB PROCESS.REC:
WHILE MORE.RECS REPEAT
Related Topics
OSOPEN
The UniBasic OSOPEN command opens a UNIX or VMS sequential file.
344
OSBREAD
OSBWRITE
The UniBasic OSBWRITE command writes data to a file starting at a byte location.
345
OSBWRITE
OSBWRITE
Syntax
OSBWRITE expr {ON | TO} file.var AT byte.expr [ON ERROR statements]
Description
The UniBasic OSBWRITE command writes an expression to a file starting at a spec-
ified byte location. OSBWRITE is a sequential write that writes a file segment directly
out to the UNIX or VMS file.
You do not have to specify a length expression since only the number of bytes in expr
is written to the file.
Reminder You must first open the file using the OSOPEN command.
UniData uses the ASCII 0 character (CHAR(0)) as a string-end delimiter. Therefore,

ASCII 0 cannot be used in any string variable within UniBasic. If a string is read into
UniBasic with a CHAR(0) character and converted to CHAR(128), this command
converts CHAR(128) back to CHAR(0) when writing a block of characters.
The STATUS function is set to the following values after you execute an OSBWRITE
statement.
• 0 if the write was successful.
• 1 for an invalid filename.
• 2 if access is denied by UniData.
Parameters
expr Specifies the expression to write to the file.

{ON | TO} file.var Specifies the file variable to which to write the
expression.
OSBWRITE Parameters
346
OSBWRITE
AT byte.expr If byte.expr is 0, the write begins at the

beginning of the file.
statements] a fatal error condition ( if the file is not open, or
if the file is a read-only file). If you do not
specify the ON ERROR clause, the program
terminates under such fatal error conditions.
OSBWRITE Parameters (continued)
Examples
In the following example, the program statement writes the data in TEST to the file
RFILE starting from the beginning of the file.
OSBWRITE TEST ON RFILE AT 0
In the next example, the program segment reads REC.ID from a select list, reads the
associated record from the CUST file and appends the record onto a variable
(BLOCK), terminating each record with an ASCII 10 (or line feed). When it is com-
plete, the code writes the block to the UNIX filename opened to the variable
CUST.SEQ.
DONE = 0
LOOP
READNEXT REC.ID ELSE DONE = 1
UNTIL DONE DO
READ REC FROM CUST,REC.ID ELSE REC = ’ ’
IF REC THEN
REC = REC.ID:@FM:REC
BLOCK := REC:CHAR(10)
END
REPEAT
OSBWRITE BLOCK ON CUST.SEQ AT 0
Related Topics
OSOPEN
OSBREAD
The UniBasic OSBREAD command reads data from a file starting at a specified byte
location.
347
OSCLOSE
OSCLOSE
Syntax
OSCLOSE file.var [ON ERROR statements]
Description
The UniBasic OSCLOSE command closes a sequential file (including the path name
from the root directory) that you have opened with the OSOPEN statement.
The STATUS function is set to 0 if the file is closed successfully, or to 5 if the close
fails.
Parameters
file.var Specifies the file varible to close.

statements] a fatal error condition (if the file is not open). If
you do not specify the ON ERROR clause, the
program terminates under this fatal error
condition.
OSCLOSE Parameters
Examples
In the following example, the program statement closes the file UNDEF.
OSCLOSE UNDEF
Related Topics
OSOPEN
348
OSDELETE
OSDELETE
Syntax
OSDELETE filename [ON ERROR statements]
Description
The UniBasic OSDELETE command deletes a UNIX or VMS sequential file.
The STATUS function is set to the following values after you execute an OSDELETE
statement.
• 0 if there is no error.
• 1 for an invalid directory.
• 2 if the system cannot access the file (permissions, etc.).
• 4 if the specified file does not exist.
• 5 if there is any other undefined error.
Parameters
filename Specifies the file to delete. filename must

include the file pathname. If you do not specify
a path name, the system searches the current
directory.
statements] a fatal error condition (if the system cannot
open the file, or if an I/O error occurs in the
read accessing process). If you do not specify
the ON ERROR clause, the program terminates
under such fatal error conditions.
OSDELETE Parameters
349
OSDELETE
Examples
In the following example, the program statement deletes the file NAMES in the cur-
rent directory.
OSDELETE "NAMES"
In the next example, the program statement deletes the file cust.rec in the UNIX sub-
directory /u/trans.
OSDELETE ’/u/trans/cust.rec’
Related Topics
File Input/Output
350
OSOPEN
OSOPEN
Syntax
OSOPEN filename [READONLY] TO file.var [ON ERROR statements]
Description
The UniBasic OSOPEN command opens a sequential file for access.
Use OSOPEN to open sequential files that do not use CHAR(10) as the line
Tip delimiter. You may then use OSBREAD to read a block of data from the file,
or OSBWRITE to write a block of data to the file.
Parameters
filename Specifies the file to open. filename may contain

a pathname to the subdirectory where the file
exists.
[READONLY] Specifies that the file should be opened for
reading only. The system does not permit any
write statements of any sort on the file. If you
attempt a WRITE statement, the system dis-
plays a run-time error message and does not
update the file. You should not use the
READONLY option if the user wishes to mod-
ify the file. READONLY is provided in con-
junction with the UniData security system. For
information on security procedures, refer to
Administering UniData on UNIX or
Administering UniData on VMS.
TO file.var Specifies a variable to which to open the file.
OSOPEN Parameters
351
OSOPEN
[ON ERROR statements] Specifies statements to execute in the event of

a fatal error condition (if there is another error
in the opened file, or if the number of files
opened with OSOPEN exceeds 100). If you do
not specify the ON ERROR clause, the pro-
gram terminates under these fatal error
conditions.
If you specify the ON ERROR clause and the
system cannot find the file, or if there are inad-
equate permissions, the system performs the
ELSE clause.
{THEN | ELSE} You only need a THEN or an ELSE clause. If
statements [END] you use THEN, you do not have to use ELSE.
Multiple statements may appear after THEN or
ELSE. If the statements are placed on multiple
lines, an END at the end of the statement is
required. The statements can also be placed on
the same line with the appropriate keyword,
separated by semi-colon(s), without using
END.
OSOPEN Parameters (continued)
Examples
In the following example, the program statement opens the file INVENTORY as
INVENT. If the system cannot access the file for any reason, the file is not opened.
OSOPEN ’INVENTORY’ TO INVENT ELSE STOP "Can’t open INVENTORY"
Related Topics
OSCLOSE
The UniBasic OSCLOSE command closes a sequential file opened with the OSOPEN
command.
OSBREAD
location.
352
OSOPEN
OSBWRITE
The UniBasic OSBWRITE command writes data to a file starting at a specified byte
location.
353
OSREAD
OSREAD
Syntax
OSREAD var FROM name.expr [ON ERROR statements]
Description
The UniBasic OSREAD command reads an entire sequential file and assigns the con-
tents of the file to a variable.
Tip Do not use OSREAD on large files. If the file is too large for the program’s
memory, the program aborts and a run-time error message is generated. If this
occurs, use OSBREAD or READSEQ.

ASCII 0 cannot be used in any string variable within UniBasic. This com-
mand converts CHAR(0) to CHAR(128) when reading a block of characters.
Parameters

data from the file.
FROM name.expr The name.expr must include the entire
pathname to the file unless name.expr exists in
the current directory.
a fatal error condition (if the system cannot
open the file, or if an I/O error occurs in the
read accessing process). If you do not specify
file does not exist, the system performs the
ELSE clause.
OSREAD Parameters
354
OSREAD
{THEN | ELSE} You only need a THEN or an ELSE clause. If

Multiple statements may appear after THEN or
ELSE. If the statements are placed on multiple
lines, an END at the end of the statement is
required. The statements can also be placed on
the same line with the appropriate keyword,
separated by semi-colon(s), without using
END.
OSREAD Parameters (continued)
Examples
In the following example, the program segment reads the data stored in the VMS file
‘BILLING’ in the subdirectory ‘DSK$1:[SYS.DATA]’ and assigns it to the variable
BILL.REC.
OSREAD BILL.REC FROM DSK$1:[SYS.DATA] BILLING ELSE
PRINT "NO BILLING RECORD FOUND"
END
Related Topics
NOCONVERT
The UniBasic NOCONVERT command controls the conversion of the special charac-
ter CHAR(0).
OSWRITE
The UniBasic OSWRITE command writes a sequential file.
OSBREAD
location.
READSEQ
The UniBasic READSEQ command assigns the next record from a sequential file.
355
OSREAD
File Input/Output
356
OSWRITE
OSWRITE
Syntax
OSWRITE expr {ON | TO} filename.expr [ON ERROR statements]
Description
The UniBasic OSWRITE command writes the contents of an expression to a sequen-
tial file.

ASCII 0 cannot be used in any string variable within UniBasic. If a string is
read into UniBasic with a CHAR(0) character and converted to CHAR(128)
this command converts CHAR(128) to CHAR(0) when writing a block of
characters.
Parameters
expr Specifies the expression to write to

filename.expr.
{ON | TO} filename.expr Specifies the name of a sequential file to which
to write.
a fatal error condition (if the file is not open, or
if an I/O error occurs in the write accessing
process). If you do not specify the ON ERROR
clause, the program terminates under such fatal
error conditions.
OSWRITE Parameters
Examples
In the following example, the program segment writes the contents of MAIL.LIST to
the file called “mergefile” in the UNIX subdirectory ‘/u/maildir’.
OSWRITE MAIL.LIST ON "/u/maildir/mergefile"
357
OSWRITE
Related Topics
NOCONVERT
ter CHAR(0).
OSREAD
The UniBasic OSREAD command reads an entire sequential file and assigns it to a
variable.
File Input/Output
358
PAGE
PAGE
Syntax
PAGE [ON num.expr] [expr]
Description
The UniBasic PAGE command prints the current output page. The system prints the
page with spaces and any specified header or footer.
If you do not specify any parameters, the result depends on the last PRINTER ON or
PRINTER OFF command executed. If the last PRNTER command executed was
PRINTER OFF, the new page is generated on the user’s terminal; if the last PRINTER
command executed was PRINTER ON, the new page is generated on the system line
printer.
Parameters
[ON num.expr] Specifies the page number of the next output

page. Each subsequent page will increment by
one.
[expr] Specifies a print file to which to send the com-
pleted page, where num.expr is the number of
the appropriate file. When you specify a
num.expr, the status of the line printer
(PRINTER ON or PRINTER OFF) is
inconsequential.
PAGE Parameters
Examples
In the following example, the program statement, depending on the printer status (ON
or OFF), completes the current page with any footings, then a new page is advanced.
PAGE
359
PAGE
In the next example, the program statement sends the completed page to the file
assigned to print unit 5. If the print unit specified cannot be found, nothing is printed.
PAGE ON 5
Related Topics
For information on terminal and printer input/output, refer to Developing UniBasic
Applications.
SETPTR
Reference.
360
PCPERFORM
PCPERFORM
Syntax
PCPERFORM str.expr [CAPTURING, dyn.array.var]
Description
The UniBasic PCPERFORM command executes a UNIX or VMS command from
Note PCPERFORM is similar to the EXECUTE and PERFORM commands,

except it executes an operating system command.
Parameters
str.expr Specifies a string to execute as a host operating

system command.
[CAPTURING, Specifies a dynamic array to which to capture
dyn.array.var] the output of the host operating system
command.
PCPERFORM Parameters
Examples
In the following example, the program statement executes the SHOW TIME com-
mand at the VMS level.
PCPERFORM "SHOW TIME" CAPTURING DATE.TIME
In the following example, the program statement executes the date command at the
UNIX level.
PCPERFORM "date" CAPTURING DATE.TIME
In the next example, the program statement performs the VMS rename command,
renaming the file cust.rec to cust.save in the current VMS directory.
PCPERFORM ’rename cust.rec cust.save’
361
PCPERFORM
In the next example, the program statement performs the UNIX mv command, mov-
ing the file cust.rec to cust.save in the current directory.
PCPERFORM ’mv cust.rec cust.save’
Related Topics
EXECUTE
The UniBasic EXECUTE and PERFORM commands execute ECL commands
(UniData or UniQuery commands), sentences, or paragraphs.
MDPERFORM
The UniBasic EXECUTE command executes ECL commands (UniData or UniQuery
commands), sentences, or paragraphs, from within a UniBasic program and transfers
lists to and from the executed commands.
362
PERFORM
PERFORM
Syntax
PERFORM “str.expr” [[ASYNC | SYNC] ON connection]
[CAPTURING dyn.array.var] [RETURNING dyn.array.var]
[RTNLIST list.num.expr] [PASSLIST list.num.expr] [PASSCOM]
EXECUTE “str.expr” [[ASYNC | SYNC] ON connection]
[CAPTURING dyn.array.var] [RETURNING dyn.array.var]
[RTNLIST list.num.expr] [PASSLIST list.num.expr] [PASSCOM]
Description
The UniBasic PERFORM and EXECUTE commands execute an ECL (Environ-
mental Control Language) command from within a UniBasic program.
You may execute multiple commands with a single EXECUTE statement by separat-
ing each command within a string variable by attribute marks. When the EXECUTE
statement occurs, the system separates each command and executes them in order.
STACKCOMMON
and one program executes another program, the unnamed common is passed to the

BASICTYPE
BASICTYPE U.
BASICTYPE Compiling
When you compile EXECUTE and PERFORM in BASICTYPE P, they use a
BASICTYPE
different parser than when you compile them under BASICTYPE U. The P-
type parser scans a file of commands that are defined in the Spectrum-SMA
standards or in McDonnell Douglas’ REALITY operating system. If the com-
mand is found in this file, it will be parsed using the P-type parser. If the com-
mand is not found in the REALITY file, it will be parsed as if the program had
363
PERFORM
been compiled with BASICTYPE U. Since all REALITY commands are

upper case, using lower case commands will always result in the use of the
standard UniData parser.
Note If you want to execute a standard UniData, UniQuery, or ECL command from
within a program compiled with BASICTYPE P, you can use the UniBasic
command UDTEXECUTE.
Parameters
“str.expr” Specifies a literal string or an expression that eval-

uates to a UniData command with appropriate
parameters. You may concatenate strings with
appropriate operators. If you pass a file name to a
PERFORM command, the file name must be the
name of a file in the current account, not a file
variable that is the result of a UniBasic OPEN
statement.
[ASYNC | SYNC] ASYNC performs an asynchronous execution and
returns control to the program immediately, with-
out waiting to get the results of the EXECUTE or
PERFORM statement. To get the results, use the
WAIT command.
SYNC performs a synchronous execution and
waits for the results of the command and returns
them before continuing with the program. You can
use these parameters when developing UniDesk-
top/Open Client applications. For information on
developing these applications, refer to Developing
[ON connection] Specifies the handle to a server you specified with
the CONNECT command. You can use this
parameter when developing UniDesktop/Open
Client applications. For information on developing
these applications, refer to Developing UniDesk-
top Applications.
PERFORM Parameters
364
PERFORM
[CAPTURING, The CAPTURING clause creates a dynamic array

dyn.arrry.var] with the output, which otherwise would appear on
the display terminal. Each line of the text becomes
an attribute in the array. Output you direct to the
printer is not affected by this clause and is still
sent to the printer.
You can nest CAPTURING clauses. Currently the
embedded level is set to 2.
The position of the CAPTURING and
RETURNING clauses are interchangeable.
UniBasic syntax does not require the CAPTUR-
ING clause to appear before the RETURNING
clause.
[RETURNING, The RETURNING clause captures the error mes-
dyn.array.var] sages from the command you execute with
PERFORM into a string variable. This variable is
a string of error message numbers separated by
spaces. If the command you execute creates a
spooler hold file, the system also enters the hold
file entry number into the returning variable.
[RTNLIST int.expr] The RTNLIST clause specifies an expression that
must evaluate to an integer zero through nine, des-
ignating the list to return back to the calling pro-
gram in BASICTYPE P. You can use the resulting
list with subsequent READNEXT statements or in
the PASSLIST clause of a PERFORM statement.
If an expression is not given after RTNLIST, the
generated list replaces the contents of list 0. If you
do not specify the RTNLIST clause, then a list
does not return.
RTNLIST does not have an effect on the UniBasic
process. In other words, if the called program is a
UniBasic program, a list does not return even
though you specify a RTNLIST. On the other
hand, PASSLIST is always effective and transfers
the a list to the called program.
PERFORM Parameters (continued)
365
PERFORM
[PASSLIST int.expr] The PASSLIST clause specifies an expression that

must evaluate to an integer 0, 1 or 2, designating
the select list to be sent to the called processor.
The passed list can be the result of previous
SELECT or GETLIST commands or the
RTNLIST clause of an PERFORM statement. If
you do not specify list.num.expr, list 0 is assumed.
Only the specified list is passed to the performed
command, the other lists in UniBasic environment
are not passed.
[PASSCOM] The PASSCOM clause is available for backward
compatibility with releases prior to 3.1.
PERFORM Parameters (continued)
Reminder The error message numbers you capture with RETURNING will vary,
depending upon which version of UniData you are running.
Examples
In the following example, the program statement performs the command in cmd3 and
sends output to a dynamic array cpt_var.
PERFORM cmd3 CAPTURING cpt_var
In the next example, the program statement execute a UniQuery command.

PERFORM "SELECT PERSONNEL WITH WAGETYPE = ’1’"
In the next example, the program segment executes a variable containing a UniData
command.
LIST.PER = "LIST PERSONNEL WAGETYPE AGE"
PERFORM LIST.PER
In the next example, the EXECUTE statement creates a record ID list using the
SELECT statement for processing within the program. This is done in conjunction
with a READNEXT statement.
EXECUTE "SSELECT CUST"
EOF = 0
LOOP
READNEXT CUST.ID ELSE EOF =1
UNTIL EOF DO
*statements
REPEAT
366
PERFORM
In the next example, the program segment executes a paragraph from within a UniBa-
sic program using the EXECUTE statement:
PARA = "PA":@AM:"DISPLAY HELLO"
EXECUTE PARA
This displays “HELLO” on the terminal.
Related Topics
EXECUTESQL
The UniBasic EXECUTESQL command passes an SQL statement directly to the Uni-
Data SQL processor.
PCPERFORM
The UniBasic PCPERFORM command executes a UNIX or VMS command.
MDPERFORM
The UniBasic MDPERFORM command executes various UniData commands, sen-
tences, or paragraphs, and transfers lists to and from the executing commands.
UDTEXECUTE
The UniBasic UDTEXECUTE command executes a command in ECLTYPE U,
regardless of the BASICTYPE used with the program.
367
PRECISION
PRECISION
Syntax
PRECISION num.expr
Description
The UniBasic PRECISION command determines how many places to the right of the
decimal point the system truncates numbers. num.expr may be a value from zero to 10.
If the num.expr is not within this range, the system does not change the current display
precision. The default precision is four places.
Whenever a numeric operation occurs, UniData converts the operands from a

Tip string variable to a numeric variable, performs the operations, and then
returns the result as a string variable. Since the conversion from numeric to
string occurs after every arithmetic operation, a series of calculations that
requires a high degree of precision should use the PRECISION statement.
Note UniBasic uses the PRECISION statement somewhat differently than other
BASIC implementations. If you notice a degradation in arithmetic accuracy,
use the PRECISION statement to increase the accuracy of sequential arith-
metic operations.
Examples
In the following example, the program statement results in all the numeric variables
being truncated after eight digits from the decimal point prior to being converted to a
string variable.
PRECISION 8
In the next example, the program statement truncates all digits right of the decimal
point.
PRECISION 0
In the next example, the program statement sets the display precision based on the
variable DEC.
PRECISION DEC
Related Topics
Mathematic Functions
For information on mathematic functions, refer to Developing UniBasic Applications.
368
PRECISION
FLOAT.PRECISION
For information on the ECL FLOAT.PRECISION command, refer to UniData
Commands Reference
369
PRINT
PRINT
Syntax
PRINT [ON num.expr] [print.expr]
Description
The UniBasic PRINT command prints data on the display terminal or the line printer,
or sends data to a print file.
You must separate multiple items in a PRINT statement by either commas or colons.
Each comma between two items separates the items by the corresponding number of
tab stops. Tab stops are set to 10 spaces. If you separate statements by a colon, the sys-
tem concatenates the items.
Unless a print expression ends with a colon, a PRINT statement automatically exe-
cutes a carriage return after printing a line. If the output from the PRINT statement
exceeds the current page width, it wraps to the next line.
Note The PRINT statement interprets two consecutive non-printing ASCII charac-
ters (i.e., CHAR(192):CHAR(192)) as one character when displaying data.
Parameters
[ON num.expr] Specifies a print file to which to send the print

expression. If you do not use the ON clause,
the destination of the PRINT statement
depends on the last PRINTER ON or
PRINTER OFF command executed. If a
PRINTER OFF command has been executed,
the data prints on the display terminal. If a
PRINTER ON command has been executed,
the data prints on the system line printer.
PRINT Parameters
370
PRINT
[print.expr] Specifies an expression to print. The print.expr

may consist of string data, any number of
string or numeric variables, UniBasic func-
tions, format strings, or a combination of all of
these. If you do not specify a print.expr, a
PRINT statement generates a new line.
PRINT Parameters (continued)
Examples
In the following example, the program segment prints HI THERE on the line printer.
PRINTER ON
PRINT "HI THERE"
In the next example, the program statement sends the value of variable X with a string
to the file specified by unit 10.
PRINT ON 10 "X = ":X
In the next example, the PRINT statement prints X, Y, and a string separated by tabs,
prints X+Y next to the string, tab twice, then prints another string, then prints the aver-
age of X and Y using the INT function.
X = 5 ; Y = 7
PRINT X,Y,"Total = ":X+Y,,"Average = ":INT((X+Y)/2)
The result is:

5 7 Total = 12 Average = 6
Each item is separated by tabs, the result of the comma separation character. A colon
causes all data items to be concatenated.
Related Topics
CRT
The UniBasic CRT command sends output only to the screen or CRT, regardless of
the use of the PRINTER ON/OFF command.
PRINTER
The UniBasic PRINTER command directs the output of PRINT statements.
371
PRINTER
PRINTER
Syntax
PRINTER {ON | OFF}
Description
The UniBasic PRINTER command directs output of PRINT, FOOTING, HEADING
and PAGE statements not sent to a file (those without the ON clause). If you specify
ON, the system directs all output to the system line printer; if you specify OFF, the
system directs all output to the display terminal.
Reminder Issuing a PRINTER ON command does not ensure the printer is turned on,
properly configured, or even present in the user’s system. If proper communi-
cation between the printer and the computer system is not present when a
printer-enabled command is issued, (a PRINT statement after a PRINTER ON
command, for example), the system generates an error.
Note If you execute a PRINTER ON statement, run-time error messages print on

the system printer.
Examples
In the following example, the program statement sends all future report output (data
from PRINT, FOOTER HEADER and PAGE commands) to the line printer.
PRINTER ON
In the next example, the program statement directs PRINT statements to the display
terminal.
PRINTER OFF
372
PRINTER CLOSE
PRINTER CLOSE
Syntax
PRINTER CLOSE [ON num]
Description
The UniBasic PRINTER CLOSE command sends data stored in either a print file or
a print buffer to the print queue for printing. When you use the ON clause to direct the
PRINTER CLOSE command to a particular print file, it does not physically close that
file. Instead, it sends the contents of the file to a print buffer, leaving the file in an
empty state. If more data is sent to the same print file, it comprises the start of a new
group of data to be printed. As many as 31 print files may be open at any one time.
The PRINTER CLOSE statement does not generate a new line at the end of a page.
UniBasic is in control of page feeds or generating new line equivalents.
Reminder Data in a print file is automatically sent to the print queue if the program exits
or you use a PRINTER CLOSE statement.
Examples
In the following example, the program statement sends the current contents of print
file 5 to the print queue.
PRINTER CLOSE ON 5
Related Topics
SETPTR
Reference.
373
PRINTERR
PRINTERR
Syntax
PRINTERR [expr] [FROM file.var]
Description
The UniBasic PRINTERR command prints error messages stored in either the sys-
tem error message file ERRMSG or a specified file.
Note To get a message from the user-defined error message file, you must open the
file first. You must specify L (carriage return/line feed) explicitly.
Creating a User-Defined Error Message

An error message file is a UniData file in which each item is a piece of an error mes-
sage. The error message consists of format codes and literal strings. The following
table describes the valid codes you may use to construct an error message.
Code Function
A Outputs the next element in expr.

A(n) Outputs the next element in expr, left-justified in an
attribute of n blanks.
C Clears the screen.
D Outputs the system date.
E {literal string} Prints the message ID at the beginning of the message
with enclosing brackets, followed by optional literal
string.
H literal string Prints the literal string.
L Prints a carriage return/line feed.
L(n) Prints n carriage returns/line feeds.
R(n) Outputs the next element in expr, right-justified in an
attribute of n blanks.
S(n) Prints n spaces, counting from the beginning of the
line.
PRINTERR Error Message Codes
374
PRINTERR
Code Function
T Outputs the system time.

W(n) Pauses for n seconds before continuing to display the
message.
X Skips the next parameter passed to the system message
printing routine.
PRINTERR Error Message Codes (continued)
Parameters
[expr] Specifies a dynamic array with elements that

constitute components of an error message.
The first element is the key of an item in the
error message file.
[FROM file.var] Specifies a file from which to execute a user-
defined error message. The default is the sys-
tem error message file.
PRINTERR Parameters
Examples
In the following example, the system ERRMSG file contains error message 4432 and
a user-defined file S_ERR contains error message E009. These messages contain the
following:
Message 4432 Message E009

in ERRMSG in S_ERR
L L(2)
E FILE H => ERR
A(10) S(6)
H DOES NOT EXIST E
L L
H CAN’T PROCEED! A
L H IS NOT PROPERLY SPECIFIED
D L
L
T
L
375
PRINTERR
The following code segment produces an error message if the file you enter for
FNAME cannot be found or you enter 12 for VAR1.
OPEN "S_ERR" TO E_FILE ELSE STOP "S_ERR NOT FOUND"
INPUT FNAME
INPUT VAR1
ER1 = "4432":@FM:FNAME
ER2 = "E009":@FM:"VAR1"
OPEN FNAME TO TFILE ELSE
PRINTERR ER1
STOP
END
IF VAR1 > 10 THEN PRINTERR ER2 FROM E_FILE
If you enter file_test for FNAME and file_test and cannot be found, the program seg-
ment produces the following error message.
[4432] FILE test_file DOES NOT EXIST
CAN’T PROCEED!
19 Oct 1989
10:34:19
If you enter 12 for VAR1, the program segment produces the following error message.
=>ERR [E009]
VAR1 IS NOT PROPERLY SPECIFIED
Related Topics
PRINT
The UniBasic PRINT command prints data on the display terminal or line printer. The
print expression may contain any literal string, numeric or string variables, or UniBa-
sic functions.
376
PROCREAD
PROCREAD
Syntax
PROCREAD var {THEN | ELSE} statements [END]
Description
The UniBasic PROCREAD command assigns the string value of the primary input
buffer of the calling Proc to a variable. PROCREAD can be used to access the primary
input buffer of a calling Proc.
PROCREAD only works in BASICTYPE P or M.

BASICTYPE
Parameters
var Specifies variable to which to assign the string

value of the primary input buffer of the calling
Proc.
{THEN | ELSE} Only a THEN or an ELSE clause is required. If
PROCREAD Parameters
Examples
In the following example, the program segment assigns the string value on the primary
input buffer to ARGUMENTS.
PROCREAD ARGUMENTS ELSE
PRINT "ERROR!"
PRINT "DIALOUT"MUST BE CALLED FROM A PROC"
ABORT
END
377
PROCREAD
Related Topics
PROCWRITE
The UniBasic PROCWRITE command writes data into the primary input buffer of the
calling Proc.
378
PROCWRITE
PROCWRITE
Syntax
PROCWRITE expr
Description
The UniBasic PROCWRITE command writes data into the primary input buffer of
the calling Proc. PROCWRITE erases any previous data in the primary input buffer
and replaces the data with the given data.
PROCWRITE only works in BASICTYPE P or M.

BASICTYPE
Examples
In the following example, the program segment writes the contents of ANSWER to
the primary input buffer.
PRINT "SEND RESULTS TO THE PRINTER? (Y OR N)"
INPUT ANSWER, Y
IF ANSWER = "Y" THEN
PRINTER ON
.
.
.
END
PROCWRITE ANSWER
Related Topics
PROCREAD
The UniBasic PROCREAD command assigns the string value of the primary input
buffer of the calling Proc to a variable.
379
PROGRAM
PROGRAM
Syntax
PROGRAM prog.name
Description
The UniBasic PROGRAM command defines the name of the current main program.
This statement is optional and is for documentation purposes only. The PROGRAM
statement must be the first non-comment statement in the program.
Examples
In the following example, the program segment declares the program name as
BOOKS.
REM This is a program to do the books
PROGRAM BOOKS
Related Topics
SUBROUTINE
The UniBasic SUBROUTINE command defines the name of a subroutine.
380
PROMPT
PROMPT
Syntax
PROMPT str.expr
Description
The UniBasic PROMPT command sets the prompt for user input to a specified one-
character string. If str.expr is longer than one character, the system only uses the first
character as the new prompt.
Note If you supply the data from a DATA statement rather than an INPUT state-
ment, the data the program receives displays after the prompt.
Tip If you set the prompt to a null character, the system does not echo the input
data to the display terminal.
Examples
In the following example, the contents of variable PSTRING (in this case an asterisk)
becomes the new prompt. If an input statement is used in the program, an asterisk
appears at the current cursor position.
PSTRING = "*"
PROMPT PSTRING
In the next example, the program statement sets the prompt at a null character. The
system will not echo the data you input.
PROMPT ""
381
PWR
PWR
Syntax
PWR(num.expr1, num.expr2)
Description
The UniBasic PWR function raises expr1 to the power of expr2.
Note PWR is synonymous with two asterisks (**) or ^.
Examples
In the following example, the program segment raises variable X to the power of 3,
first using an exponentiation operator, then using the PWR function to raise X to the
power of 3. The results are identical.
X = 2
PRINT X**3
PRINT PWR(X,3)
382
QUOTE
QUOTE
Syntax
QUOTE(str.expr)
Description
The UniBasic QUOTE function encloses a string expression with quotes.
Examples
In the following example, the program segment encloses the string stored in VAR2 by
double quotes and stores that string in VAR3. This stores the string “STRING2” in
VAR3.
VAR2 = "STRING2"
VAR3 = QUOTE(VAR2)
383
RAISE
RAISE
Syntax
RAISE(str.expr)
Description
The UniBasic RAISE function raises all UniData special delimiters to the next level.
The system raises attribute marks to record marks, value marks to attribute marks, and
subvalue marks to value marks.
Examples
In the following example, the program segment raises all delimiters to the next level.
ARRAY = ’Harry Sims’:@VM:’114 W. Smith’:@SVM:Suite 220’
ARRAY = RAISE(ARRAY)
This results in the following array:

ARRAY = ’Harry Sims’:@FM:’114 W. Smith’:@VM:’Suite 220’
Related Topics
LOWER
The UniBasic LOWER function lowers all UniData special delimiters to the next
level.
384
READ
READ
Syntax
READ dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic READ command reads a record from a file and assigns its contents to a
dynamic array. The system assigns the first attribute of the record to the first position
of the array, the second attribute to the second position, and so on.
Parameters
dyn.array.var Specifies a dynamic array to which to assign

the attributes of the array.
FROM [file.var,] Specifies a file variable from which to read the
record is read from the most recently opened
default file.
record.ID.expr Specifies a record to read from the file and
assign to the dynamic array.
statements] an error condition (if the file is not open, or if
an I/O error occurs in the read accessing pro-
cess). If you do not specify the ON ERROR
error conditions.
record.ID.expr does not exist, the system
performs the ELSE clause.
READ Parameters
385
READ
{THEN | ELSE} Specifies statements to execute if the ON

statements [END] ERROR clause is specified and the record does
not exist.
You only need a THEN or an ELSE clause. If
READ Parameters (continued)
After execution of a READ command, the STATUS function is set to zero if the read
is successful. If any other read error occurs (i.e., you do not have permissions to a file)
STATUS returns a 2. If the record is locked, STATUS returns the user number of the
user who locked the record.
If the record you specify cannot by found, the system executes the statements
BASICTYPE
after the ELSE clause and the dyn.array.var is set to null. In BASICTYPE P
or R, there is no change to dyn.array.var.
Examples
In the following example, the program statement searches the most recently opened
file for a record called “NAMES.” If it exists, its contents are assigned to the array
variable X. If it does not exist, “None found” displays.
READ X FROM "NAMES" ELSE PRINT "None found"
In the next example, the program segment reads a record from the CUSTOMER file
with an ID equal to the value in CUST.ID. If found, the system executes the subrou-
tine PROCESS.CUST; otherwise, the system prints a message and the program
branches to the label REPROMPT:
READ CUST.REC FROM CUSTOMER, CUST.ID THEN
GOSUB PROCESS.CUST
END ELSE
PRINT ’NO CUSTOMER REC FOR ’CUST.ID
END
In the next example, the program segment searches the file FILE1 for the record with
ID “ADDS.” If it is not there, the system executes the ELSE statement; this searches
FILE2 for the same record. In either case, a successful search assigns the value of the
record to the array variable Y. If neither file contains the record, the program returns
to label 150. The READ command ignores any update locks. When file integrity is of
special concern, use the READU, READVU, or MATREADU commands. To ensure
that any updates in progress complete, these commands should be employed by all
programs.
386
READ
READ Y FROM FILE1,"ADDS" ELSE

READ Y FROM FILE2,"ADDS" ELSE GOSUB ADD.RECORD
END
In the following example, the program statement is invalid since the record ID is omit-
ted.
READ REC FROM CUSTOMER ELSE PRINT ‘NO CUSTOMER’
387
READBCK
READBCK
Syntax
READBCK dyn.array.var [FROM file.var] [ON ERROR statements]
[THEN statements] ELSE statements
Description
The UniBasic READBCK command retrieves one record ID from a B+ tree based
alternate key index. READBCK reads the record from the file and assigns the record’s
contents to a dynamic array. The system assigns the record ID to the @ID variable.
READBCK retrieves the record ID related with the current alternate key value. Ini-
tially, you must set the current value using the SETINDEX command. When you exe-
cute READBCK immediately following the SETINDEX command, the system
retrieves the record ID related to the current alternate key value. Each time the system
performs this function again, the previous alternate key value in the index becomes the
current alternate key value. Using this command in a loop, the program is able to
retrieve records in the descending order of the values of an indexed attribute.
Parameters

the values read.
[FROM file.var] Specifies a file variable from which to read the
record.
error conditions. If you specify the ON
ERROR clause and the record does not exist,
the system performs the ELSE clause.
[THEN statements] Specifies statements to execute if the read is
successful.
READBCK Parameters
388
READBCK
ELSE statements Specifies statements to execute if the read is

not successful, if the current alternate key
value is not set by the SETINDEX command,
or if the system cannot locate the current alter-
nate key value (i.e., the system reaches the last
of the previous key values).
READBCK Parameters (continued)
Examples
In the following example, the program segment sets the index to the first record that
contains Smith and then reads the record just before Smith.
OPEN ’’, ’CUSTOMER’ TO tmp ELSE STOP
SETINDEX ’LNAME’, ’Smith’ ON tmp
READBCK rec FROM tmp THEN PRINT msg ELSE STOP
Related Topics
SETINDEX
The UniBasic SETINDEX command initializes the current alternate key value in the
B+ tree based alternate key index.
READFWD
The UniBasic READFWD command retrieves one record ID from a B+ tree based
alternate key index.
READ
The UniBasic READ command retrieves a record from a file and assigns its value to a
dynamic array variable.
389
READBCKL
READBCKL
Syntax
READBCKL dyn.array.var [FROM file.var] [ON ERROR statements]
[LOCKED statements] [THEN statements] ELSE statements
Description
The UniBasic READBCKL command retrieves one record ID from a B+ tree based
alternate key index and places a read-only lock on the record. READBCKL reads the
record from the file and assigns the record’s contents to a dynamic array. The system
assigns the record ID to the @variable @ID. READBCKL retrieves the record ID
related with the current alternate key value.
Initially, you must set the current value using the SETINDEX command. When you
execute READBCKL immediately following the SETINDEX command, the system
retrieves the record ID related to the current alternate key value. Each time the system
performs this function again, the previous alternate key value in the index becomes the
current alternate key value. Using this command in a loop, the program is able to
retrieve records in the descending order of the values of an indexed attribute.
Parameters

the values read.
record.
READBCKL Parameters
390
READBCKL

successful.
READBCKL Parameters (continued)
Related Topics
SETINDEX
READFWD
READBCK
391
READBCKU
READBCKU
Syntax
READBCKU dyn.array.var [FROM file.var] [ON ERROR statements]
Description
The UniBasic READBCKU command retrieves one record ID from a B+ tree based
alternate key index and places an exclusive lock on the record. READBCKU reads the
assigns the record ID to the @variable @ID. READBCKU retrieves the record ID
related with the current alternate key value. Initially, you must set the current value
using the SETINDEX command. When you execute READBCKU immediately fol-
lowing the SETINDEX command, the system retrieves the record ID related to the
current alternate key value. Each time the system performs this function again, the
previous alternate key value in the index becomes the current alternate key value.
Using this command in a loop, the program is able to retrieve records in the descend-
ing order of the values of an indexed attribute.
Parameters

the values read.
record.
READBCKU Parameters
392
READBCKU
[LOCKED statements] Specifies statements to execute if the record is

already locked. If the LOCKED clause is not
specified and the record is locked, the system
waits until the record is available.
successful.
READBCKU Parameters (continued)
Related Topics
SETINDEX
READU
The UniBasic READU command retrieves a record from a file, assigns its value to a
dynamic array variable, and sets an exclusive lock on the record being read.
READBCK
393
READFWD
READFWD
Syntax
READFWD dyn.array.var [FROM file.var] [ON ERROR statements]
Description
alternate key index. READFWD reads the record from the file and assigns the
record’s contents to a dynamic array. The system assigns the record ID to the @vari-
able @ID. READFWD retrieves the record ID related with the current alternate key
value. Initially, you must set the current value using the SETINDEX command. When
you execute READFWD immediately following the SETINDEX command, the sys-
tem retrieves the record ID related to the current alternate key value. Each time the
system performs this function again, the previous alternate key value in the index
becomes the current alternate key value. Using this command in a loop, the program is
able to retrieve records in the descending order of the values of an indexed attribute.
Parameters

the values read.
record.
successful.
READFWD Parameters
394
READFWD

READFWD Parameters (continued)
Examples
In the following example, the program segment sets the index to the first record that
contains Miller and then reads the next record.
OPEN ’’, ’CUSTOMER’ TO tmp ELSE STOP
SETINDEX ’LNAME’, ’Miller’ ON tmp
READFWD rec FROM tmp THEN PRINT msg ELSE STOP
Related Topics
SETINDEX
READBCK
READ
395
READFWDL
READFWDL
Syntax
READFWDL dyn.array.var [FROM file.var] [ON ERROR statements]
Description
The UniBasic READFWDL command retrieves one record ID from a B+ tree based
alternate key index and places a read-only lock on the record. READFWDL reads the
assigns the record ID to the @variable @ID. READFWDL retrieves the record ID
using the SETINDEX command. When you execute READFWDL immediately fol-
Parameters

the values read.
record.
READFWDL Parameters
396
READFWDL

successful.
READFWDL Parameters (continued)
Related Topics
SETINDEX
READFWD
READL
The UniBasic READL command retrieves a record from a file and assigns its value to
a dynamic array variable and sets a read-only lock on the record being read.
397
READFWDU
READFWDU
Syntax
READFWDU dyn.array.var [FROM file.var] [ON ERROR statements]
Description
The UniBasic READFWDU command retrieves one record ID from a B+ tree based
alternate key index and places a read-only lock on the record. READFWDU reads the
assigns the record ID to the @variable @ID. READFWDU retrieves the record ID
using the SETINDEX command. When you execute READFWDU immediately fol-
Parameters

the values read.
record.
READFWDU Parameters
398
READFWDU

successful.
READFWDU Parameters (continued)
Related Topics
SETINDEX
READFWD
READU
dynamic array variable, and sets an exclusive lock on the record being read.
399
READL
READL
Syntax
READL dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements]
[LOCKED statements [END]] {THEN | ELSE} statements [END]
READL dyn.array.var FROM [file.var,] record.ID.expr
[LOCKED statements [END]] [ON ERROR statements]
Description
The UniBasic READL command reads the specified record from a file and assigns its
contents to a dynamic array and sets a multiple-access read-only lock on the record
being accessed.
Tip This is a read-only lock. You should not lock a record with this command if
your intention is to update the record.
The system assigns the first attribute of the record to the first position of the array , the
second attribute to the second position, and so on.
Reminder As with the other locking read or write commands, the execution of a READL
does not prevent access by the MATREAD, MATWRITE, READ, READV,
WRITE or WRITEV statements.
After execution of a READL command, the STATUS function is set to zero if the read
is successful. If any other read error occurs (i.e., you do not have permissions to a file)
STATUS returns a 2. If the record is locked, STATUS returns the user number of the
Parameters

the values read.
READL Parameters
400
READL

record. If you do not specify file.var, the record
is read from the most recently opened default
file.
{THEN | ELSE} Specifies statements to execute if the read is
statements [END] successful (THEN) or if if the read is not suc-
cessful, if the current alternate key value is not
set by the SETINDEX command, or if the sys-
tem cannot locate the current alternate key
value (i.e., the system reaches the last of the
previous key values) (ELSE).
READL Parameters (continued)
Examples
In the following example, the program segment reads the record T1234 in the file
STOCK, assigning its contents to the dynamic array variable LAST.STOCK. The
statement sets a read-only lock on the file. If the system cannot read the file due to a
previously established lock, the system prints the message RECORD LOCKED.
READL LAST.STOCK FROM STOCK,‘T1234’
LOCKED PRINT ‘RECORD LOCKED’
ELSE PRINT ‘STOCK ITEM NOT PRESENT’
END
401
READL
Related Topics
READ
402
READLIST
READLIST
Syntax
READLIST dyn.array.var [FROM list.num] {THEN | ELSE} statements [END]
Description
The UniBasic READLIST command assigns the values remaining in an active list to
a dynamic array. Each active list element becomes an attribute in the dynamic array.
BASICTYPE READLIST performs differently in BASICTYPE P and M. The following

syntax is valid in BASICTYPE M:
READLIST dyn.array.var FROM list.num [, acct.name]

[SETTING count.var] {THEN | ELSE} statements [END]
If you create a list under an account other than the current one, you may spec-
ify the account with acct.name. The SETTING clause sets the number of ele-
ments in the list to count.var.
In BASICTYPE P use the READSELECT command, with the following syn-

tax:
READSELECT dyn.array.var [FROM sel.var]

Parameters

the values remaining in the active list.
[FROM list.num] Specifies which active list (0-9) you want to
use. If you do not specify a list.num, the default
list is zero. If no items are available in the list,
the system executes the ELSE clause.
READLIST Parameters
403
READLIST
{THEN | ELSE} Specifies statements to execute if no items are

statements [END] available in the list.
Only a THEN or an ELSE clause is required. If
READLIST Parameters (continued)
Examples
In the following example, the program segment selects the customer file and provides
a loop to process each record in sequence. If the first attribute of the record has the
value ‘P’ the program places the remaining active items in a variable called
LIST.ITEM, then writes that item on the file SL and stops processing.
EXECUTE "SELECT CUSTOMER WITH ACTIVE = ‘Y’ BY STATUS"
DONE = 0
LOOP
READNEXT CUST.ID ELSE DONE = 1
WHILE NOT(DONE) DO
READ CUST.REC FROM CUSTOMER,CUST.ID ELSE
PRINT ‘NO CUSTOMER RECORD: ’:CUST.ID
END
IF CUST.REC<1> = ‘P’ THEN
READLIST LIST.ITEM ELSE LIST.ITEM = " "
WRITE LIST.ITEM ON SL, ‘UNPROCESSED’
STOP ‘PROCESS ENDING DUE TO CUSTOMER STATUS’
END
REPEAT
In BASICTYPE P, if the list TAPE1 is saved in the current account and has the fol-
lowing contents:
TAPE1 = "V20001":@AM:"V1020":@AM:"V4056":@AM:"V2112"
The following code segment reads TAPE1 to array T and prints the contents of T and
4, the number of elements in the list:
READLIST T FROM "TAPE1" SETTING N
THEN
PRINT "NUMBER OF ELEMENTS IN LIST: ":N
PRINT "CONTENTS OF LIST": T
END
ELSE PRINT "CANNOT READ LIST";ABORT
404
READLIST
Related Topics
FORMLIST
The UniBasic FORMLIST command creates an active select list using a dynamic
array variable.
SELECT
The UniBasic SELECT command creates an active list of all record IDs in a file.
SELECT
For information on the ECL SELECT command, refer to UniData Commands
Reference.
405
READNEXT
READNEXT
Syntax
READNEXT id.var {, val.var[, subval.var]} [FROM list.num.expr]
[ON ERROR statements] {THEN | ELSE} statements [END]
Description
The UniBasic READNEXT command assigns the next record ID, from an active
select list, to a variable.
Note READNEXT does not actually read the record with the ID found, but assigns
that ID to a variable. Once assigned, you can use the variable within a READ
statement to access the appropriate record.
As an example, a customer transaction might require that data is read in a par-

ticular sequence. The sequence might be determined by selecting those IDs
needed in the appropriate order (using a sorted SELECT statement) and then
using the READNEXT statement to assign an ID to a variable.
BASICTYPE READNEXT performs differently with BASICTYPE P and M as shown in

the following syntax:
READNEXT var FROM list.name {, acct.name}

[SETTING count.var] {THEN | ELSE} statements [END]
The SETTING clause assigns the number of elements in the list to the
variable count.var.
READNEXT and Multivalued Attributes

Lists used by READNEXT can contain an optional value and subvalue position (if
you create the list using the BY.EXP keyword). The select list created using this key-
word is a sorted list based on a multivalued or subvalued attribute. The select list con-
tains; in each attribute, the record ID and the positions of the sorted value or subvalue.
The READNEXT command passes the value and subvalue positions to val.var and
subval.var. A subsequent READ statement might access the appropriate value using
val.var (and subval.var.).
READNEXT assigns the values and subvalues of each record ID to val.var and sub-
val.var. The val.var and subval.var each may contain more than one data value (sepa-
rated by subvalue marks) if you use more than one BY.EXP keyword when you create
the select list. In this case the first subvalue in val.var and subval.var correspond to the
value and subvalue position of the attribute in the first BY.EXP expression. The sec-
ond subvalue in val.var and subval.var correspond to the value and subvalue position
406
READNEXT
of the attribute in the second BY.EXP clause,... and so on for each successive
BY.EXP clause.
Parameters
id.var Specifies a variable to which to assign the

value of the next record ID
{,val.var[,subval.var]} Specifies a value and subvalue to read.
[FROM list.num.expr] Specifies which active list (0-9) you want to
use. If you do not specify a list.num, the default
list is zero. If no items are available in the list,
statements] an error condition (if list.num.expr is an illegal
list number, if list.var is not a valid list, or if
the default list is empty). If you do not specify
list is empty, the system performs the ELSE
clause.
{THEN | ELSE} Specifies statements to execute if the system
statements [END] encounters the end of the list (ELSE) or if
id.var is found (THEN).
READNEXT Parameters
Examples
In the following example, the program segment gets the next ID from the list and
assigns it to the variable CUST. If the list is exhausted, then a message displays.
READNEXT CUST.ID ELSE PRINT "END OF LIST ENCOUNTERED"
In the next example, the program segment reads 10 IDs from the list opened as list 1,
then reads the records associated with those IDs. If the list has fewer than 10 IDs, the
program jumps to 1525. If a record ID is not found in the default system file, the pro-
gram displays a message.
407
READNEXT
FOR I = 1 TO 10
READNEXT ID FROM 1 ELSE SHORT.LIST = 1 THEN
READU REC FROM CUST,ID ELSE PRINT "NOT FOUND"
END
NEXT I
In the next example, the program segment selects records from the customer file using
the BY.EXP keyword, which sorts on the multivalued keyword INV.NBR. The pro-
gram then proceeds to read through the list, item by item, assigning each successive
ID and value position to CUST.ID and INV.VAL respectively. As long as records
exist, the THEN clause is performed. When the list is exhausted, the ELSE clause is
executed and the loop is exited.
PERFORM "SELECT CUSTOMER BY.EXP INV.NBR"
DONE = 0
LOOP
READNEXT CUST.ID,INV.VAL THEN
GOSUB PRINT.INV
END ELSE DONE = 1
UNTIL DONE DO
PRINT ’PROCESSING ’:CUST.ID
REPEAT
Related Topics
SELECT
For information on the UniQuery SELECT command, refer to Using UniQuery.
408
READNEXTTUPLE
READNEXTTUPLE
Syntax
READNEXTTUPLE dyn.array.var FROM file.name.expr ELSE statements [END]
Description
The UniBasic READNEXTTUPLE command assigns the next entire record, from a
list of IDs, to a variable, with attributes separated by attribute marks from a UniData
SQL statement.
READNEXTTUPLE creates a dynamic array with each attribute, or column, in the
SQL output separated by an attribute mark (@AM).
Do not use the Unidata SQL UNNEST command in the Unidata SQL state-
Tip ment. The system may not return the entire record with attribute marks, value
marks, and/or subvalue marks if you use UNNEST.
Parameters
dyn.array.var Specifies the dynamic array to which to assign

the record.
FROM file.name.expr Specifies the file variable from which to read
the next record in the active select list.
The file.name.expr must have been created dur-
ing the current session using an
EXECUTESQL statement with an INTO
clause.
ELSE statements [END] Specifies statements to execute if the system
cannot find file.name.expr, or if the last record
has been read.
READNEXTTUPLE Parameters
Examples
In the following example, the program segment executes an SQL statement and stores
the output in an internal result file called SQL_INPUT. The READNEXTTUPLE
409
READNEXTTUPLE
statement then reads the records stored in SQL_INPUT until the last record item is
read. The process converts the attribute marks to spaces and prints each record read.
OUT.COMMAND := " FROM CUSTOMER INTO SQL_INPUT; "
DONE = 0
LOOP
READNEXTTUPLE CUST.REC FROM "SQL_INPUT" ELSE
DONE = 1
END
UNTIL DONE DO
CONVERT @AM TO " " IN CUST.REC
CONVERT @VM TO","IN CUST.REC
PRINT CUST.REC
REPEAT
Related Topics
EXECUTESQL
The UniBasic EXECUTESQL command passes an SQL statement directly to the
UniData SQL processor.
UniData SQL
For information on Unidata SQL, refer to the Using Unidata SQL.
410
READSELECT
READSELECT
Syntax
READSELECT dyn.array.var [FROM sel.var] {THEN | ELSE} statements [END]
Description
This command provides a way in BASICTYPE P to read an active select list into a
dynamic array. Refer to the READLIST command for further details.
411
READSEQ
READSEQ
Syntax
READSEQ var FROM seq.file.var {THEN | ELSE} statements [END]
Description
The UniBasic READSEQ command reads the next record from a sequential file and
assigns the data read to a variable.
Note Each read from the sequential file searches for a line feed character
(CHAR(10)) to determine the end of the record. The READSEQ process
maintains a pointer to the current position in the file (where the last record ter-
minated).
Parameters

record.
FROM seq.file.var Specifies a sequential file variable from which
to read the record.
seq.file.var must evaluate to an open sequential
file that you have opened with an OPENSEQ
statement.
{THEN | ELSE} Specifies statements to execute if the file can-
statements [END] not be found or a read is attempted past the end
of file (ELSE) or if the record is found
(THEN).
READSEQ Parameters
412
READSEQ
Examples
In the following example, the program statement reads the next record in the file
PORT.FILE and assigns it to the variable TAX.REC.
READSEQ TAX.REC FROM PORT.FILE ELSE STOP "Can’t READSEQ TAX.REC"
Related Topics
OPENSEQ
The UniBasic OPENSEQ command opens a sequential file for access.
WRITESEQ
file.
WRITESEQF
file and forces the system to physically write the data to disk.
413
READT
READT
Syntax
READT [UNIT (mu.expr)] var {THEN | ELSE} statements [END]
Description
The UniBasic READT command reads the next available record from a tape and
assigns it to a variable.
Reminder Before you use the READT command, you must attach a tape drive for use
with the T.ATT command. For information on tape commands, refer to
UniData Commands Reference. You must use the TAPELEN option for the
T.ATT command and specify the length you desire for the tape in megabytes.
This is for UniData tapes only. For information on the ECL T.ATT command,

Therefore, ASCII 0 cannot be used in any string variable within UniBasic.
This command converts (CHAR(0)) to CHAR(128) when reading a block of
characters.
Tape Unit Number and Conversions

The following table describes the valid conversion codes.
Code Meaning
0 No conversion (ASCII assumed)

1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
READT Conversion Codes
414
READT
READT and the STATUS function

The STATUS function is set after each READT operation. The following table
describes the values the STATUS function will return after you execute a READT
statement.
Value Description
0 Successful read
1 End of file encountered
2 End of tape encountered
3 Tape not assigned
4 Parity error
5 Unknown hardware error
6 Other unspecified error
STATUS Function Values
Parameters
[UNIT (mu.expr)] Specifies the conversion code (first digit), and

the unit number (second digit). UniData allows
unit numbers ranging from 0 to 9. mu.expr is
optional and the default value is UNIT (00) for
tape unit 0 and no conversion (ASCII
assumed).
record.
READT Parameters
415
READT
{THEN | ELSE} Specifies statements to execute if the read is

statements [END] unsuccessful or the end of the file (or tape) is
encountered (ELSE), or if the operation ends
successfully.
Multiple statements may appear following
THEN or ELSE. If the statements are placed on
multiple lines, an END at the end of the state-
ment is required. The statements may appear
on the same line with the keyword, separated
by semicolon(s). In this case, END is not nec-
essary.
READT Parameters (continued)
Examples
In the following example, the program segment first uses the UniData ECL T.ATT
command to reserve the tape unit 0 with no conversion. Then the program segment
reads all the records on the tape (until the end of the file or the end of the tape) and
calls an internal subroutine that processes the record.
PERFORM "T.ATT"
DONE = 0
LOOP
READT UNIT (00) TAX.RECORD ELSE DONE = 1
UNTIL DONE DO
GOSUB PROCESS.RECORD
REPEAT
Related Topics
NOCONVERT
ter CHAR(0).
REWIND
The UniBasic REWIND command rewinds a tape back to its beginning.
416
READT
WRITET
The UniBasic WRITET command writes an expression as a record to a tape.
STATUS
ECL Tape Commands

For information on the ECL tape commands (i.e., T.ATT), refer to UniData
Commands Reference
417
READU
READU
Syntax
READU dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements]
READU dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements]
Description
The UniBasic READU command reads a record from a file and assigns its contents to
a dynamic array and can lock the record being read, preventing simultaneous access
by other users or programs.
Reminder The record is locked only against access by other READU or MATREADU
statements. Statements that do not check update locks (READ, MATREAD,
etc.) access a locked file.
After execution of a READU command, the STATUS function is set to zero if the
read is successful. If any other read error occurs (i.e., you do not have permissions to a
file) STATUS returns a 2. If the record is locked, STATUS returns the user ID of the
Note The system releases record locks when you execute a WRITE or a RELEASE
statement.
Parameters

the contents of the record.
FROM [file.var,] Specifies the file variable from which to read
the record. If you do not specify a filename
with file.var, the most recently opened default
file is read.
READU Parameters
418
READU
record.ID.expr Specifies the record ID to read, either as a

variable or as a literal string.
statements] a fatal error condition (if the file is not open, or
if an I/O error occurs in the read accessing pro-
error conditions.
record does not exist, the system performs the
ELSE clause.
locked by another user. If the record is locked
by another user and a LOCKED clause does
not exist, the system waits until the record is
released to proceed.
{THEN | ELSE} Specifies statements to execute if the record is
statements [END] found (THEN) or if the record does not exist,
or you do not have permission to access the file
(ELSE).
Multiple statements may appear after THEN,
ELSE, or LOCKED clauses. If you place the
statements on multiple lines, the system
requires an END at the end of the statements.
The statements may also be written on the
same line as the keyword, with separating
semicolon(s), without using the END clause.
READU Parameters (continued)
Examples
In the following example, the program segment assigns the record, read from the
default file, with the ID “IDENT” to the variable INFO and sets an update lock on that
record. The system prints “Record locked” if the record is locked by another program
or prints “File not found” if the record does not exist. If a default file is not found, the
program aborts.
READU INFO FROM "IDENT" LOCKED PRINT "Record locked"
ELSE PRINT "File not found"
419
READU
In the next example, the program segment reads a record from the CUSTOMER file
and assigns the value to CUST.REC. If the record is found, the system prints a mes-
sage and calls a subroutine. If the record is locked or not found, the system executes a
similar set of statements. The STATUS function will return which user has locked the
record.
READU CUST.REC FROM CUSTOMER,CUST.ID THEN
PRINT "RECORD FOUND...NOW UPDATING"
GOSUB UPDATE.CUST:
END LOCKED
PRINT ‘RECORD LOCKED BY USER NUMBER ’:STATUS()
GOTO RE.READ:
END ELSE
PRINT ‘RECORD ‘:CUST.ID:’ NOT FOUND’
GOTO RE.PROMPT:
END
Related Topics
READ
READL
The UniBasic READL command retrieves a record from a file and assigns its value to
a dynamic array variable and sets a read-only lock on the record you access.
File Input/Output
420
READV
READV
Syntax
READV var FROM [file.var,] record.ID.expr, attribute.expr
Description
The UniBasic READV command assigns the data from a particular attribute of a
record to a variable.
Note READV ignores any update locks on a record. To update a record, you should
use the READVU command.
Tip You generally use the READV command when only one or two attributes are
needed from a record. This improves efficiency. If more attributes are neces-
sary or to update more attributes, use the READ or MATREAD commands.
Parameters

data from the record attribute.
the data.
If you do not specify a file with file.var, the
attribute attribute.expr is read from the most
record.ID.expr Specifies the record to read. If the record can-
not be found, the system executes the
statements after the ELSE clause; otherwise,
the system executes the statements after the
THEN clause.
attribute.expr Specifies the attribute of the record from which
to read the data.
READV Parameters
421
READV
[ON ERROR Specifies statements to be executed in the

statements] event of a fatal error condition (if the file is not
open, or if an I/O error occurs in the read
accessing process). If you do not specify the
ON ERROR clause, the program terminates
record does not exist, the system executes the
ELSE clause.
{THEN | ELSE} Specifies statements to execute if the record
statements [END] cannot be found (ELSE) or if the record is
found (THEN).
READV Parameters (continued)
Examples
In the following example, the program segment reads CUST.NAME from the CUS-
TOMER file using the variable CUST.ID. In this case the first item, or attribute 1,
from the file is read. If the record exists, the system appends the dynamic array
NAME.ARRAY with CUST.NAME as the last value of the first attribute; otherwise,
READV CUST.NAME FROM CUSTOMER,CUST.ID,1 THEN
NAME.ARRAY1,-1 = CUST.NAME
END ELSE
PRINT ’NO FILE FOR CUSTOMER ’:CUST.ID
END
In the next example, you can use the READV command with attribute.expr equal to
zero to verify that a record exists (for instance, if you are assigning IDs sequentially in
the CUSTOMER file). Each time you need to create a new ID, you need to verify that
the ID that you selected is not in use. The following code accomplishes this task,
incrementing the ID until an ID is available:
LOOP
READV CHECK FROM CUSTOMER,NEXT.ID,0 ELSE CHECK = 0
UNTIL CHECK NE 0 DO
NEXT.ID += 1
REPEAT CUST.ID = NEXT.ID
422
READV
Related Topics
READVU
The UniBasic READVU command retrieves an attribute from a record, assigns its
value to a variable, and sets an exclusive lock on the record.
READVL
The UniBasic READVL command retrieves an attribute from a record, assigns its
value to a variable, and sets a read-only lock on the record.
423
READVL
READVL
Syntax
READVL var FROM [file.var,] record.ID.expr, attribute.expr
Description
The UniBasic READVL command assigns the data from a particular attribute of a
record in a file to a variable and sets a read-only lock on the record.
Parameters

data from an attribute of a record.
an attribute from a record.
If you do not specify a file with file.var, the
data is read from the most recently opened
default file.
record.ID.expr Specifies a record from which to read an
attribute.
If the record you specify with record.ID.expr
cannot be found, the system executes the state-
ments after the ELSE clause; otherwise, the
system executes the THEN statements.
attribute.expr Specifies an attribute from which to assign the
data to a variable.
READVL Parameters
424
READVL

a fatal error condition ( if the file is not open, or
error conditions.
ELSE clause.
locked by another user. If the record is locked
by another user and a LOCKED clause does
not exist, the system waits until the record is
released to proceed.
THEN, ELSE, or LOCKED. If you place the
requires an END at the end of statements. The
statements may also be written on the same
line as the keyword, with separating semico-
lon(s), without using the END clause.
READVL Parameters (continued)
Examples
In the following example, the program statement reads the third attribute of record
CARS from the system default file and sets a read-only lock on the record. If the data
is not found, the system displays the message “NOT FOUND”.
READVL MODEL FROM "CARS",3 ELSE PRINT "NOT FOUND"
In the next example, the program segment retrieves the sixth attribute of the record
with the ID 424111234 from the STUDENT file and sets a read-only lock on the
record. If the record is locked, the system displays the message “Record locked”. If
the record is found, the system transfers control to subroutine COURSE_PROCESS;
otherwise, the program aborts after printing the message “Record not found”.
425
READVL
SID = "424111234"
C_NO = 6 READVL COURSE_NO FROM STUDENT,SID,C_NO
LOCKED PRINT "Record locked"
THEN GOSUB COURSE_PROCESS:
ELSE PRINT "Record not found"
ABORT
END
Related Topics
READU
dynamic array variable, and sets an exclusive lock on the record.
READVU
The UniBasic READVU command retrieves an attribute from a record, assigns its
value to a variable, and sets a lock on the record.
426
READVU
READVU
Syntax
READVU var FROM [file.var,] record.ID.expr, attribute.expr
Description
The UniBasic READVU command assigns the data from a particular attribute of a
particular record in a file to a variable and sets an exclusive lock on the record.
The update lock stays in effect until you execute either a RELEASE or WRITE state-
ment; however, the commands WRITE, WRITEV, MATWRITE, READ, READV
and MATREAD ignore any record locks.
You can improve efficiency by using the READVU command when you need
Tip only one or two attributes from a record. If more attributes are necessary or to
update more attributes, use the READU or MATREADU commands.
Parameters
var Specifies a variable to which to assign the data

read from the attribute of a record.
FROM [file.var,] Specifies a file from which to read the data. If
you do not specify a file.var the system reads
from the most recently opened default file.
record.ID.expr Specifies a record in the file from which to
read the data.
attribute.expr Specifies an attribute within the file from
which to read the data.
READVU Parameters
427
READVU

statements] a fatal error condition ( if the file is not open, or
error conditions.
ELSE clause.
already locked by another user. If the
LOCKED clause is not specified, the program
waits until the record becomes available.
{THEN | ELSE} Specifies statements to execute if the record is
statements [END] found (THEN) or if the record cannot be found
(ELSE).
you use THEN you do not have to use ELSE.
THEN, ELSE, or LOCKED. If you place the
requires an END at the end of the statement.
The statements may be written on the same line
as the keyword, with separating semicolon(s),
without using the END clause.
READVU Parameters (continued)
Examples
In the following example, the program statement reads the first attribute of record
SUPPL from the default system file. An update lock is set on this record.
READVU NAME FROM "SUPPL",1 ELSE NULL
In the next example, the program segment reads the seventh attribute of the record
named in the variable ID from the INV file and stores the attribute in the variable
SUPPL. If the record is locked or if the default file cannot be found, a read-error mes-
sage is displayed.
428
READVU
READVU SUPPL FROM INV,ID,7 LOCKED PRINT "Locked"

ELSE GOTO 2010:
Related Topics
READV
The UniBasic READV command retrieves an attribute from a record and assigns its
value to a variable, ignoring all locks on the record.
READVL
The UniBasic READVL command retrieves an attribute from a record, assigns its
value to a variable, and sets a read-only lock on the record.
429
READXFWD
READXFWD
Syntax
READXFWD dyn.array.var [FROM file.var] [ON ERROR statements]
Description
The UniBasic command READXFWD reads forward one record in a B+tree alternate
key index, in much the same manner as the READFWD command, but does not return
a record. READXFWD allows a programmer to move forward through the database to
read alternate keys and record IDs without incurring the overhead of retrieving a
record every time.
Parameters

the values read.
record.
successful.
READXFWD Parameters
430
READXFWD

READXFWD Parameters (continued)
Related Commands
READFWD
READBCK
READXBCK
The UniBasic READXBCK command reads backward one record ID from a B+ tree
based alternate key index, without incurring the overhead of retrieving a record, as the
READBCK command does.
431
READXBCK
READXBCK
Syntax
READXBCK dyn.array.var [FROM file.var] [ON ERROR statements]
Description
The UniBasic command READXBCK reads backward one record in a B+tree alter-
nate key index, in much the same manner as the READBCK command, but does not
return a record. READXBCK allows a programmer to move backward through the
database to read alternate keys and record IDs without incurring the overhead of
retrieving a record every time.
Parameters

the values read.
record.
successful.
READXBCK Parameters
432
READXBCK

READXBCK Parameters (continued)
Related Commands
READFWD
READBCK
READXFWD
The UniBasic READXFWD command reads forward one record ID from a B+ tree
based alternate key index, without incurring the overhead of retrieving a record, as the
READFWD command does.
433
RECORDLOCKED( )
RECORDLOCKED( )
Syntax
RECORDLOCKED (file.var, rec.id.expr)
Description
The RECORDLOCKED function has been added to determine if a record has been
locked by a user. When UDT.OPTIONS 35 is ON, this function returns a value of -2,
indicating that another user has a READU lock. This means you can lock the same
record at a lower execute level.
Return
Description
Value
4 The user executing the function has an exclusive FILELOCK.

3 The user executing the function has a shared FILELOCK.
2 The user executing the function has a READU lock.
1 The user executing the function has a READL lock.
0 The record is not locked.
-1 Another user has a READL lock.
-2 Another user has a READU lock.
-3 Another user has a shared FILELOCK.
-4 Another user has an exclusive FILELOCK.
Return Values for the RECORDLOCKED Function
The STATUS function value is set to the user number of the user who has the lock,
unless the function returns 0 or an error value.
Error Value Status Value Description
-11 -1 Currently RECORDLOCKED( )

does not support NFA files.
-12 -2 Invalid file type.
Status( ) Values for the RECORDLOCKED Function
434
RECORDLOCKED( )
Error Value Status Value Description
-13 -3 System error, unknown user.
Status( ) Values for the RECORDLOCKED Function
Parameters
file.var Specifies a previously opened file variable.

rec.id.expr Specifies an expression that evaluates to the record that you
are checking.
RECORDLOCKED() Parameters
435
RECORDLOCKL
RECORDLOCKL
Syntax
RECORDLOCKL [file.var,] record.ID.expr [ON ERROR statements]
[LOCKED statements]
Description
The UniBasic RECORDLOCKL command sets a read-only lock on a record.
The read only lock allows other users to read the record but not write to the
Tip record. You may use the WRITE, WRITEV or MATWRITE statements to
write to the record when it is locked.
Parameters
[file.var,] Specifies a file within which to search for the

record. If you do not specify a file, the system
searches for the record within the most recently
opened default file.
record.ID.expr Specifies a record to lock.
if the system cannot find the file or the default
file). If you do not specify the ON ERROR
clause, the program terminates under these
fatal error conditions.
already locked by another user. If the record is
locked by another user and you do not specify
a LOCKED clause, the program waits until the
system releases the lock on the record you
specify.
RECORDLOCKL Parameters
436
RECORDLOCKL
Examples
In the following example, the program statement sets a read-only lock on the record
HOLY in the most recently opened default file. If the record is already locked by
another user, the program to waits until the record is released.
RECORDLOCKL "HOLY"
In the next example, the program segment sets a lock on the record with the ID Alice
from file CUSTOMER. If the record is locked, the system display the message “THE
RECORD IS ALREADY LOCKED”.
RECORDLOCKL CUSTOMER,"Alice"
LOCKED PRINT "THE RECORD IS ALREADY LOCKED"
Related Topics
FILELOCK
The UniBasic FILELOCK command locks a file against access by READL, READU,
READVU, and MATREADU statements.
FILEUNLOCK
The UniBasic FILEUNLOCK command unlocks a file previously locked by the a
FILELOCK statement.
RELEASE
The UniBasic RELEASE command unlocks a record previously locked.
File Input/Output
437
RECORDLOCKU
RECORDLOCKU
Syntax
RECORDLOCKU [file.var,] record.ID.expr [ON ERROR statements]
[LOCKED statements]
Description
The UniBasic RECORDLOCKU command sets an exclusive lock on a record, pre-
venting any other user or program from accessing the record.
Tip You can use the READ, MATREAD, READV, WRITE, MATWRITE, or
WRITEV to access a file that is locked.
Parameters
[file.var,] Specifies a file within which to lock a record. If

you do not specify a file with file.var, the sys-
tem searches for the record within the most
record.ID.expr Specifies a record to lock exclusively.
error conditions.
already locked by anotheruser. If the record is
locked and you do not specify a LOCKED
clause, the system waits until the lock on the
record is released.
RECORDLOCKU Parameters
438
RECORDLOCKU
Examples
In the following example, the program statement sets an exclusive lock on the record
WELL in the most recently opened default file.
RECORDLOCKU "WELL"
In the next example, the program segment sets a lock on the record with the ID Won-
der from the CUSTOMER file. If the record is locked, the system displays the mes-
sage “THE RECORD IS ALREADY LOCKED”.
RECORDLOCKU "WELL" RECORDLOCKU CUSTOMER,"Wonder"
LOCKED PRINT "THE RECORD IS ALREADY LOCKED"
Related Topics
FILELOCK
FILEUNLOCK
The UniBasic FILEUNLOCK command unlocks a file previously locked by a FILE-
LOCK statement.
RELEASE
The UniBasic RELEASE command unlocks a record previously locked.
File Input/Output
439
RELEASE
RELEASE
Syntax
RELEASE [file.var [, record.ID.expr]] [ON ERROR statements]
Description
The UniBasic RELEASE command unlocks records previously you have previously
locked.
Note If there are no current active locks, or if the file does not have any locks, or if
the record not locked, the RELEASE statement does not have any effect.
Parameters
[file.var] Specifies a file varible within which to release

the lock. If you do not specify a file nor a
record, the system releases all record locks you
have set.
[,record.ID.expr] Specifies a record ID to release the lock
upon. If you do not specify a record with
record.ID.expr, the system release all locked
records within the file.
statements] a fatal error condition (if the file is not open). If
you do not specify the ON ERROR clause, the
program terminates this fatal error condition.
record does not exist, the system executes the
statements following the ELSE clause.
RELEASE Parameters
Examples
In the following example, the program statement releases all update locks set by the
current program. All files opened by the user are affected.
440
RELEASE
RELEASE
In the next example, the program statement releases the record “COLO” in the file
CONTACTS. Other locked records in this file remain locked.
RELEASE CONTACTS,"COLO"
Related Topics
File Input/Output
FILELOCK
FILEUNLOCK
The UniBasic FILEUNLOCK command unlocks a file previously locked by the a
FILELOCK statement.
RECORDLOCKL
The UniBasic RECORDLOCKL command sets a read-only access lock on a record.
RECORDLOCKU
The UniBasic RECORDLOCKU command sets an exclusive lock on a record that
prevents any other user or program from accessing the record.
441
REMOVE
REMOVE
Syntax
REMOVE var FROM dyn.var [AT col.pos] SETTING delim.code
Description
The UniBasic REMOVE command removes successive elements from a dynamic
array and assigns the element to a variable. REMOVE does not change the value of
the dynamic array.
REMOVE searches a dynamic array for system substring delimiters. If the system
finds a delimiter, it assigns the contents of a string up to the delimiter to the variable.
The system removes both the substring and the delimiter from the dynamic array. A
pointer is maintained that holds the position of the last substring you remove, so that
successive REMOVE statements move progressively through a dynamic variable until
you reach the end of the dynamic array. When the system reaches the last element, the
delimiter code is set to zero and the process is complete.
Note In some implementations of BASIC, the zero position is taken as first posi-
tion. UniBasic takes the first position as 1. In general, this isn’t a problem
except where the program specifies the starting position other than the begin-
ning (such as when using the INDEX function).
Parameters
var Specifies the element to which to assign the

variable.
FROM dyn.var Specifies a dynamic array from which to
remove the elements.
REMOVE Parameters
442
REMOVE
[AT col.pos] Specifies the column position in the array at

which to start removing elements.
This position is literally the number of charac-
ters, including system delimiters, from the
beginning of the array. To process the entire
array, the value must be set to 1 (zero defaults
to 1) initially. The value of col.pos changes as
the array is processes, indicating the current
position of the pointer.
SETTING delim.code Specifies the delimiter code.
REMOVE Parameters (continued)
The SETTING clause assigns the variable delim.code a value based on the delimiter
code. The following table describes the values of the delimiter codes.
Delimiter ASCII
Description
Code Value
0 string end
1 record mark 255
2 attribute mark 254
3 value mark 253
4 subvalue mark 252
5 text mark 251
6 250
7 249
REMOVE Delimiter Codes
Examples
In the following example, the program segment processes the dynamic array string
CLIENT.
443
REMOVE
DIM VAR(5,2)
CLIENT = "G.Flaubert":@VM:"Guy":@SM:"12":@VM:"Yvette":@SM:"7"
FOR I = 1 TO 5
REMOVE VAR(I,1) FROM CLIENT SETTING VAR(I,2)
NEXT I
CLIENT = CLIENT;*reset REMOVE pointer
After the loop terminates, the variables become:

VAR(1,1) = "G.Flaubert"VAR(1,2) = 3
VAR(2,1) = "Guy"VAR(2,2) = 4
VAR(3,1) = "12"VAR(3,2) = 3
VAR(4,1) = "Yvette"VAR(4,2) = 4
VAR(5,1) = "7"VAR(5,2) = 1
Notice how each pair in the array VAR becomes a substring and the delimiter that
defined it.
In the next example, the program segment starts at the beginning of the array
AMOUNTS and successively removes each INV.AMT from the array, calculates a
3.5% tax amount and adds it into the variable TAX.AMT. When MARK = 0 (the end
of the array), the LOOP is exited.
COL = 1
LOOP
REMOVE INV.AMT FROM AMOUNTS AT COL SETTING MARK
TAX.AMT += INV.AMT*.035
WHILE MARK DO REPEAT
In the next example, the program segment demonstrates the difference between Uni-
Basic and other implementations of BASIC.
ARRAY = "AB":@AM:"CD":@AM:"EF"
COL = 1
LOOP
REMOVE LINE FROM ARRAY AT COL SETTING MARK
PRINT LINE, COL, MARK
WHILE MARK REPEAT
The result, in UniBasic, is the following:

AB 42
CD 72
EF 90
In some implementations, the values are different:

AB 32
CD 62
EF 82
REMOVE is very effective and efficient in programs that are required to

Tip sequentially process the elements of a dynamic array.
In the next example, the program segment illustrates the efficiency of the REMOVE
statement versus the EXTRACT statement in terms of processing time.
444
REMOVE
MAINLINE
OPEN ’ ’, ’VOC’ TO VOC ELSE STOP ’CANNOT OPEN VOC FILE!’
READ ITEM FROM VOC, ’BIGTEST’ THEN
LINE.CNT = DCOUNT (ITEM, @AM)
PRINT "Bigtest in file VOC: "; LINE.CNT: " lines, ":
PRINT LEN(ITEM): "bytes."
GOSUB TIME.EXTRACT
GOSUM TIME.REMOVE
END ELSE
PRINT ’COULD NOT READ ITEM BIGTEST’
END
STOP
TIME.EXTRACT:
LINE.IDX = 1
START.TIME = TIME()
LOOP
UNTIL LINE.IDX LINE.CNT DO
LINE = ITEM<LINE.IDX>
LINE.IDX += 1
REPEAT
END.TIME = TIME()
PRINT "EXTRACT: ": OCONV(END.TIME-START.TIME, ’MTS’):
RETURN
TIME.REMOVE
START.TIME = TIME()
LOOP
REMOVE LINE FROM ITEM SETTING MORE.LINES
WHILE MORE.LINES DO
REPEAT END.TIME = TIME()
PRINT "REMOVE: ": OCONV(END.TIME-START.TIME, ’MTS’):
RETURN
This results in the following:

Bigtest in file VOC: 6000 lines, 59999 bytes.
Processing time:
EXTRACT: 00:07:26
REMOVE: 00:00:03
445
REMOVE
REMOVE
Syntax
REMOVE(dyn.array.var, delim.var)
Description
The UniBasic REMOVE function returns a substring (delimited an item, attribute,
value, subvalue, or text mark) from a dynamic array, then assigns the substring to a
variable. REMOVE does not change the value of the dynamic array.
Tip The REMOVE function is effective and efficient in programs required to

sequentially process the elements of a dynamic array.
Parameters
dyn.array.var Specifies the dynamic array to process.

delim.var Specifies an expression which evaluates to a
type of delimiter following the last assigned
substring.
REMOVE Parameters
The following table describes the delimiter codes the REMOVE function returns.
Delimiter ASCII
Meaning
Code Value
0 string end
1 record mark 255
2 attribute mark 254
3 value mark 253
4 subvalue mark 252
REMOVE Delimiter Codes
446
REMOVE
Delimiter ASCII
Meaning
Code Value
5 text mark 251

6 250
7 249
REMOVE Delimiter Codes (continued)
Related Topics
REMOVE
The UniBasic REMOVE command gives you an alternate way to assign a dynamic
array’s successive substrings to a variable.
447
REPLACE
REPLACE
Syntax
REPLACE(dyn.array.expr, attrib.expr, val.expr, subval.expr, replace.expr)
Or:
dyn.array.expr<attrib.expr, val.expr, subval.expr> = replace.expr
Description
The UniBasic REPLACE function replaces data in a dynamic array with an expres-
sion according to a specified attribute, value, or subvalue in a dynamic array.
For instance, if an attribute, value, or subvalue evaluates to less than zero, the replace-
ment string is placed after the last attribute, value, or subvalue, as appropriate. If the
position given does not exist (attribute six specified in an array with two attributes, for
example), the necessary number of attribute, value, and subvalue marks are added in
order to create the specified position.
Parameters
dyn.array.expr Specifies the dynamic array in which to

replace an element with replace.expr.
attrib.expr Specifies the attribute to replace. If this value is
a negative number, replace.expr is appended to
the existing value instead of replacing it. If this
value is 0, the preceding level (attribute, value,
subvalue) is replaced by replace.expr. If this
value is -1, replace.expr is appended after the
last value in this level of the array.
REPLACE Parameters
448
REPLACE
val.expr Specifies the value of the attribute to replace. If

this value is a negative number, replace.expr is
appended to the existing value instead of
replacing it. If this value is 0, the preceding
level (attribute, value, subvalue) is replaced by
replace.expr. If this value is -1, replace.expr is
appended after the last value in this level of the
array.
subval.expr Specifies the subvalue of the value of the
attribute to replace. If this value is a negative
number, replace.expr is appended to the exist-
ing value instead of replacing it. If this value is
0, the preceding level (attribute, value, sub-
value) is replaced by replace.expr. If this value
is -1, replace.expr is appended after the last
value in this level of the array.
replace.expr Specifies the expression with which to replace
the element of the dynamic array.
REPLACE Parameters (continued)
Examples
In the following example, the program statement replaces attribute 1 with the value in
the variable NAME.
CUST.REC = REPLACE(CUST.REC,1,0,0,NAME)
In the next example, the program statement replaces the first value of attribute 2 with
the value ‘220 W. 44TH’.
CUST.REC = REPLACE(CUST.REC,2,1,0,’220 W. 44TH’)
In the next example, the program segment replaces “Gone with the Mortgage”.
STG = "Movies":@AM:"The Sacrifice":@VM:"Gone with the Mortgage"
:@AM:"Rocky IV"
NEW.STG = REPLACE(STG,2,2,0,"Gone with the Wind")
PRINT NEW.STG
This results in:

STG = "Movies":@AM:"The Sacrifice":@vM:"Gone with the Wind" :@AM:"Rocky
IV"
449
REPLACE
In the next example, the first REPLACE places Harry Smith in the first attribute posi-
tion. The second REPLACE places an array with two values in the fifth attribute.
CUST.REC =’’
CUST.REC = REPLACE(CUST.REC,1,0,01’Harry Smith’)
CUST.REC = REPLACE(CUST.REC,5,0,0,"v220":@VM:"v230")
This results in:

CUST.REC = "Harry Smith":@AM::@AM::@AM::@AM:"V220":@VM:"V230"
Related Topics
DELETE
The UniBasic DELETE command deletes a record from a file.
INSERT
The UniBasic INSERT command inserts an expression with its delimiter before or
after an attribute, value, or subvalue mark in a dynamic array.
450
RESIZET
RESIZET
Syntax
RESIZET [UNIT(mu.expr)] expr [THEN statements] ELSE statements
Description
The UniBasic RESIZET command changes the block size the WRITET command
uses. When there is a variable length record, the record length is less than the block
length and the remaining portion of the block is filled as blanks.
Tip Use this command when the block size in one file is not the same as the block
size in T.ATT.
Parameters
[UNIT(mu.expr)] Specifies the conversion code and unit number.

The mu.expr is optional and the default value is
UNIT (00) for tape unit 0 and no conversion
(ASCII assumed).
expr Specifies the blocksize to which to resize.
[THEN statements] Specifies statements to execute if the command
succeeds.
ELSE statements Specifies statements to execute if the command
fails.
RESIZET Parameters

mu.expr refers to the conversion code (first digit), and the unit number (second digit).
UniData allows unit numbers ranging from 0 to 9. The following table describes the
valid conversion codes.
451
RESIZET
Code Meaning

1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
RESIZET Conversion Codes
Examples
In the following example, the program segment changes the block size the WRITET
statement uses to the length of REC.
RESIZET LEN(REC) ELSE PRINT ’RESIZET ERROR’
WRITET REC ELSE PRINT ‘WRITET ERROR’
Related Topics
SETTAPE
For information on the ECL SETTAPE command, refer to UniData Commands
Reference.
T.ATT
For information on the ECL T.AT command, refer to UniData Commands Reference.
452
RETURN
RETURN
Syntax
RETURN [TO label[:]]
Description
If you do not specify a TO clause, control passes to the statement immediately follow-
ing the original GOSUB or CALL statement in the calling program or subroutine.
Note You may only use the TO clause with subroutines contained within the main
program; i.e., “internal” subroutines.
Examples
In the following example, the program segment returns the calling program if you
input Y.
PROMPT " "
PRINT "Begin procesing?":
GOSUB YES.NO.PROMPT
.
.
.
STOP
YES.NO.PROMPT
INPUT ANS, 1_
IF ANS = ’Y’ THEN ANS = ’Y’ ELSE ANS = ’N’
RETURN
Related Topics
CALL
either from the main program or from another subroutine
GOSUB
453
REUSE
REUSE
Syntax
REUSE(dyn.array.expr)
Description
The UniBasic REUSE function causes the last element of a dynamic array to be
repeated until the number of array elements match if the dynamic array is shorter than
another array with which you multiply, add, or subtract it to.
If you do not use the REUSE function, the array is extended with either 1s or 0s,
depending on the operation: for division, a the system uses a one; in all other opera-
tions (addition, subtraction, and multiplication), the system uses a zero.
Examples
In the following example, the program segment multiplies the arrays without using the
REUSE function.
VIEWERS = 100:@VM:200:@VM:300
COST = 40:@VM:1
VCOST = VIEWERS*COST
This results in:

VCOST = 4000:@VM:200:@VM:0
VCOST becomes the same length as the longest of the two arrays used in the opera-
tion. The final value is a result of the array COST extended with a zero value; how-
ever, if you use the REUSE function:
VCOST = VIEWERS*REUSE(COST)
This results in:

VCOST = 4000:@VM:200:@VM:300
454
REWIND
REWIND
Syntax
REWIND [UNIT(mu.expr)] {THEN | ELSE} statements [END]
Description
The UniBasic REWIND command rewinds the tape back to its beginning.
Reminder Before you can use the REWIND command, you must reserve a tape drive for
use with the T.ATT command. For information on ECL T.ATT, refer to
Parameters
[UNIT(mu.expr)] Specifies the conversion code (first digit), and

unit numbers ranging from 0 to 9.
The mu.expr is optional and the default value is
UNIT (00) for tape unit 0 and no conversion
(ASCII assumed).
Multiple statements may appear following the
THEN or ELSE keywords. If the statements
are placed on multiple lines, an END at the end
of the statement is required. The statements
may appear on the same line with the keyword,
separated by semicolon(s). In this case, END is
not necessary.
REWIND Parameters
455
REWIND
Code Meaning

1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
REWIND Conversion Codes
Examples
In the following example, the program segment first uses the ECL T.ATT command
to reserve the tape unit 0 with no conversion code. Then a routine is performed that
reads all the records on the tape (until the end of the file or the end of the tape) and
calls an internal subroutine that processes the record. After the process is finished, the
REWIND command rewinds the tape.
PERFORM "T.ATT DO"
DONE = 0
LOOP
READT UNIT (00) TAX.RECORD ELSE DONE = 1
UNTIL DONE DO
GOSUB PROCESS.RECORD
REPEAT REWIND UNIT (00) ELSE PRINT ’REWIND UNSUCCESSFUL’
Related Topics
READT
The UniBasic READT command assigns the next record from a magnetic tape device
to a variable.
Tape Commands
For information on the ECL tape commands (i.e., T.ATT), refer to UniData
Commands Reference.
456
RND
RND
Syntax
RND(num.expr)
Description
The UniBasic RND function returns a random integer within the range 0 to
(num.expr - 1).
Examples
In the following example, the program statement prints a random number anywhere
from 0 to 9.
PRINT RND(10)
Related Topics
RNDSEED
The UniBasic RNDSEED command generates the same sequence of random numbers
each time you run a program
457
RNDSEED
RNDSEED
Syntax
RNDSEED expr
Description
The UniBasic RNDSEED command allows you to “seed” the pseudo random number
generator. The RND function gives you a different sequence of numbers each time.
RNDSEED generates the same sequence of random numbers each time you run a pro-
gram.
expr may be any string expression evaluating to a seed point. If you use the same expr,
the sequence of random numbers the system generates with the RND function is the
same.
Related Topics
RND
The UniBasic RND function returns a random integer.
458
SADD
SADD
Syntax
SADD(x, y)
Description
The UniBasic SADD function adds two string numbers and returns the result as a
string number. SADD is the string addition function. Arguments may be any valid
numbers or string numbers of any magnitude and precision.
Tip Using string numbers rather than standard numbers degrades processing
speed.
If either x or y contains non-numeric data, the system displays an error message and
returns a result of 0.
The SADD function results in a string number, so you can use the function in any
expression in which a string number is valid. Since string numbers may exceed the
range of numbers that standard arithmetic operators can accommodate, you may not
want to use the SADD function in any expression in which a standard number is valid.
Note The result of the SADD function may not exceed the maximum allowable
number determined by your hardware.
Examples
In the following example, the program statement assigns to variable B the sum of the
string constant (1.4149) and variable A.
B = SADD("1.4149",A)
459
SCMP
SCMP
Syntax
SCMP(x, y)
Description
The UniBasic SCMP function compares two string numbers and returns a value
depending upon the result of the comparison. SCMP is the string comparison function.
Arguments may be any valid numbers or string numbers of any magnitude and preci-
sion. If either x or y contains non-numeric data, the system displays an error message;
the comparison results in zero. The following table describes the values SCMP
returns.
Comparison Returning Value
x<y -1
x=y 0
x>y 1
SCMP Returning Values
Using string numbers rather than standard numbers slows processing speed.
Tip
Examples
In the following example, the program segment compares FA to FB. If the result of
the IF statement is true (the SCMP function returns 1), the system executes the PRINT
statement.
IF SCMP (FA,FB) GT 0 THEN
PRINT A:" IS GREATER THAN ":B
460
SDIV
SDIV
Syntax
SDIV(x, y)
Description
The UniBasic SDIV function divides two string numbers and returns the result as a
string number. SDIV divides x by y. Arguments may be any valid numbers or string
numbers of any magnitude and precision; however, result precision is limited to 14
significant digits.
Using string numbers rather than standard numbers degrades processing

Tip speed.
If either x or y contains non-numeric data, the system displays an error message; the
division results in 0. If y is equal to 0, the system displays an error message stating that
division by 0 is illegal and returns a result of 0.
The SDIV function results in a string number, so you can use the function in any
want to use the SDIV function in any expression in which a standard number is valid.
Examples
In the following example, the program statement divides the constant (1.4149) by
variable A and assigns the result to variable B.
B = SDIV("1.4149",A)
461
SELECT
SELECT
Syntax
SELECT file.var [TO {list.num.expr | list.var.expr}] [ON ERROR statements]
SELECT dyn.array [TO {list.num.expr | list.var.expr}] [ON ERROR statements]
Description
The UniBasic SELECT command creates a list of all record IDs in a file. Records
appear in the list in the order they were originally stored.
You may access the list you create with a SELECT statement with a READNEXT
statement.
The UniBasic SELECT command functions differently than the ECL SELECT com-
mand. The UniBasic SELECT makes one group of IDs at a time available to a READ-
NEXT statement immediately after the SELECT statement without having to wait for
the whole ID list to be available.
In BASICTYPE U and R, you must initialize a variable before specifying it in

BASICTYPE
list.var.expr or the system displays a run-time error. In BASICTYPE P and
M, you may not specify list.num.expr.
Note If changes occur in a group that has not been selected yet, those changes are
reflected in the program; (i.e., if an you delete an ID before the group is
selected and processed in the UniBasic program, that ID will not appear in the
list).
462
SELECT
Parameters
file.var Specifies a file variable from which to select

the records. if you do not specify file.var, the
system compiles a list from the most recently
opened default file.
You may only specify one file in each
SELECT statement. If the file you specify can-
not be found or if the default file does not exist
(no files were opened), the program aborts.
dyn.array Specifies a dynamic array from which to select
a list of attributes.
[TO {list.num.expr | Specifies a list number to which to assign the
list.var.expr}] record IDs. UniData supports ten active lists
(0-9). If you do not specify a list, SELECT
creates the default list zero.
statements] a fatal error condition (if the dynamic array
you specify is not a valid item, if the file you
specify is not a valid file, or if the system can-
not read the file). If you do not specify the ON
ERROR clause, the program terminates under
such fatal error conditions.
SELECT Parameters
When using the ECL SELECT command, SYSTEM(11) returns the number of items
remaining in the list. With the UniBasic SELECT command, SYSTEM(11) returns
the number of items remaining in the group.
Examples
In the following example, the program statement creates a list of all record IDs in the
CUSTOMER file.
SELECT CUSTOMER
In the next example, the program segment creates a list of all IDs in the file TAPES
and assigns the ID list to list number 1, it then uses the READNEXT command to read
463
SELECT
the IDs from the list sequentially, executing a subroutine, PROCESS.TAPES, each
time.
SELECT TAPES TO 1
LOOP
READNEXT TAPE.ID FROM 1 ELSE TAPE.ID = " "
WHILE TAPE.ID
GOSUB PROCESS.TAPES
REPEAT
Related Topics
SELECT
For information on the UniQuery SELECT Command, refer to UniData Commands
Reference.
464
SELECTINDEX
SELECTINDEX
Syntax
SELECTINDEX index.name.expr[, key.val.expr] FROM file.var [TO list.num.expr]
Description
The UniBasic SELECTINDEX command creates select lists based on alternate key
indices. SELECTINDEX has two forms: the first form selects by alternate key index,
the second form selects by alternate key value.
If the index name does not exist, the select list is empty and the STATUS function
returns 1; if the index name does exist, STATUS returns 0.
Parameters
index.name.expr Specifies an alternate key index from which to

select all key values values from if the
key.val.expr is not specified.
[, key.val.expr] Specifies a key value expression for
SELECTINDEX to create a select list of record
IDs (associated with the alternate key value)
found in the alternate key index.
FROM file.var Specifies a file variable from which to select
the list.
[TO list.num.expr] Specifies the list to which to select keys.
SELECTINDEX Parameters
Examples
In the following example, SELECTINDEX uses the alternate key index “LNAME”
and creates a list of all the last names contained in the STUDENT file.
SELECTINDEX "LNAME" FROM STUDENT
465
SELECTINDEX
In the next example, SELECTINDEX uses the alternate key value “SMITH” and cre-
ates a list of all occurrences of SMITH contained in the STUDENT file.
SELECTINDEX "LNAME", "SMITH" FROM STUDENT
Related Topics
INDICES
The UniBasic INDICES function returns either the names of alternate key indices, or
information about a particular alternate key index.
Alternate Key Indices

For information on alternate key indices, refer to Using UniData.
466
SELECTINFO
SELECTINFO
Syntax
SELECTINFO([list.num.expr,] code.expr)
Description
The UniBasic SELECTINFO function returns the state of a select list. list.num.expr
is an expression evaluating to the number of the select list (0-9). code.expr is an
expression evaluating to the type of information you want. The SELECTINFO
key is 1.
Parameters
list.num.expr Specifies an expression evaluating to the number of

the select list (0-9).
code.expr Specifies an expression evaluating to the type of infor-
mation you want.
SELECTINFO Parameters
The SELECTINFO function returns:
Value Description
1 The select list you specify is active.

0 The select list you specify is not active.
-1 The select list does not exist, or code.expr is not valid, or (in
BASICTYPE P) list.num.expr is not a list variable.
SELECTINFO Return Values
In BASICTYPE P, list.num.expr may be any valid list variable.

BASICTYPE
467
SEND
SEND
Syntax
SEND[X] expr[:expr2...] [:] TO line.expr {THEN | ELSE} statements [END]
Description
The UniBasic SEND command sends output data to a specified line. You usually use
SEND after a line is attached by the sending environment.
Parameters
[X] Specifies to convert expr from an exploded

ASCII hexadecimal representation string to its
binary equivalent, and then transmits on the
specified line. The conversion process ends
when the system reads the first non-
hexadecimal character.
expr[:expr2...] Specifies an expression that evaluates to a
string. This string may contain any data for-
matting expressions. You may specify more
than one expression to send.
[:] Specifies to suppress the sending of a
terminating carriage return and line feed.
TO line.expr Specifies an expression evaluating to a line
number. line.expr must be valid or an error
message displays and you enter the UniBasic
debugger.
If the line is attached, the process has exclusive
use of a line. If the line is not attached, the
system performs the ELSE clause.
SEND Parameters
468
SEND

the THEN or ELSE contains with multiple
lines.
SEND Parameters (continued)
Note SEND with the X option suppresses the output of a pair > (return/line feed);
however SENDX does not allow the quotation marks and the colon (‘:’) to
exist as part of syntax, although it is implied.
Examples
In the following example, the program statement sends the string to line 0 unless line 0
is not attached by the current environment. If the line 0 is not attached by the current
environment, the system displays the message, “Line not attached”.
SEND BEGIN_TRANSMISSION TO 0
ELSE PRINT "Line not attached"
In the next example, the program statement converts the string to HELLO WORLD
before sending it to line zero.
TESTVAR = "48454C404F WORLD"
SENDX TESTVAR TO 0 ELSE PRINT "Line not attached"
Related Topics
GET
The UniBasic GET command receives unprompted input from an attached line.
PROTOCOL
The ECL PROTOCOL command sets data line transmission characteristics and proto-
cols for a specified line. For information on PROTOCOL, refer to UniData
Commands Reference.
469
SEQ
SEQ
Syntax
SEQ(“char.expr”)
Description
The UniBasic SEQ function converts the character expression to a single ASCII code
value. The SEQ function is the complement of the CHAR function.
Examples
In the following example, the program statement prints the ASCII code corresponding
to the character “#” (in this case, 35).
PRINT SEQ("#")
Related Topics
CHAR
The UniBasic CHAR function changes ASCII numeric data to a character expression.
470
SEQS
SEQS
Syntax
SEQS(“char.expr”)
Description
The UniBasic SEQS function converts the character expressions in each element of a
dynamic array to a single ASCII code value.
Examples
In the following example, the program statement prints the ASCII code corresponding
to the value in each element of the dynamic array ARR1. The result is 65}66}67}68.
ARR1 = "A":@AM:"B":@AM:"C":@AM:"D"
PRINT SEQS(ARR1)
Related Topics
CHARS
The UniBasic CHARS function changes ASCII numeric data in each element of a
dynamic array to a character expression.
471
SETINDEX
SETINDEX
Syntax
SETINDEX index.name.expr [, [rop] key.val.expr [, id.expr]] [ON file.var]
Description
The UniBasic SETINDEX command initializes a key in an alternate key index.
Note You are only allowed to have the current alternate key value for one index of
a file at a time, even though the number of indices on a file is unlimited. Each
time you use SETINDEX, the current value is set to one in the new index and
the subsequent READFWD/READBCK statement reads the record associated
with the alternate key values in the new index.
After SETINDEX is executed, STATUS is set to one of the following values:
0 A primary key exists

1 Error
2 A primary key does not exist
STATUS() Values
Parameters
index.name.expr Specifies the B+tree based alternate key index.

[rop] One of several valid operators (see below). The
default rop operator is EQ.
SETINDEX Parameters
472
SETINDEX
[, key.val.expr] Specifies the key value you wish to initialize. If

you do not specify this value, the system sets
the internal pointer to the first key value in the
B+tree.
If you specify FIRST_ALT_KEY or
LAST_ALT_KEY, as rop you may not specify
key.val.expr.
[, id.expr] Specifies an item identifier. This sets the index
position to the item.
id.expr must be a specific item identifier.
When the id.expr entered does not exist, SET-
INDEX sets the position to the next key value.
[ON file.var] Specifies the file to act on.
SETINDEX Parameters (continued)
The following table describes the valid rop operators. If you do not specify rop, the
default is EQ.
Operator Resulting Current Alternate Key Value
EQ First value equal to or greater than specified (same

as GE).
GT First value greater than specified.
GE First value greater than or equal to specified (same
as EQ).
LT First value less than specified.
LE First value less than or equal to specified.
FIRST_ALT_KEY First alternate key value. If you specify this as rop,
you may not specify key.val.expr.
LAST_ALT_KEY Last alternate key value. If you specify this as rop,
you may not specify key.val.expr.
SETINDEX Operators
Tip The system uses and maintains this value for the READBCK, READFWD,
and related statements. Normally, you should use LT, LE, or
473
SETINDEX
LAST_ALT_KEY operators before READBCK statements. You should use

GT, GE, EQ, or FIRST_ALT_KEY with READFWD statements.
Examples
In the following example, the program segment sets the pointer at the first occurrence
of the data element containing ‘Miller’ and is described by the dictionary item,
‘LNAME’.
OPEN ' ', 'CUSTOMER' TO tmp
ELSE STOP
SETINDEX 'LNAME', 'Miller' ON tmp
Related Topics
READFWD
READBCK
The UniBasic READBCK command retrieves on record ID from a B+ tree based
474
SETTABLE
SETTABLE
Syntax
SETTABLE [NEXT | table.no [RELATIVE | ABSOLUTE]] ON connection
Description
The UniBasic SETTABLE command makes the specified table the current table in
the current result set. The result set is a set of tables returned when UniData executes a
batch of commands. For each command in a batch, the server returns a result table.
The number of tables in the result set is equal to the number of commands in the batch.
You can only move forward in the result set. You cannot move to a table number less
than the current one.
STATUS
After the execution of the SETTABLE statement, STATUS is set to one of the follow-
ing:
0 Success
2 Other errors
SETTABLE Command STATUS Values
475
SETTABLE
Parameters
[NEXT | table.no] NEXT makes the next table in the result set
the current table. table.no makes a specified
table number in the result set the current table.
[RELATIVE | RELATIVE specifies that table.no is relative
ABSOLUTE] to the position of the current table in the result
set. ABSOLUTE specifies that table.no is
unrelated to the position of the current table in
the result set. It is relative to where the table is
in the result set.
ON connection Specifies the handle to a server you specified
with the CONNECT command.
[ON ERROR statements] The ON ERROR clause allows the program to
continue to perform if the SETTABLE state-
specify.
SETTABLE Parameters
476
SETROW
SETROW
Syntax
SETROW [{NEXT | [PREVIOUS | PRIOR] | CURRENT} row.num
{RELATIVE | ABSOLUTE}] ON connection [ON ERROR statements]
Description
The UniBasic SETROW command sets the specified row to the current row in the
current table. You can go back up to 1000 rows from the current row.
STATUS
After the execution of the SETROW statement, STATUS is set to one of the
following:
0 Success
2 Position is out of bounds
3 Other error
SETROW Command STATUS Values
Parameters
NEXT Sets the next row in the current table to be

the current row.
[PREVIOUS | PRIOR] Sets the previous row in the current table
to be the current row.
SETROW Parameters
477
SETROW
CURRENT Sets the current row in the current table to

be the current row.
row.num Makes a specified row number in the cur-
rent table the current row.
{RELATIVE | ABSOLUTE} RELATIVE specifies that row.no is rela-
tive to the position of the current row in
the current table. ABSOLUTE specifies
that table.no is unrelated to the position of
the current row in the current table. It is
relative to where the row is in the current
table.
ON connection Specifies the handle to a server you speci-
fied with the CONNECT command.
[ON ERROR statements] The ON ERROR clause allows the pro-
gram to continue to perform if the SET-
ROW statement fails. It then executes the
statements you specify.
SETROW Parameters (continued)
478
SIN
SIN
Syntax
SIN(num.expr)
Description
The UniBasic SIN function returns the trigonometric sine of the numeric expression
num.expr.
Examples
In the following example, the program segment assigns the sine of the number 25 to
the variable SIN.X. In this case .4226.
X = 25
SIN.X=SIN(X)
In the next example, the program statement prints 1.0000, the sine of 90.
PRINT SIN(90)
479
SLEEP
SLEEP
Syntax
SLEEP [hh:mm[:ss]] [seconds]
RQM [hh:mm[:ss]] [seconds]
Description
The UniBasic SLEEP and RQM commands halt program execution for the time
specified in seconds, or until the time you specify.
Tip You may use SLEEP or RQM to have a processing or reporting program wait
until midnight before running in order to better use your system resources.
SLEEP is also useful when waiting for the release of locked system resources.
Reminder The original purpose of RQM was to release remaining execution time
reserved for a program, allowing other programs to use the time. If a particu-
lar program is very computation-intensive, RQM may improve overall system
performance.
Parameters
[hh:mm [:ss]] Specifies the time to sleep until, in hours,

minutes and seconds.
seconds Specifies the number of seconds to sleep.
SLEEP Parameters
Examples
In the following example, the program statement halts program execution for ten sec-
onds.
SLEEP 10
In the next example, the program statement suspends program execution until 11:45
PM.
SLEEP 23:45
480
SLEEP
In the next example, the program statement halts program execution for one second.
SLEEP
481
SMUL
SMUL
Syntax
SMUL(x, y)
Description
The UniBasic SMUL function multiplies two string numbers and returns the result as
a string number. SMUL is the string multiplication function. Arguments may be any
valid numbers or string numbers of any magnitude and precision. Using string num-
bers rather than standard numbers degrades processing speed.
returns a result of zero.

Tip speed.
Note The SMUL function results in a string number, so you can use the function in
any expression in which a string number is valid. Since string numbers may
exceed the range of numbers that standard arithmetic operators can accommo-
date, you may not want to use the SMUL function in any expression in which
a standard number is valid.
Examples
In the following example, the program statement multiplies the constant (1.4149) by
variable A and assigns the result to variable B.
B = SMUL("1.4149",A)
482
SOUNDEX
SOUNDEX
Syntax
SOUNDEX(expr)
Description
The UniBasic SOUNDEX function converts an expression into a phonetic code. You
may use it to compare alphabetic strings, such as names, where alternate spelling or
misspelling should not cause a mismatch. expr is an expression evaluating to a string
value.
SOUNDEX evaluates the expression by:
• Returning the first alphabetic letter.
• Converting the remainder of the string to uppercase.
• Ignoring letters A, E, H, I, O, U, W, Y, and non-alphabetic characters.
• Converting each valid letter to a phonetic code.
• Testing for duplication. If a character is next to another character that has
the same phonetic code, it is not included.
• Adjusting the length of the code to four characters by truncating codes
longer than four characters or padding zeros to any expression less than
four characters long.
The following table shows SOUNDEX sample output values:
Expression SOUNDEX
STEPHEN S315
STEVEN S315
TERMINATE T655
RRR R600
UniBasic SOUNDEX Sample Output Values
483
SOUNDEX
The following table displays the phonetic code for each letter that UniData evaluates.
Code Letters
1 BFPV
2 CGJKQSXZ
3 DT
4 L
5 MN
6 R
UniBasic SOUNDEX Phonetic Codes
484
SPACE
SPACE
Syntax
SPACE(expr)
Description
The UniBasic SPACE function returns the number of spaces you specify with expr in
string form.
Reminder Functions may appear within PRINT statements, if concatenated with the
proper operator.
Examples
In the following example, the program statement prints HI and THERE separated by
15 spaces.
PRINT "HI":SPACE(15):"THERE"
This results in:

HI THERE
485
SPACES
SPACES
Syntax
SPACES(dyn.array.expr)
Description
The UniBasic SPACES function returns the number of spaces each element of the
dynamic array dyn.array.expr contains.
Examples
In the following example, the program segment prints the number of spaces each ele-
ment of the dynamic array ARR1 contains.
ARR1 = 1:@AM:2:@AM:3:@AM:4:@AM:5
ARR2 = SPACES(ARR1)
This results in ARR2 containing one space in the first element, two spaces in the sec-
ond element, etc.
486
SPLICE
SPLICE
Syntax
SPLICE(expr1,“expr”, expr2)
Description
The UniBasic SPLICE function concatenates two strings or arrays and inserts an
expresion between them.
Parameters
expr1 Specifies first string or array to concatenate.

expr Specifies expression to insert between expr1 and expr2
when concatenating them.
expr2 Specifies second string or array to concatenate.
SPLICE Parameters
Examples
In the following example, the program segment concatenates PHONE to NUMBER
and inserts a dash (-) in between the two strings.
PHONE = "555"
NUMBER = "1234"
PRINT SPLICE (PHONE,"-",NUMBER)
This results in:

555-1234
In the following example, the program segment concatenates each element of array
ARR1 to array ARR2 and inserts a plus sign (+) in-between the two elements.
ARR1 = 1:@AM:2:@AM:3
ARR2 = 4:@AM:5:@AM:6
PRINT SPLICE (ARR1,"+",ARR2)
This results in:

1+4}2+5}3+6
487
SQUOTE
SQUOTE
Syntax
SQUOTE(str.expr)
Description
The UniBasic SQUOTE function encloses a string, (regardless of its contents) with
single quotes.
Examples
In the following example, the program statement prints ‘This is ‘a’ test’ on screen.
PRINT SQUOTE("This is ’a’ test")
In the next example, the program segment prints ‘This is another test’
X = "This is another test"
PRINT SQUOTE(X)
Related Topics
QUOTE
The UniBasic QUOTE function encloses an expression with quotes.
488
SQRT
SQRT
Syntax
SQRT(num.expr)
Description
The UniBasic SQRT function returns the square root of a positive numeric argument.
Examples
In the following example, the program statement prints SQUARE ROOT OF 16 IS 4.
PRINT "SQUARE ROOT OF 16 IS ":SQRT(16)
489
SSUB
SSUB
Syntax
SSUB(x, y)
Description
The UniBasic SSUB function subtracts the second string number from the first string
number and returns the result as a string number. SSUB is the string subtraction func-
tion. Arguments may be any valid numbers or string numbers of any magnitude and
precision.

Tip speed.
returns a result of zero.
The SSUB function results in a string number, so you can use the function in any
want to use the SSUB function in any expression in which a standard number is valid.
Examples
In the following example, the program statement assigns to variable B the difference
of the string constant (1.4149) and variable A.
B = SSUB("1.4149",A)
490
STATUS
STATUS
Syntax
STATUS( )
Description
The UniBasic STATUS function returns a value that specifies the condition of the
command you just executed.
Each command has a unique set of values it returns for the STATUS function. For
information on the values a particular command returns, refer to the documentation
for that command.
Examples
In the following example, the STATUS function returns a value of 0, indicating a suc-
cessful conversion of a valid date. STATUS would return a 1 if 7334 is an invalid
input date or would return a 2 if D is an invalid conversion specification.
PRINT OCONV(7334,"D")
PRINT STATUS
491
STOP
STOP
Syntax
STOP [expr]
Description
The UniBasic STOP command halts execution of the current program. If you specify
an expression, the system prints the expression on the display terminal prior to halting
the program. expr may be any expression that contains variables, functions, and arith-
metic or string operators.
STOP returns to the UniData prompt, calling menu, or calling paragraph depending on
how you executed the program.
The ABORT command returns you to the system level regardless of what pro-
Tip cess initiated the program.
The STOP command performs differently with BASICTYPE P. The follow-

BASICTYPE
ing syntax is valid in BASICTYPE P:
STOP [message-id]
STOP [expr,...]
The message-id must evaluate to a key contained in the system error message
file. ERRMSG file. expr may be any expression that contains variables, func-
tions, and arithmetic or string operators.
Examples
In the following example, the program segment attempts to read a record from a file.
If the record does not exist, the program aborts and prints the message RECORD IS
MISSING at line 10, column 10 on the terminal.
CUST.ID = 1234
OPEN ’’, ’CUSTOMER’ READONLY TO CUSTOMER ELSE STOP "Cannot Open"
READ REC FROM CUSTOMER, CUST.ID ELSE
STOP @(10,10):’RECORD IS MISSING’
END
In the next example, the segment prints a prompt if an error flag ERR.FLAG has been
set and reads the user’s input into the variable ANS. If ANS equals Y, the program
stops.
492
STOP
ERR.FLAG = 1
IF ERR.FLAG THEN
PRINT "STOP PROGRAM?"
INPUT ANS
IF ANS = "Y" THEN STOP
END
In the next example, in BASICTYPE P, the program segment prints an error message
from record 10075 in the ERRMSG FILE if the program aborts.
If A < 0 THEN ABORT 10075
Related Topics
ABORT
The UniBasic ABORT command terminates the program in progress and returns you
to the UniData system level.
PRINTERR
The UniBasic PRINTERR command prints error messages stored in either the system
error message file ERRMSG or the user-defined error message file.
493
STR
STR
Syntax
STR(str.expr, num.expr)
Description
The UniBasic STR function returns a string composed of a number of repetitions of a
string.
Parameters
str.expr Specifies a string expression to evaluate, concatenate

num.expr times, and return.
num.expr Specifies the number of repetitions of the string expression
to concatenate before returning.
STR Parameters
Examples
In the following example, the program statement prints a string of 25 hyphen charac-
ters on the user’s terminal.
PRINT STR("-",25)
This results in:

-------------------------
494
STRS
STRS
Syntax
STRS(dyn.array.expr)
Description
The UniBasic STRS function returns the each element of the dynamic array dyn.array
the number of times you specify with expr.
Examples
In the following example, the program segment prints the each element of the
dynamic array ARR1 ten times.
ARR1 = 1:@AM:2:@AM:3:@AM:4:@AM:5
ARR2 = STRS(ARR1,10)
PRINT ARR2
This results in:

1111111111}2222222222}3333333333}4444444444}5555555555
495
SUBROUTINE
SUBROUTINE
Syntax
SUBROUTINE sub.name [(argument1 [, argument2] ...)]
Description
The UniBasic SUBROUTINE command determines the beginning of an external
subroutine.
The SUBROUTINE statement must be the first non-comment line in a subroutine.
You can specify arguments to pass data between the main program and the subroutine.
If you pass arguments, the number of arguments in the CALL statement and the SUB-
ROUTINE statement must match. Variables you pass between a main program and
subroutine need not have the same names. Changes made to arguments in the subrou-
tine retain their new values when the system exits the subroutine and control reverts to
the calling program.
Note All subroutines must be cataloged using the ECL CATALOG command prior
to being called. For further information on the CATALOG command, refer to
Parameters
sub.name Specifies the subroutine name.

[(argument1 Specifies arguments to pass into the subroutine. The sub-
[,argument2] routine’s arguments can be simple variables, dynamic
...)] arrays, or matrices.
SUBROUTINE Parameters
Examples
In the following example, the main program prompts the user for two numbers. These
are sent to the subroutine COMP, together with an empty variable C. COMP, using
unique variable names, calculates the average, returning the value in the third variable.
496
SUBROUTINE
REM Main program

PRINT "Enter A,B:":; INPUT A; INPUT B
CALL COMP(A,B,C)
PRINT "Average = ":C
STOP
REM Calculates average of two numbers

SUBROUTINE COMP(X,Y,Z)
Z = (X+Y)/2
RETURN
END
Related Topics
CALL
either from the main program of from another subroutine.
PROGRAM
The UniBasic PROGRAM command defines the name of the current main program
for documentation purposes.
CATALOG
For information on the ECL CATALOG command, refer to UniData Commands
Reference.
497
SUBSTRINGS
SUBSTRINGS
Syntax
SUBSTRINGS(dyn.array, num.expr1, num.expr2)
Description
The UniBasic SUBSTRINGS function extracts strings from elements within a
dynamic array.
Parameters
dyn.array Specifies the dynamic array from which to extract the

substring.
num.expr1 Specifies a character position where the extraction opera-
tion starts.
num.expr2 Specifies the number of characters to return starting from
num.expr1.
SUBSTRINGS Parameters
Examples
In the following example, the program segment extracts the first character of each ele-
ment of the dynamic array LASTNAMES.
LASTNAMES = "Smith":@AM:"Jones":@AM:"Johnson":@AM:"Howard"
LINITIAL = SUBSTRINGS("LASTNAMES",1,1)
PRINT LINITIAL
This results in:

S}J}J}H
498
SUM
SUM
Syntax
SUM(dyn.array [, <attribute.expr [, value.expr]>] [, start.expr [, stop.expr]])
Description
The UniBasic SUM function adds the numeric values in the dynamic array dyn.array
according to dynamic array delimiters. SUM begins with the lowest level of delimiter
and sums all values to the next level.
The UniBasic SUM function has new extensions that allow you to input a range, start-
ing position, and level for which to perform the sum. (3.1.5)
Parameters
The following table describes the parameters of the SUM command:
dyn.array Specifies a dynamic array of numeric values

to sum.
[, <attribute.expr Specifies an optional range within the
[, value.expr]>] dynamic array to sum. The range is specified
[, start.expr [, stop.expr]] as an attribute, a value, and a starting and stp-
ping point.
SUM Parameters
If you have an array of several groups of subvalues separated by values, SUM

Tip performs a sum for each group of subvalues and returns a string of numeric
values. A subsequent SUM returns a single value.
Examples
In the following example, the program segment begins with an array of two values,
each with two subvalues. The SUM function sums the subvalues and returns a string
with two numeric values.
NUM.ARRAY = 12:@SM:10:@VM:15:@SM:15
VAL1 = SUM(NUM.ARRAY)
Results in:
VAL1 = 22:@VM:30
499
SUM
In the next example, the program statement sums VAL1 and returns the numeric value
52 with no dynamic array delimiters.
VAL1 = SUM(VAL1)
500
SWAP
SWAP
Syntax
SWAP str.expr1 WITH str.expr2 IN var
Description
The UniBasic SWAP command replaces all occurrences of one string in a variable
with a second string. The search string does not have to be the same length as the
replacement string.
Tip SWAP functions like CONVERT but swaps one string for another.
Parameters
str.expr1 Specifies the string expression to replace with str.expr2.

str.expr2 Specifies the string expression with which to replace
str.expr1.
IN var Specifies the variable in which to replace str.expr1 with
str.expr2.
SWAP Parameters
Examples
In the following example, the program segment replaces all occurrences of the string
“AB” with the string “AZ” in the variable VAR. The new string assigned to VAR is
“THE TAZ WAS GRAZBED”.
VAR = "THE TAB WAS GRABBED"
SWAP "AB" WITH "AZ" IN VAR
In the next example, SWAP does not replace a character with a character but a string
with a string. This results in HARRY BELAFONTE printing.
STRING = ‘MARION BELAFONTE’
SWAP ‘MARION’ WITH ‘HARRY’ IN STRING
PRINT STRING
501
SWAP
Related Topics
CONVERT
The UniBasic CONVERT command changes all occurrences of characters in a string
to other characters.
502
SYSTEM
SYSTEM
Syntax
SYSTEM(expr)
Description
The UniBasic SYSTEM function retrieves certain system level parameters set either
by previous UniBasic statements or by ECL commands such as SETPTR, TERM, and
query statements.
Note The SYSTEM function is similar to the STATUS function and to several of
the @variables feature in Appendix B @variables. The values of the SYS-
TEM function after the execution of UniBasic command are the same as the
values of the STATUS function under the same condition.
Parameters
expr must evaluate to a number from 0 to 16. If you specify zero, then the value of
SYSTEM is determined by a previously executed UniBasic command. If you select a
number is from 1 to 16, then the system corresponds to predefined system parameters
as described in the following table:
1 1 if PRINTER ON or (P) option or 0 if data is printed to

terminal.
2 Current terminal or page size (width).
3 Current terminal or page length (number of lines on page).
4 Number of lines remaining on current page.
5 Current printer page number.
6 Current number of lines printed on the terminal or printer
page.
7 Terminal type.
8 Current tape block size.
SYSTEM Parameters
503
SYSTEM
9 Current CPU millisecond count from the start of the

program.
10 1 if the current stack (STON) condition enabled; 0 if current
stack is inactive.
11 n if SELECT list is active. n = # of items selected. 0 if the
SELECT list is not active.
12 Current time in milliseconds (local time).
13 Sleeps one second.
14 Number of typeahead characters.
15 Returns command options as a character string.
16 Run level, same as @LEVEL.
17 Indicates where the system transfers control of a UniBasic
program when you run the next RETURN statement.
0 Has no called subroutine or internal subroutine GOSUB
to return to.
1 Returning from a CALL
2 Returning from a GOSUB
18-29 Not currently used.
30 Shows the level to which the break key is set. If the value is
0, the break key is enabled. For all other values, the
BREAK key is disabled. To enable the BREAK key, you
must offset the number of BREAK OFF statements in a
program by an equal number of BREAK ON statements to
bring the value of SYSTEM(30) to zero.
31 Not currently used.
32 Returns current BASICTYPE.
33 Returns the implementation of UniData that is currently
running, either UNIX or VMS.
34 Not currently used.
35 Number of the current language in use.
SYSTEM Parameters (continued)
504
SYSTEM
36 Shows the current settijg for DATE.FORMAT. For setting

0, date format is MM/DD/YY. For setting 1, DATE.FOR-
MAT is DD/MM/YY.
37 The character of the current separator for numeric
thousands.
38 The character of the current separator for decimals.
39 The character of the current symbol for money.
40 Returns the name of the current program being run.
41 Returns the UniData release tape serial number.
SYSTEM Parameters (continued)
Examples
In the following example, the program segment turns on the printer if data is currently
being sent to the display terminal.
IS.ON = SYSTEM(1)
IF IS.ON = 0 THEN
PRINT ’TURNING THE PRINTER ON’
PRINTER ON
END
505
TAN
TAN
Syntax
TAN(num.expr)
Description
The UniBasic TAN function returns the trigonometric tangent of a numeric expres-
sion num.expr.
Examples
In the following example, the program statement prints .2679, the tangent of the argu-
ment 15.
PRINT TAN(15)
506
TIME
TIME
Syntax
TIME( )
Description
The UniBasic TIME function returns the internal system time of day, expressed as the
number of seconds elapsed since midnight.
Note There are no arguments to the TIME function.
Examples
In the following example, the program statement prints the current internal system
time of day. If the time is 1:01 A.M., the system prints the value 3660, the number of
seconds since midnight.
PRINT TIME()
In the next example, the TIME function is used in conjunction with the OCONV func-
tion for conversion to an “external” format:
PRINT OCONV(TIME(),"MT")
Related Topics
DATE
The UniBasic DATE function returns the current system date in internal format.
TIMEDATE
tem time and date in external form.
507
TIMEDATE
TIMEDATE
Syntax
TIMEDATE( )
Description
tem time and the date in external form.
The format the TIMEDATE function returns is:
hh:mm:ss dd mmm yyyy
Examples
In the following example, the program statement assigns the string representation of
the current system time and date to the variable TSTRING.
TSTRING = TIMEDATE()
If the current time and date is July 1st, 1991, at 11:45 AM, TSTRING is:
"11:45:00 01 JUL 1991"
Related Topics
DATE
The UniBasic DATE function returns the current system date in internal format.
TIME
The UniBasic TIME function returns the internal system time of day, expressed as the
number of seconds elapsed since midnight.
508
TRANSACTION ABORT
TRANSACTION ABORT
Syntax
TRANSACTION ABORT
Description
The UniBasic TRANSACTION ABORT command cancels the active transaction.
UniData discards the pending writes. As a result, other users never know that a trans-
action was in progress, and none of the updates associated with the transaction take
place.
A transaction may abort due to any of several conditions in addition to the
TRANSACTION ABORT statement. They include:
• A program that finishes before a transaction commit is issued (STOP or
END).
• A CHAIN to another program.
• An error that terminates the program before a transaction commit is
issued.
• A user breaks out of the program before a transaction commit is issued.
This can be controlled programmatically by disabling the break key dur-
ing a transaction.
• A forced logout or a process is killed, thereby terminating a program
before a transaction commit is issued.
The system handles these abort conditions in the same way as the TRANSACTION
ABORT statement, i.e., it cancels the transaction.
Tip You should be aware of these various abort conditions and control the result-
ing action from within the program where possible and appropriate. For
example, write statements that fail execute the ON ERROR clause if it exists,
otherwise the program aborts and the transaction also aborts.
509
TRANSACTION ABORT
Examples
In the following example, the transaction process will abort if var is a null.
TRANSACTION START
THEN PRINT "Transaction started."
ELSE PRINT "Transaction start failed, STATUS = ":STATUS(): STOP
READU var FROM file.var, record1
var += 2
IF var = 10 THEN TRANSACTION ABORT; GOTO ERR:
WRITE var TO file.var, record1
TRANSACTION COMMIT
THEN PRINT "Transaction committed."
ELSE PRINT "Transaction Aborted, STATUS = ":STATUS(); STOP
510
TRANSACTION COMMIT
TRANSACTION COMMIT
Syntax
TRANSACTION COMMIT [THEN statement(s)] [ELSE statement(s)]
Description
The UniBasic TRANSACTION COMMIT command concludes the active transac-
tion. UniData writes all pending writes to the appropriate files. If a TRANSACTION
COMMIT statement executes without an active transaction, the system executes the
ELSE clause, otherwise the system executes the THEN clause. You must specify a
THEN or an ELSE clause. You may specify both clauses.
The system performs the following steps during a transaction commit:
• Disables the break key
• Writes all updates
• Releases all record locks locked inside the transaction
• Executes the THEN clause, if it exists
• Enables the break key
If the transaction cannot commit and the ELSE clause executes, the system performs
the following steps:
• Aborts the transaction
• Executes the ELSE clause, if it exists
• Releases all record locks inside the transaction
STATUS Values
The following table describes the values the UniBasic STATUS function returns when
you use it with the TRANSACTION COMMIT command:
Value Description
1 Transaction not started.

2 Recoverable File System
is not running.
STATUS Values
511
TRANSACTION COMMIT
Value Description
3 Transaction can’t commit.
STATUS Values (continued)
Examples
In the following example, the TRANSACTION COMMIT command ends the transac-
tion process and writes the new record to the database.
TRANSACTION COMMIT
THEN PRINT "Transaction committed."
ELSE PRINT "Transaction aborted, STATUS = ":STATUS(); STOP
512
TRANSACTION START
TRANSACTION START
Syntax
TRANSACTION START [THEN statement(s)] [ELSE statement(s)]
Description
The UniBasic TRANSACTION START command initiates a new transaction and
temporarily stores all updates until a TRANSACTION COMMIT or TRANSAC-
TION ABORT statement. A transaction start that you issue when another transaction
is active (nested transactions) executes the ELSE clause, if present, and the associated
statements. Otherwise, the system executes the THEN clause, if present, and the asso-
ciated statements. You must specify a THEN or an ELSE clause. You may specify
both clauses.
Parameters
The following table describes the parameters:
[THEN statement(s)] Specifies statements to execute when you

start the transaction.
ELSE statement(s)]} Specifies statements to execute if you start
this transaction when another transaction is
active (nested transactions).
TRANSACTION START Parameters
STATUS Values
The following table describes the values the UniBasic STATUS function returns when
you use it with the TRANSACTION START command:
Value Description
1 Indicates a nested start.
STATUS Values
513
TRANSACTION START
Value Description
2 Indicates the Recover-

able File System is not
on.
STATUS Values (continued)
Note For information on the STATUS function, refer to the Developing UniBasic
Applications.
Examples
In the following example, the TRANSACTION START command starts the transac-
tion process:
TRANSACTION START
THEN PRINT "Transaction started."
ELSE PRINT "Transaction start failed, STATUS = ":STATUS();STOP
514
TRIM
TRIM
Syntax
TRIM(str.expr[,char[,type]])
Description
The UniBasic TRIM function removes any spaces from a string expression. If the sys-
tem does not find any spaces, the string remains unchanged.
TRIM removes any leading or trailing spaces from a string and converts any contigu-
ous spaces in a string to one space. Single blanks between text are not removed.
Parameters
str.expr Specifies a string expression from which to remove spaces

or a specified character char.
[,char] Specifies a character, instead of spaces, to remove from
str.expr.
If you do not specify char, TRIM removes all preceding,
trailing, and contiguous spaces from the string.
[,type] Specifies the type of removal to perform. If you do not
specify a type, R is the default. If char is null, the system
does not perform the operation.
TRIM Parameters
You may also specify the type of removal to perform. The following table describes
each type of removal.
Type Description
L Removes all leading occurrences of char.

T Removes all trailing occurrences of char.
TRIM Types
515
TRIM
Type Description
B Removes leading and trailing occurrences of char.

A Removes all occurrences of char.
R Removes all leading, trailing, and contiguous occurrences
of char.
TRIM Types (continued)
Examples
In the following example, the program statement removes the trailing blanks from the
variable NAME.
NAME = " Zenith, R. "
NAME = TRIM(NAME)
This results in
NAME = "Zenith,R."
In the next example, the program segment removes the asterisks from the variables X
and Y in BASICTYPE P.
X = TRIM("***NOT***ICE***","*")
Y = TRIM("***NOT***ICE***","*","A")
This results in:

X = "NOT*ICE"
Y = "NOTICE"
Related Topics
TRIMB
The UniBasic TRIMB function deletes any trailing blanks of a string.
TRIMF
The UniBasic TRIMF function deletes any leading blanks of a string.
516
TRIMB
TRIMB
Syntax
TRIMB(str.expr)
Description
The UniBasic TRIMB function removes any trailing spaces from a string expression.
If the system does not find any trailing spaces, the string remains unchanged.
Examples
In the following example, the program statement removes the trailing blanks from the
variable NAME.
NAME = " Zenith, R. "
NAME = TRIMB(NAME)
This results in:

NAME = " Zenith,R."
Related Topics
TRIM
The UniBasic TRIM function removes any leading, trailing, or contiguous spaces in a
string.
TRIMF
The UniBasic TRIMF function removes any leading spaces in a string.
517
TRIMF
TRIMF
Syntax
TRIMF(str.expr)
Description
The UniBasic TRIMF function removes any leading spaces from the string expres-
sion. If the system does not find any leading spaces, the string remains unchanged.
Examples
In the following example, the program segment removes the leading spaces from the
variable NAME, storing the resulting string.
NAME= " Zenith, R. "
NAME = TRIMF(NAME)
This results in:

"Zenith, R. "
Related Topics
TRIM
The UniBasic TRIM function removes any leading, trailing, or contiguous spaces in a
string.
TRIMB
The UniBasic TRIMB function removes any trailing spaces in a string.
518
TRIMS
TRIMS
Syntax
TRIMS(dyn.array)
Description
The UniBasic TRIMS function removes any spaces from each element of a dynamic
array. If the system does not find any spaces, the element remains unchanged.
TRIMS removes any leading or trailing spaces from a string and converts any contig-
uous spaces in a string to one space. Single blanks between text are not removed.
Examples
In the following example, the program segment removes any spaces from each ele-
ment of the dynamic array ARR1.
ARR1 = " Jones ":@AM:" Smith ":@AM:" Johnson "
ARR1 = TRIMS(ARR1)
This results in:

Jones}Smith}Johnson
519
UDTEXECUTE
UDTEXECUTE
Syntax
UDTEXECUTE str.expr [[ASYNC | SYNC] ON connection]]
[CAPTURING cap.var] [RETURNING cap.var] [PASSCOM]
Description
The UniBasic UDTEXECUTE command executes a command in ECLTYPE U,
regardless of the BASICTYPE you compiled the program with. This command is sim-
ilar to using the EXECUTE command in a program compiled in BASICTYPE U.
When you compile a program in BASICTYPE P, any PERFORM or

Tip EXECUTE commands pass the PERFORM string to a non-standard UniData
parser. This parser looks for a specific sentence structure common to
BASICTYPE P systems. Standard UniQuery sentences may not be handled
correctly in this circumstance. Therefore, when you want to execute a stan-
dard UniQuery statement from within a UniBasic program which has been
compiled under BASICTYPE P, use the UDTEXECUTE command instead of
PERFORM or EXECUTE.
STACKCOMMON
when one program executes another program, the unnamed common is passed to the

BASICTYPE
BASICTYPE U.
520
UDTEXECUTE
Parameters
str.expr Specifies a command to execute.

[CAPTURING cap.var] Specifies a dynamic array to create and assign
the output, which would otherwise appear on
the display terminal. Each line of the text
becomes an attribute in the array. Output you
direct to the printer is not affected by this
clause and is still sent to the printer.
You may nest EXECUTE statements that use
the CAPTURING clause. Currently, the
embedded level is set to 2.
[RETURNING cap.var] Specifies a string variable to which to assign
any error messages from the command you
execute with UDTEXECUTE.
The RETURNING clause captures the error
messages from the command you execute with
PERFORM into a string variable. This variable
is a string of error message numbers separated
by spaces. If the command you execute creates
a spooler hold file, the hold file entry number is
also entered into the returning variable.
[PASSCOM] The PASSCOM clause is available for back-
ward compatibility with releases prior to 3.1.
UDTEXECUTE Parameters
Related Topics
EXECUTE and PERFORM
The UniBasic EXECUTE and PERFORM commands execute an ECL command from
521
UNASSIGNED
UNASSIGNED
Syntax
UNASSIGNED(var.name)
Description
The UniBasic UNASSIGNED function checks a variable in a program to see if it is
currently assigned a value. If the variable is not assigned a value, the function returns
1; otherwise, it returns 0.
Examples
In the following example, the program statement returns 0 if FILENAME is currently
assigned a value; returns 1 if a value is not currently assigned.
X = UNASSIGNED(FILENAME)
522
UNLOCK
UNLOCK
Syntax
UNLOCK [num.expr]
Description
The UniBasic UNLOCK command unlocks predefined computer resources reserved
by the LOCK command. Resource numbers may range from 0 to 63. If you do not
specify a resource number, the system releases all locks you have set. If there are no
locked resources at the time of execution, the statement does not have any effect.
Reminder The system does not automatically releases all locks when the user exits the
program.
Examples
In the following example, the program statement unlocks all computer resources
reserved by the current user.
UNLOCK
Related Topics
LOCK
The UniBasic LOCK command reserves a computer resource for the current UniBasic
program.
LIST.LOCKS
For information on the ECL LIST.LOCKS command, refer to UniData Commands
Reference.
523
UPCASE
UPCASE
Syntax
UPCASE(string.expr)
Description
The UniBasic UPCASE function converts lower case characters in a string to upper-
case characters. Numeric values are not changed.
Examples
In the following example, the program segment converts “be bold!!” to “BE BOLD!!”
STRING = ’be bold!!’
PRINT UPCASE(STRING)
Related Topics
DOWNCASE
The UniBasic DOWNCASE function converts upper case characters in a string to
lowercase characters.
524
USE
USE
Syntax
USE database ON connection [ON ERROR statements]
Description
The UniBasic USE command specifies what database to use when connected to a
server. Each server can access more than one database and VOC file. For information
on how to set up databases so you can access them, refer to Administering UniServer.
STATUS
After the execution of the USE statement, STATUS is set to one of the following:
0 Success
1 Server is not connected
2 Database couldn’t be found
3 Database has a different UDTHOME than the server
4 Other errors
USE Command STATUS Values
Parameters
database The name of the database to use.

connection The handle of the connection to the server.
USE Parameters
525
USE

statements] tinue to perform if the USE statement fails. It then
executes the statements you specify.
USE Parameters (continued)
526
WAIT
WAIT
Syntax
WAIT connection [ON ERROR statements]
Description
The UniBasic WAIT command holds the execution of a UniBasic program until the
results of an asynchronous execution are returned. When UniData executes an EXE-
CUTESQL, EXECUTE, PERFORM, UDTEXECUTE or CALL statement in an asyn-
chronous manner, the program does not wait for the results of the execution and
continues executing the program. The WAIT command specifies when to stop execu-
tion and wait for the results.
When you specify the SYNC parameter with an EXECUTESQL, EXECUTE,

Tip PERFORM, UDTEXECUTE or CALL statement, the program performs a
synchronous execution and waits for the results of the command and returns
them before continuing with the program.

STATUS
After the execution of the WAIT statement, STATUS is set to one of the following:
0 Success
2 Other errors
WAIT Command STATUS Values
527
WAIT
Parameters
connection Specifies the handle to a server you specified

with the CONNECT command.
[ON ERROR statements] The ON ERROR clause allows the program to
continue to perform if the WAIT statement fails.
It then executes the statements you specify.
WAIT Parameters
528
WEOF
WEOF
Syntax
WEOF [UNIT(mu.expr)] {THEN | ELSE} statements [END]
Description
The UniBasic WEOF command writes an EOF (end-of-file) mark to a magnetic tape.
Parameters
[UNIT(mu.expr)] Specifies the conversion code (first digit), and

unit numbers ranging from 0 to 9.
The mu.expr is optional and the default value
for UNIT is (00) for tape unit 0 and no
conversion (ASCII assumed).
{THEN | ELSE} Specifies statements to execute if the write is
statements [END] successful (THEN) or unsuccessful (ELSE)
multiple lines, an END at the end is required.
The statements may appear on the same line
with the keyword, separated by semicolon(s).
In this case END is not necessary.
WEOF Parameters
529
WEOF

Code Meaning

1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
WEOF Conversion Codes
WEOF and the STATUS function

The STATUS function is set after each WEOF operation. The following table
describes the values the STATUS function returns after you execute a WEOF state-
ment.
Value Description
0 Successful read
3 Tape not assigned
4 Parity error
Examples
In the following example, the program statement writes an end-of-file mark to tape 0.
If the system is unable to write the end of file mark, the system executes the ELSE
clause.
WEOF UNIT(00) ELSE "Unable to write an end-of-file"
530
WEOF
Related Topics
READT
to a variable.
REWIND
The UniBasic REWIND command rewinds a magnetic tape back to its beginning.
WRITET
The UniBasic WRITET command writes an expression as a record to a magnetic tape.
531
WEOFSEQ
WEOFSEQ
Syntax
WEOFSEQ seq.file.var [ON ERROR statements]
Description
The UniBasic WEOFSEQ command writes an end-of-file mark at the record pointer
position in a sequential file.
WEOFSEQ is generally used after a series of WRITESEQ operations.

Tip
Parameters
seq.file.var Specifies a sequential file variable to which to

write the end-of-file mark.
error conditions.
WEOFSEQ Parameters
Examples
In the following example, the program statement writes an end-of-file mark to the file
TRIAL.RUN at the current pointer position.
WEOFSEQ TRIAL.RUN
Related Topics
OPENSEQ
The UniBasic OPENSEQ command opens a sequential file for access.
532
WEOFSEQ
READSEQ
The UniBasic READSEQ command assigns the next record from an open sequential
file to a variable.
WRITESEQ
file.
Sequential Input/Output
For information on sequential input/output, refer to Developing UniBasic
Applications.
533
WRITE
WRITE
Syntax
WRITE expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic WRITE command writes an expression to a record.
The WRITE statement releases record locks set by the MATREADU,

Tip READL, READU, and READVU commands. If it is necessary to maintain a
record lock, use the WRITEU command.
The record being accessed is automatically locked by the system during the execution
of the write operation to maintain file integrity (this is not a programmable lock). If
the STATUS function is set to -2 after the execution of a WRITE statement, the record
was locked prior to the write; if the STATUS function is equal to 0, the record was
unlocked.
Note The system displays an error message when trying to write to an inaccessible
file.
Parameters
expr Specifies an expression to write to the record.

{ON | TO} file.var Specifies a file variable to which to write the
expression.
If you do not specify file.var, the system writes
the expression to the most recently opened
default file.
record.ID.expr Specifies a record to which to write the expres-
sion. If the record already exists, the new
expression you specify with expr replaces the
existing information. If the record you specify
does not exist, the system creates the record.
WRITE Parameters
534
WRITE

error conditions.
WRITE Parameters (continued)
Examples
In the following example, the program statement writes the variable SRO to the
default system file as a record with ID M87.
WRITE SRO TO "M87"
In the next example, the program statement writes the contents of the variable OVER-
STOCK to the file named in variable FNAME as a record, with ID OS.
WRITE OVERSTOCK TO FNAME,"OS"
535
WRITELIST
WRITELIST
Syntax
WRITELIST var ON list.name
Description
The UniBasic WRITELIST command writes the contents of a variable to a saved list
in SAVEDLISTS of the current account.
Note WRITELIST only saves the first value of the attribute into the saved list (i.e.,
if the attribute is a singlevalued attribute, the system saves the value in that
attribute to the list; if the attribute contains multivalues or subvalues, the sys-
tem only saves the first multivalue or subvalue). The values you save can then
be used as item IDs to retrieve the data record.
Parameters
var Specifies a variable to write to a saved list.

ON list.name Specifies a saved list to which to write the con-
tents of var.
WRITELIST Parameters
Related Topics
READLIST
The UniBasic READLIST command assigns the values remaining in an active list to a
dynamic array.
GET.LIST
For information on the ECL GET.LIST command, refer to UniData Commands
Reference.
536
WRITESEQ
WRITESEQ
Syntax
WRITESEQ expr [APPEND] {ON | TO} seq.file.var [ON ERROR statements]
Description
The UniBasic WRITESEQ command writes an expression as a record on a sequential
file from a current record pointer position.
Tip Perform the READSEQ command to position the record pointer set prior to
performing WRITESEQ.
Note WRITESEQ may or may not physically write a record to disk. The system
stores records in the system buffer until its capacity is reached; only then are
they written to disk.
Parameters
expr Specifies an expression to write as a record.

expr has a size limit based on parameters set at
system installation.
[APPEND] Use the APPEND option to start the
WRITESEQ process at the end-of-file mark. If
you use the APPEND option in a file that does
not contain data, the system creates a new file.
{ON | TO} seq.file.var Specifies a sequential file variable to which to
write the expression.
WRITESEQ Parameters
537
WRITESEQ

error conditions.
system cannot find the end-of-file mark, the
{THEN | ELSE} If the current pointer position is not at the end
statements [END] of the file, the system executes the statements
after the ELSE clause. If the operation ends
successfully, the system executes the state-
ments after the THEN clause.
essary.
WRITESEQ Parameters (continued)
Examples
In the following example, the program segment writes the expression
BAD.ACCOUNTS to the file ACCOUNTS. A message displays if the record pointer
is not at the end-of-file.
WRITESEQ BAD.ACCOUNTS TO ACCOUNTS
ELSE PRINT "NOT AT END-OF-FILE"
Related Topics
WRITESEQF
file and forces the computer to physically write the data to disk.
538
WRITESEQF
WRITESEQF
Syntax
WRITESEQF expr [APPEND] {ON | TO} seq.file.var [ON ERROR statements]
Description
The UniBasic WRITESEQF command writes an expression as a record on a sequen-
tial file from a current record pointer position and forces the system to immediately
write the data to the disk.
Perform the READSEQ command to position the record pointer set prior to
Tip performing WRITESEQF.
Parameters
expr Specifies an expression to write as a record.

expr has a size limit based on parameters set at
system installation.
[APPEND] Use the APPEND option to start the
WRITESEQF process at the end-of-file mark.
If you use the APPEND option in a file that
does not contain data, the system creates a new
file.
{ON | TO} seq.file.var Specifies a sequential file variable to which to
write the expression.
WRITESEQF Parameters
539
WRITESEQF

error conditions.
system cannot find the end-of-file mark, the
{THEN | ELSE} If the current pointer position is not at the end
statements [END] of the file, the system executes the statements
after the ELSE clause. If the operation ends
successfully, the system executes the state-
ments after the THEN clause.
essary.
WRITESEQF Parameters (continued)
Examples
In the following example, the program statement writes the variable CHK.WRITE to
the file PAYROLL. All records currently in the output buffer are written to disk along
with this record.
WRITESEQF CHK.WRITE ON PAYROLL ELSE GOTO 100:
Related Topics
WRITESEQ
file.
540
WRITET
WRITET
Syntax
WRITET [UNIT(mu.expr)] expr {THEN | ELSE} statements [END]
Description
The UniBasic WRITET command allows you to write the value of an expression as a
record onto tape.
Note Before you can use the WRITET command you must reserve a tape drive for
use with the T.ATT command. For detailed information on tape commands,

Therefore, ASCII 0 cannot be used in any string variable within UniBasic. If a
string is read into UniBasic with a CHAR(0) character and converted to
CHAR(128), this command converts CHAR(128) back to CHAR(0) when
writing a block of characters.

Code Meaning

1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
WRITET Conversion Codes
Multi-Reel Tape Processing

You must use the TAPELEN option for the T.ATT command and specify the length
you desire for the tape in megabytes. This is for UniData tapes only. For information
on the ECL T.ATT command, refer to UniData Commands Reference.
541
WRITET
WRITET and the STATUS function

The STATUS function is set after each WRITET operation. The following table
describes the values the STATUS function will return after you execute a WRITET
statement.
Value Description
0 Successful read
3 Tape not assigned
4 Parity error
Parameters
[UNIT(mu.expr)] Specifies aconversion code (first digit), and

unit number (second digit). UniData allows
unit numbers ranging from 0 to 9. The mu.expr
is optional and the default value is UNIT (00)
for tape unit 0 and no conversion (ASCII
assumed).
expr Specifies an expression to write as a record on
the tape.
WRITET Parameters
542
WRITET
{THEN | ELSE} If the write is unsuccessful or the end of the file

statements [END] (or tape) is encountered, the system executes
the statements after the ELSE clause. If the
operation ends successfully, the system exe-
cutes the statements after the THEN clause.
essary.
WRITET Parameters (continued)
Examples
In the following example, After using the T.ATT command, system writes the vari-
able TAX.RECORD to tape.
PERFORM "T.ATT"
WRITET UNIT (00) TAX.RECORD ELSE PRINT ‘TAPE PROBLEM’
Related Topics
READT
to a variable
Tape Commands
For information on ECL tape commands (i.e., T.ATT), refer to UniData Commands
Reference.
543
WRITEU
WRITEU
Syntax
WRITEU expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
Description
The UniBasic WRITEU command writes an expression to a record and does not
release the record if it was previously locked by one of the lock processes in the
MATREADU, READL, READU, or READVU statements.
Parameters
expr Specifies an expression to write to the record..

{ON | TO} [file.var,] Specifies a file variable to which to write the
expression.
If you do not specify file.var, the system writes
the expression to the most recently opened
default file.
record.ID.expr Specifies a record to which to write the
expression.
statements] a fatal error condition (if the file is not open, if
an I/O error occurs in the write accessing pro-
cess, or if the file is a read-only file). If you do
not specify the ON ERROR clause, the pro-
gram terminates under such fatal error
conditions.
WRITEU Parameters
Examples
In the following example, the program statement writes the variable IDEA.57 to the
file IDEAS as a record with the ID ‘LAST’. The lock remains in place if the record
was locked prior to performing WRITEU.
544
WRITEU
WRITEU IDEA.57 ON IDEAS,‘LAST’
Related Topics
WRITEV
The UniBasic WRITEV command writes an expression of an attribute of a data
record.
545
WRITEV
WRITEV
Syntax
WRITEV expr {ON | TO} [file.var,] record.ID.expr, attrib.expr
Description
The UniBasic WRITEV command writes an expression to an attribute of a data
record, and writes only a single attribute rather than an entire record.
Note The WRITEV command releases any update locks on a record.
Parameters
expr Specifies an expression to write to an attribute of a

record.
{ON | TO} Specifies a file to which to write the expression.
[file.var,] If you do not specify a file with file.var, the record
is written to the most recently opened default file.
If the specified file cannot be found or if a default
file does not exist, the program aborts and an error
message displays (unless you use the ON ERROR
clause).
expression.
attrib.expr Specifies an attribute to which to write the
expression.
WRITEV Parameters
546
WRITEV
[ON ERROR Specifies statements to execute in the event of a

statements] fatal error condition (if the file is not open, if an
I/O error occurs in the write accessing process, or
if the file is a read-only file). If you do not specify
WRITEV Parameters (continued)
Examples
In the following example, the program statement writes the variable NAME to the first
attribute in the customer record with CUST.ID in the file CUSTOMER.
WRITEV NAME ON CUSTOMER,CUST.ID,1
In the next example, the program segment reads an attribute in the record with ID of
TAPE.ID in the file TAPES into the variable NBR.TIMES.
READV NBR.TIMES FROM TAPES,TAPE.ID,
NBR.TIMES.ATTRIBUTE
NBR.TIMES += 1
WRITEV NBR.TIMES ON TAPES,TAPE.ID, NBR.TIMES.ATTRIBUTE
The position of the attribute within the actual record is stored in the variable
NBR.TIMES.ATTRIBUTE. After reading the variable, the system increments and
writes the variable back using the WRITEV command.
Related Topics
READV
The UniBasic READV command retrieves an attribute from a record and assigns its
value to a variable.
WRITE
The UniBasic WRITE command writes an expression to a record of a previously
opened file.
File Input/Output
547
WRITEVU
WRITEVU
Syntax
WRITEVU expr {ON | TO} [file.var,] record.ID.expr, attrib.expr
Description
The UniBasic WRITEVU command writes an expression to an attribute of a data
record, and writes only a single attribute rather than an entire record, but does not
release a lock set previously by any locking READ statement. As with the WRITEV
statement, the record ID and attribute number are mandatory.
The ON ERROR clause allows the program after the WRITEVU statement to con-
tinue to perform under the following fatal error conditions: if the file is not open, if an
I/O error occurs in the write accessing process, or if the file is a read-only file. If you
do not specify the ON ERROR clause, the program terminates under such fatal error
conditions.
Parameters
expr Specifies an expression to write to an attribute of a

record.
{ON | TO} Specifies a file to which to write the expression. If
[file.var,] you do not specify a file with file.var, the record is
written to the most recently opened default file. If
the specified file cannot be found or if a default
file does not exist, the program aborts and an error
message displays (unless you use the ON ERROR
clause).
expression.
attrib.expr Specifies an attribute to which to write the
expression.
WRITEVU Parameters
548
WRITEVU
[ON ERROR Specifies statements to execute in the event of a

statements] fatal error condition (if the file is not open, if an I/
O error occurs in the write accessing process, or if
the file is a read-only file). If you do not specify
WRITEVU Parameters (continued)
Examples
In the following example, the program statement writes the variable NEW.TAPES in
the file TAPES to the record with ID TAPE.ID as an attribute in the position
NEW.ATTRIBUTE.
WRITEVU NEW.TAPES ON TAPES, TAPE.ID,NEW.ATTRIBUTE
549
XLATE
XLATE
Syntax
XLATE(file.expr, rec.id.expr, attrib.expr, "code")
Description
The UniBasic XLATE function returns the contents of an attribute.
Parameters
file.expr Specifies the name of a file from which to

return the contents of an attribute. file.expr
must be the name of a valid UniData file, not
the value of a file variable, even if the same file
was opened within the program.
rec.id.expr Specifies an expression evaluating to a record
ID in file.expr.
attrib.expr Specifies an expression evaluating to a valid
attribute in file.expr.
code Specifies the XLATE code.
XLATE Parameters
XLATE Codes
The following table describes the XLATE valid codes.
Code Description
C If the record does not exist or the attribute is null, substi-

tute the id.exp for the value of the function
V If the record does not exist or the attribute is null, return a
null value and print an error message.
XLATE Codes
550
XLATE
Code Description
X If the record does not exist or the attribute is null, return a

null.
XLATE Codes
Note You must place code specifications in "quotes".
Related Topics
TRANS
For information on the TRANS function, refer to Using UniData.
551
Appendix A SOFTWARE PRODUCTS
ASCII Character Codes
This appendix describes each ASCII (American Standard Code for Information Inter-
change) code.
ASCII Value Character Hex Character
000 NUL 0
001 SOH 1
002 STX 2
003 ETX 3
004 EOT 4
005 ENQ 5
006 ACK 6
007 BEL 7
008 BS 8
009 HT 9
010 LF A
552
011 VT B
012 FF C
013 CR D
014 SO E
015 SI F
016 DLE 10
017 DC1 11
018 DC2 12
019 DC3 13
020 DC4 14
021 NAK 15
022 SYN 16
023 ETB 17
024 CAN 18
025 EM 19
026 SUB 1A
027 ESC 1B
028 FS 1C
029 GS 1D
030 RS 1E
031 US 1F
032 (space) 20
033 ! 21
034 " 22
035 # 23
ASCII Character Codes (continued)
553
036 $ 24
037 % 25
038 & 26
039 ’ 27
040 ( 28
041 ) 29
042 * 2A
043 + 2B
044 , 2C
045 - 2D
046 . 2E
047 / 2F
048 0 30
049 1 31
050 2 32
051 3 33
052 4 34
053 5 35
054 6 36
055 7 37
056 8 38
057 9 39
058 : 3A
059 ; 3B
060 < 3C
554
061 = 3D
062 > 3E
063 ? 3F
064 @ 40
065 A 41
066 B 42
067 C 43
068 D 44
069 E 45
070 F 46
071 G 47
072 H 48
073 I 49
074 J 4A
075 K 4B
076 L 4C
077 M 4D
078 N 4E
079 O 4F
080 P 50
081 Q 51
082 R 52
083 S 53
084 T 54
085 U 55
555
086 V 56
087 W 57
088 X 58
089 Y 59
090 Z 5A
091 [ 5B
092 \ 5C
093 ] 5D
094 ^ 5E
095 _ 5F
096 ‘ 60
097 a 61
098 b 62
099 c 63
100 d 64
101 e 65
102 f 66
103 g 67
104 h 68
105 i 69
106 j 6A
107 k 6B
108 l 6C
109 m 6D
110 n 6E
556
111 o 6F
112 p 70
113 q 71
114 r 72
115 s 73
116 t 74
117 u 75
118 v 76
119 w 77
120 x 78
121 y 79
122 z 7A
123 { 7B
124 | 7C
125 } 7D
126 ~ 7E
127 DEL 7F
128 Ç 80
129 ü 81
130 é 82
131 â 83
132 ä 84
133 à 85
134 å 86
135 ç 87
557
136 ê 88
137 ë 89
138 è 8A
139 ï 8B
140 î 8C
141 ì 8D
142 Ä 8E
143 Å 8F
144 É 90
145 æ 91
146 Æ 92
147 ô 93
148 ö 94
149 ò 95
150 û 96
151 ù 97
152 ÿ 98
153 Ö 99
154 Ü 9A
155 ¢ 9B
156 £ 9C
157 ¥ 9D
158 ¤ 9E
159 ƒ 9F
160 á A0
558
161 í A1
162 ó A2
163 ú A3
164 ñ A4
165 Ñ A5
166 ª A6
167 º A7
168 ¿ A8
169 “ A9
170 ” AA
171 ‹ AB
172 › AC
173 ¡¦ AD
174 « AE
175 » AF
176 ã B0
177 õ B1
178 Ø B2
179 ø B3
180 œ B4
181 Œ B5
182 À B6
183 Ã B7
184 Õ B8
185 § B9
559
186 ‡ BA
187 † BB
188 ¶ BC
189 © BD
190 ® BE
191 ™ BF
192 „ C0
193 … C1
194 ‰ C2
195 • C3
196 – C4
197 — C5
198 ° C6
199 Á C7
200 Â C8
201 È C9
202 Ê CA
203 Ë CB
204 Ì CC
205 Í CD
206 Î CE
207 Ï CF
208 Ò D0
209 Ó D1
210 Ô D2
560
211 D3
212 D4
213 Ù D5
214 Ú D6
215 Û D7
216 Ÿ D8
217 ß D9
218 DA
219 DB
220 DC
221 DD
222 DE
223 DF
224 E0
225 E1
226 E2
227 E3
228 E4
229 E5
230 E6
231 E7
232 E8
233 E9
234 EA
235 EB
561
236 EC
237 ED
238 EE
239 EF
240 F0
241 F1
242 F2
243 F3
244 F4
245 F5
246 F6
247 F7
248 F8
249 F9
250 FA
251 Text Mark FB
252 Sub Value Mark FC
253 Value Mark FD
254 Attribue Mark FE
255 Record Mark FF
562
Appendix B SOFTWARE PRODUCTS
@variables
This appendix describes the @variables available in UniBasic, the compiler @vari-
ables, and the various return codes returned by the @SYSTEM.RETURN.CODE
@variable.
563
@variables
@Variables
The following table describes the valid @variables.
@variable Description
@ACCOUNT Returns the UNIX or VMS path where

you first entered UniData. Note that the
value of @ACCOUNT does not change
when a LOGTO statement is executed.
@AM Inserts an Attribute Mark at compile time.
For information on other compiler vari-
ables, refer to the Compiler @Variables
section in this appendix.
@COMMAND Last UniData command executed.
Changes the value for each statement exe-
cuted at the UniData ECL prompt ( : ) and
in the UniBasic EXECUTE statement.
@CONV Used with CALCULATE and the
Braces{} function. Returns the conversion
code from a dictionary item.
@CRTHIGH Height of the CRT screen.
@CRTWIDE Width of the CRT screen.
@DATA DATA statements used in conjunction
with INPUT statements are stored in a
stack. This stack is accessible in the
@DATA variable. Data elements are
delimited by ASCII 013 (CR). @DATA is
a READ ONLY variable.
@DATE System date when the program began in
the internal format.
@DAY Two-digit day of the month.
@DICT Current dictionary (must perform an
assignment).
@variables
564
@variables
@FORMAT Used with CALCULATE and the {}

“braces” function. Returns the format code
from a dictionary item.
@GID Returns the UNIX or VMS group ID
assigned to a user.
@HEADER Used with CALCULATE and the {}
“braces” function. Returns the column
heading from a dictionary item.
@ID Current user ID, (must perform an
assignment).
@LASTVERB Stores the last executed command.
@LEVEL Current PERFORM or EXECUTE level.
@LOGNAME Returns the user’s login name.
@LPTRHIGH Page length (height) of the system line
printer.
@LPTRWIDE Page width of the system line printer.
@MONTH Two-digit representation of the current
month.
@PARASENTENCE The last paragraph or sentence entered. It
retains the name and parameters of the
current executing paragraph. If there is not
a paragraph currently being executed, it
contains a null value. If another paragraph
is called within the paragraph being exe-
cuted, then its value is the data of the
called paragraph. When the process
returns to the original paragraph, its value
is reset to the value of the original
paragraph.
@PATH Current UNIX or pathname for the direc-
tory where the user resides. The value of
@PATH changes with the LOGTO
command.
@variables (continued)
565
@variables
@RECORD Current record (must be assigned).

@RECUR0 Recursive user defined. @RECUR#
@RECUR1 variables are reset at the ECL prompt.
@RECUR2
@RECUR3
@RECUR4
@RM Inserts a Record Mark at compile time.
@SENTENCE The sentence that invoked the current
UniBasic program in progress. Changes
the value for each statement executed at
the UniData ECL prompt ( : ) and each
statement in a para graph or sentence in a
UniBasic program. Each EXECUTE and
CHAIN statement also changes its value.
@SM Inserts a Subvalue Mark (same as @SVM)
at compile time.
@SVM Inserts a Subvalue Mark (same as @SM)
at compile time.
@SYS.BELL Allows the bell on the users terminal to be
enabled or disabled.
566
@variables
@SYSTEM.RETURN.CODE Returns a value indicating a condition or

error after the execution of an ECL com-
mand. For most commands, a 0 indicates
the command was completed correctly,
and a -1 indicates that the command was
not completed correctly.
For some commands, the value that this
@variable returns differ. Refer to the
“@SYSTEM.RETURN.CODE” section in
this appendix.
@TIME The time when the program began, in the
internal format.
@TM Inserts a Text Mark at compile time. The
Text Mark has no direct effect, but can be
used by UniBasic programs.
ables, refer to the “Compiler @Variables”
@TRANSACTION Returns 1 if there is a transaction occur-
ring, 0 if there is no transaction occurring.
@TTY Returns the terminal port name, such as
tty01, tty1a, console, etc.
@TUPLE Used with the Screen and Report Genera-
tors. Refer to Using Application Tools.
@UID The UNIX user ID number for the user.
@UDTNO Returns an integer between 1 and the max-
imum number of users allowed on the sys-
tem. Numbers are assigned sequentially,
based on the sequence of entry into
UniData. Phantom processes are counted.
@USER0 User defined. @USER# variables retain
@USER1 the value throughout a user session unless
@USER2 the values are explicitly changed.
@USER3
@USER4
567
@variables
@USERNO Current udt process ID number.

@USER.RETURN.CODE User defined.
@USER.TYPE Returns the type of process currently run-
ning. UniBasic has two types of processes:
normal terminal processes and background
or phantom processes.
@VM Inserts a Value Mark at compile time.
ables, refer to the “Compiler @Variables”
@WHO Contains the final node at the end of the
directory tree (e.g., if you are under /u/ud/
AP, the value of @WHO should be AP).
@YEAR Two digit representation of the year.
568
@variables
Compiler @variables
The following @variables cause compiler to insert special delimiters for dynamic
arrays at compile time.
@AM Attribute mark

@VM Value mark
@SM Subvalue mark
@RM Record mark
@TM Text mark
@SVM Subvalue mark
(same as @SM)
Compiler @variables
569
@variables
@SYSTEM.RETURN.CODE Values
@SYSTEM.RETURN.CODE returns various values depending upon the command
executed just prior to evaluating @SYSTEM.RETURN.CODE.
@SYSTEM.RETURN.CODE is available in UniBasic, but is affected by a wide vari-
ety of commands, both UniBasic commands and ECL commands.
ECL @SYSTEM.RETURN.CODE Values

The following table describes the possible values for various ECL commands:
Command Success Return Value Error Return Value
BSELECT The number of items in -1

the select list.
BUILD.INDEX The number of indices -1
built.
CREATE.INDEX The number of indices -1
created.
DELETE.INDEX The number of indices -1
deleted.
ESEARCH The number of items in -1
the select list.
FORM.LIST The number of items in -1
the select list.
GET.LIST The number of items in -1
the select list.
LIST The number of items -1
listed.
LIST.INDEX The number of indices -1
listed.
LIST.ITEM The number of items -1
listed.
ECL @SYSTEM.RETURN.CODE Values
570
@variables
LIST.LABEL The number of items -1

listed.
LOCK 0 -1 if you specify an
invalid lock number.
-2 if the resource is
locked by another user.
MERGE.LIST The number of items in -1
the select list.
MODIFY The number of records -1
modified.
NSELECT The number of items in 0
the select list.
QSELECT The number of items in -1
the select list.
SAVE.LIST The number of items -1
saved.
SELECT The number of items in -1
the select list.
SORT The number of items -1
listed.
SORT.ITEM The number of items -1
listed.
SORT.LABEL The number of items -1
listed.
SSELECT The number of items in -1
the select list.
STACKCOMMON 1 for ON N/A
0 for OFF
ECL @SYSTEM.RETURN.CODE Values (continued)
571
@variables
UniBasic @SYSTEM.RETURN.CODE Values

The following table describes the possible values for UniBasic commands:
GETREADU The number of locks. -1

INPUT N/A -1
INPUT@ N/A -1
PCPERFORM 0 -1
UniBasic @SYSTEM.RETURN.CODE Values
572
Index SOFTWARE PRODUCTS
Symbols @PARASENTENCE, 565

@PATH, 565
$BASICTYPE, 25 @RECORD, 23, 239, 566
parameters, 25 @RECUR0, 566
$DEFINE, 26 @RECUR1, 566
$IFDEF, 27 @RECUR2, 566
$IFNDEF, 29 @RECUR3, 566
$INCLUDE, 31 @RECUR4, 566
$INSERT, 31 @RM, 566, 569
$UNDEFINE, 33 @SENTENCE, 566
@, 16 @SM, 566, 569
@ terminal function, 17 @SVM, 566, 569
@ACCOUNT, 564 @SYS.BELL, 566
@AM, 564, 569 @SYSTEM.RETURN.CODE, 567, 570
@COMMAND, 564 @TIME, 567
@CONV, 23, 564 @TM, 567, 569
@CRTHIGH, 564 @TRANSACTION, 567
@CRTWIDE, 564 @TTY, 567
@DATA, 564 @TUPLE, 567
@DATE, 564 @UDTNO, 567
@DAY, 564 @UID, 187, 567
@DICT, 23, 564 @USER.RETURN.CODE, 568
@FORMAT, 23, 565 @USER.TYPE, 568
@GID, 565 @USER0, 567
@HEADER, 23, 565 @USER1, 567
@ID, 239, 565 @USER2, 567
@LASTVERB, 565 @USER3, 567
@LEVEL, 504, 565 @USER4, 567
@LOGNAME, 565 @USERNO, 568
@LPTRHIGH, 565 @variables, 563
@LPTRWIDE, 565 @VM, 568, 569
@MONTH, 565 @WHO, 568
573
Index
@YEAR, 568 dynamic, extracting strings, 498

{ }, 23, 51 dynamic, maximum numeric element, 284
dynamic, removing elements, 442
dynamic, removing spaces, 519
A dynamic, repeating elements, 495
dynamic, repeating last element, 454
ABORT, 34
dynamic, replacing data, 448
ABS, 36
dynamic, returning substrings, 446
absolute value, 36
generating a dynamic array, 261
ACOS, 37
resizing, 118
active list, 403
ASCII, 39, 64, 65
clearing, 73
ASCII code
creating, 163
converting an expression, 470, 471
creating from saved lists, 179
ASIN, 40
returning condition, 504
ASSIGN, 41
active select list
assigning
assigning record ID, 406
attributes to a matrix, 271, 274, 277
adding
data from a record to a variable, 421, 424, 427
string numbers, 459
data to a variable, 343
values in a dynamic array, 499
input buffer of calling Proc to a variable, 377
ALPHA, 38
lists to dynamic arrays, 403
alphabetic character
next entire record to a variable, 409
checking for, 38
next record from a sequential file, 412
alternate character set, 18
record from an active select list, 406
alternate key
records to a dynamic array, 385, 400, 418
initializing the value, 473
values to all elements of a matrix, 259
alternate key index, 398, 472
variables, 130
creating lists, 465
assignment, 296
retrieving records, 388, 390, 392, 394, 396
ASYNC, 52, 135, 135
returning, 147
ATAN, 42
returning information about, 220
attached line
returning names, 220
receiving input, 170
American Standard Code for Information Inter-
terminating input from, 170
change, 39, 64, 65
attached lines
AND logical function, 43
sending data, 468
arc cosine, 37
attribute
arc sine, 40
returning contents, 550
arc tangent, 42
writing, 546
argument
attribute mark, 569
passing, 496
attributes
array
deleting from an array, 108
comparing, 131
audible signal, 18
creating, 117
dynamic, adding values, 499
dynamic, assigning records, 385
dynamic, concatenating, 487
574
Index
B CATS, 61
CHAIN, 62
b+ tree CHANGE, 63
alternate key index, 388, 390, 392, 394, 396, 398 changing
base logarithm, 245 block size, 451, 451
BASICTYPE, 25 numeric expressions to ASCII, 64
executing commands in BASICTYPE U, 520 numeric values to ASCII, 65
returning current, 504 opposite sign, 294
bell, 18 strings, 92
binary conversion, 322 CHAR, 64, 296
BITAND, 43 CHAR(0), 296
BITNOT, 45 CHAR(128), 296
BITOR, 44 converting, 296
BITXOR, 46 character
blink mode, 17 trapping, 232
block size character string
changing, 451 converting, 208
returning, 503 CHARS, 65
BPIOCP, 47 checking
braces, 23, 51 if a select list is active, 467
bracket function, 296 variables for assignment, 522
branching CHECKSUM, 66
expressions, 57 CLEAR, 67
statements, 191 CLEAR COM, 68
BREAK, 49 CLEAR COMMON, 68
break key, 49 CLEARCOM, 68
buffer CLEARCOMMON, 68
print, 373 CLEARDATA, 69
CLEARFILE, 70
clearing
C active select lists, 73
C subroutine active temporary tables, 75
calling, 56 data que, 69
CALCULATE, 23, 51 named common, 68
CALL, 52, 52, 453 records, 70
CALLC, 56 screens, 17
calling SQL file variables, 75
C subroutines, 56 unnamed COMMON, 68
programs, 52 CLEARINPUT, 72
subroutines, 52 CLEARSELECT, 73
capturing CLEARSQL, 75
error messages, 287, 365, 521 CLOSE, 76
text, 286, 286, 365, 365, 521 CLOSESEQ, 78
CASE, 57 closing
CAT, 60 data files, 76
575
Index
dictionary files, 76 CRT, 99

files, 76 DATA, 100
sequential access files, 78 DEBUG, 104
sequential files, 348 DEFFUN, 106
COL1, 80 DEL, 108
COL2, 81 DELETE, 110
color combination, 18 DELETELIST, 114
column position DELETEU, 115
returning, 81 DIM, 117
COM, 83 DIMENSION, 117
command DISPLAY, 99
!, 82 ECHO, 126
$BASICTYPE, 25 END, 127
$DEFINE, 26 ENTER, 128
$IFDEF, 27 EQU, 132
$IFNDEF, 29 EQUATE, 132
$INCLUDE, 31 EXECUTE, 363
$INSERT, 31 EXECUTESQL, 135
$UNDEFINE, 33 EXIT, 138
*, 82 FILELOCK, 149
ABORT, 34 FILEUNLOCK, 151
ASSIGN, 41 FIND, 153
BPIOCP, 47 FINDSTR, 155
BREAK, 49 FLUSH, 157
CALL, 52 FOOTING, 161
CALLC, 56 FOR/NEXT, 164
CASE, 57 FORMLIST, 163
CHAIN, 62 FUNCTION, 166
CLEAR, 67 GARBAGECOLLECT, 167
CLEAR COM, 68 GET, 170
CLEAR COMMON, 68 GETCOLUMNDATA, 173
CLEARCOM, 68 GETCOLUMNNAME, 175
CLEARCOMMON, 68 GETLIST, 179
CLEARDATA, 69 GETNEXTTUPLE, 181
CLEARFILE, 70 GETREADU, 186
CLEARINPUT, 72 GOSUB, 189
CLEARSELECT, 73 GOTO, 191
CLEARSQL, 75 GROUPSTORE, 195
CLOSE, 76 HEADING, 201
CLOSESEQ, 78 HUSH, 204
COM, 83 IF/THEN/ELSE, 215
COMMON, 83 INPUT, 223
CONNECT, 87 INPUT @, 227
CONTINUE, 89 INPUTCLEAR, 72
CONVERT, 90 INPUTERR, 229
576
Index
INPUTIF, 230 READBCKU, 392

INPUTNULL, 231 READFWD, 394
INPUTTRAP, 232 READFWDL, 396
INS, 234 READFWDU, 398
LOCATE, 246 READL, 400
LOCK, 250 READLIST, 403
LOOP/REPEAT, 253 READNEX, 406
MAT, 259 READNEXTTUPLE, 409
MATBUILD, 261 READSELECT, 411
MATPARSE, 268 READSEQ, 412
MATREAD, 271 READT, 414
MATREADL, 274 READU, 418
MATREADU, 277 READV, 421
MATWRITE, 280 READVL, 424
MATWRITEU, 282 READVU, 427
MDPERFORM, 285 RECORDLOCKED, 434
NEXT, 295 RECORDLOCKL, 436
NOCONVERT, 296 RECORDLOCKU, 438
NULL, 300 RELEASE, 440
ON/GOSUB, 331 REM, 82
ON/GOTO, 333 REMOVE, 442
OPEN, 335 RESIZET, 451
OPENSEQ, 339 RETURN, 453
OSBREAD, 343 returning condition, 491
OSBWRITE, 346 REWIND, 455
OSCLOSE, 348 RNDSEED, 458
OSDELETE, 349 RQM, 480
OSOPEN, 351 SELECT, 462
OSREAD, 354 SELECTINDEX, 465
OSWRITE, 357 SEND, 468
PAGE, 359 SETINDEX, 472
PCPERFORM, 361 SETROW, 477
PERFORM, 363 SETTABLE, 475
PRECISION, 368 SLEEP, 480
PRINT, 370 STOP, 492
PRINTER, 372 SUBROUTINE, 496
PRINTER CLOSE, 373 SUM, 499
PRINTERR, 374 SWAP, 501
PROCREAD, 377 TRANSACTION ABORT, 509
PROCWRITE, 379 TRANSACTION COMMIT, 511
PROGRAM, 380 TRANSACTION START, 513
PROMPT, 381 UDTEXECUTE, 520
READ, 385 UNLOCK, 523
READBCK, 388 USE, 525
READBCKL, 390 WAIT, 527
577
Index
WEOF, 529 control variable

WEOFSEQ, 532 defining, 26
WRITE, 534 controlling
WRITELIST, 536 character display, 126
WRITESEQ, 537 conversion
WRITESEQF, 539 binary, 207
WRITET, 541 converting different bases, 207
WRITEU, 544 date, 206
WRITEV, 546 hex, 207
WRITEVU, 548 left justify, 209
command option left-justified, 209
returning as string, 504 masked character, 208
commands in BASICTYPE U, 520 masked decimal, 209
comment, 82 octal, 207
COMMON, 52, 83, 128 packed decimal, 210
clearing named, 68 right-justified, 210
clearing unnamed, 68 Tfile, 210
declaring, 83 time, 210
comparing CONVERT, 90, 92, 296
arrays, 131 converting, 39
string numbers, 460 alphabetic character to SOUNDEX, 326
COMPILE.DICT, 239 arrays to ASCII, 65
compiler @variables, 569 attribute marks to record marks, 384
compiling attribute marks to value marks, 256
directing, 26 character strings, 208
inserting source code, 31 dates, external to internal, 206
options, 27, 29 decimal into different bases, 322
programs, 25 decimal number to an integer, 209
concatenating expression to a single ASCII code value, 470, 471
arrays, 61 expressions to phonetic code, 483
elements of dynamic arrays, 487 integer to date, 305
strings, 60, 487 integer to time, 321
conditional expression, 57, 215 internal format to external, 330
configuration information lower case, 311
returning, 146 lower case to upper case, 524
CONNECT, 87, 87 packed decimal to external format, 317, 318
parameters, 88 packed decimals, 210
return values, 87 strings, 90
connecting strings to ASCII, 64
Open Server, 87 subvalue marks to value marks, 384
CONTINUE, 89, 138 text, 39
control to EBCDIC, 125
passing, 128 to lower case, 122
program, 52 upper case, 311
transferring to a statement, 333 value marks to attribute marks, 384
578
Index
value marks to subvalue marks, 256 decimal character

COS, 94 returning, 505
cosine, 94 decimal point
inverse, 37 determining placement, 368
COUNT, 95, 297 declaring
COUNTS, 97 end of program, 127
creating default file, 336, 421
active lists, 163 DEFFUN, 106, 106
active select lists from saved lists, 179 example, 106
arrays, 117 defining
footers, 161 control variables, 26
header, 201 null character for input, 231
list of record IDs in a file, 462 page length, 41
lists based on alternate key indices, 465 page number, 41
matrices, 117 page width, 41
user-defined error messages, 374 program names, 380
CRT, 99 system level parameters, 41
cursor terminal type, 41
addressing, 47 DEL, 108
controlling, 16 DELETE, 110, 112
DELETELIST, 114
DELETEU, 115
D deleting
attributes, 112
DATA, 100
attributes from an array, 108
data
data from an array, 108
formatting, 158
defined variables, 33
inputting, 100
delimiters, 108
writing to a file, 346
lists, 114
data file
records, 110, 112, 115
closing, 76
saved lists, 114
data queue, 100, 223
sequential files, 349
DATE, 101
strings, 90, 92
date
type ahead character buffer, 72
converting, 305
delimiter
converting external to internal, 206
inserting, 144
converting from integer, 305
raising to the next level, 384
returning, 508
specifying in a dynamic array, 262
DCOUNT, 102, 297
determining
DEBUG, 104
beginning of an external subroutine, 496
debugger, 49
group a key is hashed to, 200
entering, 104
numeric expression, 301, 302
decimal
dictionary file
masked, 313
closing, 76
packed, 317, 318
DIM, 117
579
Index
DIMENSION, 117 E
dimensioning
arrays, 117 EBCDIC, 39, 125
matrices, 117 EBCDIC to ASCII, 39
DIR, 120 ECHO, 126
directing ECL command
output of print statements, 372 executing, 285
disabling, 204 enabling
break key, 49 break key, 49
DISCONNECT, 121 terminal output, 204
parameter, 121 terminal pagination, 47
displaying enclosing
characters, 126 strings in double quotes, 123
error messages, 229 strings in quotes, 383
output to display terminal, 99 strings in single quotes, 488
distributing END, 127, 215
strings to a matrix, 268 end
division FOR/NEXT structure, 295
returning remainder, 291 end-of-file mark
string numbers, 461 writing, 529
double quotes ENTER, 128
enclosing a string in, 123 entering
double-precision rounding, 124 UniBasic debugger, 49, 104
DOWNCASE, 122 environmental variable, 177
DQUOTE, 123 EQ, 130
DROUND, 124 EQS, 131
dummy statement, 300 EQU, 132
dynamic array equal
adding values, 499 not, 292, 293
assigning records, 400 EQUATE, 132
assigning records to, 385 ERRMSG, 374, 492
concatenating, 487 ERRMSG file, 34
extracting strings, 498 error message
generating, 261 capturing, 287, 365, 521
maximum numeric element, 284 creating the file, 374
removing elements, 442 file, 374, 492
removing spaces, 519 printing, 374
repeating elements of, 495 retrieving, 178
repeating last element, 454 system error message file, 492
replacing data, 448 EXECUTE, 363
returning substrings, 446 EXECUTESQL, 135
specifying delimiters, 262 executing, 520
ECL commands, 363
ECL statements, 62
paragraphs, 285
sentences, 285
580
Index
statements repeatedly, 164 sequential, opening, 339, 351

UniData commands, 285, 363 sequential, reading, 354
UNIX commands, 361 sequential, reading next record, 412
VMS commands, 361 sequential, writing end-of-file mark, 532
EXIT, 138 sequential, writing to, 357, 537, 539
EXP, 139 system error messages, 374
expression translation, 328
locating, 246 unlocking, 151
Extended Binary Coded Decimal Information FILEINFO, 146
Code, 39, 125 FILELOCK, 149, 434
external subroutine, 56 FILEUNLOCK, 151
calling, 52 FIND, 153
EXTRACT, 140 FINDSTR, 155
extracting FMT, 158
attributes, 327 FMTS, 158
continuous groups, 193 footer
data, 140 creating, 161
strings, 21, 309 FOOTING, 161
strings from dynamic arrays, 498 options, 162
FOR/NEXT, 164
FOR/NEXT structure
F end, 295
forcing
FIELD, 142
a response from the user, 72
FIELDSTORE, 144
output to display terminal, 99
file
format mask, 158
closing, 76
formatting
default, 336, 421
data, 158
error message, 374
FORMLIST, 163
error message, creating, 374
function, 61
error messages, 492
@, 16
locking, 149
[ ], 21
print, 373
{ }, 23, 51
privileges, 120
ABS, 36
reading, 385
ACOS, 37
returning configuration information, 146
ALPHA, 38
returning group size, 147
ASCII, 39
returning hash type, 147
ASIN, 40
returning hold file path, 185
ATAN, 42
returning minimum modulus, 147
BITAND, 43
returning modulus, 147
BITNOT, 45
returning print file path, 185
BITOR, 44
returning type, 146
BITXOR, 46
returninig block size of file, 147
braces, 23, 51
sequential, closing, 348
CALCULATE, 23, 51
sequential, deleting, 349
581
Index
CAT, 60 INT, 238

CHANGE, 63 ITYPE, 239
CHAR, 64 LE, 241
CHARS, 65 LEN, 243
CHECKSUM, 66 LENS, 244
COL1, 80 LES, 242
COL2, 81 LN, 245
CONVERT, 92 LOWER, 256
COS, 94 LT, 257
COUNT, 95 LTS, 258
COUNTS, 97 MATCH, 264
DATA, 101 MATCHES, 264
DCOUNT, 102 MATCHFIELD, 266
DELETE, 112 MAXIMUM, 284
DIR, 120 MINIMUM, 290
DOWNCASE, 122 MOD, 291
DQUOTE, 123 NE, 292
DROUND, 124 NEG, 294
EBCDIC, 125 NES, 293
EQ, 130 NOT, 298
EQS, 131 NOTS, 299
EXP, 139 NUM, 301
EXTRACT, 140 NUMS, 302
FIELD, 142 OCONV, 303
FIELDSTORE, 144 OCONVS, 330
FILEINFO, 146 PWR, 382
FMT, 158 QUOTE, 383
FMTS, 158 RAISE, 384
GE, 168 REM, 291
GES, 169 REMOVE, 446
GETENV, 177 REPLACE, 448
GETERRMSG, 178 REUSE, 454
GETPTR, 183 RND, 457
GETPU, 185 SADD, 459
GETUSERGROUP, 188 SCMP, 460
GETUSERNAME, 187 SDIV, 461
GROUP, 193 SELECTINFO, 467
GT, 198 SEQ, 470
GTS, 199 SEQS, 471
HASH, 200 SIN, 479
ICONV, 205 SMUL, 482
IN, 217 SOUNDEX, 483
INDEX, 218 SPACE, 485
INDICES, 220 SPACES, 486
INMAT, 117, 222 SPLICE, 487
582
Index
SQRT, 489 GOTO, 191

square brackets, 21 greater than, 198, 199
SQUOTE, 488 greater than or equal to, 168
SSUB, 490 GROUP, 193
STATUS, 491 group extraction, 193
STR, 494 group number
STRS, 495 returning, 188
SUBSTRINGS, 498 GROUPSTORE, 195
SUM, 499 GT, 198
SYSTEM, 503 GTS, 199
TAN, 506
TIME, 507
TIMEDATE, 508 H
trigonometric, 37, 40, 42, 94
half-intensity mode, 17
trigonometric, sine, 479
halting
trigonometric, tangent, 506
program execution, 480, 492
TRIM, 515
HASH, 200
TRIMB, 517
header
TRIMF, 518
creating, 201
TRIMS, 519
HEADING, 201
UNASSIGNED, 522
hex conversion, 322
UPCASE, 524
home cursor, 17
XLATE, 550
HUSH, 204
G I
GARBAGECOLLECT, 167
ICONV, 205
GE, 168
binary, 207
generating
file translation, 210
dynamic arrays, 261
hex, 207
GES, 169
left justify, 209
GET, 170
masked character, 208
GETCOLUMNDATA, 173
masked decimal, 209
parameters, 173
octal, 207
GETCOLUMNNAME, 175
packed decimal, 210
GETENV, 177
right justify, 210
GETERRMSG, 178
time, 210
GETLIST, 179
IF/THEN/ELSE, 215
GETNEXTTUPLE, 181
ignoring
GETPTR, 183
locks, 421
GETPU, 185
IN, 217
GETREADU, 186
INCLUDE file, 26
GETUSERGROUP, 188
incrementing
GETUSERNAME, 187
values, 164
GOSUB, 189, 453
583
Index
INDEX, 218, 297 INTO, 135

index inverse cosine, 37
alternate key, creating lists, 465 inverse sine, 40
alternate key, retrieving records, 388, 390, 394, inverse tangent, 42
396, 398 inverting
alternate key, retrieving records from, 392 logical result, 298, 299
INDICES, 220 ITYPE, 239
initializing
alternate key values, 473
INMAT, 117, 222, 335 J
INPUT, 223
justification, 159
input
left, 315
buffer, 377, 379
right, 319
defining prompt, 381
unprompted, 170
INPUT @, 227 K
INPUTCLEAR, 72
INPUTERR, 229 KEY, 49
INPUTIF, 230 key, 200
INPUTNULL, 231
inputting, 217
data, 100, 223 L
data at a specified location, 227 label
data from the type ahead buffer, 230 statements, 189
null characters, 231 language
raw data, 217 returning current, 504
unprompted input, 170 LE, 241
INPUTTRAP, 232 left justify, 315
INS, 234 LEN, 243, 297
INSERT, 236 length
inserting character expression, 243
delimiters, 144, 234, 236 LENS, 244
expression between elements of a dynamic array, LES, 242
487 less than, 257, 258
expressions, 144, 234, 236 less than or equal to, 241, 242
expressions between strings, 487 lines
source code, 31 sending data, 468
strings, 195 list
INT, 238 assigning record ID, 406
integer assigning to a dynamic array, 403
converting to date, 305 checking if active, 467
converting to time, 321 clearing, 73
returning values, 238 creating, 163
internal subroutine deleting, 114
transferring control to, 189 passing, 287, 366
584
Index
returning condtion, 504 M

returning state, 467
transferring, 285, 287, 365 mask
writing to, 536 format, 158
LIT, 132 masked decimal, 313
LITERALLY, 132 MAT, 259
LN, 245 MATBUILD, 261
load percentage MATCH, 264
returning, 147 MATCHES, 264
local memory, 67 MATCHFIELD, 266
LOCATE, 246 matching
locating patterns, 264
strings, 246 MATPARSE, 268
LOCK, 250 MATREAD, 271
lock MATREADL, 274
exclusive, 277, 392, 427, 438 MATREADU, 277
ignoring, 421 matrix
not releasing, 282, 544, 548 assigning attributes, 271, 274, 277
on records, 115 assigning values to, 259
read-only, 274, 390, 396, 398, 400, 400, 424, 424 distributing portions of a string, 268
releasing, 440 writing elements to records, 280, 282
setting, 436 MATWRITE, 280
locking MATWRITEU, 282
files, 149 MAXIMUM, 284
records, 418 McDonnell Douglas, 25
logarithm MDPERFORM, 285
natural base, 245 memory
logical function releasing space, 167
AND, 43 merge factor percentage
NOT, 45 returning, 147
OR, 44 message
XOR, 46 error, printing, 374
logical result MINIMUM, 290
inverting, 298, 299 MOD, 291
LOOP/REPEAT, 253 modulo, 200
LOWER, 256 money symbol
lower case returning, 505
converting to, 122, 311 moving
converting to upper case, 524 the cursor, 17
LT, 257 multiplying
LTS, 258 string numbers, 482
585
Index
N right justify (MR), 319

text extraction (T), 327
name time (MT), 321
defining for a program, 380 OCONV (S), 326
named variable OCONV Date (D), 305
making available to external subroutines, 83 OCONVS, 330
natural base logarithm, 245 octal conversion, 322
NE, 292 ON/GOSUB, 331
NEG, 294 ON/GOTO, 333
NES, 293 OPEN, 335
NEXT, 164, 165, 295 Open Server, 87
NOCONVERT, 296 opening
NOT, 298 a file, 335
not equal, 292, 293 hashed files, 335
NOT logical function, 45 sequential files, 339, 351
NOTS, 299 Unidata files, 335
NULL, 215, 300 OPENSEQ, 339
null character operating system
defining, 231 returning, 504
NUM, 301 opposite sign
number changing to, 294
converting a decimal number to an integer, 209 option
random, 457 command, returning as a string, 504
numeric element OR logical function, 44
maximum, 284 OSBREAD, 296, 343
minimum, 290 OSBWRITE, 296, 346
numeric expression OSCLOSE, 348
determining, 301, 302 OSDELETE, 349
NUMS, 302 OSOPEN, 351
OSREAD, 296, 354
OSWRITE, 296, 357
O
OCONV, 303
binary (MB), 322 P
file translation (Tfile), 328 packed decimal, 317, 318
group (G), 309 PAGE, 359
hex (MX), 322 page
left justify (ML), 315 length, 41
length (L), 310 number, 41
masked character (MC), 311 printing, 359
masked decimal (MD), 313 returning current number, 503
octal (MO), 322 returning current number of printed lines, 503
packed decimal (MP), 317 returning length, 503
packed decimal (MP1), 318 returning size, 503
pattern match (P), 324 width, 41
586
Index
pagination, 47 data to a print file, 370

terminal, 47 directing output, 372
paging error messages, 374
options, 47 privilege
paragraph returning, 120
executing, 285 PROCREAD, 377
parameter PROCWRITE, 379
system level, 41 PROGRAM, 380
system level, retrieving, 503 program
PASSCOM, 84, 287, 366, 366, 521, 521 control, transferring to a statement, 333
passing declaring end, 127
arguments, 496 defining names, 380
control to a program, 128 returning name, 505
lists, 287, 366 returning time from start, 504
matrices, 83 size limitation, 62
SQL statements, 135 stopping execution, 480, 492
variables, 83 program control, 52
variables to external subroutines, 84 transferring, 56, 331, 453
pattern match, 264, 324 PROMPT, 381
PCPERFORM, 361 prompt
PERFORM, 363 defining, 381
permission protected mode, 17
returning, 148 PWR, 382
phonetic code
converting to, 483
Pick Basic, 25 Q
positive value, 36
QUOTE, 383
power
quote
raising a variable, 382
enclosing strings, 383
PRECISION, 368
single, enclosing a string, 488
PRINT, 370
print
the contents of the screen, 18 R
PRINTER, 372
printer RAISE, 384
returning condition, 503 raising
returning settings, 183 delimiters to the next level, 384
PRINTER CLOSE, 373 powers, 382
PRINTERR, 374 random number, 457
printing returning same sequence, 458
current output page, 359 seeding, 458
data from a print buffer, 373 range
data from a print file, 373 returning data within, 325
data on a line printer, 370 READ, 385
data on the display terminal, 370 READBCK, 388
587
Index
READBCKL, 390 remainder

READBCKU, 392 returning, 291
READFWD, 394 remark, 82
READFWDL, 396 REMOVE, 442, 446
READFWDU, 398 removing
reading elements of a dynamic array, 442
data from a file, 343 leading spaces, 518
next record from a sequential file, 412 spaces from a dynamic array, 519
next record from tape, 414 spaces from a string, 515
records, 400 spaces, trailing, 517
records from a file, 385, 418 REPEAT, 253
sequential files, 354 repeating
READL, 400, 434 last element of a dynamic array, 454
READLIST, 403 statements, 253
READNEXT, 406 REPLACE, 448
READNEXTTUPLE, 409 replacing
READONLY, 335, 340, 351 data in a dynamic array, 448
READSELECT, 411 strings, 21, 63, 90, 92, 132, 195, 501
READSEQ, 412 reserving
READT, 296, 414 computer resources, 250
READU, 418, 434 resetting
READV, 421 local memory to zero, 67
READVL, 424 terminal pagination, 47
READVU, 427 RESIZET, 451
Reality Basic, 25 resizing
record arrays, 118
assigning to a variable, 421, 424, 427 resource
clearing, 70 unlocking, 523
deleting, 115 retrieving
locking, 418 attributes from another file, 328
writing to, 534 error messages, 178
record ID records from an alternate key index, 388, 390,
assigning from an active select list, 406 392, 394, 396, 398
creating list, 462 system level parameters, 503
record lock, 115 RETURN, 52, 189, 331, 453
record mark, 569 RETURNING, 170, 172
RECORDLOCKED, 434, 434 returning
return values, 434 alternate key indices information, 220
status values, 434 alternate key indices names, 220
RECORDLOCKL, 436 command options as a string, 504
RECORDLOCKU, 438 condition of active list, 504
RELEASE, 440 condition of executed commands, 491
releasing condition of stack, 504
reserved memory space, 167 contents of an attribute, 550
REM, 291 current BASICTYPE, 504
588
Index
current dimension of a matrix, 222 string position, 153

current number of lines printed on page, 503 string positions, 155
current printer page number, 503 string starting position, 218
current printer settings, 183 strings delimited by, 142
current tape block size, 503 substring column position, 81
current time from start of program, 504 substring column positions, 80
data of a certain length, 310 substrings from a dynamic array, 446
data within a range, 325 tangent, 506
date, 101, 508 terminal or page length, 503
file configuration information, 146 terminal or page size, 503
file privileges, 120 time, 507, 508
file size, 120 time and date, 508
group number, 188 time in milliseconds, 504
hold file path, 185 UNIX environmental variable, 177
integer values, 238 user name, 187
language in use, 504 VMS logical name, 177
last date and time a file was modified, 120 REUSE, 454
length of character expression, 243, 244 reusing
minimum numeric element, 290 last element of a dynamic array, 454
money symbol, 505 reverse video mode, 17
name of the current running program, 505 REWIND, 455
natural base logarithm, 245 rewinding
number of elements in a matrix, 222 tapes, 455
number of lines remaining on current page, 503 right justify, 319
number of substring delimited by, 102 RND, 457
number of times a substring appears, 95 RNDSEED, 458
number of times substring appears in an array, 97 rounding
number of typeahead characters, 504 values, 124
operating system, 504 RQM, 480
pattern match, 324 run level
portions of a string, 266 returning, 504
positive values, 36
print file path, 185
printer condition, 503 S
random numbers, 457
SADD, 459
remainder of division, 291
saved list
repetitions of a string, 494
deleting, 114
repetitions of each element of a dynamic array,
making active, 179
495
writing to, 536
run level, 504
SCMP, 460
separator for decimals, 505
screen
separator for numeric thousands, 505
automatic pagination, 16
spaces, 485, 486
position, 16, 16
square root of a number, 489
SDIV, 461
state of a select list, 467
589
Index
seeding sine
random numbers, 458 inverse, 40
SELECT, 462 returning, 479
select list single quote
assigning record ID, 406 enclosing a string, 488
checking if active, 467 size limitation
clearing, 73 avoiding, 62
creating from saved lists, 179 SLEEP, 480
returning state, 467 sleeping
SELECTINDEX, 465 one second, 504
SELECTINFO, 467, 467 SMUL, 482
SEND, 468 sorting key, 247
sending SOUNDEX, 483
data to a line, 468 SPACE, 485
output to display terminal, 99 space
sentence removing from a string, 515
executing, 285 removing leading, 518
SEQ, 297, 470 removing trailing, 517
SEQS, 471 returning, 485
sequential access file SPACES, 486
closing, 78 special characters, 217
sequential file, 31 spelling
closing, 348 finding alternate spelling, 483
deleting, 349 SPLICE, 487
opening, 339, 351 splicing
reading, 354 dynamic arrays, 487
reading next record, 412 strings, 487
writing, 357 split factor percentage
writing end-of-file mark, 532 returning, 147
writing to, 537, 539 SQL file variable
sequential write, 346 clearing, 75
SETINDEX, 472 SQL INTO clause, 135
SETPTR, 183 SQRT, 489
SETROW, 477 square bracket, 21
parameters, 477 square root
SETTABLE, 475 returning, 489
SETTING, 170, 171 SQUOTE, 488
setting SSUB, 490
exclusive locks, 438 stack
local memory to zero, 67 returning condition, 504
read-only lock, 436 STACKCOMMON, 85, 285, 363, 520
sign statement
changing, 294 dummy, 300
SIN, 479 executing repeatedly, 164
label, 333
590
Index
transferring control, 333 SWAP, 297, 501

statement label, 189 SYNC, 52, 135, 135
STATUS, 491 SYSTEM, 503
STEP, 164, 164 system ERRMSG file, 34
STOP, 492 system level parameter, 41
stopping
program execution, 480, 492
STR, 494 T
string, 21
T.ATT, 414, 455, 541
concatenating, 487
TAN, 506
converting, 208
tangent, 506
extracting, 21
inverse, 42
inserting between other strings, 487
tape
locating, 246
block size, returning, 503
number of times appearing, 95
processing, multi-reel, 414, 541
number of times appearing in an array, 97
reading next record, 414
repeating, 494
rewinding, 455
replacing, 21, 63, 132, 501
writing to, 541
returning portions of, 266
tape processing
returning positions, 153, 155
multi-reel, 414, 541
starting position, 218
TAPELEN, 414, 541
string concatenation, 296
terminal, 47
string number
functions, 16, 17
adding, 459
returning length, 503
comparing, 460
returning size, 503
dividing, 461
returning type, 503
multiplying, 482, 482
terminal output, 204
subtracting, 490
disabling, 204
STRS, 495
enabling, 204
SUBROUTINE, 496
terminal type, 41
subroutine
terminating
calling, 52
FOR/NEXT statements, 138
determining beginning, 496
input from an attached line, 170
transferring control, 331, 453
LOOP REPEAT statements, 138
transferring control to, 189
programs, 34, 62
substring assignment, 296
subroutines, 34
substring column position
text
returning, 80
capturing, 286, 365, 521
SUBSTRINGS, 498
extraction, 327
subtracting
justification, 159
string numbers, 490
text mark, 569
subvalue mark, 569, 569
Tfile, 210
SUM, 499
thousand
suppressing
returning separator, 505
characters on display terminal, 126
TIME, 507
591
Index
time UNFILTERED, 224

conversions, 210 UniBasic debugger, 49, 104
returning, 507, 508 UniData command
returning in milliseconds, 504 executing, 285
time conversion, 321 UniData SQL, 409
TIMEDATE, 508 UNLOCK, 523
TRANSACTION ABORT, 509 unlocking
example, 510 files, 151
TRANSACTION COMMIT, 511 records, 440
example, 512 resources, 523
STATUS values, 511 unnamed COMMON, 83
TRANSACTION START, 513, 513 UPCASE, 524
example, 514 upper case
STATUS values, 513 converting to, 311
transfering converting to lower case, 524
program control, 52 USE, 525, 525
transferring parameters, 525
control to a statement, 191 user
control to ECL commands, 62 returning name, 187
lists, 285, 287, 365
program control, 56, 331, 453
program control to a statement, 333 V
program control to internal subroutine, 189
value mark, 569
translating
variable
files, 328
assigning, 130
trapping
assigning data, 343
characters, 232
checking for assignment, 522
trigonometric function, 37, 40
defining, 27, 29
TRIM, 515
making available to external subroutines, 83
TRIMB, 517
pattern matching, 264
TRIMF, 518
virtual attribute
TRIMS, 519
accessing, 239
type ahead buffer, 230
virtual attributes, 23, 51, 239
type ahead character
executing, 23, 51
deleting, 72
typeahead character
returning, 504 W
WAIT, 527
U WAITING, 170, 172
WEOF, 529
UDTEXECUTE, 520
WEOFSEQ, 532
UNASSIGNED, 522
WRITE, 534
undefining
write
variables, 33
sequential, 346
underlining mode, 17
592
Index
WRITELIST, 536
WRITESEQ, 537
WRITESEQF, 539
WRITET, 296, 451, 541
WRITEU, 544
WRITEV, 546
WRITEVU, 548
writing
attributes to a record, 546, 548
data to a file, 346
directly to the disk, 539
end-of-file mark, 529
end-of-file mark to a sequential file, 532
expressions to a record, 534, 544
matrices to records, 280, 282
primary input buffer of a calling Proc, 379
to a saved list, 536
to a sequential file, 537, 539
to sequential files, 357
to tape, 541
X
X, 171
XLATE, 550
XOR logical function, 46
593
UniBasic
A UniData Application
Development Tool
DATA MANAGEMENT THAT WORKS.
UniBasic Commands Reference D33-0015

Basic Udt

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Basic Udt

Caricato da

Copyright:

Formati disponibili

UniBasic Commands

DATA MANAGEMENT THAT WORKS.

Copyright © 1994 Unidata, Inc.

Principal Technical Writer

Product Information Group

Contributors and Technical Reviewers

Reference UniBasic Commands and Functions ....................... 14

OCONV Length (L) ....................................................................310

Appendix A ASCII Character Codes ........................................... 552

UniBasic Commands and

Elements of Syntax Statements

command names square brackets indicate

no brackets or braces a vertical line indicates that

COMMAND required [option] [option1 | option2]

An easy way to control screen attributes is to assign the required @ function

Note Any reference to @ functions turns off automatic screen pagination.

col.expr Specifies the column position at which the

-num.expr Specifies a @ terminal function. Refer to the

-1 Clear screen, home cursor

-19 Audible signal (bell)

@ Terminal Functions (continued)

-64 Sent by function key F1

@ Terminal Functions (continued)

Terminal and Printer Input/Output

BASICTYPE In BASICTYPE M, the [ ] “square brackets” function can remove a substring

string.expr In the first form, the function replaces part or

Note The BASICTYPE param must be in quotes.

If the $DEFINE statements are kept in a separate INCLUDE file, it is a minor

var Specifies variable to check to determine whether to

var Specifies variable to check to determine whether to

record Specifies the record, including the code you

pathname Specifies the directory containing seq.file-

$INCLUDE Parameters (continued)

BASICTYPE The ABORT command in BASICTYPE P provides additional functions.

Error Message File

num.expr1 num.expr2 Result

BITAND Function Operation Results

num.expr1 num.expr2 Result

BITOR Function Operation Results

BITNOT Function Operation Results

num.expr1 num.expr2 Result

BITXOR Function Operation Results

New Line Pressing Return on the keyboard displays another screen

[KEY] KEY is optional and has no effect; it is included for com-

CALL is very efficient for passing large amounts of data to a subroutine.

sub.name The name of a subroutine to call.

Calling a C Subroutine in UNIX

CASE expression1 Specifies any UniBasic expression. If the

CASE expression2 Specifies any UniBasic expression. If the

CASE Parameters (continued)

Use this command to avoid system-imposed limitations on program size by

BASICTYPE The CHAIN statement performs differently with BASICTYPE P and M. If

string Specifies the original text string.

In the next example, the program segment will print

CLEAR performs differently with BASICTYPE P. All variables in unnamed

[file.var] Specifies a dictionary or data file to clear.

Terminal and Printer Input/Output

[file.var] Specifies a dictionary or data file to close.

seq.file.var Specifies a sequential access file to close.

Sequential File Input/Output

CASE IN <> VAL

With BASICTYPE M and P, UniData is more flexible because COMMON

COMMON and ECL Commands