UniBasic Commands Reference - Rocket Software

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\BASICREF\BASRTITL.fm 

March 5, 2010 4:03 pm 

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta 

Beta Beta Beta Beta 

UniData 

UniBasic Commands 

Reference 

UDT-720-BASR-1

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\BASICREF\BASRTITL.fm 

March 5, 2010 4:03 pm 

ii UniBasic Commands Reference 

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta 

Notices 

Edition 

Publication date: July 2008 

Book number: UDT-720-BASR-1 

Product version: UniData 7.2 

Copyright 

© Rocket Software, Inc. 1988-2008. All Rights Reserved. 

Trademarks 

The following trademarks appear in this publication: 

Trademark Trademark Owner 

Rocket Software 

Rocket Software, Inc. 

Dynamic Connect® Rocket Software, Inc. 

RedBack® 

SystemBuilder 

UniData® 

UniVerse 

U2 

U2.NET 

U2 Web Development Environment 








wIntegrate® Rocket Software, Inc. 

Microsoft® .NET 

Microsoft® Office Excel®, Outlook®, Word 

Windows® 

Windows® 7 

Windows Vista® 

Java and all Java-based trademarks and logos 

UNIX® 

Microsoft Corporation 





Sun Microsystems, Inc. 

X/Open Company Limited

The above trademarks are property of the specified companies in the United States, 

other countries, or both. All other products or services mentioned in this document 

may be covered by the trademarks, service marks, or product names as designated 

by the companies who own or market them. 

License agreement 

This software and the associated documentation are proprietary and confidential to 

Rocket Software, Inc., are furnished under license, and may be used and copied only 

in accordance with the terms of such license and with the inclusion of the copyright 

notice. This software and any copies thereof may not be provided or otherwise made 

available to any other person. No title to or ownership of the software and associated 

documentation is hereby transferred. Any unauthorized use or reproduction of this 

software or documentation may be subject to civil or criminal liability. The information 

in the software and documentation is subject to change and should not be construed 

as a commitment by Rocket Software, Inc. 

Restricted rights notice for license to the U.S. Government: Use, reproduction, or 

disclosure is subject to restrictions as stated in the “Rights in Technical Data- 

General” clause (alternate III), in FAR section 52.222-14. All title and ownership in 

this computer software remain with Rocket Software, Inc. 

Note 

This product may contain encryption technology. Many countries prohibit or restrict 

the use, import, or export of encryption technologies, and current use, import, and 

export regulations should be followed when exporting this product. 

Please be aware: Any images or indications reflecting ownership or branding of the 

product(s) documented herein may or may not reflect the current legal ownership of 

the intellectual property rights associated with such product(s). All right and title to 

the product(s) documented herein belong solely to Rocket Software, Inc. and its 

subsidiaries, notwithstanding any notices (including screen captures) or any other 

indications to the contrary. 

Contact information 

Rocket Software 

275 Grove Street Suite 3-410 

Newton, MA 02466-2272 

USA 

Tel: (617) 614-4321 Fax: (617) 630-7100 

Web Site: www.rocketsoftware.com 

UniBasic Commands Reference iii

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta 

Table of Contents 

Elements of Syntax Statements . . . . . . . . . . . . . . . 1-23 

! . . . . . . . . . . . . . . . . . . . . . . . . 1-24 

# . . . . . . . . . . . . . . . . . . . . . . . . 1-25 

#< . . . . . . . . . . . . . . . . . . . . . . . . 1-26 

#> . . . . . . . . . . . . . . . . . . . . . . . . 1-27 

$BASICTYPE . . . . . . . . . . . . . . . . . . . . 1-28 

$DEFINE . . . . . . . . . . . . . . . . . . . . . 1-30 

$IFDEF . . . . . . . . . . . . . . . . . . . . . . 1-31 

$IFNDEF . . . . . . . . . . . . . . . . . . . . . 1-33 

$INCLUDE . . . . . . . . . . . . . . . . . . . . . 1-35 

$INSERT. . . . . . . . . . . . . . . . . . . . . . 1-37 

$UNDEFINE . . . . . . . . . . . . . . . . . . . . 1-38 

& . . . . . . . . . . . . . . . . . . . . . . . . 1-39 

* . . . . . . . . . . . . . . . . . . . . . . . . 1-40 

** . . . . . . . . . . . . . . . . . . . . . . . . 1-41 

*= . . . . . . . . . . . . . . . . . . . . . . . . 1-42 

+ . . . . . . . . . . . . . . . . . . . . . . . . 1-43 

+= . . . . . . . . . . . . . . . . . . . . . . . . 1-44 

- . . . . . . . . . . . . . . . . . . . . . . . . 1-45 

-= . . . . . . . . . . . . . . . . . . . . . . . . 1-46 

/ . . . . . . . . . . . . . . . . . . . . . . . . 1-47 

/= . . . . . . . . . . . . . . . . . . . . . . . . 1-48 

: . . . . . . . . . . . . . . . . . . . . . . . . 1-49 

^ . . . . . . . . . . . . . . . . . . . . . . . . 1-50 

:= . . . . . . . . . . . . . . . . . . . . . . . . 1-51 

< . . . . . . . . . . . . . . . . . . . . . . . . 1-52 

. . . . . . . . . . . . . . . . . . . . . . . . 1-56 

=< . . . . . . . . . . . . . . . . . . . . . . . . 1-57 

>< . . . . . . . . . . . . . . . . . . . . . . . . 1-58 

\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\BASICREF\BASRTOC.fm (bookTOC.template) 

Table of 

Contents

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\BASICREF\BASRTOC.fm 

(bookTOC.template) 

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta 

v UniBasic Commands Reference 

> . . . . . . . . . . . . . . . . . . . . . . . . 1-59 

>= . . . . . . . . . . . . . . . . . . . . . . . 1-60 

@ . . . . . . . . . . . . . . . . . . . . . . . . 1-61 

[] . . . . . . . . . . . . . . . . . . . . . . . . 1-67 

{}. . . . . . . . . . . . . . . . . . . . . . . . 1-69 

ABORT . . . . . . . . . . . . . . . . . . . . . . 1-71 

ABS . . . . . . . . . . . . . . . . . . . . . . . 1-74 

acceptConnection . . . . . . . . . . . . . . . . . . . 1-75 

ACOS . . . . . . . . . . . . . . . . . . . . . . 1-77 

addAuthenticationRule . . . . . . . . . . . . . . . . . 1-81 

addCertificate . . . . . . . . . . . . . . . . . . . . 1-83 

addRequestParameter . . . . . . . . . . . . . . . . . 1-85 

ALPHA . . . . . . . . . . . . . . . . . . . . . . 1-87 

amInitialize. . . . . . . . . . . . . . . . . . . . . 1-88 

amReceiveMsg . . . . . . . . . . . . . . . . . . . 1-90 

amReceiveRequest . . . . . . . . . . . . . . . . . . 1-92 

amSendMsg . . . . . . . . . . . . . . . . . . . . 1-94 

amSendRequest . . . . . . . . . . . . . . . . . . . 1-96 

amSendResponse . . . . . . . . . . . . . . . . . . . 1-98 

amTerminate . . . . . . . . . . . . . . . . . . . . 1-100 

analyzeCertificate. . . . . . . . . . . . . . . . . . . 1-102 

AND . . . . . . . . . . . . . . . . . . . . . . . 1-104 

ASCII . . . . . . . . . . . . . . . . . . . . . . 1-105 

ASIN . . . . . . . . . . . . . . . . . . . . . . 1-106 

ATAN . . . . . . . . . . . . . . . . . . . . . . 1-109 

BITAND . . . . . . . . . . . . . . . . . . . . . 1-107 

BITNOT . . . . . . . . . . . . . . . . . . . . . 1-108 

BITOR . . . . . . . . . . . . . . . . . . . . . . 1-109 

BITXOR . . . . . . . . . . . . . . . . . . . . . 1-110 

BPIOCP. . . . . . . . . . . . . . . . . . . . . . 1-111 

BPIOCPN . . . . . . . . . . . . . . . . . . . . . 1-113 

BREAK . . . . . . . . . . . . . . . . . . . . . . 1-115 

BYTELEN . . . . . . . . . . . . . . . . . . . . . 1-117 

CALCULATE . . . . . . . . . . . . . . . . . . . . 1-118 

CALL . . . . . . . . . . . . . . . . . . . . . . 1-120 

CALLC . . . . . . . . . . . . . . . . . . . . . . 1-123 

CASE . . . . . . . . . . . . . . . . . . . . . . 1-125 

CAT . . . . . . . . . . . . . . . . . . . . . . . 1-128 

CATS . . . . . . . . . . . . . . . . . . . . . . 1-130 

CHAIN . . . . . . . . . . . . . . . . . . . . . . 1-131 

CHANGE . . . . . . . . . . . . . . . . . . . . . 1-133 

CHAR . . . . . . . . . . . . . . . . . . . . . . 1-135




vi UniBasic Commands Reference 

CHARLEN. . . . . . . . . . . . . . . . . . . . . 1-137 

CHARS . . . . . . . . . . . . . . . . . . . . . . 1-138 

CHECKSUM . . . . . . . . . . . . . . . . . . . . 1-139 

CLEAR . . . . . . . . . . . . . . . . . . . . . . 1-140 

CLEARCOMMON . . . . . . . . . . . . . . . . . . 1-142 

CLEARDATA . . . . . . . . . . . . . . . . . . . . 1-144 

CLEARFILE . . . . . . . . . . . . . . . . . . . . 1-145 

CLEARINPUT . . . . . . . . . . . . . . . . . . . 1-147 

CLEARSQL . . . . . . . . . . . . . . . . . . . . 1-150 

CLOSE . . . . . . . . . . . . . . . . . . . . . . 1-151 

CLOSESEQ . . . . . . . . . . . . . . . . . . . . 1-153 

closeSocket. . . . . . . . . . . . . . . . . . . . . 1-155 

CloseXMLData . . . . . . . . . . . . . . . . . . . 1-156 

COL1 . . . . . . . . . . . . . . . . . . . . . . 1-157 

COL2 . . . . . . . . . . . . . . . . . . . . . . 1-158 

COMMON . . . . . . . . . . . . . . . . . . . . . 1-159 

CONTINUE . . . . . . . . . . . . . . . . . . . . 1-164 

CONVERT . . . . . . . . . . . . . . . . . . . . . 1-166 

CONVERT . . . . . . . . . . . . . . . . . . . . . 1-168 

COS . . . . . . . . . . . . . . . . . . . . . . . 1-170 

COUNT. . . . . . . . . . . . . . . . . . . . . . 1-171 

createCertificate . . . . . . . . . . . . . . . . . . . 1-175 

createCertRequest . . . . . . . . . . . . . . . . . . 1-177 

createRequest. . . . . . . . . . . . . . . . . . . . 1-180 

createSecureRequest . . . . . . . . . . . . . . . . . . 1-183 

createSecurityContext . . . . . . . . . . . . . . . . . 1-186 

DATA . . . . . . . . . . . . . . . . . . . . . . 1-187 

DATE . . . . . . . . . . . . . . . . . . . . . . 1-188 

DBTOXML . . . . . . . . . . . . . . . . . . . . 1-189 

DCOUNT . . . . . . . . . . . . . . . . . . . . . 1-191 

DEACTIVATEKEY . . . . . . . . . . . . . . . . . . 1-193 

DEBUG. . . . . . . . . . . . . . . . . . . . . . 1-196 

DEFFUN . . . . . . . . . . . . . . . . . . . . . 1-197 

DEL . . . . . . . . . . . . . . . . . . . . . . . 1-200 

DELETE . . . . . . . . . . . . . . . . . . . . . 1-202 

DELETE . . . . . . . . . . . . . . . . . . . . . 1-204 

DELETELIST . . . . . . . . . . . . . . . . . . . . 1-206 

DELETEU . . . . . . . . . . . . . . . . . . . . . 1-208 

DIM . . . . . . . . . . . . . . . . . . . . . . . 1-210 

DIGEST. . . . . . . . . . . . . . . . . . . . . . 1-213 

DIR . . . . . . . . . . . . . . . . . . . . . . . 1-215 

DISPLAY . . . . . . . . . . . . . . . . . . . . . 1-218




vii UniBasic Commands Reference 

DISPLAYWIDTH . . . . . . . . . . . . . . . . . . 1-219 

DOWNCASE . . . . . . . . . . . . . . . . . . . . 1-220 

DQUOTE . . . . . . . . . . . . . . . . . . . . . 1-221 

DROUND . . . . . . . . . . . . . . . . . . . . . 1-222 

EBCDIC . . . . . . . . . . . . . . . . . . . . . 1-217 

ECHO . . . . . . . . . . . . . . . . . . . . . . 1-218 

EDADRV_Cleanup . . . . . . . . . . . . . . . . . . 1-219 

EDADRV_CloseStmt . . . . . . . . . . . . . . . . . 1-220 

EDADRV_Connect . . . . . . . . . . . . . . . . . . 1-222 

EDADRV_Disconnect . . . . . . . . . . . . . . . . . 1-224 

EDADRV_DropStmt. . . . . . . . . . . . . . . . . . 1-225 

EDADRV_EndTransaction . . . . . . . . . . . . . . . . 1-227 

EDADRV_ExecuteStmt . . . . . . . . . . . . . . . . . 1-229 

EDADRV_FetchStmt . . . . . . . . . . . . . . . . . 1-231 

EDADRV_FreeResult . . . . . . . . . . . . . . . . . 1-233 

EDADRV_GetDBInfo . . . . . . . . . . . . . . . . . 1-234 

EDADRV_GetErrmsg . . . . . . . . . . . . . . . . . 1-238 

EDADRV_GetSpecialInfo . . . . . . . . . . . . . . . . 1-239 

EDADRV_LoadSymbols . . . . . . . . . . . . . . . . 1-242 

EDADRV_Perform . . . . . . . . . . . . . . . . . . 1-245 

EDADRV_PrepareStmt . . . . . . . . . . . . . . . . . 1-247 

ENABLEDEC. . . . . . . . . . . . . . . . . . . . 1-249 

ENCODE . . . . . . . . . . . . . . . . . . . . . 1-251 

ENCRYPT . . . . . . . . . . . . . . . . . . . . . 1-253 

END . . . . . . . . . . . . . . . . . . . . . . . 1-256 

ENTER . . . . . . . . . . . . . . . . . . . . . . 1-257 

EQ . . . . . . . . . . . . . . . . . . . . . . . 1-259 

EQS . . . . . . . . . . . . . . . . . . . . . . . 1-261 

EQU . . . . . . . . . . . . . . . . . . . . . . . 1-262 

EREPLACE . . . . . . . . . . . . . . . . . . . . 1-265 

EXECUTE . . . . . . . . . . . . . . . . . . . . . 1-266 

EXECUTESQL . . . . . . . . . . . . . . . . . . . 1-271 

EXIT. . . . . . . . . . . . . . . . . . . . . . . 1-275 

EXP . . . . . . . . . . . . . . . . . . . . . . . 1-276 

EXTRACT . . . . . . . . . . . . . . . . . . . . . 1-277 

FIELD . . . . . . . . . . . . . . . . . . . . . . 1-247 

FIELDSTORE. . . . . . . . . . . . . . . . . . . . 1-249 

FILEINFO . . . . . . . . . . . . . . . . . . . . . 1-252 

FILELOCK . . . . . . . . . . . . . . . . . . . . 1-256 

FILEUNLOCK . . . . . . . . . . . . . . . . . . . 1-258 

FIND . . . . . . . . . . . . . . . . . . . . . . 1-260 

FINDSTR . . . . . . . . . . . . . . . . . . . . . 1-263




viii UniBasic Commands Reference 

FLUSH . . . . . . . . . . . . . . . . . . . . . . 1-265 

FMT . . . . . . . . . . . . . . . . . . . . . . . 1-266 

FOOTING . . . . . . . . . . . . . . . . . . . . . 1-270 

FORMLIST . . . . . . . . . . . . . . . . . . . . 1-273 

FOR/NEXT . . . . . . . . . . . . . . . . . . . . 1-275 

FUNCTION . . . . . . . . . . . . . . . . . . . . 1-278 

GARBAGECOLLECT . . . . . . . . . . . . . . . . . 1-281 

GE . . . . . . . . . . . . . . . . . . . . . . . 1-282 

generateKey . . . . . . . . . . . . . . . . . . . . 1-284 

GES . . . . . . . . . . . . . . . . . . . . . . . 1-287 

GET . . . . . . . . . . . . . . . . . . . . . . . 1-288 

getCipherSuite. . . . . . . . . . . . . . . . . . . . 1-291 

GETENV . . . . . . . . . . . . . . . . . . . . . 1-293 

getHTTPDefault . . . . . . . . . . . . . . . . . . . 1-294 

GETLIST . . . . . . . . . . . . . . . . . . . . . 1-296 

GETPTR . . . . . . . . . . . . . . . . . . . . . 1-299 

GETPU . . . . . . . . . . . . . . . . . . . . . . 1-301 

GETQUEUE . . . . . . . . . . . . . . . . . . . . 1-302 

GETREADU . . . . . . . . . . . . . . . . . . . . 1-304 

getResponseHeader . . . . . . . . . . . . . . . . . . 1-306 

getSocketInformation . . . . . . . . . . . . . . . . . 1-307 

getSocketOptions . . . . . . . . . . . . . . . . . . . 1-309 

GETUSERGROUP . . . . . . . . . . . . . . . . . . 1-312 

GETUSERID . . . . . . . . . . . . . . . . . . . . 1-313 

GETUSERNAME . . . . . . . . . . . . . . . . . . 1-314 

GOSUB . . . . . . . . . . . . . . . . . . . . . . 1-315 

GOTO . . . . . . . . . . . . . . . . . . . . . . 1-317 

GROUP . . . . . . . . . . . . . . . . . . . . . . 1-319 

GROUPSTORE . . . . . . . . . . . . . . . . . . . 1-321 

GT . . . . . . . . . . . . . . . . . . . . . . . 1-325 

GTS . . . . . . . . . . . . . . . . . . . . . . . 1-327 

HASH . . . . . . . . . . . . . . . . . . . . . . 1-327 

HEADING . . . . . . . . . . . . . . . . . . . . . 1-328 

HUSH . . . . . . . . . . . . . . . . . . . . . . 1-331 

ICONV . . . . . . . . . . . . . . . . . . . . . . 1-333 

ICONV Date (D) . . . . . . . . . . . . . . . . . . . 1-336 

ICONV Group (G) . . . . . . . . . . . . . . . . . . 1-340 

ICONV Length (L) . . . . . . . . . . . . . . . . . . 1-342 

ICONV Masked Character (MC) . . . . . . . . . . . . . . 1-344 

ICONV Masked Decimal (MD) . . . . . . . . . . . . . . 1-346 

ICONV Left Justify (ML) . . . . . . . . . . . . . . . . 1-348 

ICONV Packed Decimal (MP). . . . . . . . . . . . . . . 1-350




ix UniBasic Commands Reference 

ICONV Packed Decimal (MP1) . . . . . . . . . . . . . . 1-351 

ICONV Right Justify (MR). . . . . . . . . . . . . . . . 1-352 

ICONV Time (MT) . . . . . . . . . . . . . . . . . . 1-354 

ICONV Hex (MX | HEX), Octal (MO), Binary (MB) . . . . . . . 1-356 

ICONV Pattern Match (P) . . . . . . . . . . . . . . . . 1-359 

ICONV Range (R) . . . . . . . . . . . . . . . . . . 1-360 

ICONV SOUNDEX (S) . . . . . . . . . . . . . . . . . 1-362 

ICONV Text Extraction (T) . . . . . . . . . . . . . . . 1-363 

ICONV File Translation (Tfile) . . . . . . . . . . . . . . 1-365 

ICONVS . . . . . . . . . . . . . . . . . . . . . 1-366 

IF/THEN/ELSE . . . . . . . . . . . . . . . . . . . 1-368 

IN. . . . . . . . . . . . . . . . . . . . . . . . 1-370 

INDEX . . . . . . . . . . . . . . . . . . . . . . 1-371 

INDICES . . . . . . . . . . . . . . . . . . . . . 1-373 

initSecureServerSocket function . . . . . . . . . . . . . . 1-375 

initServerSocket . . . . . . . . . . . . . . . . . . . 1-377 

INMAT . . . . . . . . . . . . . . . . . . . . . . 1-379 

INPUT . . . . . . . . . . . . . . . . . . . . . . 1-382 

INPUT @ . . . . . . . . . . . . . . . . . . . . . 1-386 

INPUTCLEAR . . . . . . . . . . . . . . . . . . . 1-390 

INPUTERR . . . . . . . . . . . . . . . . . . . . 1-391 

INPUTIF . . . . . . . . . . . . . . . . . . . . . 1-393 

INPUTNULL . . . . . . . . . . . . . . . . . . . . 1-394 

INPUTTRAP . . . . . . . . . . . . . . . . . . . . 1-395 

INS . . . . . . . . . . . . . . . . . . . . . . . 1-397 

INSERT. . . . . . . . . . . . . . . . . . . . . . 1-399 

INT . . . . . . . . . . . . . . . . . . . . . . . 1-401 

ISMB . . . . . . . . . . . . . . . . . . . . . . 1-402 

ISNV . . . . . . . . . . . . . . . . . . . . . . 1-403 

ISNVS . . . . . . . . . . . . . . . . . . . . . . 1-405 

ITYPE . . . . . . . . . . . . . . . . . . . . . . 1-407 

LE . . . . . . . . . . . . . . . . . . . . . . . 1-408 

LEN . . . . . . . . . . . . . . . . . . . . . . . 1-410 

LENS . . . . . . . . . . . . . . . . . . . . . . 1-412 

LES . . . . . . . . . . . . . . . . . . . . . . . 1-413 

LISTUSER . . . . . . . . . . . . . . . . . . . . . 1-414 

LN . . . . . . . . . . . . . . . . . . . . . . . 1-416 

loadSecurityContext . . . . . . . . . . . . . . . . . . 1-417 

LOCATE . . . . . . . . . . . . . . . . . . . . . 1-419 

LOCK . . . . . . . . . . . . . . . . . . . . . . 1-425 

LOOP/REPEAT . . . . . . . . . . . . . . . . . . . 1-428 

LOWER. . . . . . . . . . . . . . . . . . . . . . 1-432




x UniBasic Commands Reference 

LT . . . . . . . . . . . . . . . . . . . . . . . 1-433 

LTS . . . . . . . . . . . . . . . . . . . . . . . 1-435 

MAT . . . . . . . . . . . . . . . . . . . . . . . 1-436 

MATBUILD . . . . . . . . . . . . . . . . . . . . 1-439 

MATCH. . . . . . . . . . . . . . . . . . . . . . 1-442 

MATCHFIELD . . . . . . . . . . . . . . . . . . . 1-444 

MATPARSE . . . . . . . . . . . . . . . . . . . . 1-446 

MATREAD . . . . . . . . . . . . . . . . . . . . 1-449 

MATREADL . . . . . . . . . . . . . . . . . . . . 1-452 

MATREADU . . . . . . . . . . . . . . . . . . . . 1-455 

MATWRITE . . . . . . . . . . . . . . . . . . . . 1-459 

MATWRITEU. . . . . . . . . . . . . . . . . . . . 1-462 

MAXIMUM . . . . . . . . . . . . . . . . . . . . 1-464 

MBLEN. . . . . . . . . . . . . . . . . . . . . . 1-465 

MDPERFORM . . . . . . . . . . . . . . . . . . . 1-466 

MINIMUM. . . . . . . . . . . . . . . . . . . . . 1-470 

MOD . . . . . . . . . . . . . . . . . . . . . . 1-471 

NE . . . . . . . . . . . . . . . . . . . . . . . 1-474 

NEG . . . . . . . . . . . . . . . . . . . . . . . 1-476 

NES . . . . . . . . . . . . . . . . . . . . . . . 1-477 

NFAUSER . . . . . . . . . . . . . . . . . . . . . 1-478 

NOCONVERT . . . . . . . . . . . . . . . . . . . 1-479 

NOT . . . . . . . . . . . . . . . . . . . . . . . 1-481 

NOTS . . . . . . . . . . . . . . . . . . . . . . 1-482 

NULL . . . . . . . . . . . . . . . . . . . . . . 1-483 

NUM . . . . . . . . . . . . . . . . . . . . . . 1-484 

NUMS . . . . . . . . . . . . . . . . . . . . . . 1-486 

OCONV. . . . . . . . . . . . . . . . . . . . . . 1-487 

OCONV Date (D) . . . . . . . . . . . . . . . . . . 1-489 

OCONV Group (G) . . . . . . . . . . . . . . . . . . 1-494 

OCONV Length (L) . . . . . . . . . . . . . . . . . . 1-496 

OCONV Masked Character (MC) . . . . . . . . . . . . . 1-498 

OCONV Masked Decimal (MD) . . . . . . . . . . . . . . 1-501 

OCONV Left Justify (ML) . . . . . . . . . . . . . . . . 1-504 

OCONV Packed Decimal (MP) . . . . . . . . . . . . . . 1-507 

OCONV Packed Decimal (MP1) . . . . . . . . . . . . . . 1-508 

OCONV Right Justify (MR) . . . . . . . . . . . . . . . 1-509 

OCONV Time (MT) . . . . . . . . . . . . . . . . . . 1-512 

OCONV Hex (MX | HEX), Octal (MO), Binary (MB) . . . . . . . 1-514 

OCONV Pattern Match (P) . . . . . . . . . . . . . . . . 1-517 

OCONV Range (R) . . . . . . . . . . . . . . . . . . 1-519 

OCONV SOUNDEX (S) . . . . . . . . . . . . . . . . 1-521




xi UniBasic Commands Reference 

OCONV Text Extraction (T) . . . . . . . . . . . . . . . 1-523 

OCONV File Translation (Tfile) . . . . . . . . . . . . . . 1-525 

OCONVS . . . . . . . . . . . . . . . . . . . . . 1-527 

ON/GOSUB . . . . . . . . . . . . . . . . . . . . 1-529 

ON/GOTO . . . . . . . . . . . . . . . . . . . . . 1-532 

OPEN . . . . . . . . . . . . . . . . . . . . . . 1-534 

openSecureSocket function. . . . . . . . . . . . . . . . 1-537 

OPENSEQ . . . . . . . . . . . . . . . . . . . . . 1-539 

openSocket . . . . . . . . . . . . . . . . . . . . . 1-542 

OpenXMLData . . . . . . . . . . . . . . . . . . . 1-544 

OR . . . . . . . . . . . . . . . . . . . . . . . 1-546 

OSBREAD . . . . . . . . . . . . . . . . . . . . . 1-547 

OSBWRITE . . . . . . . . . . . . . . . . . . . . 1-550 

OSCLOSE . . . . . . . . . . . . . . . . . . . . . 1-554 

OSDELETE . . . . . . . . . . . . . . . . . . . . 1-556 

OSOPEN . . . . . . . . . . . . . . . . . . . . . 1-558 

OSREAD . . . . . . . . . . . . . . . . . . . . . 1-561 

OSWRITE . . . . . . . . . . . . . . . . . . . . . 1-563 

PAGE . . . . . . . . . . . . . . . . . . . . . . 1-563 

PAUSE . . . . . . . . . . . . . . . . . . . . . . 1-565 

PCPERFORM . . . . . . . . . . . . . . . . . . . . 1-567 

PERFORM . . . . . . . . . . . . . . . . . . . . . 1-569 

PRECISION . . . . . . . . . . . . . . . . . . . . 1-570 

PrepareXML . . . . . . . . . . . . . . . . . . . . 1-572 

PRINT . . . . . . . . . . . . . . . . . . . . . . 1-574 

PRINTER . . . . . . . . . . . . . . . . . . . . . 1-577 

PRINTER CLOSE . . . . . . . . . . . . . . . . . . 1-578 

PRINTERR . . . . . . . . . . . . . . . . . . . . 1-579 

PROCREAD . . . . . . . . . . . . . . . . . . . . 1-583 

PROCWRITE . . . . . . . . . . . . . . . . . . . . 1-587 

PROGRAM . . . . . . . . . . . . . . . . . . . . 1-588 

PROMPT . . . . . . . . . . . . . . . . . . . . . 1-589 

protocolLogging . . . . . . . . . . . . . . . . . . . 1-591 

PWR . . . . . . . . . . . . . . . . . . . . . . . 1-593 

QUOTE . . . . . . . . . . . . . . . . . . . . . . 1-593 

RAISE . . . . . . . . . . . . . . . . . . . . . . 1-595 

READ . . . . . . . . . . . . . . . . . . . . . . 1-596 

READBCK. . . . . . . . . . . . . . . . . . . . . 1-599 

READBCKL . . . . . . . . . . . . . . . . . . . . 1-602 

READBCKU . . . . . . . . . . . . . . . . . . . . 1-606 

READFWD . . . . . . . . . . . . . . . . . . . . 1-610 

READFWDL . . . . . . . . . . . . . . . . . . . . 1-613




xii UniBasic Commands Reference 

READFWDU . . . . . . . . . . . . . . . . . . . . 1-617 

READL . . . . . . . . . . . . . . . . . . . . . . 1-621 

READLIST . . . . . . . . . . . . . . . . . . . . 1-625 

READNEXT . . . . . . . . . . . . . . . . . . . . 1-628 

READNEXTTUPLE. . . . . . . . . . . . . . . . . . 1-632 

READSELECT . . . . . . . . . . . . . . . . . . . 1-635 

READSEQ . . . . . . . . . . . . . . . . . . . . . 1-636 

readSocket . . . . . . . . . . . . . . . . . . . . . 1-638 

READT . . . . . . . . . . . . . . . . . . . . . . 1-640 

READU. . . . . . . . . . . . . . . . . . . . . . 1-643 

READV. . . . . . . . . . . . . . . . . . . . . . 1-647 

READVL . . . . . . . . . . . . . . . . . . . . . 1-650 

READVU . . . . . . . . . . . . . . . . . . . . . 1-653 

READXBCK . . . . . . . . . . . . . . . . . . . . 1-656 

READXFWD . . . . . . . . . . . . . . . . . . . . 1-658 

ReadXMLData . . . . . . . . . . . . . . . . . . . 1-660 

RECORDLOCKED . . . . . . . . . . . . . . . . . . 1-662 

RECORDLOCKL . . . . . . . . . . . . . . . . . . 1-665 

RECORDLOCKU . . . . . . . . . . . . . . . . . . 1-668 

RELEASE . . . . . . . . . . . . . . . . . . . . . 1-670 

ReleaseXML . . . . . . . . . . . . . . . . . . . . 1-672 

REM . . . . . . . . . . . . . . . . . . . . . . . 1-673 

REMOVE . . . . . . . . . . . . . . . . . . . . . 1-675 

REMOVE . . . . . . . . . . . . . . . . . . . . . 1-680 

REPLACE . . . . . . . . . . . . . . . . . . . . . 1-682 

RESIZET . . . . . . . . . . . . . . . . . . . . . 1-686 

RETURN . . . . . . . . . . . . . . . . . . . . . 1-688 

REUSE . . . . . . . . . . . . . . . . . . . . . . 1-689 

REWIND . . . . . . . . . . . . . . . . . . . . . 1-691 

RND . . . . . . . . . . . . . . . . . . . . . . . 1-693 

RNDSEED . . . . . . . . . . . . . . . . . . . . . 1-694 

RQM. . . . . . . . . . . . . . . . . . . . . . . 1-695 

SADD . . . . . . . . . . . . . . . . . . . . . . 1-696 

saveSecurityContext . . . . . . . . . . . . . . . . . . 1-697 

SCMP . . . . . . . . . . . . . . . . . . . . . . 1-699 

SDIV . . . . . . . . . . . . . . . . . . . . . . 1-701 

SELECT . . . . . . . . . . . . . . . . . . . . . 1-702 

SELECTINDEX . . . . . . . . . . . . . . . . . . . 1-706 

SELECTINFO. . . . . . . . . . . . . . . . . . . . 1-709 

SEND . . . . . . . . . . . . . . . . . . . . . . 1-711 

SEQ . . . . . . . . . . . . . . . . . . . . . . . 1-713 

SEQS . . . . . . . . . . . . . . . . . . . . . . 1-714




xiii UniBasic Commands Reference 

setAuthenticationDepth . . . . . . . . . . . . . . . . . 1-715 

setCipherSuite . . . . . . . . . . . . . . . . . . . . 1-717 

setClientAuthentication . . . . . . . . . . . . . . . . . 1-719 

SETENV . . . . . . . . . . . . . . . . . . . . . 1-721 

setHTTPDefault . . . . . . . . . . . . . . . . . . . 1-722 

SETINDEX . . . . . . . . . . . . . . . . . . . . 1-725 

setPrivateKey . . . . . . . . . . . . . . . . . . . . 1-730 

setRandomSeed . . . . . . . . . . . . . . . . . . . 1-732 

setRequestHeader. . . . . . . . . . . . . . . . . . . 1-734 

setSocketOptions . . . . . . . . . . . . . . . . . . . 1-736 

showSecurityContext . . . . . . . . . . . . . . . . . 1-738 

SIGNATURE . . . . . . . . . . . . . . . . . . . . 1-740 

SIN . . . . . . . . . . . . . . . . . . . . . . . 1-743 

SLEEP . . . . . . . . . . . . . . . . . . . . . . 1-744 

SMUL . . . . . . . . . . . . . . . . . . . . . . 1-746 

SOAPCreateRequest . . . . . . . . . . . . . . . . . . 1-747 

SOAPCreateSecureRequest . . . . . . . . . . . . . . . 1-749 

SOAPGetDefault . . . . . . . . . . . . . . . . . . . 1-752 

SOAPGetFault. . . . . . . . . . . . . . . . . . . . 1-754 

SOAPGetResponseHeader . . . . . . . . . . . . . . . . 1-756 

SOAPRequestWrite . . . . . . . . . . . . . . . . . . 1-758 

SOAPSetParameters . . . . . . . . . . . . . . . . . . 1-763 

SOAPSetRequestBody . . . . . . . . . . . . . . . . . 1-765 

SOAPSetRequestContent . . . . . . . . . . . . . . . . 1-767 

SOAPSetRequestHeader . . . . . . . . . . . . . . . . 1-769 

SOAPSubmitRequest . . . . . . . . . . . . . . . . . 1-771 

SORT . . . . . . . . . . . . . . . . . . . . . . 1-773 

SOUNDEX. . . . . . . . . . . . . . . . . . . . . 1-774 

SPACE . . . . . . . . . . . . . . . . . . . . . . 1-776 

SPACES . . . . . . . . . . . . . . . . . . . . . 1-777 

SPLICE . . . . . . . . . . . . . . . . . . . . . . 1-778 

SQLAllocConnect . . . . . . . . . . . . . . . . . . 1-780 

SQLAllocEnv . . . . . . . . . . . . . . . . . . . . 1-782 

SQLAllocStmt. . . . . . . . . . . . . . . . . . . . 1-784 

SQLBindCol . . . . . . . . . . . . . . . . . . . . 1-786 

SQLBindParameter . . . . . . . . . . . . . . . . . . 1-788 

SQLCancel . . . . . . . . . . . . . . . . . . . . . 1-792 

SQLColAttributes . . . . . . . . . . . . . . . . . . 1-794 

SQLColumns . . . . . . . . . . . . . . . . . . . . 1-798 

SQLConnect . . . . . . . . . . . . . . . . . . . . 1-801 

SQLDescribeCol . . . . . . . . . . . . . . . . . . . 1-803 

SQLDisconnect . . . . . . . . . . . . . . . . . . . 1-805

xiv UniBasic Commands Reference 

SQLError . . . . . . . . . . . . . . . . . . . . . 1-807 

SQLExecDirect . . . . . . . . . . . . . . . . . . . 1-810 

SQLExecute . . . . . . . . . . . . . . . . . . . . 1-813 

SQLFetch . . . . . . . . . . . . . . . . . . . . . 1-815 

SQLFreeConnect . . . . . . . . . . . . . . . . . . . 1-817 

SQLFreeEnv . . . . . . . . . . . . . . . . . . . . 1-819 

SQLFreeStmt . . . . . . . . . . . . . . . . . . . . 1-821 

SQLGetInfo . . . . . . . . . . . . . . . . . . . . 1-824 

SQLGetTypeInfo . . . . . . . . . . . . . . . . . . . 1-829 

SQLNumParams . . . . . . . . . . . . . . . . . . . 1-834 

SQLNumResultCols . . . . . . . . . . . . . . . . . . 1-836 

SQLParamOptions . . . . . . . . . . . . . . . . . . 1-838 

SQLPrepare . . . . . . . . . . . . . . . . . . . . 1-841 

SQLRowCount . . . . . . . . . . . . . . . . . . . 1-844 

SQLSetConnectOption . . . . . . . . . . . . . . . . . 1-846 

SQLSetParam . . . . . . . . . . . . . . . . . . . . 1-850 

SQLSpecialColumns. . . . . . . . . . . . . . . . . . 1-851 

SQLStatistics . . . . . . . . . . . . . . . . . . . . 1-855 

SQLTables . . . . . . . . . . . . . . . . . . . . . 1-860 

SQLTransact . . . . . . . . . . . . . . . . . . . . 1-863 

SQRT . . . . . . . . . . . . . . . . . . . . . . 1-866 

SQUOTE . . . . . . . . . . . . . . . . . . . . . 1-867 

SSUB . . . . . . . . . . . . . . . . . . . . . . 1-868 

STATUS . . . . . . . . . . . . . . . . . . . . . 1-869 

STOP . . . . . . . . . . . . . . . . . . . . . . 1-870 

STR . . . . . . . . . . . . . . . . . . . . . . . 1-872 

STRS . . . . . . . . . . . . . . . . . . . . . . 1-874 

submitRequest. . . . . . . . . . . . . . . . . . . . 1-875 

SUBROUTINE . . . . . . . . . . . . . . . . . . . 1-878 

SUBROUTINE (Update Trigger) . . . . . . . . . . . . . . 1-880 

SUBROUTINE (Delete Trigger) . . . . . . . . . . . . . . 1-884 

SUBSTRINGS . . . . . . . . . . . . . . . . . . . 1-887 

SUM . . . . . . . . . . . . . . . . . . . . . . . 1-889 

SWAP . . . . . . . . . . . . . . . . . . . . . . 1-891 

SYSTEM . . . . . . . . . . . . . . . . . . . . . 1-893 

TAN . . . . . . . . . . . . . . . . . . . . . . . 1-871 

TIME . . . . . . . . . . . . . . . . . . . . . . 1-872 

TIMEDATE . . . . . . . . . . . . . . . . . . . . 1-873 

TRANSACTION ABORT . . . . . . . . . . . . . . . . 1-874 

TRANSACTION COMMIT . . . . . . . . . . . . . . . 1-876 

TRANSACTION START . . . . . . . . . . . . . . . . 1-879 

TRIM . . . . . . . . . . . . . . . . . . . . . . 1-881

TRIMB . . . . . . . . . . . . . . . . . . . . . . 1-884 

TRIMF . . . . . . . . . . . . . . . . . . . . . . 1-885 

TRIMS . . . . . . . . . . . . . . . . . . . . . . 1-886 

UDTEXECUTE. . . . . . . . . . . . . . . . . . . . 1-889 

UNASSIGNED . . . . . . . . . . . . . . . . . . . . 1-891 

UNLOCK . . . . . . . . . . . . . . . . . . . . . 1-892 

UPCASE . . . . . . . . . . . . . . . . . . . . . . 1-894 

WAKE. . . . . . . . . . . . . . . . . . . . . . . 1-896 

WEOF. . . . . . . . . . . . . . . . . . . . . . . 1-898 

WEOFSEQ . . . . . . . . . . . . . . . . . . . . . 1-900 

WRITE . . . . . . . . . . . . . . . . . . . . . . 1-902 

WRITELIST. . . . . . . . . . . . . . . . . . . . . 1-906 

WRITESEQ . . . . . . . . . . . . . . . . . . . . . 1-908 

WRITESEQF . . . . . . . . . . . . . . . . . . . . 1-910 

writeSocket . . . . . . . . . . . . . . . . . . . . . 1-912 

WRITET . . . . . . . . . . . . . . . . . . . . . . 1-914 

WRITEU . . . . . . . . . . . . . . . . . . . . . . 1-917 

WRITEV . . . . . . . . . . . . . . . . . . . . . . 1-920 

WRITEVU . . . . . . . . . . . . . . . . . . . . . 1-924 

XDOMAddChild . . . . . . . . . . . . . . . . . . . 1-928 

XDOMAppend . . . . . . . . . . . . . . . . . . . . 1-931 

XDOMClone . . . . . . . . . . . . . . . . . . . . 1-933 

XDOMClose. . . . . . . . . . . . . . . . . . . . . 1-935 

XDOMCreateNode. . . . . . . . . . . . . . . . . . . 1-936 

XDOMCreateRoot . . . . . . . . . . . . . . . . . . . 1-939 

XDOMEvaluate. . . . . . . . . . . . . . . . . . . . 1-942 

XDOMGetAttribute . . . . . . . . . . . . . . . . . . 1-945 

XDOMGetNodeName. . . . . . . . . . . . . . . . . . 1-947 

XDOMGetNodeType . . . . . . . . . . . . . . . . . . 1-949 

XDOMGetNodeValue . . . . . . . . . . . . . . . . . . 1-950 

XDOMGetOwnerDocument . . . . . . . . . . . . . . . . 1-952 

XDOMGetUserData . . . . . . . . . . . . . . . . . . 1-953 

XDOMInsert. . . . . . . . . . . . . . . . . . . . . 1-958 

XDOMLocate . . . . . . . . . . . . . . . . . . . . 1-961 

XDOMLocateNode . . . . . . . . . . . . . . . . . . 1-964 

XDOMOpen . . . . . . . . . . . . . . . . . . . . . 1-967 

XDOMRemove . . . . . . . . . . . . . . . . . . . . 1-969 

XDOMReplace . . . . . . . . . . . . . . . . . . . . 1-972 

XDOMSetNodeValue . . . . . . . . . . . . . . . . . . 1-974 

XDOMSetUserData . . . . . . . . . . . . . . . . . . 1-976 

XDOMTransform . . . . . . . . . . . . . . . . . . . 1-977 

XDOMValidate . . . . . . . . . . . . . . . . . . . . 1-979 

Table of Contents xv

xvi UniBasic Commands Reference 

XDOMValidateDom . . . . . . . . . . . . . . . . . . 1-981 

XDOMWrite . . . . . . . . . . . . . . . . . . . . 1-983 

XLATE . . . . . . . . . . . . . . . . . . . . . . 1-986 

XMAPClose . . . . . . . . . . . . . . . . . . . . 1-990 

XMAPCreate . . . . . . . . . . . . . . . . . . . . 1-991 

XMAPOpen . . . . . . . . . . . . . . . . . . . . 1-993 

XMAPReadNext . . . . . . . . . . . . . . . . . . . 1-995 

XMAPToXMLDoc . . . . . . . . . . . . . . . . . . 1-997 

XMLError . . . . . . . . . . . . . . . . . . . . . 1-1000 

XMLExecute . . . . . . . . . . . . . . . . . . . . 1-1001 

XMLGetError . . . . . . . . . . . . . . . . . . . . 1-1004 

XMLGetOptions . . . . . . . . . . . . . . . . . . . 1-1005 

XMLGetOptionValue . . . . . . . . . . . . . . . . . 1-1007 

XMLSetOptions . . . . . . . . . . . . . . . . . . . 1-1009 

XMLTODB . . . . . . . . . . . . . . . . . . . . 1-1011 

Appendix A ASCII Character Codes 

Appendix B UniBasic@variables 

@variables . . . . . . . . . . . . . . . . . . . . . B-2 

Delimiter @variables . . . . . . . . . . . . . . . . . B-6 

@SYSTEM.RETURN.CODE Values . . . . . . . . . . . . B-7 

Appendix C Operators in UniBasic 

Arithmetic Operators. . . . . . . . . . . . . . . . . . C-2 

Boolean Operators . . . . . . . . . . . . . . . . . . C-4 

Relational Operators . . . . . . . . . . . . . . . . . . C-5 

Appendix D Reserved Words 

Appendix E Commands Affected by BASICTYPEs and UDT.OPTIONS 

Appendix F Commands That Set STATUS() Return Values

UniBasic Commands and Functions 

This section contains a detailed alphabetic listing of UniBasic commands, functions, 

and operators that include descriptions and working examples. 

Functions perform specialized operations that augment and enhance commands. You 

always use functions as expressions or in expressions following a command. 

1-22

1-23 UniBasic Commands Reference 

Elements of Syntax Statements 

This reference manual uses a common method to present syntax for UniData 

commands. The syntax statement includes the command name, required arguments, 

and options you can use with the command. Italics represents a variable you can 

replace with any valid option. The following figure illustrates the elements of a 

syntax statement. 

command names 

appear in boldface 

no brackets or braces 

indicates a required 

argument 

square brackets indicate 

an optional argument 

a vertical line indicates that 

you can choose between 

the given arguments 

COMMAND required [option] [option1 | option2] 

{option1 | option2} required... "string" 

quotation marks 

must enclose a 

literal string 

braces indicate that you 

must choose between 

the given arguments 

an ellipsis indicates that 

you can enter more than 

one argument

! 

! is a synonym for the * and REM commands, which you can use to create comments. 

It also is a synonym for the OR operator. For information about creating comments, 

see REM. For information about the OR operator, see OR. 

Synonyms 

*, REM, OR 

! 1-24

# 


# is a synonym for the NE relational operator. For more information, see NE. 

Synonyms 

, >

#< 

#< is a synonym for the GE relational operator. For more information, see GE. 

Synonyms 

>=, =>, GE 

#< 1-26

#> 


#> is a synonym for the LE relational operator. For more information, see LE. 

Synonyms 

$BASICTYPE 

Syntax 

$BASICTYPE "param" 

Description 

The UniBasic $BASICTYPE command compiles data in a specified BASICTYPE. 

The $BASICTYPE statement must be the first noncomment statement in the program 

or subroutine. 

You can include only one $BASICTYPE statement per file (main program or 

subroutine), but you can split a program into separately cataloged subroutines for the 

purpose of changing BASICTYPE. 

If you do not specify $BASICTYPE, UniData compiles the program in the 

BASICTYPE specified in the ECL BASICTYPE command. The default type is U. 

Note: The BASICTYPE param must be in quotation marks. 

Parameters 

The following table describes each parameter of the syntax. 

Parameter Description 

U UniBasic 

P Pick ® BASIC 

R Advanced Revelation ® BASIC 

M McDonnell Douglas BASIC/ Reality ® BASIC 

$BASICTYPE Parameters 

$BASICTYPE 1-28

Related Command 

UniData 

BASICTYPE – For information, see the UniData Commands Reference. 

1-29 UniBasic Commands Reference

$DEFINE 

Syntax 

$DEFINE var 

Description 

The UniBasic $DEFINE command defines a control variable you can use later to 

direct compilation. 

Tip: Keep $DEFINE statements in a separate INCLUDE file to facilitate recompiling 

programs with different definitions. 

Example 

In the following example, SMALL is defined when the program segment is 

compiled, and UniData defines array1 as a 10-element array initialized with 0: 

$DEFINE SMALL 

$IFDEF SMALL 

DIM array1(10) 

MAT array1 = 0 

$ENDIF 

Related Commands 

UniBasic 

$UNDEFINE, EQU 

$DEFINE 1-30

$IFDEF 

Syntax 


$IFDEF var statements1 [$ELSE statements2] $ENDIF 

Description 

The UniBasic $IFDEF command conditionally compiles UniBasic statements 

depending on the existence of a variable definition. Variables are defined by 

$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 initialized with 0: 

$DEFINE SMALL 

$IFDEF SMALL 



$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 



$ENDIF 



$DEFINE, $IFNDEF 

$IFDEF 1-32

$IFNDEF 

Syntax 


$IFNDEF var statements1 [$ELSE statements2] $ENDIF 

Description 

The UniBasic $IFNDEF command conditionally compiles UniBasic statements 

depending on the absence of a variable definition. Variables are defined 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

Example 

In the following example, the program segment nests the $IFDEF and $IFNDEF 

statements. 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, 

depending on whether ONE is defined. 

$IFDEF LARGE 

DIM A(1000) 

$IFDEF ONE 

MAT A = 1 

$ELSE 

MAT A = 0 

$ENDIF 

$ELSE 

$IFNDEF SMALL 

DIM A(100) 

$ELSE 

DIM A(10) 

$ENDIF 

$IFDEF ONE 

MAT A = 1 

$ELSE 

MAT A = 0 

$ENDIF 

$ENDIF 



$DEFINE, $IFDEF 

$IFNDEF 1-34

$INCLUDE 

Syntax 


$INCLUDE record [FROM [DICT] filename] 

$INCLUDE filename {, | | > } record 

$INCLUDE [pathname {, | | > }] seq.filename 

Synonym 

$INSERT 

Description 

The UniBasic $INCLUDE and $INSERT commands insert UniBasic source code 

from the file you specify into the program being compiled. 

The third form of the syntax inserts code from a UNIX, or Windows platform 

sequential file. 

Note: In $BASICTYPEs P and M, you can enter $INCLUDE or INCLUDE.

Parameters 



record Specifies the record that contains the code you want to insert. 

filename Specifies the name of a UniData directory containing the record. If you do 

not specify filename, the system searches for record in the current file 

where the program being compiled resides. 

pathname Specifies the directory containing seq.filename. If you do not specify 

pathname, the system searches for seq.filename in the current directory. 

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 an operating system sequential file. 

$INCLUDE Parameters 

Note: 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 into the program being 

compiled the code contained in file code_seg1 in directory BP: 

$INCLUDE code_seg1 FROM BP 

The next example demonstrates the use of the $INCLUDE command in UniData for 

UNIX. The program statement inserts into the program being compiled the code 

contained in sequential file my_code in directory /usr/ud/mydir: 

$INCLUDE /usr/ud/mydir/my_code 

$INCLUDE 1-36

$INSERT 

$INSERT is a synonym for the $INCLUDE command. For more information, see 

$INCLUDE. 

Synonym 

$INCLUDE 


$UNDEFINE 

Syntax 

$UNDEFINE var 

Description 

The UniBasic $UNDEFINE command deletes the definition of var previously 

defined by $DEFINE. 



$DEFINE, EQU 

$UNDEFINE 1-38

& 


& is a synonym for the AND Boolean operator. For more information, see AND. 

Synonym 

AND

* 

Syntax 

expr * expr 

Synonyms 

!, REM 

Description 

The * arithmetic operator multiplies the expressions on either side of the operator. 

The asterisk (*) also is a synonym for the ! and REM commands, which you can use 

to create comments. For information about creating comments, see REM. 

Note: You must include the REUSE function to apply arithmetic operations to all 

elements of a dynamic array. 

Example 

The following program segment uses the * operator to multiply VAR1 and VAR2: 

X = VAR1 * VAR2 



REM, SMUL 

* 1-40

** 


** is a synonym for the ^ arithmetic operator. For more information, see ^. 

Synonym 

^

*= 

Syntax 

var *= expr 

Description 

The *= arithmetic operator multiplies the value of a variable by the number you 

specify. 

Tip: Using the *= operator is a more efficient way of multiplying a variable. For 

example, LINES *= 2 is more efficient than LINES = LINES * 2. 



Example 

In the following example, the variable LINES is multiplied by 2, which sets LINES 

equal to 14: 

LINES = 7 

LINES *= 2 

*= 1-42

+ 

Syntax 

expr + expr 

+expr 

Description 

In the first version of the syntax, the + arithmetic operator adds the two numbers on 

either side of the operator. 

In the second version of the syntax, + acts as a unary plus operator (same as multiplying 

by +1). 

Example 

The following program segment is taken from the sample program in “Appendix A - 

Sample Program” in Developing UniBasic Applications. The third statement places 

the cursor at the location computed by 9+ENTRY, then the program displays the 

seventh element of the array ORDER.REC at that location. 


FOR ENTRY = 1 TO NUM_ENTRIES 

NEW.PRICE = "" 

DISPLAY @(10,9+ENTRY):OCONV(ORDER.REC,"MR2$,"): 

INPUT @(45,9+ENTRY):NEW.PRICE 

NEW.PRICE = OCONV(NEW.PRICE,"MCN") 

IF NEW.PRICE # '' AND NUM(NEW.PRICE) THEN 

ORDER.REC = NEW.PRICE 

NEED.TO.WRITE = 1 

END 

NEXT ENTRY 



ABS, NEG, SADD, SUM

+= 

Syntax 

var += expr 

Description 

The += arithmetic operator increments the value of a variable by the number you 

specify. 

Tip: Using the += operator is a more efficient way of incrementing a variable. For 

example, LINES += 1 is more efficient than LINES = LINES + 1. 

Example 

In the following example, the variable LINES is incremented by 1, which sets LINES 

equal to 8: 

LINES = 7 

LINES += 1 

+= 1-44


- 

Syntax 

expr -expr 

-expr 

Description 

In the first version of the syntax, the - arithmetic operator subtracts the expr on the 

right from the expr on the left of the operator. 

In the second version of the syntax, - acts as a unary minus operator, which produces 

the same result as multiplying by -1. 

Examples 

In the following example, VAR2 is subtracted from VAR1 and the result is assigned 

to the variable X: 

X = VAR1 - VAR2 

In the next example, the - operator is used as the unary minus and changes the sign 

of VAR: 

VAR = -VAR 



ABS, NEG

-= 

Syntax 

var -= expr 

Description 

The -= arithmetic operator decrements the value of a variable by the number you 

specify. 

Tip: Using the -= operator is a more efficient way to decrement a variable. For 

example, LINES -= 1 is more efficient than LINES = LINES -1. 

Example 

In the following example, the variable LINES is decremented by 1, which sets LINES 

equal to 6: 

LINES = 7 

LINES -= 1 

-= 1-46


/ 

Syntax 

expr1 / expr2 

Description 

The / arithmetic operator divides the two numbers on either side of the operator. 

Example 

The following statement divides price by cost to determine quantity: 

PRICE / COST = QUANTITY 



SDIV

= 

Syntax 

var /= expr 

Description 

The /= arithmetic operator divides the value of a variable by the number you specify. 

Tip: Using the /= operator is a more efficient way of dividing a variable. For 

example, LINES /= 2 is more efficient than LINES = LINES/2. 

Example 

In the following example, the variable LINES is divided by 2, which sets LINES 

equal to 10: 

LINES = 20 

LINES /= 2 

/= 1-48


: 

: is a synonym for the CAT function. For more information, see CAT. 

Synonym 

CAT

^ 

Syntax 

expr1^expr2 

Synonym 

** 

Description 

The ^ arithmetic operator raises expr1 to the power of expr2. 

Example 

In the following example, the program segment raises variable X to the power of 3, 

first using an exponentiation operator **, second using the PWR function, and last 

using the exponentiation operator ^. The results are identical. 

X = 2 

PRINT X**3 

PRINT PWR(X,3) 

PRINT X^3 



PWR 

^ 1-50

:= 

Syntax 

var := expr 

Description 


The := arithmetic operator concatenates the value of an expression to a variable. 

Tip: Using the := operator is a more efficient way of concatenating a variable. For 

example, LINES := 0 is more efficient than LINES = LINES CAT 0. 

Example 

In the following example, the variable LINES is concatenated with 0, which sets 

LINES equal to 100: 

LINES = 10 

LINES := 0

< is a synonym for the LT (less than) relational operator. For more information, see 

LT. 

Synonym 

LT 

< 1-52

The UniBasic function retrieves, inserts, or replaces elements in a dynamic array. 

It also acts as the not equal to relational operator. For information about retrieving, 

see EXTRACT. For information about inserting and replacing, see REPLACE. For 

information about the not equal to relational operator, see NE. 

Synonyms 

#, >

= 


= is a synonym for the EQ relational operator. For more information, see EQ. 

Synonym 

EQ

=> 

=> is a synonym for the GE relational operator. For more information, see GE. 

Synonyms 

#=, GE 

=> 1-56

=< 


=< is a synonym for the LE relational operator. For more information, see LE. 

Synonyms 

#>,

>< is a synonym for NE relational operator. For more information, see NE. 

Synonyms 

#, , NE 

>< 1-58


> is a synonym for the GT relational operator. For more information, see GT. 

Synonym 

GT

= 

>= is a synonym for the GE relational operator. For more information, see GE. 

Synonyms 

#, GE 

>= 1-60

@ 

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 can specify various terminal functions by num.expr. 

Any reference to @ functions turns off automatic screen pagination. 

Tip: Assign @ functions to variables if you expect to use the @ function more than 

once. 

Use the @ function in a PRINT statement to direct the terminal to take some action 

before printing.

Parameters 



col.expr Specifies the column position to place the cursor. 

Can be a literal value or variable. 

Must be a positive numeric value. 

Value 0 is the leftmost column on the screen. For most terminals, col.expr 

can range from 0 to 79 (the right-hand side of the screen). 

,row.expr Specifies the row at which to place the cursor. Defaults to the current row. 

Can be either a literal value or variable. 

Must be a positive value. 

Value 0 is the top of the screen. For most terminals, row.expr can range 

from 0 to 23 (the last row on the screen). 

-num.expr Specifies an @ terminal function. For valid @ terminal functions and their 

effects, see the next table. 

@ Parameters 

Tip: Use PRINT, DISPLAY, and CRT in combination with the UniBasic @ function 

to position the cursor on the screen before printing or to execute other terminal 

functions. Execute the ECL REUSE.ROW command to determine whether a line feed 

is executed when the UniBasic PRINT @ function references column only. For 

example, PRINT @(10) rather than PRINT @(3,10). 

@ Function Options 

The following @ function options direct the terminal to take an action. 

Option Description 

-1 Clear screen, home cursor. 

-2 Home cursor. 

-3 Clear from cursor to end of screen. 

@ Function Options 

@ 1-62



-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 Nondestructive space (cursor right). 

-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. 

@ Function Options (continued)


-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. 









@ Function Options (continued) 

@ 1-64

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" 

In the next example, the program segment prints two messages at different points on 

the screen: 





-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. 

ROW = 0 ; COL = 0 

PRINT @(COL,ROW):"TOP":@(COL,ROW+21):"BOTTOM" 

In the next example, the program segment initiates reverse video mode, prints a 

prompt, and then stops reverse video mode: 

PRINT @(-13) 

PRINT "ENTER NAME:": 

PRINT @(-14) 

@ Function Options (continued)

In the next example, the program segment clears the screen and places the cursor in 

the home position (0,0): 

CLS = @(-1) 

PRINT CLS 



@variables – For information, see Appendix B, “UniBasic@variables.” 

UniData 

REUSE.ROW – For information, see the UniData Commands Reference. 

@ 1-66

[] 

Syntax 


string.expr [num.expr1,num.expr2] = expr 

expr = string.expr [num.expr1, num.expr2] 

Description 

The UniBasic [] (square brackets) function extracts or replaces strings. 

Null Value Handling 

With null value handling on, when UniBasic encounters the null value in a command 

parameter where a number is expected (num.expr1, num.expr2), it displays a warning 

message and uses 0. 

Note: In BASICTYPE M and P, the [] (square brackets) function can remove a 

substring entirely and can also remove parts of the substring. 

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 UniData 

performs an extraction, it returns that number of characters. If UniData 

performs a replacement, it replaces that number of characters. 

[ ] Parameters

Examples 

In the following example, the program segment extracts the first character of the 

variable LAST.NAME (in this case, an S): 

LAST.NAME = 'Smith' 

L.INITIAL = LAST.NAME[1,1] 

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 spaces: 

A = "12345" 

A[2,3] = "" 

In BASICTYPE U, system output is as follows: 

A = "1 5" 

In BASICTYPEs M and P, the substring is extracted as follows: 

A = "15" 

The following program inserts the null value into string X, which contains 12345, and 

then prints this element before and after converting @NULL to the printable string 

“@NULL”: 

X=12345 

X[3,1]=@NULL 

PRINT "X[3,1] is printed on the next line." 

PRINT X[3,1] 

X = CHANGE(X[3,1], @NULL,"@NULL") 

PRINT "X[3,1] is printed on the next line." 

PRINT X 

This program prints the following text: 

X[3,1] is printed on the next line. 

X[3,1] is printed on the next line. 

@NULL 

[] 1-68

{} 

{} is a synonym for the CALCULATE function. For more information, see 

CALCULATE. 

Synonym 

CALCULATE 


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 

UniData prompt, whether the aborted program was called by another program or 

executed through a UniData menu or paragraph. ABORT can include an optional 

string expr to display when the program aborts. The expression can contain variables, 

functions, and/or arithmetic or string operators. 

The UniBasic commands ABORT and PRINTERR return the system message whose 

ID you specify in the command. You can also retrieve system messages using a 

UniBasic program by opening the system message file and reading a message record 

by ID. 

Note: ENGLISH.MSG is the default system message file that is activated when you 

install UniData. If you execute udtlang.config to select a language group, a different 

system message file could be activated. To find out which language is installed on 

your system, execute the ECL command SET.LANG CURRENT. For more 

information, see UniData International. 

The ABORT command in BASICTYPE P provides additional functions. ABORT 

prints either a user-defined message specified by the string expr, or a UniData system 

message identified by message-id: 

ABORT [message-id] 

ABORT [expr,...] 

In the first form of the syntax, the message-id must be a variable that evaluates to a 

key contained in the UniData message file. If no message exists, the number entered 

in message-id is returned. In the second form of the above syntax, you can specify 

more than one expr. 

ABORT 1-71

Note: You can use the ECL ON.ABORT command so that ABORT does not terminate 

the process. For information about the ECL ON.ABORT command, see the UniData 

Commands Reference. 

Examples 

In the following program segment, the user is prompted if an error flag ERR.FLAG 

has been set. The user’s input is read into the variable “answer”. If “answer” equals 

“Y”, the program aborts. 


ERR.FLAG = 1 

IF ERR.FLAG THEN 

PRINT "ABORT PROGRAM?" 

INPUT answer 

IF ANS = "Y" THEN ABORT 

... 

In the next example, in BASICTYPE P, an error message prints and the program 

terminates when CLIENTS cannot be opened: 

EID = "Error Message Text." 

ERR_MSG = "CAN'T OPEN FILE" 

OPEN "CLIENTS" TO CLIENTS.FILE ELSE 

ABORT ERR_MSG, EID 

END 

In the next example, in BASICTYPE P, the program segment prints the error message 

from record 10075 in the error message file if the program aborts: 

$BASICTYPE "P" 

OPEN 'CLIENTS' TO CLIENT.FILE ELSE STOP "CANNOT OPEN" 

READ REC FROM CLIENT.FILE, "99" ELSE ABORT 10075 



PRINTERR, STOP 

UniData 

ON.ABORT, CLEAR.ONABORT – For information, see the UniData Commands 

Reference.

Error Message File – For information, see Administering UniData on UNIX or 

Administering UniData on Windows Platforms. 

ABORT 1-73

ABS 

Syntax 

ABS(expr) 

Description 

The UniBasic ABS function returns the positive numeric value (absolute value) of 

the argument. expr can be any numeric expression. 

Examples 

In the following example, the program segment prints the absolute value of the 

variable NUM, which is 999: 

NUM = -999 

PRINT ABS(NUM) 

In the next example, the program statement replaces the variable NUM with its 

absolute value: 

NUM = ABS(NUM) 



NEG 


acceptConnection 

Syntax 

acceptConnection(svr_socket, blocking_mode, timeout, in_addr, in_name, 

socket_handle) 

Note: This function is case-sensitive. If you want it to be case-insensitive, you 

must compile your programs using the BASIC command with the -i option. 

Description 

Use the acceptConnection function to accept an incoming connection attempt on the 

server side socket. 

Parameters 



svr_socket The handle to the server side socket returned by initServerSocket(). 

blocking_mode 0 - default (blocking) 

1 - blocking. In this mode and the current blocking mode of svr_socket 

is set to blocking, acceptConnection() blocks the caller until a 

connection request is received or the specfied time_out has expired. 

2 - non-blocking. In this mode if there are no pending connections 

present on the queue, acceptConnection() returns an error status code. 

In this mode, time_out is ignored. 

time_out Timeout in milliseconds. 

acceptConnection Parameters 

acceptConnection 1-75



in_addr The buffer that receives the address of the incoming connection. If 

NULL, it will return nothing. 

in_name The variable that receives the name of the incoming connection. If 

NULL, it will return nothing. 

socket_handle The handle to the newly created socket on which the actual connection 

will be made. The server will use readSocket(), writeSocket(), and so 

forth, with this handle to commuinicate with the client. 

The following table describes the status of each return code. 

Return Code Status 

0 Success. 

acceptConnection Parameters (continued) 

Non-zero See Socket Function Error Return Codes. 

acceptConnection Return Codes

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 to +1, UniData 

displays an error message and returns 0 as the result. 

With null value handling on, the result of any mathematical operation, function, or 

comparison involving the null value is the null value. Therefore, ACOS returns the 

null value when expr is the null value. 

Examples 

In the following example, the program statement assigns 60, the 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) 


ASIN, ATAN, COS, SIN, TAN 

ACOS 1-77

ACTIVATEKEY 

Syntax 

ACTIVATEKEY , [ON ] [ON ERROR 

] 

Description 

Use the ACTIVATEKEY command to activate a key or wallet. It is necessary to 

activate a key if you want to supply a password for key protection. 

Note: You can activate only keys with password protection with this command. Keys 

that do not have password protection are automatically activated. 

Parameters 




key.id The key ID or wallet ID to activate. If you provide a Wallet ID, 

UniData activates all keys in the wallet. 

ACTIVATEKEY Parameters


password The password corresponding to key.id. 

ON NFA_SERVER The name of the NFA_SERVER on which you want to activate 

the encryption key. The syntax for NFA_SERVER can be either: 

STATUS Codes 

@domain.var where domain.var specifies the ID for a VOC 

entry that contains the NFA server connection parameters. 

OR 

“MACHINE PORT [, UDTHOME 

]” 

NFA files are always encrypted and decrypted on the remote 

machine by the NFA server. 

ON ERROR statements If you specify ON ERROR statements and an error occurs, 

UniData executes the statements following the ON ERROR 

clause. Otherwise, UniData executes the next statement. 

The ACTIVATEKEY statement rerurns the following STATUS codes regarding 

wallet operations: 

STATUS 

Code 

Description 

0 Operation successful 

ACTIVATEKEY Parameters (continued) 

1 Key is already activated or deactivated. This applies to a single key, not 

a wallet operation 

2 Operation failed. This applies to a single key, not a wallet operation 

3 Invalid wallet ID or password 

4 No access to wallet 

ACTIVATEKEY STATUS Codes 

ACOS 1-79

STATUS 

Code 

Example 


Description 

5 Invalid key ID or password 

6 No access to one of the keys in the wallet 

9 Other error 

ACTIVATEKEY STATUS Codes (continued) 

The following example illustrates how to activate an encryption key: 

ACTIVATEKEY "test","myunidata" ON ERROR PRINT "Unable to activate key"

addAuthenticationRule 

Syntax 

addAuthenticationRule(context, serverOrClient, rule, ruleString) 



Description 

The addAuthenticationRule function adds an authentication rule to a security 

context. The rules are used during SSL negotiation to determine whether or not the 

peer is to be trusted. 

UniData currently supports the following rules: 

Verification Strength rule – The rule governs the SSL negotiation and 

determines whether or not an authentication process is considered 

successful. There are two levels of security, generous and strict. If you 

specify generous, the certificate need only contain the subject name 

(common name) that matches the one you specify by “Peer Name” to be 

considered valid. If you specify strict, the incoming certificate must pass a 

number of checks, including signature check, expiry check, purpose check, 

and issuer check. 

PeerName rule – If you specify the PeerName rule and provide common 

names separated by attributes marks in ruleString, UniData stores trust 

server/client names in the context. 

For more information about the addAuthenticationRule function, see UniBasic 

Extensions. 

addAuthenticationRule 1-81

Parameters 




context The Security Context handle. 

ServerOrClient Flag 1 – Server 

Flag 2 – Client 

UniData treats any other value as a value of 1. 

Rule The rule name string. Valid settings are PeerName or 

VerificationStrength. 

RuleString Rule content string. May be attribute mark separated. 

addAuthenticationRule Parameters 


Return 

Code Status 

0 Success 

1 Invalid Security Context handle 

2 Invalid rule name 

3 Invalid rule content 

addAuthenticationRule Return Codes

addCertificate 

Syntax 

addCertificate(certPath, usedAs, format, algorithm, context) 



Description 

The addCertificate function loads a certificate, or multiple certificates, into a 

security context for UniData to use as a server or client certificate. Alternatively, this 

function can specify a directory which contains the certificates that are either used as 

CA (Certificate Authority) certificates to authenticate incoming certificates, or act as 

a Revocation list to check against expired or revoked certificates. 

For detailed information about the addCertificate function, see UniBasic 

Extensions. 

Parameters 



certPath A string containing the name of the OS-level file that holds the certificate, 

or the directory containing certificates. 

usedAs 1– Used as a client/server certificate. 

2 – Used as an issuer certificate. 

3 – Used as a Certificate Revocation List (CRL) 

addCertificate Parameters 

addCertificate 1-83


format 1 – PEM format 

2 – DER format 

algorithm 1 – RSA key 

2 – DSA key 


context The Security context handle. 


Return 

Code Status 

0 Success 

addCertificate Parameters (continued) 

1 Invalid Security Context handle. 

2 Certificate file could not be opened or directory does not exist. 

3 Unrecognized format. 

4 Corrupted or unrecognized certificate contents. 

5 Invalid parameter value(s). 

addCertificate Return Codes

addRequestParameter 

Syntax 

addRequestParameter(request_handle, parameter_name, parameter_value, 

content_handling) 



Description 

The addRequestParameter function adds a parameter to the request. 

Parameters 



request_handle The handle to the request. 

parameter_name The name of the parameter. 

parameter_value The value of the parameter. 

content_handling The dynamic MIME type for the parameter value. 

addRequestParameter Parameters 


Return 

Code Status 

0 Success. 

addRequestParameter Return Codes 

addRequestParameter 1-85


Return 

Code Status 

1 Invalid request handle. 

2 Invalid parameter. 

3 Bad content type. 

addRequestParameter Return Codes (continued) 

Note: For a GET request, content_handling is ignored. 

For a POST request with default content type, the default for content_handling is 

“Content-Type:text/plain” if content_handling is not specified. For a POST request 

with “Multipart/*” content-type, content_handling is a dynamic array containing 

Content-* strings separated by field marks (@FM). They will be included in the 

multipart message before the data contained in parameter_value is sent. An example 

of content_handling: 

Content-Type: application/XML @FM 

Content-Dispostion: attachment; file=”C:\drive\test.dat” @FM 

Content-Length: 1923 

Specifically, for a POST request with content type “multipart/form-data”, a 

“Content-Dispostion: form-data” header will be created (or, in the case of Content- 

Dispostion already in content_handling, “form-data” will be added to it). 

For both a GET and a POST request with either no content type specified or specified 

as “application/x-www-form-urlencoded”, as described in createRequest(), URL 

encoding is performed on data in parameter_value automatically. Basically, any 

character other than alpha-numeric is considered “unsafe” and will be replaced by 

%HH where HH is the ASCII value of the character in question. For example, ‘#’ is 

replaced by %23, and ‘/’ is replaced by %2F, etc.. One exception is that by 

convention, spaces (‘ ‘) are converted into ‘+’. 

For a POST method with other MIME-type specified, no encoding is done on data 

contained in parameter_value.

ALPHA 

Syntax 

ALPHA("str.expr") 

Description 

The UniBasic ALPHA function tests a string to see if it is composed entirely of 

alphabetic characters. If str.expr is made entirely of alphabetic characters (not special 

characters, escape sequences, or the null value), the function returns 1. If numeric or 

other characters are present in str.expr, or if str.expr evaluates to an empty string or 

the null value, the function returns 0. 

Because UniBasic does not recognize multibyte characters as alphabetic, ALPHA 

returns 0 instead of converting them. 

Examples 

In the following example, the program statement prints 0 because the literal string 

contains the numeric character 2: 

PRINT ALPHA("ABCDEFGHIJK2") 

In the next example, the program segment prints 1 because the string ALPHA 

contains only alphabetic characters: 

ALPHA.T=ALPHA("CORONA") 

PRINT ALPHA.T 

In the next example, the program statement prints 0 because the string does not 

contain any characters. An empty string is not considered to be an alphabetic 

character. 

PRINT ALPHA("") 

ALPHA 1-87

amInitialize 

Syntax 


amInitialize(hSession,appName, policyName, reasonCode) 



Description 

The amInitialize function creates and opens an AMI session. The output parameter, 

hsession, is a session handle that is valid until the session is terminated. This function 

returns a status code indicating success, warning, or failure. 

Parameters 



hSession Upon successful return, holds a handle to a session. You can then use the 

handle in other UniData WebSphere MQ API calls. [OUT] 

appName An optional name that you can use to identify the session. [IN] 

policyName The name of a policy. If you specify ““ (null), UniData uses the system 

default policy name. [IN] 

reasonCode Holds an AMI Reason Code when the function returns a status indicating 

an AMI warning, or an AMI error occurred. You can use the AMI Reason 

Code to obtain more information about the cause of the warning or error. 

See the MQSeries Application Messaging Interface manual for a list of 

AMI Reason Codes and their descriptions. [OUT] 

amInitialize Parameters



0 – AMCC_SUCCESS Function completed successfully. 

1 – AMCC_WARNING A warning was returned from AMI. The 

reasonCode output parameter contains an 

AMI reason code with further details about 

the warning. 

2 – AMCC_FAILED An error was returned from AMI. The 

reasonCode output parameter contains an 

AMI reason code with further details about 

the error. 

115 – U2AMI_ERR_SESSION_IN_USE An active session already exists (under a 

different hSession variable than the one being 

passed in). 

Other A non-AMI error occurred. 

amInitialize Return Codes 

amInitialize 1-89

amReceiveMsg 

Syntax 

amReceiveMsg(hSession,receiverName,policyName, selMsgName, maxMsgLen, 

dataLen, data, rcvMsgName, reasonCode) 



Description 


The amReceiveMsg function receives a message sent by the amSendMsg function. 

For detailed information about amReceiveMsg, see UniBasic Extensions. 

Parameters 



hSession The session handle returned by amInitialize. [IN] 

receiverName The name of a receiver service. If you do not specify a name, UniData 

uses the system default receiver name. [IN] 

policyName The name of a policy. If you do not specify a name, UniData uses the 

system default policy name. [IN] 

selMsgName Optional parameter specifying the name of a message object containing 

information (such as a Correl ID) that UniData uses to retrieve the 

required message fromthe queue. See UniBasic Extensions for detailed 

information about this parameter. [IN] 

maxMsgLen The maximum message length the application will accept. Specify as - 

1 to accept messages of any length. See UniBasic Extensions for 

detailed information about this parameter. [IN] 

amReceiveMsg Parameters


dataLen The length of the retrieved message data, in bytes. Specify ““ (null) if 

not required. [OUT] 

data The received message data. [OUT] 

rcvMsgName The name of a message object for the retrieved message. You can 

specify ““ (null) for this parameter, in which case UniData uses the 

system default name (constant AMSD_RCV_MSG). See UniBasic 

Extensions for detailed information about this parameter. [IN] 

reasonCode Holds an AMI reason code when the function returns a status indicating 

an AMI warning or an AMI error occurred. You can use the AMI reason 

code to obtain more information about the cause of the warning or error. 


AMI reason codes and their descriptions. [OUT] 



amReceiveMsg Parameters (continued) 

0 – AMCC_SUCCESS Function complete successfully. 

1 – AMCC_WARNING A warning was returned from AMI. The reasonCode output 

parameter contains an AMI reason code with further details 

about the warning. 

2 – AMCC_FAILED An error was returned from AMI. The reasonCode output 


about the error. 


amReceiveMsg Return Codes 

amReceiveMsg 1-91

amReceiveRequest 

Syntax 

amReceiveRequest(hSession, receiverName, policyName, maxMsgLen, dataLen, 

data, rcvMsgName, senderName, reasonCode) 



Description 


The amReceiveRequest function receives a request message. 

For detailed information about this function, see UniBasic Extensions. 

Parameters 



hSession The session handle returned by the amInitialize function. [IN] 

receiverName The name of a receiver service. If you specify ““ (null), UniData uses the 

system default receiver name. [IN] 

policyName The name of a policy. If you do not specify a policy name, UniData uses 

the system default policy name. [IN] 

maxMsgLen The maximum message length the application will accept. Specify -1 to 

accept messages of any length. See UniBasic Extensions for detailed 

information about this parameter. [IN] 

dataLen The length of the message data, in bytes. Specify ““(null) if this is not 

required. [OUT] 

data The received message data. [OUT] 

amReceiveRequest Parameters


rcvMsgName The name of the message object for the received message. If you specify 

““(null) for this parameter, UniData uses the system default receiver 

name. UniData uses the value for rcvMsgName in the subsequent call to 

the amSendResponse function. [IN] 

senderName The name of a special type of sender service known as a response sender, 

to which the response message will be sent. This sender name must not 

be defined in the repository. If you do not specify a name, UniData uses 

the system default response sender service. [IN] 








amReceiveRequest Parameters (continued) 





2 – AMCC_FAILED An error was returned from AMI. The reason code output 




amReceiveRequest Return Codes 

amReceiveRequest 1-93

amSendMsg 

Syntax 


amSendMsg(hSession, senderName, policyName, data, sndMsgName, reasonCode) 



Description 

The amSendMsg function sends a datagram (send and forget) message. 

For detailed information about this function, see UniBasic Extensions. 

Parameters 




senderName The name of a sender service. If you specify ““(null), UniData uses the 

system default receiver name. [IN] 

policyName The name of a policy. If you specify ““(null), UniData uses the system 


data The message data to be sent. [IN] 

sndMsgName The name of a message object for the message being sent. If you specify 

““(null), UniData uses the system default policy name. [IN] 






amSendMsg Parameters











amSendMsg Return Codes 

amSendMsg 1-95

amSendRequest 

Syntax 

amSendRequest(hSession, senderName, policyName, data, sndMsgName, 

reasonCode) 



Description 


The amSendRequest function sends a request message. 

Parameters 




senderName The name of a sender service. If you specify ““(null), UniData uses the 

system default sender name. [IN] 



responseName The name of the receiver service to which the response to this send 

request should be sent. Specify ““(null) if you do not require a response. 

[IN] 

dataLen The length of the message data, in bytes. [IN] 

amSendRequest Parameters




““(null), UniData uses the system default message name (constant 

AMSD_SND_MSG). [IN] 

reasonCode Holds an AMI reason code when the functions returns a status indicating 







amSendRequest Parameters (continued) 









amSendRequest Return Codes 

amSendRequest 1-97

amSendResponse 

Syntax 

amSendResponse(hSession, senderName, policyName, rcvMsgName, data, sndMsgName, 

reasonCode) 



Description 


The amSendResponse function sends a request message. 

Parameters 



hSession The session handle returned by amInitialize. [IN] 

senderName The name of the sender service. It must be set to the senderName you 

specify for the amReceiveRequest function. [IN] 

policyName The name of a policy. If you specify ““(null), UniData uses the default 

policy name. 

rcvMsgName The name of the received message to which this message is a response. 

It must be set to the rcvMsgName you specify for the amReceiveRequest 

function. [IN] 

dataLen The length of the message data, in bytes. [IN] 

amSendResponse Parameters




““(null), UniData uses the system default message name (constant 

AMSD_SND_MSG). 




[OUT] 



amSendResponse Parameters (continued) 









amSendResponse Return Codes 

amSendResponse 1-99

amTerminate 

Syntax 

amTerminate(hSession, policyName, reasonCode) 



Description 

The amTerminate function closes a session. 

Parameters 




hSession The session handle returned by amInitialize. [IN/OUT] 







AMI reason codes and their descriptions. 

amTerminate Parameters




1– AMCC_WARNING A warning was returned from AMI. The reasonCode output 



2 – AMCC_FAILED An error was returned from AMI. The reasoncode output 





amTerminate 1-101

analyzeCertificate 

Syntax 

analyzeCertificate(cert, format, result) 



Description 

The analyzeCertficate function decodes a certificate and inputs plain text in the 

result parameter. The result parameter then contains such information as the subject 

name, location, institute, issuer, public key, other extensions, and the signature of the 

issuer. 

Parameters 


Paramet 

er Description 


cert A string containing the certificate file name. 

format 1 – PEM 

2 – DER 

result A dynamic array containing parsed cert data, in ASCII format. 

analyzeCertificate Parameters


Return 

Code Status 

0 Success 

1 Failed to open cert file 

2 Invalid format 

3 Unrecognized cert 

4 Other errors 

analyzeCertificate Return Codes 

analyzeCertificate 1-103

AND 

Syntax 

expr1 AND expr2 

Synonym 

& 

Description 

The AND Boolean operator combines a set of expressions. If expr1 or expr2 is false, 

the combined expression is false. Both expressions must be true for a true condition. 

Example 

In the following example, the program segment combines two expressions (X < Y) 

and (Y < Z). Both expressions must be true for the program to call subroutine 

RETRY. 


X = 1 ; Y = 2 ; z = 3 

IF (X < Y) AND (Y < Z) THEN GOSUB RETRY: 



NOT, OR

ASCII 

Syntax 

ASCII(expr) 

Description 

The UniBasic ASCII (American Standard Code for Information Interchange) 

function converts a string in EBCDIC (Extended Binary Coded Decimal Information 

Code) format to the corresponding ASCII values. Even though the ASCII function 

works with data in any format, its results are meaningful only when it is applied to 

EBCDIC data. 

For more information about ASCII character codes, see Appendix A, “ASCII 

Character Codes.” 

Note: Use the UniBasic commands CHAR and SEQ to convert between ASCII 

character and decimal value. 

Example 

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) 



CHAR, CHARS, EBCDIC, SEQ 

ASCII 1-105

ASIN 

Syntax 

ASIN(expr) 

Description 

The UniBasic ASIN function returns the trigonometric arc sine (inverse sine) of a 

numeric expression. 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 UniData displays an error 

message and returns 0 as the result. 


comparison involving the null value is the null value. Therefore, ASIN returns the 


Examples 

In the following example, the program statement assigns 30, the 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) 


ACOS, ATAN, COS, SIN, TAN 


ASSIGN 

Syntax 

ASSIGN expr TO SYSTEM(option) 

Description 

The UniBasic ASSIGN command redefines some system-level parameters. The 

value in option changes to the value you specify with expr. 

Parameters 


For parameters 2, 3, and 5, expr must be numeric. For parameter 7, expr must be a 

string representing a valid terminal type and must be enclosed in quotation marks. 

Example 


2 Page width 

3 Page length 

5 Page number 

7 Terminal type 

ASSIGN Parameters 

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) 

ASIN 1-107


UniData 

TERM – For information, see the UniData Commands Reference. 


ATAN 

Syntax 

ATAN(expr) 

Description 

The UniBasic ATAN function returns the trigonometric arc tangent (inverse tangent) 

of a numeric expression expr in degrees. 


comparison involving the null value is the null value. Therefore, ATAN returns the 


Example 

In the following example, the program segment prints the arc tangent of the variable 

VAL. VAL is set to 45. 

VAL = 1 

PRINT ATAN(VAL) 


ACOS, ASIN, COS, SIN, TAN 

ATAN 1-109

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. 


comparison involving the null value is the null value. BITAND returns the null value 

when num.expr1 or num.expr2 is the null value. 

The following table shows the results of the BITAND function on various sets of 

input. 

Example 

In the following example, the program statement prints a 0: 

PRINT BITAND(0,1) 


num.expr1 

num.expr 

2 Result 

0 0 0 

0 1 0 

1 0 0 

1 1 1 

3 9 1 

23 87 23 

BITAND Function Operation Results

BITNOT 

Syntax 

BITNOT(num.expr) 

Description 

The UniBasic BITNOT function performs the bit-wise NOT logical function on the 

argument num.expr. 


comparison involving the null value is the null value. Therefore, BITNOT returns the 

null value when num.expr is the null value. 

The following table shows the results of the BITNOT function on the valid input: 0 

and 1. 

Example 

In the following example, the program statement prints 1: 

PRINT BITNOT(0) 

num.expr Results 

0 1 

1 0 

BITNOT Function Operation Results 

BITNOT 1-108

BITOR 

Syntax 

BITOR(num.expr1,num.expr2) 

Description 

The UniBasic BITOR function performs the bit-wise OR logical function on the 



comparison involving the null value is the null value. Therefore, BITOR returns the 

null value when num.expr1 or num.expr2 is the null value. 

The following table shows the results of the BITOR function on various sets of input. 

Example 

In the following example, the program statement prints a 1: 

PRINT BITOR(0,1) 


num.expr1 num.expr2 Result 

0 0 0 

0 1 1 

1 0 1 

1 1 1 

3 9 11 

23 87 87 

BITOR Function Operation Results

BITXOR 

Syntax 

BITXOR(num.expr1,num.expr2) 

Description 

The UniBasic BITXOR function performs the bit-wise XOR logical function on the 



comparison involving the null value is the null value. Therefore, BITXOR returns the 

null value when num.expr1 or num.expr2 is the null value. 

The following table shows the results of the BITXOR function on various sets of 

input. 

Example 

In the following example, the program statement prints 1: 

PRINT BITXOR(0,1) 

num.expr1 num.expr2 Result 

0 0 0 

0 1 1 

1 0 1 

1 1 0 

3 9 10 

23 87 64 

BITXOR Function Operation Results 

BITXOR 1-110

BPIOCP 

Syntax 

BPIOCP 

Description 

The UniBasic BPIOCP command turns automatic pagination on. With pagination 

on, printing to a terminal (without using cursor addressing) pauses at the bottom of 

each screen display. The user is prompted before the next screen is displayed as 

follows: 


Enter to continue... 

Three user responses are valid for this prompt,which are listed in the following table. 

Input Description 

ENTER Pressing ENTER displays another screen of data. 

N Continues display and disables automatic pagination (no pause at bottom of 

each screen display). 

Q Quits the current process and returns to the previous process. 

BPIOCP User Responses 

Example 

The page control process is automatically disabled if the @ function is executed. For 

example, all of the following statements disable terminal pagination: 

PRINT @(1) 

CRT @(2) 

VARIABLE = @(3) 

With page control disabled, UniData assumes that the program will control the 

paging of data. To turn automatic pagination on from within a UniBasic program, use 

BPIOCP.

An example is provided with the BPIOCPN command. 



BPIOCPN 

BPIOCP 1-112

BPIOCPN 

Syntax 

BPIOCPN 

Description 

The UniBasic BPIOCPN command turns off automatic pagination. With pagination 

off, printing to a terminal does not pause at the bottom of each screen display. 

Example 

In the following example, the program prints the first 60 records of the INVENTORY 

file with pagination disabled by @(0,0). Then the BPIOCP command enables 

automatic pagination. The next 23 records are printed, and the user is prompted to 

press ENTER to continue. At this point, the user also can enter N to disable 

pagination. 


After all 60 records have printed, BPIOCPN executes. A prompt displays this information. 

When the user presses ENTER at the prompt, 60 records print with 

pagination off. 

JUNK = @(0,0) ; * Disable pagination 

OPEN 'INVENTORY' READONLY TO INVENTORY.FILE ELSE NULL 

SELECT INVENTORY.FILE 

PRINT "Printing after terminal addressing: @(0,0)" 

FOR X = 1 TO 60 

READNEXT REC THEN PRINT REC 

NEXT X 

PRINT "Sixty rec ids printed." 

PRINT "BPIOCP executing." 

BPIOCP ; *Enable pagination 

FOR X = 1 TO 60 

READNEXT REC THEN PRINT X:" ":REC 

NEXT X 


PRINT "BPIOCPN executing." 

INPUT var 

BPIOCPN ; *Disable pagination 

FOR X = 1 TO 60 

READNEXT REC THEN PRINT X:" ":REC 

NEXT X 


CLEARSELECT 

END 



BPIOCP 

BPIOCPN 1-114

BREAK 

Syntax 

BREAK [KEY] {ON | OFF | expr} 

Description 

The UniBasic BREAK command enables or disables the interrupt key to exit a 

program to the ‘!’ debugger prompt and displays the current program line number. 

The program must have been compiled and run with debugger options. For instructions, 

see the ECL BASIC and RUN commands in the UniData Commands 

Reference. 

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 interrupt key is not operational. This status continues even if you exit a 

program with the interrupt key disabled. 

Parameters 




KEY KEY is optional and has no effect. It is included for backward compatibility 

only. 

ON Enables the terminal interrupt key to stop the execution of a UniBasic 

program and enter the UniBasic debugger. 

OFF Disables the interrupt key. Pressing the interrupt key has no effect on program 

execution. 

expr Enables the terminal interrupt 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 interrupt key if the break counter is less than or equal to zero: 

BREAK ON 

In the next example, a numeric expression determines whether to enable the interrupt 

key. If X is greater than 0, UniData enables the interrupt key. 

BREAK X > 0 


UniData 

PTERM – For information, see the UniData Commands Reference. 

BREAK 1-116

BYTELEN 

Syntax 

BYTELEN (string) 

Description 

The UniBasic BYTELEN function returns the number of bytes required to store a 

character. From one to four bytes could be required. 

Example 

The following figure illustrates a string that shows below each “character” the 

number of bytes required to store that character. The string contains eight bytes. 

Therefore, BYTELEN would return 8 for this string. 

Number 

of bytes 



CHARLEN, DISPLAYWIDTH, ISMB, LEN, MBLEN 


2 3 1 2

CALCULATE 

Syntax 

CALCULATE(dictionary.item) 

{dictionary.item} 

Description 

The UniBasic CALCULATE or {} (braces) function executes a virtual attribute. The 

dictionary.item must be a valid virtual attribute within the dictionary previously 

opened to the @DICT variable with an OPEN statement. 

Note: Before you use this function, you must compile the dictionary of the file you will 

open to the @DICT variable by using the ECL COMPILE.DICT or CD command. 

In the CALCULATE() form, the dictionary.item can be a quoted string or a UniBasic 

variable. The expression uses the data from the current @RECORD during the evaluation 

process. 

In the {} form, the dictionary.item must be the literal dictionary name with no 

quotation marks. 

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 @CONV, @FORMAT, 

and @HEADER. You can then use these @ variables in other UniBasic functions, 

such as ICONV, OCONV, and FMT. For more information about @ variables, see 

Appendix B, “UniBasic@variables.” 

CALCULATE 1-118

Example 

In the following example, the program segment opens the ORDERS file to the 

variable ORDER.FILE and the dictionary of the ORDERS file to the special @DICT 

variable. After selecting the ORDERS file, the program reads the value of each 

record ID into @ID, reads the value of the order record into @RECORD, then uses 

the {} (braces) function to evaluate the order balance (storing the total in 

TOTAL.DUE). The braces function updates the @CONV and @FORMAT variables, 

which are used to print the total with the correct format. 


OPEN 'ORDERS' TO ORDER.FILE ELSE 

STOP 'NO ORDER FILE' 

END 

OPEN 'DICT','ORDERS' TO @DICT ELSE 

STOP 'NO DICTIONARY FOR ORDERS FILE' 

END 

TOTAL.DUE = 0 

SELECT ORDER.FILE 

MORE = 1 

LOOP 

READNEXT @ID ELSE MORE = 0 

UNTIL NOT(MORE) DO 

READ @RECORD FROM ORDER.FILE,@ID ELSE 

@RECORD = '' 

END 

TOTAL.DUE += {GRAND_TOTAL} 

REPEAT 

TOTAL.DUE = OCONV(TOTAL.DUE,@CONV) 

PRINT "Total Accounts Receivable":FMT(TOTAL.DUE,@FORMAT) 

CLEARSELECT 

END 



ITYPE

CALL 

Syntax 

CALL *sub.name [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] 

[ASYNC | SYNC] [ON connection] 

CALL @var [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] 


CALL sub.name [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] 


Description 

The UniBasic CALL command transfers program control to an external subroutine. 

The first form of the syntax calls a globally cataloged subroutine. 

The second form of the syntax calls a subroutine named in a variable. 

The third form of the syntax calls a subroutine directly. 

The called program or subroutine must contain a RETURN statement, which returns 

control to the calling program or subroutine. 

You can nest subroutines up to 1,024 levels deep. 

Note: You must catalog subroutines before using them in a UniBasic CALL statement. 

You must separate individual arguments by commas and enclose the set of arguments 

within parentheses. You can place arguments on multiple lines. Each continued line 

must end with a comma. Regardless of placement, the number and type of arguments 

in the CALL statement must match the number and type of arguments in the 

SUBROUTINE statement within the external subroutine. Arrays and singlevalued 

arguments can be passed in the same CALL statement. 

Tip: You can also pass variables through named and unnamed common areas. 

Variables stored in common area(s) are accessible to both calling and called 

programs without being passed as arguments. You cannot use the same variable 

name in both a SUBROUTINE argument and a common variables list. 

CALL 1-120

Parameters 



Examples 

Note: A sample program that calls an external subroutine is provided in “Appendix 

A, Sample Program” in Developing UniBasic Applications. 

In the following example, the program statement calls the subroutine VID, passing 

the variables TITLE and ST: 

CALL VID(TITLE,ST) 

In the next example, the program segment calls the subroutine MONTHTOTAL by 

calling @var VID (see CALL Parameter table above), which holds the string 

“MONTHTOTAL”. Note that VID is defined before it is called. 

VID = "MONTHTOTAL" 

CALL @VID(TOTAL) 


sub.name The name of the called subroutine. 

@var A variable that contains the name of the subroutine to call. 

argument1, argument2 Any valid argument passed to the subroutine. 

MAT array1, 

MAT array2 

Any valid array passed to the subroutine. 

ASYNC | SYNC UniData no longer supports this parameter, but it remains for 

syntax compatibility. 

ON connection UniData no longer supports this parameter, but it remains for 


CALL Parameters

In the next example, the program segment calls the contents of cell (1,12) in the array 

cells, thus calling the subroutine RECEIPTS with the argument “MON1_12”. In the 

use of @matrices, you can select the array element by the use of an index (a variable 

within the dimensions of the array). 

"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 because subroutine SUBS, 

which is shown after this example, has a different number of arguments than the 

CALL statement. Called and calling programs must pass the same number of 

parameters. 

CALL SUBS(X,Y,Z) 

The subroutine SUBS, which the program in the previous example calls, follows: 

SUBROUTINE SUBS(X) 



CHAIN, COMMON, ENTER, GOSUB, RETURN, SUBROUTINE 

CALL 1-122

CALLC 

Syntax 

CALLC c.sub.name [(argument1[,argument2]...)] 

CALLC @var [(argument1[,argument2]...)] 

Description 

The UniBasic CALLC command transfers program control to an external function 

(c.sub.name). The second form of the syntax calls a function whose name is stored in 

a UniBasic variable (@var). The program could pass back return values in variables. 

CALLC arguments can be simple variables or complex expressions, but not arrays. 

CALLC can be used as a command or function. 

Calling a C Program in UNIX 

You must link the C program to UniData before calling it from a UniBasic program. 

Perform the following procedure to prepare UniData for CALLC: 


1. Write and compile the C program. 

2. Define the C program call interface. 

3. Build the runtime version of UniData (containing the linked C program). 

4. Write, compile, and execute the UniBasic program. 

For more information about this procedure, see Developing UniBasic Applications. 

Calling a Function on Windows Platforms 

The CALLC implementation in UniData for Windows Platforms uses the Microsoft 

Windows Dynamic Link Library (DLL) facility. This facility allows separate pieces 

of code to call one another without being permanently bound together. Linking 

between the separate pieces is accomplished at runtime (rather than compile time) 

through a DLL interface.

For CALLC, developers create a DLL and then call that DLL from UniData. E-type 

VOC entries for each function called from a DLL communicate interface information 

to UniData. For additional information and examples, see Administering UniData on 

UNIX or Administering UniData on Windows Platforms. 

Examples 

In the following example, the called subroutine draws a circle with its center at the 

twelfth row and twelfth 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, and 

it is called indirectly: 

SUB.NAME = DRAW.CIRCLE 

CALLC @SUB.NAME(RADIUS,CENTER) 

In the next example, CALLC is used as a function, assigning the return value of the 

subroutine PROGRAM.STATUS in the variable RESULT: 

RESULT = CALLC PROGRAM.STATUS 



CALL 

CALLC 1-124

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 BEGIN CASE and END CASE is unlimited. 

The number of statements within each CASE branch is unlimited. CASE statements 

can be nested. 

The CASE command tests each of the expressions in sequence. If an expression 

evaluates as true, the system executes the statements that follow it. When one of the 

CASE expressions is found to be true, the system does not test any subsequent 

expressions. If none of the conditions is true, the system does not execute any 

statements. 

With null value handling turned on, a test of the null value returns a negative result. 

For an overview of how the null value affects UniBasic, see Developing UniBasic 

Applications. 


Parameters 



CASE expression1 Any UniBasic conditional expression. If the expression is true, 

execute statements1. 

statements1 The UniBasic statements to execute if expression1 is true. 

CASE expression2 Any UniBasic conditional expression. If the expression is true, 

execute statements2. 

statements2 The UniBasic statements to execute if expression2 is true. 

CASE 1 

statements 

Examples 

Note: An example of the use of CASE is included in the sample program in “Appendix 

A - Sample Program” of Developing UniBasic Applications. 

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 the display terminal. 

BEGIN CASE 

CASE DUE.DATE > DATE() 

GOSUB PRINT.OVERDUE: 

CASE DUE.DATE

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 not 1 

or 2, 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 because the evaluation expression 

appears on the BEGIN CASE line: 

BEGIN CASE VAR 1 

In the next example, the statement is invalid because BEGIN CASE must appear 

before the first CASE statement: 

CASE VAL 



IF/THEN/ELSE, LOOP/REPEAT

CAT 

Syntax 

expr1 CAT expr2 

Synonym 

: 

Description 

The UniBasic CAT arithmetic operator concatenates expr1 to expr2. 

Examples 

In the following example, the program segment concatenates A to B, and then prints 

123456: 

A = "123" 

B = "456" 

C = A CAT B 

PRINT C 

The following program segment compiles and runs only with null value handling on. 

The program concatenates two strings, one ending with the null value, and another 

beginning with ‘123.’ This produces the string @AM@NULL123@AM456. The called 

subroutine, print.setup, converts UniData delimiters and the null value to printable 

characters. (This subroutine is printed in the entry for “CHANGE” on page 133.) 

PRT.STG = '' 

Z=123:@AM:456 

Y=@AM:@NULL 

STG = Y CAT Z 

CALL print.setup(STG,PRT.STG) 

PRINT PRT.STG 

CAT 1-128



CATS, SPLICE 


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. 

Example 

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 



CAT, SPLICE 

CATS 1-130

CHAIN 

Syntax 

CHAIN "str.expr" 

Description 

The UniBasic CHAIN command terminates the current UniBasic program and 

executes the ECL command str.expr. CHAIN performs a function similar to the 

EXECUTE statement, except that control is not returned to the original program. 

UniData treats str.expr as a command you type at the ECL colon (:) prompt. If str.exp 

executes a UniBasic program, variables could be passed through common areas, but 

all other variables are reinitialized when the new program begins. 

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

sequentially running several smaller programs rather than one large program. 

UDT.OPTIONS 6 and 40 affect the operation of the CHAIN command. For more 

information, see the UDT.OPTIONS Commands Reference. 

Examples 

In the following example, the program terminates and UniData executes the ECL 

command “RUN BP FORMLET”. FORMLET is a compiled UniBasic program. 

UniData does not return control 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" 




CALL, COMMON, ENTER, GOSUB 

CHAIN 1-132

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 an empty string, the system does not change 

string. CHANGE supports multibyte languages. 

Parameters 



Examples 

In the following example, the program segment prints “UniBasic Release 6.1”: 


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 

STRA = "UniBasic Release 6.1" 

OLDRELEASE = "6.0" 

NEWRELEASE = "6.1" 

STRB = CHANGE(STRA, OLDRELEASE,NEWRELEASE) 

PRINT STRB 

In the next example, the program segment prints “NEW STRC = A23A24A25A26”: 

STRC = "123124125126" 

PRINT "NEW STRC =":CHANGE(STRC,"1","A")

The following subroutine converts UniData delimiters and the null value to printable 

characters. (This subroutine compiles only with null value handling turned on.) 

SUBROUTINE PRINT.SETUP(STG, PRT.STG) 

PRT.STG = CHANGE(STG, @NULL, "@NULL") 

PRT.STG = CHANGE(PRT.STG, @AM, "@AM") 

PRT.STG = CHANGE(PRT.STG, @VM, "@VM") 

RETURN 

CHANGE 1-134

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. expr can be 

a constant, variable, numeric function, or any combination of these. expr must 

evaluate to a positive number from 0 to 255 (the range of ASCII character codes). 

CHAR supports multibyte languages. 

Not all ASCII codes are printable. Some represent terminal controls, and others are 

reserved for special uses. For more information about ASCII character codes, see 

Appendix A, “ASCII Character Codes.” 

Tip: Use @variables to represent UniData delimiters and the null value. IBM 

recommends that you not use the UniBasic functions CHAR or CHARS to insert these 

variables because the ASCII code that represents it varies with language group. 

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 ASCII 

code. 

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) 




ASCII, CHARS, EBCDIC, SEQ 

CHAR 1-136

CHARLEN 

Syntax 

CHARLEN (string) 

Description 

The UniBasic CHARLEN function returns the number of characters in a character 

string. A multibyte character could require from one to four bytes to encode. 

Example 

The following figure illustrates a string of four multibyte characters. CHARLEN 

would return 4 for this string. 

Number 

of bytes 



BYTELEN, DISPLAYWIDTH, ISMB, LEN, MBLEN 


2 3 1 2

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. 

array elements can contain a constant, variable, numeric function, or any combination 

of these. array elements must evaluate to a positive number 0–255 (the range 

of ASCII character codes). CHARS supports multibyte languages. 

Not all ASCII codes are printable. Some represent terminal controls, and others are 

reserved for special uses. For more information about ASCII character codes, see 

Appendix A, “ASCII Character Codes.” 

Tip: Use @variables to represent UniData delimiters and the null value. IBM 

recommends that you not use the UniBasic functions CHAR or CHARS to insert these 

variables because the ASCII code that represents it varies with language group. 

Example 

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) 



ASCII, CHAR, EBCDIC, SEQ 

CHARS 1-138

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. 

For more information about ASCII characters values, see Appendix A, “ASCII 

Character Codes.” 

Tip: You can use the CHECKSUM function to check whether data was copied 

correctly, or whether information processed properly, by comparing the 

CHECKSUM of the original data with the CHECKSUM of the copy. 

Example 

In the following example, the program statement prints out 2445, the checksum of 

string “123456789”: 

PRINT CHECKSUM("123456789") 


CLEAR 

Syntax 

CLEAR 

Description 

The UniBasic CLEAR command sets the values of all variables stored in local 

memory to 0, including all array elements. Variables assigned to named or unnamed 

common areas are not affected. 

Tip: CLEAR can be used at any point within a program. 

Note: CLEAR performs differently with BASICTYPEs M and P. All variables in 

unnamed common areas are also set to 0. 

Examples 

In the following example, the program statement clears all variables not held in 

common if the variable INITIALIZE is true and BASICTYPE is U. The variable 

INITIALIZE also set to 0 (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 BASICTYPEs P and M: 

COMMON NAME(100) 

X = 4 

Y = X - 1 

CLEAR 

CLEAR 1-140



COMMON, CLEARCOMMON 

UniData 

DELETECOMMON – For information, see the UniData Commands Reference. 


CLEARCOMMON 

Syntax 

CLEARCOMMON [/common.label/] 

Synonyms 

CLEAR COMMON, CLEARCOM, CLEAR COM 

Description 

The UniBasic CLEARCOMMON command sets all variables in a named common 

area to zero. If you do not specify common.label, CLEARCOMMON sets all 

variables specified in the unnamed common area 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 common 

areas if the variable INITIALIZE.COMMON is true: 

IF INITIALIZE.COMMON THEN CLEAR COMMON 



CLEAR, COMMON 

CLEARCOMMON 1-142

UniData 

DELETECOMMON, STACKCOMMON – For information, see the UniData 



CLEARDATA 

Syntax 

CLEARDATA 

Description 

The UniBasic CLEARDATA command clears data stored by any executed DATA 

statements. Subsequent INPUT statements request data from the keyboard because 

the input queue is empty. 

Example 

In the following example, a DATA statement sets up an input queue. An INPUT 

statement then reads the first item (100) into the variable VAL. Because 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 input queue. If the first value had not been 100, 120 would 

have been assigned from the second item in the input queue. 

DATA 100,120,105,54,120 

INPUT VAL 

IF VAL = 100 THEN CLEARDATA 

PRINT "VALUE": ; INPUT VAL2 



DATA, INPUT 

CLEARDATA 1-144

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 can clear only 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 Optional. Specifies a dictionary or data file to clear. 

The file must have been opened previously with an OPEN 

statement. 

If you do not specify a file.var, the system reads from the 

default file. If no default file is open, a fatal READ error occurs. 

A default file is one for which no file variable is assigned in the 

OPEN statement. 

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 fatal error conditions. 

CLEARFILE Parameters

Example 

In the following example, the program statement removes all records from the file 

PASTDUE. The dictionary of PASTDUE remains unchanged after the execution of 

this statement. 

CLEARFILE PASTDUE 



OPEN, OPENSEQ, OSOPEN 

UniData 

CLEAR.FILE – For information, see the UniData Commands Reference. 

CLEARFILE 1-146

CLEARINPUT 

Syntax 

CLEARINPUT 

Synonym 

INPUTCLEAR 

Description 

The UniBasic CLEARINPUT command clears the terminal type-ahead buffer so the 

next INPUT statement forces a response from the user. 

Example 

In the following example, the CLEARINPUT statement clears the terminal typeahead 

buffer so the user must respond to the prompt: 


CLEARINPUT 

PRINT "DO YOU WANT TO DELETE THIS FILE?(Y OR N)"; INPUT X,1 



CLEARDATA, INPUT, SYSTEM

CLEARSELECT 

Syntax 

CLEARSELECT [num.expr] [ALL] 

Description 

The UniBasic CLEARSELECT command clears active select lists. You can specify 

a particular ID list by specifying num.expr as 0 through 9. ALL clears all active select 

lists. If you do not specify a parameter, UniData clears the default ID list (zero). If 

you specify an ID list outside the valid range, a runtime error occurs. 

You generally create active lists by executing 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. Because multiple 

select lists can be active at one time, the CLEARSELECT statement could clear one 

or all of the currently active lists. 

Examples 

In the following example, the program segment clears select list 1: 

ID.LIST=1 

CLEARSELECT ID.LIST 

In the next example, the program statement clears the default list 0: 

CLEARSELECT 



SELECT, GETLIST 

CLEARINPUT 1-148

UniQuery 

GET.LIST, SELECT, SSELECT – For information, see Using UniQuery. 


CLEARSQL 

Syntax 

CLEARSQL [file.name.expr] 

Description 

The UniBasic CLEARSQL command clears all active temporary tables that were 

created during the current session (for example, created with the EXECUTESQL 

command with a corresponding TO clause). If you do not specify file.name.expr, 

CLEARSQL clears all the UniData SQL file variables created during this UniBasic 

session. 

Note: When a program returns to the UniData prompt, UniData clears all UniData 

SQL file variables regardless of whether you execute CLEARSQL. 



EXECUTESQL 

CLEARSQL 1-150

CLOSE 

Syntax 

CLOSE [file.var] [ON ERROR statements] 

Description 

The UniBasic CLOSE command closes a dictionary or data file. 

Note: You can use the OPEN command to access an unlimited number of files in a 

single UniData process. However, the operating system could limit the number of 

files that can be opened across numerous processes and users. 

Parameters 




file.var Specifies a dictionary or data file to close. If you do not specify 

file.var, the default file is closed. If no default file is open, the 

command has no effect. 

A default file is created by omitting the file variable in the 



the file is not open. 


terminates under fatal error conditions. 

CLOSE Parameters

Example 

In the following example, the program segment opens and closes the file 

INVENTORY: 

OPEN 'INVENTORY' TO INVENTORY.FILE ELSE STOP 

CLOSE INVENTORY.FILE 



OPEN 

CLOSE 1-152

CLOSESEQ 

Syntax 

CLOSESEQ seq.file.var [ON ERROR statements] 

Description 

The UniBasic CLOSESEQ command closes a sequential file that you opened with 

the OPENSEQ or OSOPEN command. The CLOSESEQ command releases the 

exclusive file lock set by the OPENSEQ command. If any new lines (sequential 

records) were added to the file, UniData writes a new end-of-file mark after the new 

lines. 

Parameters 



Example 

In the following example, the statement closes the sequential file referred to by the 

file variable DATA.59: 

CLOSESEQ DATA.59 


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

The file must have been opened previously with an OPENSEQ 

or OSOPEN statement. 


the file is not open. 


terminates under such fatal error conditions. 

CLOSESEQ Parameters



CLOSE, OPENSEQ, OSCLOSE, OSOPEN 

CLOSESEQ 1-154

closeSocket 

Syntax 

closeSocket(socket_handle) 



Description 

Use the closeSocket function to close a socket connection. 

Parameters 





socket_handle The handle to the socket you want to close. 

closeSocket Parameters 

Return 

Code Status 

0 Success. 


Return Code Status

CloseXMLData 

Syntax 

CloseXMLData(xml_data_handle) 



Description 

The CloseXMLData function closes the dynamic array variable for an XML 

document. 

Parameters 



xml_data_handle The name of the XML data file handle created by the OpenXMLData 

function. 

CloseXMLData Parameters 

The return value is one of the following: 

Example 

XML.SUCCESS Success 

XML.ERROR Failure 

XML.INVALID.HANDLE2 Invalid xml_data_handle 

The following example illustrates use of the CloseXMLData function: 

status = CloseXMLData(STUDENT_XML) 

CloseXMLData 1-156

COL1 

Syntax 

COL1( ) 

Description 

The UniBasic COL1 function returns the column position preceding a substring 

found by the FIELD function. The COL1 function has no arguments. If you do not 

execute the FIELD function before executing COL1, the function returns 0. COL1 

supports multibyte languages. 

The FIELD function examines a string for a particular delimiter and returns the 

substring marked by the specified occurrence of that delimiter. While the FIELD 

function returns the substring itself, the COL1 function returns the position preceding 

the substring. 

Example 

In the following example, the FIELD function searches the string STRING for the 

third occurrence of the delimiter “,”. FIELD retrieves the substring “10” in 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() 



COL2, FIELD, INDEX

COL2 

Syntax 

COL2( ) 

Description 

The UniBasic COL2 function returns the column position following a substring 

found by the FIELD function. The COL2 function has no arguments. If you do not 

execute the FIELD before executing COL2, the function returns a zero. COL2 


The FIELD function examines a string for a particular delimiter and returns the 

substring 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. 

Example 

In the following example, the FIELD function searches the string STRING for the 

third occurrence of the delimiter “,”. FIELD assigns the substring “10” 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() 



COL1, FIELD, INDEX 

COL2 1-158

COMMON 

Syntax 

COMMON [/common.name/] var1 [,var2][ARR1]...[,] 

Synonym 

COM 

Description 

The UniBasic COMMON command stores variables that can be accessed from any 

subroutine or program. You can declare one unnamed common area and multiple 

named common areas. The number of variables that a common area can contain 

depends on the virtual memory of your system. For information about virtual 

memory, see Administering UniData on UNIX or Administering UniData on 

Windows Platforms. 

Constraints and Considerations 

Keep the following points in mind when writing programs that use common to pass 

variables: 


Common variables are not passed when you execute CHAIN to another 

UniBasic program. 

Unnamed common is removed when you return to the ECL prompt, but 

named common remains in memory until deleted with the ECL DELETE- 

COMMON command, even if the program aborts. 

COMMON must be the first noncomment statement in the called program. 

CLEARCOMMON sets the common variable to 0. DELETECOMMON 

removes common variables.

Variables in a common area must be declared the same type, dimension, and 

in the same order by all programs accessing them. Programs can declare 

more or fewer variables, and can change the name of the variables. The 

order of the names in a program’s COMMON statement determines which 

names go with which values. 

Common names are limited to a length of seven characters. No error 

message is returned when longer names are truncated during compilation. 

In the following example, STRING2 overwrites STRING1 because both 

names, commons1 and commons2, are truncated to “commons”: 

COMMON commons1 STRING1 

COMMON commons2 STRING2 

COMMON BASICTYPEs 

You can pass variables using common in any BASICTYPE. Here are some notes: 

With BASICTYPEs M and P, use of COMMON is more flexible because in 

these BASICTYPEs no zero element is maintained in arrays. For example, 

two programs declare COMMON, which are described in the following 

table. 

STACKCOMMON defaults to OFF in BASICTYPEs R and U, but is 

always ON in BASICTYPEs P and M. 

You can use the PASSCOM option for compatibility purposes, but its use is 

not needed to pass common variables. 

STACKCOMMON 

First Program Second Program 

Declares COMMON as: 

A,B(5) 

Assigns values of: 

A = 4 and B(3) = 5 

Declares COMMON as: 

U,V,W,X,Y,Z 

Therefore: 

U = 4 and X = 5 

Example Renaming COMMON Variables 

The ECL STACKCOMMON command makes use of common areas more flexible, 

although it requires additional memory. STACKCOMMON settings have the 

following effects: 

COMMON 1-160


If STACKCOMMON is off when one program executes another, the 

contents of unnamed common areas are passed to the executed program and 

back to the executing program. 

If STACKCOMMON is on when one program executes another program, 

the contents of unnamed common areas are not passed to the program you 

execute. Instead, they are saved, and the called program’s unnamed 

common areas are initialized to 0. When control is passed back to the calling 

program, it is restored to its value before the program call. Unnamed 

common areas are never passed to a phantom program. 

Parameters 



/common.name/ Specifies a name for a named common variable. common.name can 

have any valid variable name no longer than seven characters. Default 

(no common name provided) stores the variable in unnamed common. 

var1 A variable to place in the named or unnamed common. 

,var2 A second variable to place in the named or unnamed common areas. 

ARR1 An array to place in the named or unnamed common area. Do not 

declare common arrays with a DIM statement. Arrays in a common 

cannot be dynamically redimensioned. 

, You can enter a COMMON statement on several lines by terminating 

each line to be continued with a comma. 

COMMON Parameters 

Examples 

In the following example, the COMMON statement declares the arrays NAME and 

DATES, and declares the variable DCHANGE in unnamed 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. The comma (,) continuation 

character ends the continued line. 

COMMON /MENU/ X,Y,XDIM,YDIM,S.CHAR 

COMMON /CALC/ RATE(10),AMOUNT(10),DATE1, 

DATE2,LATE 

In the following example, the program segment is invalid because COMMON is not 

the first statement in the called program, and because variables in COMMON cannot 

be reassigned new values in a called program: 

VALUE = 253 

COMMON VALUE,SUBVALUE,ATTRIBUTE 

The following two programs demonstrate passing a variable through common. The 

FIRST_PROG establishes the common variable VAR, and then NEXT_PROG 

declares this variable, adds 1 to it, and prints it. 

FIRST_PROG 

COMMON VAR 

VAR = 1 

PRINT "IN FIRST_PROG" 

PRINT VAR 

CALL NEXT_PROG 

NEXT_PROG 

*Program NEXT_PROG 

COMMON VAR 

PRINT "IN NEXT_PROG" 

VAR = VAR+1 

PRINT VAR 

Here is the output from these programs: 

:RUN BP FIRST_PROG 

IN FIRST_PROG 

1 

IN NEXT_PROG 

2 



CLEAR, CLEARCOMMON 

COMMON 1-162

UniData 

DELETECOMMON, STACKCOMMON – For information, see the UniData 

Commands Reference manual. 


CONTINUE 

Syntax 

CONTINUE 

Description 

The UniBasic CONTINUE command transfers control to the next iteration of a 

FOR/NEXT or LOOP/REPEAT statement. 

Tip: Use CONTINUE instead of GOTO in structured programs. 

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 makes the 

code more difficult to read and maintain. By using CONTINUE, you can clearly 

express the program logic without degrading program structure. 

Example 

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 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 

The preceding code produces the following output: 

I = 1 

I = 2 

I = 3 

... 

I = 8 

CONTINUE 1-164



EXIT 


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. UniBasic compares each character of the replacement 

string expr2 and, if necessary, replaces each character of the target string expr1 on an 

individual basis. UniBasic does not compare and insert strings as a whole. 

CONVERT supports multibyte languages. 

CONVERT can delete characters from a string, but it does not insert additional 

characters. If the replacement substring expr2 contains more characters than are in 

the substring it replaces (expr1), the extra characters are ignored. 

Parameters 


Examples 


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 

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 becomes 34,0,03,35,44. 

NSTRING = "12,0,01,15,22" 

CONVERT "12" TO "34" IN NSTRING 

CONVERT 1-166

In the next example, the program segment converts all occurrences of AC to X, which 

sets NSTRING equal to XBDEFG (notice that C is deleted): 


NSTRING = "ABCDEFG" 

CONVERT "AC" TO "X" IN NSTRING 

In the following example, the replacement string of “F,G” is longer than the string it 

is intended to replace, so the extra characters, “,G”, are ignored. After the conversion, 

NSTRING equals F,C,D,E. 

NSTRING = "A,C,D,E" 

CONVERT "A" TO "F,G" IN NSTRING 



CONVERT function, SWAP

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. UniBasic does not compare and insert strings as a whole. 

CONVERT supports multibyte languages. 

CONVERT can delete characters from a string expression, but it does not insert 

additional characters. If the replacement substring expr2 contains more characters 

than are in the substring it replaces (expr1), the extra characters are ignored. 

Parameters 


Examples 


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 

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) 

CONVERT 1-168

In the next example, the program segment displays 1AA33BB667. Note that the fives 

in X are dropped because no corresponding substitute is provided. 

X = "122334455667" 

PRINT CONVERT("245","AB",X) 

In the following example, Z becomes kakakakaka because the extra character “t” in 

S2 is ignored: 

Y="sasasasasa" 

S1="s" 

S2="kt" 

Z=CONVERT(S1,S2,Y) 

PRINT Z 



CONVERT command, SWAP 


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 0.5. 

COSINE = COS(60) 

In the next example, the program statement prints the cosine of the variable VAL plus 

10: 

PRINT COS(VAL+10) 


ACOS, ASIN, ATAN, COS, SIN, TAN 

COS 1-170

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 

substring 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 str.expr2 is not 

found, the COUNT function returns 0. COUNT supports multibyte languages. 

Note: In BASICTYPEs P and M, after UniData finds str.expr2, it searches the string 

again with the new starting point after the first character of the first occurrence of 

str.expr2. UniData can find overlapping character strings. 

Parameters 



Examples 

In the following example, the program segment searches the string STRING for the 

number of occurrences of the substring II. It returns this number, 2, in the variable IC. 


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 

STRING = "JAWSII,ROCKYIII,STARTREKIV" 

IC = COUNT(STRING,"II")

In the next example, the same program segment compiled under BASICTYPE P or 

M searches the string STRING for the number of occurrences of the substring II and 

assigns that number, 3, to the variable IC. It counts two occurrences of the substring 

II in ROCKYIII. 


STRING = "JAWSII,ROCKYIII,STARTREKIV" 

IC = COUNT(STRING,"II") 

COUNT 1-172

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, expr, 

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.expr is not found, COUNTS returns 0. COUNTS supports multibyte languages. 

Note: In BASICTYPEs P and M, after UniData finds str.expr, it searches the string 

again with the new starting point after the first character of the first occurrence of 

str.expr. UniData can find overlapping character strings. 

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 string STR for the 

number of occurrences of substring I, and returns the answer in the variable IC. After 

execution, IC contains 2}3}1. 

STR = "JAWSII":@VM:"ROCKYIII":@VM:"STARTREKIV" 

IC = COUNTS(STR,"I") 

In the next example, the same program segment compiled under BASICTYPE P or 

M searches the string STR for the number of occurrences of the substring II and 

assigns the values to the variable IC. After execution, IC contains 1}2}0. 


STR = "JAWSII":@VM:"ROCKYIII":@VM:"STARTREKIV" 

IC = COUNTS(STR,"II") 

If the preceding code is compiled in BASICTYPE U or R, COUNTS returns “1}1}0” 

in the variable IC. 

COUNT 1-174

createCertificate 

Syntax 

createCertificate(action, req, signKey, keyPass, CAcert, days, extensions, certOut) 



Description 

The createCertificate function generates a certificate. The certificate can either be a 

self-signed certificate as a root CA that you can use later to sign other certificates, or 

it can be a CA signed certificate. The generated certificate conforms to X509V3 

standard. 

The difference between CA-signing and leaf-CA-signing is that, for CA-signing, the 

resultant certificate can serve as an intermediate CA certificate to sign other certificates, 

while leaf-CA-signing generates certificates that are intended for end user use 

only. 

This function is provided mainly for the purpose of enabling application development 

and testing. As such, the certificate generated contains only a minimum amount of 

information and does not allow any extensions specified by the X509 standard and 

that are supported by many other vendors. It is recommended that you implement a 

complete PKI solution partnered with a reputed PKI solution vendor. 

For detailed information about the createCertificate function, see UniBasic 

Extensions. 


Parameters 



action 1 - Self-signing 

2 - CA-signing 

3 - leaf-CA-signing 

req A string containing the certificate request file name. 

signKey A string containing the private key file name. 

keyPass A string containing the pass phrase to protect the private key. 

CAcert A string containing the CA certificate. 

days The number of days for which the certificate is valid. The default is 365 

days. 

extensions A string containing extension specifications. 

certOut A string containing the generated certificate file. 

createCertificate Parameters 


Return 

Code Status 

0 Success. 

1 Cannot read certificate request file. 

2 Cannot read the key file. 

3 Cannot read the CA certificate file. 

4 Cannot generate the certificate. 


createCertificate 1-176

createCertRequest 

Syntax 

createCertRequest(key, inFormat, keyLoc, algorithm, digest, passPhrase, 

subjectData, outFile, outFormat) 



Description 

The createCertRequest() function generates a PKCS #10 certificate request from a 

private key in PKCS #8 form and a set of user specified data. The request can be sent 

to a CA or used as a parameter to createCertificate() to obtain an X.509 public key 

certificate. 

The certificate request will typically contain the information described in the 

following table. 

Item Description 

Version Defaults to 0. 

The subject data must be provided by the requester through the dynamic array, 

subjectData. It contains @FM separated attributes in the form of “attri=value”. 


Subject The identification data of the certificate holder. This includes, country, 

state/province, locality (city), organization, unit, common name, email 

address, and so forth. 

Public key The key’s algorithm (RSA or DSA) and value. 

Signature The signature of the requester, (signed by the private key). 

Certificate Request Information

The following table describes the commonly used subjectData attributes. 

Item Description Example 

C Country C=US 

ST State ST=Colorado 

L Locality L=Denver 

O Organization O=MyCompany 

OU Organization Unit OU=Sales 

CN Common Name CN=service@mycompany.com 

Email Email Address Email=john.doe@mycompany.com 

subjectData Attributes 

For detailed information about creating a certificate request, see UniBasic 

Extensions. 

Parameters 



key A string containing the key or name of the file storing the key. 

inFormat The key format. 

1 - PEM 

2 - DER 

keyLoc 1 - Put the key into string privKey/pubKey. 

2 - Put the key into a file. 

algorithm 1 - RSA 

2 - DSA 

digest 1 - MD5 

2 - SHA1 

passPhrase A string storing the pass phrase to protect the private key. 

createCertRequest Parameters 

createCertRequest 1-178




subjectData The identification information of the requester. 

outFile A string containing the path name of the file where the certificate request 

is stored. 

outFormat The generated certificate format. 

1 - PEM 

2 - DER 

Return 

Code Status 

0 Success. 

createCertRequest Parameters (continued) 

1 Private key file cannot be opened. 

2 Unrecognized key or certificate format. 

3 Unrecognized key type. 

4 Unrecognized encryption algorithm. 

5 Unrecognized key (corrupted key or algorithm mismatch). 

6 Invalid pass phrase. 

7 Invalid subject data (illegal format or unrecognized attribute, 

etc.). 

8 Invalid digest algorithm. 

9 Output file cannot be created. 

99 Cert Request cannot be generated. 

Return Code Status

createRequest 

Syntax 

createRequest(URL, http_method, request_handle) 



Description 

The createRequest function creates an HTTP request and returns a handle to the 

request. 

Parameters 


Parameter Option 

URL A string containing the URL for a resource on a web server. An 

accepted URL must follow the specified syntax defined in RFC 1738. 

The general format is: http://:/?. 

The host can be either a name string or IP address. The port is the port 

number to which you want to connect, which usually defaults to 80 and 

is often omitted, along with the preceding colon. The path tells the web 

server which file you want, and, if omitted, means “home page” for the 

system. The searchpart can be used to send additional information to a 

web server. 

http_method A string which indicates the method to be performed on the resource. 

See the table below for the available (case-sensitive) methods. 

request_handle A handle to the request object. 

createRequest Parameters 

createRequest 1-180

The following table describes the available methods for http_method. 

Method Description 


GET Retrieves whatever information, in the form of an entity, identified 

by the Request-URI. If the Request-URI refers to a data-producing 

process, it is the produced data which shall be returned as the entity 

in the response and not the source text of the process, unless that 

text happens to be the output of the process. 

POST [:] For this method, it can also have an optional MIME-type 

to indicate the content type of the data the request intends to send. If no 

MIME-type is given, the default content type will be “application/x-wwwform-urlencoded”. 

Currently, only “multipart/form-data” is internally 

supported, as described in function addRequestParameter() and 

submitRequest(), although other “multipart/* data can also be sent if the 

user can assemble it on his/her own. (The multipart/form-data format itself 

is thoroughly described in RFC 2388). 

HEAD The HEAD method is identical to GET except that the server 

MUST NOT return a message-body in the response. The metainformation 

contained in the HTTP headers in response to a HEAD 

request SHOULD be identical to the information sent in response to 

a GET request. This method can be used for obtaining 

metainformation about the entity implied by the request without 

transferring the entity-body itself. This method is often used for 

testing hypertext links for validity, accessibility, and recent modification. 

OPTIONS The OPTIONS method represents a request for information about 

the communication options available on the request/response chain 

identified by the Request-URI. This method allows the client to 

determine the options and/or requirements associated with a 

resource, or the capabilities of a server, without implying a resource 

action or initiating a resource retrieval. HTTP 1.1 and later. 

DELETE The DELETE method requests that the origin server delete the 

resource identified by the Request-URI. HTTP 1.1 and later. 

createRequest Methods


TRACE The TRACE method is used to invoke a remote, application-layer 

loop- back of the request message. HTTP 1.1 and later. 

PUT The PUT method requests that the enclosed entity be stored under 

the supplied Request-URI. HTTP 1.1 and later but not supported. 

CONNECT /* HTTP/1.1 and later but not supported */ 


Return 

Code Status 

0 Success. 

createRequest Methods (continued) 

1 Invalid URL (Syntactically). 

2 Invalid method (For HTTP 1.0, only GET/POST/HEAD) 


Note: If URL does include a searchpart, it must be in its encoded format (space is 

converted into +, and other non-alphanumeric characters are converted into %HH 

format. See addRequestParameter() for more details). However, host and path are 

allowed to have these “unsafe” characters. UniBasic will encode them before 

communicating with the web server. 

This function can also be used later to support other protocols (like FTP, in which 

case the URL supplied would be in the form of: 

ftp://:@:/cwd1/.../cwdN>/;type= . The http_method option would be ignored for an FTP request. 

createRequest 1-182

createSecureRequest 

Syntax 

createSecureRequest(URL, http_method, request_handle, security_context) 

Description 

The createSecureRequest function behaves exactly the same as the 

createRequest() function, except for the fourth parameter, a handle to a security 

context, which is used to associate the security context with the request. If the URL 

does not start with “https” the parameter is ignored. If the URL starts with “https” but 

an invalid context handle or no handle is provided, the function aborts and returns 

with an error status. 

Parameters 




URL A string containing the URL for a resource on a web server. An 

accepted URL must follow the specified syntax defined in RFC 

1738. The general format is: 

http://:/?. The host can be either a 

name string or IP address. The port is the port number to connect to, 

which usually defaults to 80 and is often omitted, along with the preceding 

colon. The path tells the web server which file you want, and, 

if omitted, means “home page” for the system. The searchpart can be 

used to send additional information to a web server. 

http_method A string which indicates the method to be performed on the resource. 

See the table below for the available (case-sensitive) methods. 

request_handle A handle to the request object. 

securityContext A handle to the security context. 

createSecureRequest Parameters

The following table describes the available methods for http_method. 


GET Retrieves whatever information, in the form of an entity, identified 

by the Request-URI. If the Request-URI refers to a data-producing 

process, it is the produced data which shall be returned as the entity 

in the response and not the source text of the process, unless that 

text happens to be the output of the process. 

POST [:] For this method, it can also have an optional MIME-type 

to indicate the content type of the data the request intends to send. If no 

MIME-type is given, the default content type will be “application/x-wwwform-urlencoded”. 

Currently, only “multipart/form-data” is internally 

supported, as described in function addRequestParameter() and 

submitRequest(), although other “multipart/* data can also be sent if the 

user can assemble it on his/her own. (The multipart/form-data format itself 

is thoroughly described in RFC 2388). 

HEAD The HEAD method is identical to GET except that the server 

MUST NOT return a message-body in the response. The metainformation 

contained in the HTTP headers in response to a HEAD 

request SHOULD be identical to the information sent in response to 

a GET request. This method can be used for obtaining 

metainformation about the entity implied by the request without 

transferring the entity-body itself. This method is often used for 

testing hypertext links for validity, accessibility, and recent modification. 

OPTIONS The OPTIONS method represents a request for information about 

the communication options available on the request/response chain 

identified by the Request-URI. This method allows the client to 

determine the options and/or requirements associated with a 

resource, or the capabilities of a server, without implying a resource 

action or initiating a resource retrieval. HTTP 1.1 and later. 

DELETE The DELETE method requests that the origin server delete the 

resource identified by the Request-URI. HTTP 1.1 and later. 

createRequest Methods 

createSecureRequest 1-184



Note: If URL does include a searchpart, it must be in its encoded format (space is 

converted into +, and other non-alphanumeric characters are converted into %HH 

format. See addRequestParameter() for more details). However, host and path are 

allowed to have these “unsafe” characters. UniBasic will encode them before 

communicating with the web server. 


TRACE The TRACE method is used to invoke a remote, application-layer 

loop- back of the request message. HTTP 1.1 and later. 

PUT The PUT method requests that the enclosed entity be stored under 

the supplied Request-URI. HTTP 1.1 and later but not supported. 

CONNECT /* HTTP/1.1 and later but not supported */ 

createRequest Methods (continued) 


0 Success. 

1 Invalid URL (Syntactically). 

2 Invalid method (For HTTP 1.0, only 

GET/POST/HEAD) 

Return Code Status

createSecurityContext 

Syntax 

createSecurityContext(context, version) 



Description 

The createSecurityContext function creates a security context and returns a handle 

to the context. 

A security context is a data structure that holds all aspects of security characteristics 

that the application intends to associate with a secured connection. Specifically, the 

following information may be held for each context: 

Protocol version 

Sender’s certificate to be sent to the peer 

Issuer’s certificate or certificate chain to be used to authenticate incoming 

certificate 

Certificate verification depth 

Certificate Revocation List 

Sender’s private key for signature and key exchange 

Flag to perform client authentication (useful for server socket only) 

Context ID and time stamp 

For detailed information about the createSecurityContext function, see UniBasic 

Extensions. 

createSecurityContext 1-186

Parameters 





context The security context handle. 

version A string with the following values: SSLv2, SSLv3 or TLSv1. 

createSecurityContext Parameters 

Return 

Code Status 

0 Success. 

1 Security context could not be created. 

2 Invalid version. 

Return Code Status

CRT 

Syntax 

CRT [print.expr] 

Synonym 

DISPLAY 

Description 

The UniBasic CRT command sends output to the display terminal regardless of the 

use of the PRINTER ON/OFF command. print.expr can consist of any of the 

following: 

String data. 

Any number of strings or numeric variables. 

UniBasic functions. 

Tip: Use the UniBasic @ function before the CRT command to position the cursor on 

the screen or execute other terminal functions before printing to the terminal. 

Set UDT.OPTIONS 5 on if you want the display to pause at the end of each page. For 

information about UDT.OPTIONS, see the UDT.OPTIONS Commands Reference. 

To suppress the line feed at the end of displayed text, end the CRT or DISPLAY 

statement with a colon. 

createSecurityContext 1-188

DATA 

Syntax 

DATA expr1 [,expr2]... 

Description 

The UniBasic DATA command places data in an input queue stored in @DATA. 

ASCII character 013 (CR) delimits elements in the queue. Each subsequent INPUT 

statement reads one element. @DATA is read-only. For more information about @ 

variables, see Appendix B, “UniBasic@variables.” 

The expressions (expr1 and expr2) can be literal strings or variables. You can 

continue DATA statements over several lines by placing a comma at the end of each 

line to be continued. 

UniData places data in the queue in order of execution of DATA commands. The 

queue processes on a first-in, first-out basis. When the input queue is empty, UniData 

requests input from the terminal. The input queue remains available through program 

CHAIN and EXECUTE operations, but is cleared when control returns to the 

UniData ECL prompt (:). 

Tip: You can load inline prompts in paragraphs with the DATA command. For 

instructions, see the UniData Commands Reference. 

Example 

In the following example, the program segment executes a DATA statement 

containing 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

DATE 

Syntax 

DATE( ) 

Description 

The UniBasic DATE function returns the current system date in internal format. 

Internal format is the number of days after December 31, 1967. 

Example 

The following statement prints the current system date in external format: 

PRINT OCONV(DATE(),"D") 



ICONV Date (D), OCONV Date (D), TIMEDATE 

DATE 1-188

DBTOXML 

Syntax 

DBTOXML(xml_document, doc_location, u2xmap_file, u2xmap_location, 

condition, status) 

Description 

Creates an XML document from the UniData database. 

Parameters 

The following table describes each parameter of the syntax.T 



xml_document The name of the XML document to create. 

doc_flag A flag defining the type of xml_document. Valid values are: 

? XML.FROM.FILE - xml_document is a file name. 

? XML.FROM.STRING -xml_document is the name of 

variable containing the XML document. 

u2xmap_file The name of the U2XMAP file to use to produce the XML 

document. 

u2xmap_location The location of the U2XMAP file. 

? XML.FROM.FILE - u2xmap_file is a file name. 

? XML.FROM.STRING - is u2xmap_file the name of variable 

containing the mapping rules. 

condition A query condition for selecting data from the UniData 

file, for example, WHERE SCHOOL = "CO002" 

Status XML.SUCCESS or XML.FAILURE. 

DBTOXML Parameters

Note: The XML options set previously at the session level through the 

XMLSETOPTIONS command or through the XMLSetOptions() API are used when 

you run the DBTOXML API in the current UniData session. 

DBTOXML 1-190

DCOUNT 

Syntax 

DCOUNT(str,delim) 

Description 

The UniBasic DCOUNT function returns the number of substrings delimited by 

delim in a string. If str is an empty string, UniData returns 0. If str contains data but 

no delimiter, UniData returns 1. DCOUNT supports multibyte languages. 

Parameters 


Paramete 

r Description 

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 1 because no delimiter is found in 

the string: 

STR = 123 

DCOUNT(STR,@VM) 

PRINT SUBS 


str Specifies the string to search for occurrences of substrings delimited by delim. 

delim Specifies the delimiter to use in searching str. 

DCOUNT Parameters

The following example prints 3: 

STR="A/B/C" 

PRINT DCOUNT(STR,"/") 



COUNT, COUNTS 

DCOUNT 1-192

DEACTIVATEKEY 

Syntax 

DEACTIVATEKEY , [ON ] [ON ERROR 

] 

Description 

Use the DEACTIVATEKEY command to deactivate a key or a wallet. This command 

is useful to deactivate keys to make your system more secure. 

Note: You can deactivate only keys with password protection with this command. 

Keys that do not have password protection are automatically activated and cannot be 

deactivated. 

Parameters 




key.id The key ID or wallet ID to deactivate. If you provide a Wallet ID, 

UniData deactivates all keys in the wallet. 

DEACTIVATEKEY Parameters


password The password corresponding to key.id. 

ON NFA_SERVER The name of the NFA_SERVER on which you want to 

deactivate the encryption key. The syntax for NFA_SERVER 

can be either: 

@domain.var where domain.var specifies the ID for a VOC 

entry that contains the NFA server connection parameters. 

OR 

“MACHINE PORT [, UDTHOME 

]” 

NFA files are always encrypted and decrypted on the remote 

machine by the NFA server. 




STATUS Codes 

The DEACTIVATEKEY statement rerurns the following STATUS codes regarding 

wallet operations: 

STATUS 

Code 

DEACTIVATEKEY Parameters (continued) 

Description 

0 Operation successful 

1 Key is already activated or deactivated. This applies to a single key, not 

a wallet operation 

2 Operation failed. This applies to a single key, not a wallet operation 

3 Invalid wallet ID or password 

4 No access to wallet 

DEACTIVATEKEY STATUS Codes 

DEACTIVATEKEY 1-194

STATUS 

Code 

Example 

The following example illustrates deactivating an encryption key: 


Description 

5 Invalid key ID or password 

6 No access to one of the keys in the wallet 

9 Other error 

DEACTIVATEKEY STATUS Codes (continued) 

DEACTIVATEKEY "test","myunidata" ON ERROR PRINT "Unable to deactivate key"

DEBUG 

Syntax 

DEBUG 

Description 

The UniBasic DEBUG command stops program execution, turns control over to the 

interactive UniBasic debugger, and then displays the debugger prompt (!). Pressing 

the interrupt key also gives control to the debugger. For information about the 

UniBasic debugger, see Using the UniBasic Debugger. 

To use the DEBUG command to display the contents of variables, you must compile 

the program with the D option. 

Note: 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 about UDT.OPTIONS, see the UDT.OPTIONS 


When you enter the debugger, a message similar to the following displays, and the 

cursor is placed at the debugger prompt: 

DEBUGGER called before line 1 of program BP/TEST 

! 



ABORT 

UniData 

BASIC, DEBUG.FLAG, DEBUGLINE.ATT, DEBUGLINE.DET, ON.ABORT, 

RUN, SETDEBUGLINE, UNSETDEBUGLINE – For information, see the UniData 


DEBUG 1-196

DEFFUN 

Syntax 

DEFFUN function.name [([MAT] arg.1[,[MAT]arg.2]...)] 

[CALLING catalog.name] 

Description 

The UniBasic DEFFUN command declares a user-written function, making the 

function available in a UniBasic program. You must declare the function before you 

can use it in a program. 

Note: You also must define the function with the UniBasic FUNCTION command in 

a separately cataloged file before you can call it. 

Function Naming 

The function name used in the DEFFUN statement must be the same as the name of 

the cataloged file that contains the FUNCTION statement. Either of the following 

statements declares the function cataloged under the name func.name: 


DEFFUN func.name(arg, arg,...) 

DEFFUN name(arg, arg,...) CALLING func.name 

Within the calling program, the name used in the DEFFUN statement and the name 

used to call the function must be the same. This does not need to be the same name 

as the cataloged program file or the name used in the FUNCTION statement.

Parameters 



function.name Specifies the function name that the calling statement uses in 

this program. 

(MAT arg.1 ,MAT 

arg.2...) 

Examples 

Specifies the arguments to be passed to the function. You must 

enclose arguments in parentheses and separate them with 

commas. Precede an argument with MAT to indicate that the 

argument is an array. 

CALLING file.name Specifies the function’s cataloged file name. Include this 

statement if the cataloged program name differs from 

function.name. Can be a literal or variable. 

DEFFUN Parameters 

The DEFFUN statement in the following example declares myfunc. The CALLING 

clause indicates that the name of the cataloged file that contains the FUNCTION 

statement is called yourfunc. In the first print statement, the function is called and the 

return value is printed. 

DEFFUN myfunc(a, MAT b, c) CALLING "yourfunc" ;* Declare function. 

DIM b(10) ;* Define array. 

a = 2 ;* Set upper bound. 

FOR i = 1 TO a ;* Initialize array. 

b(i) = i 

NEXT i 

PRINT "r from FUNCTION: ":myfunc(a, MAT b, c) 

PRINT "c from FUNCTION: ":c 

DEFFUN 1-198

The preceding program calls the following function. The name of this cataloged file 

is yourfunc. This is the name that must match the DEFFUN statement in the program 

above. Notice that the function definition uses yet another name for the function 

(anotherfunc). 


FUNCTION anotherfunc(a, MAT b, c) ;* Start function 

definition. 

DIM b(-1) ;* Declare array. 

r = 0 ;* Initialize return value. 

c = 1 ;* Initialize value passed 

back. 

FOR i = 1 TO a ;* To the upper bound passed 

in: 

r += b(i) ;* Sum array members. 

c *= b(i) ;* Multiply array members. 

NEXT i 

RETURN r ;* Return value. 

The following screen example shows the command that runs the program and the 

output from the program: 

:RUN BP FUNCTION.CALL 

r from FUNCTION: 3 

c from FUNCTION: 2 

The following example calls a user-defined 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 



FUNCTION

DEL 

Syntax 

DEL dyn.array.var 

Description 

The UniBasic DEL command deletes an attribute, value, or subvalue from a dynamic 

array. The corresponding delimiter is also removed. 

The DELETE function and the DEL command perform the same action. 

Warning: DEL destroys the data and the corresponding delimiters. Use the DEL 

command with caution. 

Parameters 



dyn.array.var Specifies the dynamic array on which to perform the delete operation. 

attrib.expr Specifies which attribute of the dynamic array to delete. If val.expr is 

omitted, DEL deletes the entire attribute, including all values and 

subvalues. 

,val.expr Specifies which value of the dynamic array attribute to delete. If 

subval.expr 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 

DEL 1-200

Examples 

The following program segment is taken from “Appendix A, Sample Program” of 

Developing UniBasic Applications. It deletes the attribute in the variable POSITION. 

This removes one order for a particular client from the CLIENTS file in the demo 

database. 


DELETE_RECORD: 

* (Assuming the order #'s are on line 12) 

READVU ORDER_LINE FROM CLIENT_FILE,CLIENT_NUMBER,12 THEN 

LOCATE ORDER_NUMBER IN ORDER_LINE SETTING POSITION THEN 

DEL ORDER_LINE 

END 

In the following example, the program segment deletes the third attribute of the 

dynamic array ARRAY1. The attribute removed is ‘Anne’. 

ARRAY1 = '#543':@AM:'Dorothy':@AM:'Anne':@AM:'Parker' 

DEL ARRAY1 

In the following example, the statement is invalid. The DEL statement has too many 

parameters: 

ARRAY1 = '#543':@AM:'Dorothy':@AM:'Anne':@AM:'Parker' 

DEL ARRAY 



DELETE, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS

DELETE 

Syntax 

DELETE [file.var,] record.ID.expr [ON ERROR statements] 

Description 

The UniBasic DELETE command deletes a record from a UniData file. In addition, 

the DELETE command releases any locks on the record that have been set by 

previous commands. 

Note: The DELETEU command also deletes a record, but it does not release locks. 

This is the only difference between DELETE and DELETEU statements. 

UniBasic locks are advisory only. For more information,see Developing UniBasic 

Applications. 

Parameters 



file.var Specifies the file from which to delete the record. 

If you do not specify a file.var, UniData reads from the default 

file. If no default file is open, a fatal DELETE error occurs. 



record.ID.expr Specifies the record to delete. 

ON ERROR statements Specifies UniBasic statements to execute if the DELETE 

statement fails because UniData 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 

DELETE 1-202

Examples 

The following program statement eliminates the record with the ID of PEANUT from 

the default file: 

DELETE "PEANUT" 

The following 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 

The following statement is invalid because the file variable is specified incorrectly in 

the DELETE statement: 


OPEN 'CUSTOMER' TO CUST ELSE STOP 'NO CUST' 

DELETE CUSTOMER, C.ID 

The following program segment is taken from “Appendix A, Sample Program” of 

Developing UniBasic Applications. The DELETE command deletes the record in the 

ORDERS file after the corresponding attribute is deleted from the CLIENTS file. 

Both steps are necessary to remove the order record itself, and to remove the 

reference to the order in the client record (the attribute in the CLIENTS file). 






END 

WRITEV ORDER_LINE ON CLIENT_FILE, CLIENT_NUMBER, 12 

END 

* 

DELETE ORDERS_FILE, ORDER_NUMBER 

RELEASE CLIENT_FILE,CLIENT_NUMBER 

RETURN 



DEL, DELETE, DELETEU

DELETE 

Syntax 

DELETE(dyn.array, attrib.expr[,val.expr [,subval.expr]]) 

Description 

The UniBasic DELETE function deletes an attribute, value, or subvalue from a 

dynamic array. The corresponding delimiter is also removed. 

The DELETE function and the DEL command perform the same action. 

Parameters 



dyn.array.var Specifies the dynamic array from which to delete. 

attrib.expr Specifies which attribute of the dynamic array to delete. If val.expr is 

omitted, DELETE deletes the entire attribute, including all values and 

subvalues. 

,val.expr Specifies which value of the dynamic array attribute to delete. If 

subval.expr is omitted, DELETE deletes the entire value, including all 

subvalues. 

,subval.expr Specifies which subvalue of the dynamic array attribute value to delete. 

DELETE Parameters 

Examples 

In this 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) 

DELETE 1-204

In the next example, the program statement removes the first subvalue of the first 

value of the second attribute in ARRAY. The modified array is assigned to ARRAY2. 

ARRAY2=DELETE(ARRAY,2,1,1) 

In the next example, the program segment deletes the third attribute, including A, B, 

and C: 


ARRAY = 1:@AM:2:@AM:'A':@VM:'B':@VM:'C' 

ARRAY = DELETE(ARRAY,3,0,0) 



DEL, DELETE, DELETEU

DELETELIST 

Syntax 

DELETELIST list.name.expr 

Description 

The UniBasic DELETELIST command deletes a saved select list. 

Select lists are saved by the UniQuery SAVE.LIST command and the UniBasic 

WRITELIST command. 

list.name.expr is the name of the saved list to be deleted. If the list you specify cannot 

be found, UniData displays an error message and takes no action. 

Example 

The following statement deletes the saved list CUST in the current account: 

DELETELIST "CUST" 



FORMLIST, READLIST, SELECT, SELECTINDEX, SELECTINFO, 

WRITELIST 

UniQuery 

DELETE.LIST, GET.LIST, SAVE.LIST, SELECT, SSELECT – For information, see 

the UniQuery Commands Reference. 

DELETELIST 1-206

UniData SQL 

SELECT – For information, see the UniData SQL Commands Reference. 


DELETEU 

Syntax 

DELETEU [file.var,] record.ID.expr [ON ERROR statements] 

Description 

The UniBasic DELETEU command deletes the specified record from a UniData file. 

The DELETEU command retains record locks that were set by the same user process. 

This allows UniData to delete a record and re-create it while retaining a lock on it. 

Note: The DELETE command also deletes a record, but it releases locks. This is the 

only difference between DELETE and DELETEU statements. 

UniBasic locks are advisory only. For information about UniData file and record 

locks, see Developing UniBasic Applications. 

Parameters 



file.var, Specifies the file from which to delete the record. 


file. If no default file is open, a fatal DELETE error occurs. 



record.ID.expr Specifies the record to delete. 

ON ERROR statements Specifies UniBasic statements to execute if the DELETE 

statement fails because UniData 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 

DELETEU 1-208

Examples 

In the following example, the statement eliminates the record with the record ID of 

JONES from the most recently opened default file: 

DELETEU "JONES" 

The following segment deletes the record. The record ID is stored in the variable 

DEL_ID. The file was opened to the variable DISCOUNT. 

DEL_ID = "ACTION_FILMS" 

DELETEU DISCOUNT, DEL_ID 



DEL, DELETE, DELETE function, RELEASE 


DIM 

Syntax 

DIM name1(rows[,cols]) [,name2(rows[,cols])]... 

Synonym 

DIMENSION 

Description 

The UniBasic DIM command creates and determines the dimensions of a dimensioned 

array. You can specify arrays with one dimension (rows) or two dimensions 

(rows or rows, cols). In addition, the following limitations apply: 

You must dimension any array before you use it within a program. 

Zero elements other than 0,0 (such as 0,5 or 1,0) are invalid. 

The maximum number of elements you can specify is based on the total 

amount of virtual memory available on your system. 

Arrays passed to a subroutine cannot be redimensioned within the 

subroutine. 

For information about system configurations, see Administering UniData on UNIX 

or Administering UniData on Windows Platforms. 

MATREAD, MATWRITE, and MATPARSE load and empty an array from left to 

right and from top to bottom beginning with element 1,1 and ending by placing 

excess data in element 0,0. 

Note: BASICTYPEs M and P do not support position 0,0 in arrays. You could lose 

data if an array is too small for the amount of data you are attempting to load into it 

with MATPARSE. 

DIM 1-210

Parameters 


Paramete 

r Description 

INMAT Function Return Values 

After you execute DIM, the UniBasic INMAT function returns one of the values 

described in the following table. 

Resizing Arrays 

You can use the DIM statement to dynamically redimension an array without losing 

any data if the size of the redimensioned array is large enough to contain all data in 

the original array. When you redimension, UniBasic places the old data elements into 

the new array from left to right and from top to bottom. All leftover data is placed in 

the 0,0 element. 


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. If cols is omitted, the array is 

one-dimensional. 

DIM Parameters 

Value Description 

0 The dimensioned array was not created. UniData returns an error message, but 

program execution continues. 

1 Memory was insufficient to create the dimensioned array. UniData returns an error 

message, but program execution continues. 

n The dimensioned array was created. n is the number of elements in the array. 

INMAT Function Return Values

Although you can change the size of an array during program execution, its configuration 

cannot change. For example, a two-dimensional array cannot be changed to 

one-dimensional and vice versa. 

Examples 

In the following example, the program statement creates three arrays: one-dimensional 

NAME, one-dimensional TITLES, and two-dimensional DATES. 

DIM NAME(100),TITLES(100),DATES(100,2) 

In the next example, two DIMENSION statements are included in the same program, 

although because the new array is smaller than the original, all excess data is placed 

in element 0,0. After the execution of the second DIMENSION statement, the array 

has the dimension of 100 by 10. 

DIM WAGES(50,100) 

DIM WAGES(100,10) 

The following program segment creates the array TEST by setting variable A to 30, 

and then declaring TEST as a one-dimensional array of 30 elements: 

A = 30 

DIM TEST (A) 

The following sample code is invalid because array size is declared with nonnumeric 

variables “(” and “)” and because you cannot use a variable in a dimension statement: 

TEST = "(10,5)" 

DIM TEST 

In contrast, the following statement is valid: 

DIM TEST (10,5) 



INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, 

MATREADU, MATWRITE, MATWRITEU 

DIM 1-212

DIGEST 

Syntax 

DIGEST(algorithm, data, dataLoc, result) 

Description 

The DIGEST function generates a message digest of supplied data. A message digest 

is the result of a one-way hash function (digest algorithm) performed on the message. 

Message digest has the unique properties that alight change in the input results in a 

significant difference in the resulting digest. Therefore, the probability of two 

different messages resulting in the same digest (collision) is very unlikely. It is also 

virtually impossible to reverse to the original message from a digest. Message digest 

is widely used for digital signatures and other purposes. 

The desired digest algorithm is specified in algorithm. You specify data and its 

location are with data and dataLoc, respectively. UniData puts the arrived digest into 

a dynamic array in result. Since digest is short and has a fixed length, it is always put 

into a string, and no file option is provided. The result can be in either binary or hex 

format. 


Parameters 



algorithm A string containing the digest algorithm name (uppercase or lowercase). 

UniData supports the following algorithms: 

“md2” 

“md4” 

“md5” 

“mdc2” 

“rmd160” 

“sha” 

“sha1” 

data Data or the name of the file containing the data to be digested. 

dataLoc 1 - Data in a string 

2 - Data in a file 

result A string to store the digest result. 

DIGEST Parameters 


Return 

Code Status 

0 Success 

1 Unsupported digest algorithm 

2 The data file cannot be read 

3 Message digest cannot be obtained 

4 Invalid parameters 


DIGEST 1-214

DIR 

Syntax 

DIR(file.expr) 

Description 

The UniBasic DIR function returns the file size (in bytes), the last date and time the 

file was modified (in internal format), and the privileges for the file. UniData stores 

these values in the first four attributes of the return value. file.expr must evaluate to 

a file name at the operating system level. If you do not specify a path, UniData 

searches the current directory. 

Example 

The following UNIX program segment retrieves the file statistics on the UniData 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. UniData stores the second and 

third attributes in internal format, and the example converts them to the external 

format. 


FILESTAT = DIR("/usr/accounting/gl") 

SIZE = FILESTAT 

DATE.MOD = OCONV(FILESTAT,'D2/') 

TIME.MOD = OCONV(FILESTAT,'MT') 

PRINT 'The gl file is ':SIZE 

PRINT 'And was last modified: ':DATE.MOD,TIME.MOD

DISABLEDEC 

Syntax 

DISABLEDEC [, ], [ON ERROR 

] 

Description 

Use the DISABLEDEC command to turn off decryption on a file or fields you 

specify. 

Parameters 



filename The name of the file on which you want to disable decryption. 

field_list A comma-separated list of fields for which you want to disable 

decryption. Do not enter spaces between the field names. 




DISABLEDEC Parameters 

DIR 1-216

STATUS Codes 

DISABLEDEC has the following STATUS codes: 

STATUS 

Code Description 

Example 

The following example illustrates disabling decryption on two fields in a file using a 

quoted string: 


0 No error, operation successful 

1 Decryption is already disabled 

2 General operation failure, such as an open file error 

3 File is not an encrypted file 

4 Attempting operation on a WHOLERECORD encrypted file 

5 Field(s) is not an encrypted field 

6 Cannot locate information to disable decryption 

7 Field is not a valid field in this file 

DISABLEDEC STATUS Codes 

DISABLEDEC "CUSTOMER","NAME,PHONE" ON ERROR PRINT "Unable to disable 

decryption 

The next example illustrates disabling decryption on two fields using variables: 

CUST="CUSTOMER" 

FIELDS="NAME,PHONE" 

DISABLEDEC CUST,FIELDS ON ERROR PRINT "Unable to disable decryption"

DISPLAY 

DISPLAY is a synonym for the CRT command. For further information, see CRT. 

Synonym 

CRT 

DISPLAY 1-218

DISPLAYWIDTH 

Syntax 

DISPLAYWIDTH (string) 

Description 

The UniBasic DISPLAYWIDTH function returns the number of bytes needed to 

display a string expression. For instance, the display width of English characters is 

one. In languages that use multibyte characters, the display width of a character can 

be 1, 2, 3, or 4 bytes, depending on the language and the character. 

Example 

The following illustration shows a string that indicates below each “character” the 

number of bytes required to display that character. The string contains eight bytes. 

Therefore, DISPLAYWIDTH would return 8 for this string. 

Number 

of bytes 



BYTELEN, CHARLEN, ISMB, LEN, MBLEN 


2 3 1 2

DOWNCASE 

Syntax 

DOWNCASE(str.expr) 

Description 

The UniBasic DOWNCASE function converts all characters in a string (str.expr) to 

lowercase. Special characters, including the null value, are not converted by this 

function. DOWNCASE does not convert multibyte characters. 

Example 

In the following example, the program segment converts the contents of the variable 

USTRING to lowercase letters: 

USTRING = "WHY am I HAPPY?" 

DSTRING = DOWNCASE(USTRING) 

DSTRING now contains “why am i happy?”. 



ICONV Masked Character (MC), OCONV Masked Character (MC), UPCASE 

DOWNCASE 1-220

DQUOTE 

DQUOTE is a synonym for the QUOTE function. For more information, see 

QUOTE. 

Synonym 

QUOTE 


DROUND 

Syntax 

DROUND(val.expr [,precision.expr]) 

Description 

The UniBasic DROUND function performs double-precision rounding on a value. 

Double-precision rounding uses two words to store a number, accommodating a 

larger number than in single-precision rounding, which stores each number in a 

single word. 

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 Specifies the precision for the rounding. The valid range is 0 to 14. 

Default precision is four places. 

DROUND Parameters 

Example 

In the following example, the DROUND statement results in 18.84955596. The 

equation is resolved, and then the result is rounded to eight decimal places. 

A= DROUND((3.14159265999*2*3),8) 

PRINT A 

DROUND 1-222



PRECISION 

UniData 

FLOAT.PRECISION – For information, see the UniData Commands Reference. 


EBCDIC 

Syntax 

EBCDIC(expr) 

Description 

The UniBasic EBCDIC (Extended Binary Coded Decimal Information Code) 

function converts the ASCII (American Standard Code for Information Interchange) 

data in expr to its corresponding EBCDIC values. 

Note: BASICTYPE U, the standard application, converts data to EBCDIC format 

before the data is written to tape. 

Example 

In the following example, the program statement first prints a message, and then 

prints the EBCDIC equivalent of the ASCII variable VAL: 

PRINT "EBCDIC equivalent":EBCDIC(VAL) 



ASCII, CHAR, CHARS, SEQ 

EBCDIC 1-217

ECHO 

Syntax 

ECHO [ON | OFF | expr] 

Description 

The UniBasic ECHO command controls whether characters display on the terminal 

screen as you type them on the keyboard. 

Tip: Use ECHO for security purposes when the entry of an ID or password should 

not display on the terminal screen. 

Parameters 



Example 

The following program segment enables echoing because A+B is not 0: 

A = 1 

B = 3 

ECHO A+B 


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 expr is 0, ECHO is set to OFF. When expr is not 0, ECHO is set to 

ON. expr must be numeric. 

ECHO Parameters

EDADRV_Cleanup 

Syntax 

RETCODE EDADRV_Cleanup 

Description 

This is the last function that EDA calls. This function frees all allocated memory and 

all handles to the external database, closes all files, and frees the driver environment. 

Return Codes 

The following table describes the EDADRV_Cleanup return codes. 

Return 

Code Error Description 

0 N/A Successful. 

EDADRV_Cleanup Return Codes 

EDADRV_Cleanup 1-219

EDADRV_CloseStmt 

Syntax 

RETCODE EDADRV_CloseStmt(stmthdl) 

Description 

Once a cursor is opened by the execution of the EDADRV_ExecuteStmt function, it 

remains open even after all the rows have been fetched. The 

EDADRV_CloseStatement closes any open cursors associated with the statement 

handle. 

Warning: The result buffer allocated by the EDADRV_FetchStmt function should not 

be freed by this function, it can only be freed by the EDADRV_FreeResult function. 

Input Variable 

The following table describes the input parameter. 


Type Argument Description 

EDA_T_STMT_HDL stmthdl 

EDADRV_CloseStmt 

Statement handle.

Return Codes 

The following table describes the EDADRV_CloseStmt return codes. 

Return 



1 EDADRV_ERR_SYSTEM External system error. 

103 EDADRV_INVALID_STMT_ID Invalid statement handle. 

EDADRV_CloseStmt Return Codes 

EDADRV_CloseStmt 1-221

EDADRV_Connect 

Syntax 

RETCODE EDADRV_Connect(connhdl,datasource,login_name,password) 

Description 

The EDADRV_Connect function makes a connection to an external database. 

Input Variables 

The following table describes the input variables. 

Output Variable 

The following table describes the output variable. 



char * datasource The name of the data source. 

char * login_name The user login name. 

char * password The password corresponding to the login name. 

EDADRV_Connect Input Variables 


EDA_T_CONN_HDL * connhdl The connection handle. 

EDADRV_Connect Output Variable

Return Codes 

The following table describes the EDADRV_Connect return codes. 

Return 




101 EDADRV_ERR_MEMORY Internal memory allocation error. 

EDADRV_Connect Return Codes 

EDADRV_Connect 1-223

EDADRV_Disconnect 

Syntax 

RETCODE EDADRV_Disconnect(connhdl) 

Description 

The EDADRV_Disconnect function disconnects from an external database and 

releases the connection handle. 


The following table describes the input variable. 

Return Codes 

The following table describes the EDADRV_Disconnect return codes. 



EDA_T_CONN_HDL connhdl The connection handle. 

EDADRV_Disconnect Input Variable 

Return 




102 EDADRV_INVALID_CONN_ID Invalid connection handle. 

EDADRV_Disconnect Return Codes

EDADRV_DropStmt 

Syntax 

RETCODE EDADRV_DropStmt(stmthdl) 

Description 

The EDADRV_DropStmt function closes any open cursors associated with the 

statement handle and makes the SQL statement unavailabe for any future use. 

Warning: The result buffer allocated by the EDADRV_FetchStmt function should not 

be freed by this function, it can only be freed by the EDADRV_FreeResult function. 


The following table describes the input parameter. 


EDA_T_STMT_HDL stmthdl 

EDADRV_DropStmt 

Statement handle. 

Return Codes 

The following table describes the EDADRV_DropStmt return codes. 

Return 




103 EDADRV_INVALID_STMT_ID Invalid statement handle. 

EDADRV_DropStmt Return Codes 

EDADRV_DropStmt 1-225


EDADRV_EndTransaction 

Syntax 

RETCODE EDADRV_EndTransaction(connhdl,trans_flag) 

Description 

The EDADRV_EndTransaction function commits or rolls back a transaction on the 

external database, depending on the value of trans_flag. 





int trans_flag The action to take if the transaction ends. Valid 

values are: 

0 – EDA_COMMIT. Commit the 

transaction. 

1 – EDA_ROLLBACK. Rollback the 

transaction. 

EDADRV_EndTransaction Input Variables 

EDADRV_EndTransaction 1-227

Return Codes 

The following table describes the EDADRV_EndTransaction return codes. 


Return 





114 EDADRV_INVALID_TRANS_FLAG Invalid END TRANSACTION 

flag. 

EDADRV_EndTransaction Return Codes

EDADRV_ExecuteStmt 

Syntax 

RETCODE EDADRV_ExecuteStmt(stmthdl,parameters,rowcount) 

Description 

EDA calls the EDADRV_ExecuteStmt function to execute an SQL statement that has 

been prepared with EDA_PrepareStmt. 

EDA provides parameter values for each input and input/output parameter. Parameter 

values are supplied in a string format, separated by field marks. The value of the field 

mark is determined by calling the EDADRV_GetADDAttr function. The 

EDADRV_ExecuteStmt function binds each parameter and executes a statement that 

has already been prepared with the EDADRV_PrepareStmt function. If the statement 

is INSERT, UPDATE, or DELETE (statement type EDASTMT_DML), the output 

variable rowcount contains the number of rows affected by the operation. If the 

statement is a query (statement type EDASTMT_QUERY), rowcount contains the 

number of columns of the result set. If the statement is a stored procedure (statement 

type EDASTMT_PROCEDURE), rowcount is not set. 




EDA_T_STMT_HDL stmthdl The statement handle. 

EDA_T_STRING parameters The statement parameters. 

EDADRV_ExecuteStmt Input Variables 

EDADRV_ExecuteStmt 1-229



Return Codes 

The following table describes the EDADRV_ExecuteStmt return codes. 



int * rowcount The number of the rows affected by the INSERT, UPDATE, 

or DELETE statement, or the number of columns in the result 

set, or the values of output and input/output parameters of a 

stored procedure. 

EDADRV_ExecuteStmt Output Variable 

Return 




2 EDADRV_SYSERR_OBJ_EXIST Object already exists. 


103 EDADRV_INVALID_STATEMENT_ID Invalid statement handle. 

111 EDADRV_INVALID_PARAM_TYPE Invalid parameter type 

112 EDADRV_INVALID_DATATYPE Invalid data type 

113 EDADRV_TOO_MANY_OUT_PARAM Too many output parameters. 

EDADRV_ExecuteStmt Return Codes

EDADRV_FetchStmt 

Syntax 

RETCODE EDADRV_FetchStmt(stmthdl,direction,numrows,rowsfetched, 

result) 

Description 

The EDADRV_FetchStmt function fetches numrows rows from an open cursor. 

Currently, EDA only uses forward scrolling. EDA expects the result set to be returned 

in a string format. The rows of the result are separated with record marks 

(EDADRV_ATTR_RM) and column values within each row separated with the 

NULL character (“\0”). 

In order to hold the result set, the EDADRV_FetchStmt function allocates a buffer. 

This buffer can only be freed by the EDADRV_FreeResult function. 



Type Variable Description 

EDA_T_STMT_HDL stmthdl The statement handle. 

int direction The fetch direction. Valid values are: 

0 – Fetch Forward 

int numrows The number of rows to fetch. 

EDADRV_FetchStmt Input Variables 

EDADRV_FetchStmt 1-231

Output Variables 

The following table describes the output variables. 

Return Codes 

The following table describes the EDADRV_FetchStmt return codes. 



int * rowsfetched The number of the row retrieved. 

EDA_T_RESULT * result The result string. 

EDADRV_FetchStmt Output Variables 

Return 





103 EDADRV_INVALID_STMT_ID Invalid cursor handle. 

104 EDADRV_INVALID_FETCH_DIR Invalid fetch direction. 

EDADRV_FetchStmt Return Codes

EDADRV_FreeResult 

Syntax 

RETCODE EDADRV_FreeResult(buf) 

Description 

The buffer allocated by the EDADRV_FetchStmt or the EDADRV_Perform function 

is not freed until EDA calls the EDADRV_FreeResult function. The 

EDADRV_FreeResult function frees the result set buffer. 


The following table describes the input variable. 

Return Codes 


EDA_T_RESULT buf The result buffer 

EDADRV_FreeResult Input Variable 

The following table describes the EDADRV_FreeResult return codes. 

Return 



EDADRV_FreeResult Return Codes 

EDADRV_FreeResult 1-233

EDADRV_GetDBInfo 

Syntax 

RETCODE EDADRV_GetDBInfo(connhdl,infotype,dbinfo) 

Description 

The EDADRV_GetDBInfo function returns general information about the database 

to which the application is currently connected. 






int infotype The information type. Valid values are: 

EDADRV_DBMS_NAME – The name of the 

database 

EDADRV_DBMS_VERSION – The database 

version. 

EDADRV_SERVER_NAME – The name of 

the instance on the external database. 

EDADRV_DATABASE_NAME – The name 

of the database. 

EDADRV_GetDBInfo Input Variables




EDA_T_RESULT * dbinfo The database information. 

EDADRV_GetDBInfo Output Variable 

Return Codes 

The following table describes the EDADRV_GetDBInfo return codes. 

Return 






115 EDADRV_INVALID_INFOTYPE Invalid information type. 

EDADRV_GetDBInfo Return Codes 

EDADRV_GetDBInfo 1-235

EDADRV_GetEDAAttr 

Syntax 

RETCODE EDADRV_GetEDAAttr(attribute_type,value) 

Description 

The EDADRV_GetEDAAttr function receives an attribute name – value pair. 

Valid values for the EDA driver attribute are: 


Type Attribute Name Description 

EDADRV_T_STR EDADRV_ATTR_SYSNAME At this release, the only valid value 

is UniData. 

EDADRV_T_STR EDADRV_ATTR_VERSION Valid values are 7.1 or 7.2. 

EDADRV_T_INT EDADRV_ATTR_RM The ASCII character representing 

a record mark (RM), such as ^255. 

EDADRV_T_INT EDADRV_ATTR_FM The ASCII character representing 

a field mark (FM), such as ^254. 

EDADRV_T_INT EDADRV_ATTR_VM The ASCII character representing 

a value mark (VM), such as ^253. 

EDADRV_T_INT EDADRV_ATTR_SM The ASCII character representing 

a subvalue mark (SM), such as 

^252. 

EDADRV_T_INT EDADRV_ATTR_TM The ASCII character representing 

a text mark (TM), such as ^251. 

EDADRV_T_INT EDADRV_NULLVAL The ASCII character representing 

the null value. 

EDADRV_GetEDAAttr Values




int attribute_type The name of the EDA driver attribute. 

EDA_T_SYMBOL value The value for the EDA driver attribute. 

EDADRV_SetParam Input Variables 

Return Codes 

The following table describes the EDADRV_GetEDAAttr return codes. 

Return 



105 EDADRV_INVALID_DRV_ATTR Invalid driver attribute. 

EDADRV_GetEDAAttr Codes 

EDADRV_GetDBInfo 1-237

EDADRV_GetErrmsg 

Syntax 

RETCODE EDADRV_GetErrmsg(errmsg) 

Description 

If the last driver function returned an error code, EDA calls this function to retrieve 

the corresponding error message string. If the error is returned from the external 

database, the driver returns this external database error. Otherwise, the driver should 

generate its own error message. 



Return Codes 

The following table describes the EDADRV_GetErrmsg return codes. 



EDA_T_RESULT * errmsg The error message string. 

EDADRV_GetErrmsg Output Variable 

Return 





EDADRV_GetErrmsg Return Codes

EDADRV_GetSpecialInfo 

Syntax 

RETCODE EDADRV_GetSpecialInfo(infotype,parameters,dbinfo) 

Description 

EDA calls the EDADRV_GetSpecialInfo function to retrieve special information 

about the database to which it is currently connected, such as rename table, rename 

index, and BLOB data type equivalents. 

When you specify EDADRV_BLOB_FIELD as the infotype, do not specify the 

parameter input variable. The output parameter returns the data type for the BLOB 

field on the external database, followed by the separator ‘\0’ and ‘0’ or ‘1’ for 

precision. For example, DB2 returns ‘CLOB\01’ and SQL Server returns 

‘VARCHAR(MAX)\00.’ 

When you specify EDADRV_RENAME_TABLE or EDADRV_RENAME_INDEX 

as the infotype, you must also specify both the source table or index name and the 

target table or index name, separated by “\0.” The output variable returns the rename 

table or rename index statement from the external database. 

When you specify EDADRV_DRIVER_INFO as the infotype, do not specify the 

parameter variable. The output parameter returns EDA driver information, including 

the EDA driver version, the supplier of the EDA driver, the date the EDA driver was 

created, the EDA driver target database name, and the EDA driver target database 

version. 

EDADRV_GetSpecialInfo 1-239


The following table describes the input variables for the EDADRV_GetSpecialInfo 

function. 

Variable Description 


The following table describes the output variable for the EDADRV_GetSpecialInfo 

function. 


infotype The information type. Valid values are: 

EDADRV_BLOB_FIELD – The data type for the BLOB 

field. 

EDADRV_RENAME_TABLE – The rename table statement. 

EDADRV_RENAME_INDEX – The rename index 

statement. 

EDADRV_DRIVER_INFO – information about the EDA 

driver. 

parameters The parameter array. 

EDADRV_GetSpecialInfo Input Variables 


EDA_T_RESULT * dbinfo The database information. 

EDADRV_GetSpecialInfo Input Variables

Return Codes 

The following table describes the EDADRV_GetSpecialInfo return codes. 

Return 




115 EDADRV_INVALID_INFOTYPE Invalid information type. 

EDADRV_GetSpecialInfo Return Codes 

EDADRV_GetSpecialInfo 1-241

EDADRV_LoadSymbols 

Syntax 

RETCODE EDA_LoadSymbols(numsymbols, symbols) 

Description 

The EDADRV_LoadSymbols function loads other functions to the EDA Driver 

Symbol array. This is the first function EDA calls. 

The EDA Driver Symbol array is an array of structures of the type 

EDA_T_SYMBOL. It contains pointers to all other driver functions as array 

elements. 

EDADRV_LoadSymbols allocates memory for the Driver Symbol array, fills in the 

array with either pointers to other driver functions or constants according to the 

following template. 


Array 

Index Array Element Value Description 

0 EDASYM_DBTYPE The driver’s data model. At this 

release, UniData only supports 

EDA_1NF. 

1 EDASYM_DBFAMILY The name of the driver database, such 

as DBMS_DB2, 

DBMS_MSSQLSERVER, 

DBMS_OTHERS. 

2 EDASYM_VERSION The version of this driver. This is for 

information purposes only, EDA does 

not use this value. 

3 EDASYM_CONNECT The pointer to EDADRV_Connect. 

4 EDASYM_DISCONNECT The pointer to 

EDADRV_Disconnect. 

Driver Functions

Array 

Index Array Element Value Description 

5 EDASYM_END_TRANSACTION The pointer to 

EDADRV_EndTransaction. 

6 EDASYM_PREPARE_STMT The pointer to 

EDADRV_PrepareStmt. 

7 EDASYM_DROP_STMT The pointer to EDADRV_DropStmt. 

8 EDASYM_EXECUTE_STMT The pointer to EDADRV_Execute. 

9 EDASYM_CLOSE_STMT The pointer to EDADRV_Close. 

10 EDASYM_FETCH_STMT The pointer to EDADRV_FetchStmt. 

11 EDASYM_PERFORM The pointer to EDADRV_Perform. 

12 EDASYM_SET_ATTRIBUTE The pointer to 

EDADRV_GetEDAAttr. 

13 EDASYM_GET_ERRMSG The pointer to 

EDADRV_GetErrmsg. 

14 EDASYM_CLEANUP The pointer to EDADRV_Cleanup. 

15 EDASYM_GET_DBINFO The pointer to 

EDADRV_GetDBInfo. 

16 EDASYM_FREE_RESULT The pointer to 

EDADRV_FreeResult. 

17 EDASYM_GETSPECIALINFO The pointer to 

EDADRV_GetSpecialInfo. 

Driver Functions 

EDADRV_LoadSymbols 1-243



Return Codes 

The following table describes the EDADRV_LoadSymbols return codes. 



int * numsymbols The number of symbols returned. 

EDA_T_SYMBOL * symbols The Driver Symbol Array pointer. 

EDADRV_LoadSymbols Output Variables 

Return 




108 EDADRV_CONFIG_NOT_EXIST edaconfig file does not exist. 

109 EDADRV_OPEN_CONFIG_ERROR Could not open edaconfig file. 

110 EDADRV_DB2INSTANCE_NOT_SET DB2INSTANCE in edaconfig file 

not set. 

EDADRV_LoadSymbols Return Codes

EDADRV_Perform 

Syntax 

RETCODE EDADRV_Perform(connhdl,stmt,numrows,result) 

Description 

The EDADRV_Perform function combines the processing of the 

EDADRV_PrepareStmt and the EDADRV_Execute functions, and if the statement is 

a query, it also fetches the entire result set as in EDADRV_FetchStmt. See the above 

functions for a description of the processing performed by the EDADRV_Perform 

function. The driver designer may choose to either Prepare and Execute or Execute 

Direct on the external database side. 





EDA_T_STMT stmt The statement content. 

EDADRV_Perform Input Variables 



Type Variable Descripton 

int * numrows The number of rows retrieved or affected. 

EDA_T_RESULT * result The result string. 

EDADRV_Perform Output Parameters 

EDADRV_Perform 1-245

Return Codes 

The following table describes the EDADRV_Perform return codes. 


Return 




2 EDADRV_SYSERR_OBJ_EXIST Object already exists. 



106 EDADRV_TOO_MANY_DATA Too much data fetched. 


113 EDADRV_TOO_MANY_OUT_PARAM Too many output parameters. 

EDADRV_Perform Return Codes

EDADRV_PrepareStmt 

Syntax 

RETCODE EDADRV_PrepareStmt(connhdl,stmthdl,stmt) 

Description 

The EDADRV_PrepareStmt function prepares a statement passed to it by EDA. If the 

driver already has a statement handle that it can reuse, it may choose to return this 

preallocated handle in the stmthdl output variable, otherwise, it allocates a new 

statement handle and returns it in stmthdl. 

If the statement is a DDL statement (statement type EDASTMT_DDL) or a DML 

statement, such as INSERT, UPDATE or DELETE (statement type 

EDASTMT_DML), or a SELECT statement (statement type EDASTMT_QUERY), 

the statement may contain input parameters. These parameters are designated by 

parameter markers (“?”). In this case, EDA supplies as many parameter descriptions 

as there are parameter markers. 

If the statement is a stored procedure call (statement type 

EDASTMT_PROCEDURE), the statement may contain input, output, and 

input/output parameters (parameter types of EDAPARAM_IN, EDAPARAM_OUT, 

and EDAPARAM_INOUT). In this case, EDA supplies as many parameter descriptions 

as there are input and input/output parameters of a stored procedure. 

The EDADRV_PrepareStmt function allocates an array of EDA_T_PTYPE structures, 

converts EDA data type into the corresponding external database data type, and 

associates this array with the statement handle for its later use in 

EDADRV_ExecuteStmt. 

EDADRV_PrepareStmt 1-247





Return Codes 

The following table describes the EDADRV_PrepareStmt return codes. 




EDA_T_STMT stmt The statement content. 

EDADRV_PrepareStmt Input Variables 


EDA_T_STMT_HDL * stmthdl The statement handle. 

EDADRV_PrepartStmt Output Variable 

Return 







EDADRV_PrepareStmt Return Codes

ENABLEDEC 

Syntax 

ENABLEDEC [,], [ON ERROR 

] 

Description 

Use the ENABLEDEC command to activate decryption on a file or fields you 

specify. 

Parameters 



filename The name of the file on which you want to enable decryption. 

field_list A comma-separated list of fields for which you want to enable 

decryption. Do not enter spaces between the field names. 




ENABLEDEC Parameters 

ENABLEDEC 1-249

STATUS Codes 

ENABLEDEC has the following STATUS codes: 

STATUS 


Example 

The following example illustrates enabling decryption on two fields in a file using a 

quoted string: 


0 No error, operation successful 

1 Decryption is already enabled 

2 General operation failure, such as an open file error 

3 File is not an encrypted file 

4 Attempting operation on WHOLERECORD encrypted file 

5 Field(s) is not an encrypted file 

6 Cannot locate information to disable encryption 

7 Field is not a valid field in this file 

ENABLEDEC STATUS Codes 

ENABLEDEC "CUSTOMER","NAME,PHONE" ON ERROR PRINT "Unable to enable 

decryptiON 

The next example illustrates enabling decryption on two fields using variables: 

CUST="CUSTOMER" 

FIELDS="NAME,PHONE" 

ENABLEDEC CUST,FIELDS ON ERROR PRINT "Unable to enable decryption"

ENCODE 

Syntax 

ENCODE(algorithm, action, data, dataLoc, result, resultLoc) 

Description 

The ENCODE() function performs data encoding on input data. Currently, UniData 

supports only Base64 encoding. Base 64 encoding is designed to represent arbitrary 

sequences of octets that do not need to be humanly readable. A 65-character subset 

of US-ASCII is used, enabling 6-bits to be represented per printable character. The 

subset has the important property that it is represented identically in all versions of 

ISO646, including US-ASCII, and all characters in the subset are also represented 

identically in all versions of EBCDIC. The encoding process represents 24-bit groups 

of input bits as output strings of 4 encoded characters. The encoded output stream 

must be represented in lines of no more than 76 characters each. All line breaks must 

be ignored by the decoding process. All other characters not found in the 65-character 

subset should trigger a warning by the decoding process. 

The function can perform either encoding or decoding, as specified by action. The 

data can either be in the dynamic array, data, or in a file whose name is specified in 

data, determined by dataLoc. 

Parameters 



algorithm A string containing the encode method name. UniData currently only 

supports the Base64 method. 

action 1 - Encode 

2 - Decode 

data Data or the name of the file containing the data to be encoded or decoded. 

ENCODE Parameters 

ENCODE 1-251






result Encoded or decoded data or the name of the file storing the processed 

data. 

resultLoc 1 - Result in a string 

2 - Result in a file. 

ENCODE Parameters (continued) 

Return 

Code Status 

0 Success. 

1 Unsupported algorithm. 

2 Invalid parameters (invalid data or result location 

type, and so forth). 

3 The data cannot be read. 

4 The data cannot be encoded or decoded. 

Return Code Status

ENCRYPT 

Syntax 

ENCRYPT(algorithm, action, data, dataLoc,key, keyLoc, keyAction, salt, IV, result, 

resultLoc) 

Description 

The ENCRYPT() function performs symmetric encryption operations. You can call 

various block and stream symmetric ciphers through this function. The supported 

ciphers are listed in UniBasic Extensions. 

You specify ciphers by algorithm, and they are not case sensitive. You can specify 

Base64 encoding and decoding with the action parameter. If you specify encoding, 

the encrypted data is Base64 encoded before being entered into result. If you specify 

decoding, the data is Base64 decoded before being encrypted. Specify the data and 

its location using data and dataLoc, respectively. You can explicitly specify Key, read 

it from a file, or, alternatively, derived it on the fly by specifying keyAction, in which 

case the key string is used as a pass phrase to derive the actual key. The encrypted or 

decrypted data is put into the dynamic array result, or a file, as specified by resultLoc. 

Salt is used to provide more security against certain kinds of cryptanalysis attacks, 

such as dictionary attacks. If you specify an empty salt, UniData uses an internally 

generated salt in deriving the key. UniData ignores Salt when action is set to decrypt. 

UniData uses IV (Initialization Vector) to provide additional security to some block 

ciphers. It does not need to be secret but should be fresh, meaning different for each 

encrypted data. If you supply an existing key, IV is generally needed. However, if the 

encryption key is to be derived from a pass phrase, IV can be generated automatically. 

Both salt and IV must be provided in hexadecimal format. 

ENCRYPT 1-253

Parameters 

he following table describes each parameter of the syntax. 



algorithm A string containing the cipher name. 

action 1 - Encrypt 

2 - Base64 encode after encryption 

3 - Decrypt 

4 - Base64 decode before encryption 

5 - One-line Base64 encoding, which does not place line breaks in the 

result. 

6 - One-line Base64 decoding, which does not place line breaks in the 

result. 

data Data or the name of the file containing the data to be processed. 



key The actual key (password) or file name containing the key. 

keyLoc 1 - Key in data 

2 - Key in file 

keyAction 1 - Use actual key 

2 - Derive key from pass phrase 

Salt A string containing the Salt value. 

IV A string containing IV. 

result The result buffer or the name of the file storing the result. 

resultLoc 1 - Result in a string 

2 - Result in a file. 

ENCRYPT Parameters


Return 

Code Status 

0 Success. 

1 Invalid cipher. 

2 Invalid parameters (location/action value is 

out of range, etc.). 


4 The key cannot be derived. 

5 Base 64 encoding/decoding error. 

6 Encryption/decryption error. 

ENCRYPT Return Codes 

ENCRYPT 1-255

END 

Syntax 

END 

Description 

The UniBasic END command declares the end of a program or a block of statements. 

UniBasic does not require you to use END at the end of a program. 

Example 

In the following example, the END in bold type declares the end of the program 

segment. (The first END ELSE ends the THEN clause in the IF/THEN/ELSE 

statement.) 

A = 0 

PRINT "Enter a number: ": 

INPUT X 

IF X>0 THEN 

PRINT "Incrementing." 

A += 1 

END ELSE 

PRINT "Decrementing." 

A -= 1 

END 

PRINT A 


ENTER 

Syntax 

ENTER filename 

ENTER @variable 

Description 

The UniBasic ENTER command passes control to the program you specify. It terminates 

the program that is passing control and executes the cataloged program. The 

ENTER command allows variables to pass through common areas, but all other 

variables are reinitialized when the new program begins. 

Note: This command does not return control to the original program by default. For 

structured programming, use GOSUB and RETURN. This makes the program easier 

to read and maintain. 

The ENTER command processes faster than the CHAIN command. 

Examples 

In the following example, the program statement transfers control to cataloged 

program 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 

ENTER 1-257



CALL, CHAIN, COMMON, GOSUB 


EQ 

Syntax 

variable = expr 

expr1 EQ expr2 

Synonym 

= 

Description 

The UniBasic EQ operator serves as an assignment operator and a relational operator. 

As an assignment operator, it assigns expr to variable. As a relational operator, it tests 

whether expression expr1 is equal to expr2. 

expr1 and expr2 can be any valid UniBasic expressions, variables, strings, or literals. 

Relational operators make the comparisons that direct program flow in conditional 

statements like the following: 

IF VAR1 = VAR2 THEN GOSUB SUB1 

DO UNTIL VAR1 = VAR2 

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 

EQ 1-259

Examples 

In the following example, the program statement assigns the value of 60 to the 

variable PAGELENGTH: 

PAGELENGHTH EQ 60 

In the next example, the EQ relational operator is used in a conditional test. The 

program segment tests whether A equals 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 



EQS 


EQS 

Syntax 

EQS(array1,array2) 

Description 

The UniBasic EQS function compares each value in array1 to its corresponding 

value in array2. UniData returns an array with 1 in each position where values are 

equal, and 0 in each position for values that are not equal. 

Example 

In the following example, the program segment compares ARRAY1 to ARRAY 2 

and returns ARRAY3. After EQS, ARRAY3 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) 

EQS 1-261

EQU 

Syntax 

EQU constant1 TO value1 [[,constant2 TO value2]...] 

EQU constant1 {LITERALLY | LIT} string2 [[,constant2 {LITERALLY | 

LIT} string2]...] 

Synonym 

EQUATE 

Description 

The UniBasic EQU command replaces a constant with an array, function, number, 

string, or variable name when the program is compiled. 

The only difference between the statements using TO and those using LITERALLY 

is the use of quotation marks. In the TO form, you cannot enclose literals in quotation 

marks. In the LITERALLY form, you must enclose literals in quotation marks. 

After the execution of an EQUATE statement, you can use the constant symbols and 

variables interchangeably at all levels of the program. 

EQUATE variables are available from within the UniBasic debugger. 

The variable literal string limit is 2,048 characters. EQUATE has the same limit. 

Tip: EQUATE enables you to use longer, more meaningful names as you write code. 

These names are replaced with the actual value when the program is compiled. 

EQUATE also lets you equate a control character to a meaningful name. UniData 

does not use memory for a constant symbol because the replacement takes place 

during compilation. 


Parameters 


Paramete 

r Description 

constant Specifies the constant to be replaced with value when the program is 

compiled. 

value Specifies the value to replace constant with when the program is compiled. 

string Specifies a literal string, in quotes, to replace constant with when the program 

is compiled. 

EQ Parameters 

Examples 

In the following example, all occurrences of the constant SB are replaced with the 

value CHAR(8) (clear screen) during program compilation: 

EQUATE SC TO CHAR(8) 

In the next example, UniData replaces every occurrence of the constant TITLE with 

the string ALGONQUIN: 

EQUATE TITLE LITERALLY "ALGONQUIN" 

In the next example, UniData replaces every occurrence of the constant TRUE with 

the value 1, and every occurrence 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 

EQU 1-263

In the next example, UniData replaces every occurrence of the constant FULLNAME 

with the expression in the EQUATE statement. The program segment prints “Mary 

Jones”. 


EQUATE FULLNAME LITERALLY "FIRST_NAME:' ':LAST_NAME" 

FIRST_NAME = "Mary" 

LAST_NAME = "Jones" 

PRINT FULLNAME 

After the program is compiled, the print statement looks like this: 

PRINT FIRST_NAME:' ':LAST_NAME 

The following example shows the same program segment using the TO form of the 

statement syntax. In this case, the quotation marks around FIRST_NAME:' 

':LAST_NAME are removed. 

EQUATE FULLNAME TO FIRST_NAME:' ':LAST_NAME 

FIRST_NAME = "Mary" 

LAST_NAME = "Jones" 

PRINT FULLNAME

EREPLACE 

Syntax 

EREPLACE(expression, substring, replacement [,occurrence [,begin] ] ) 

Description 

The EREPLACE function replaces substring in expression with another substring. If 

you do not specify occurrence, each occurrence of substring is replaced. 

Parameters 



expression The expression in which you want to replace substring. 

substring The substring you want to replace. If substring is an empty string, 

replacement is prefixed to expression. If replacement is an empty string, 

all occurrences of substring are removed. 

replacement The replacement value for substring. 

occurrence Specifies the number of occurrences of substring to replace. To replace all 

occurrences, specify occurrence as a number less than 1. 

begin Specifies the first occurrence of substring to replace. If you omit begin, or 

specify a value less than 1, it defaults to 1. 

EREPLACE Parameters 

If expression evaluates to the null value, null is returned. If substring, replacement, 

occurrence, or begin evaluates to the null value, the EREPLACE function fails and 

the program terminates with a run-time error message. 

Note: The EREPLACE function behaves like the CHANGE function except when 

substring evaluates to an empty string. 

EREPLACE 1-265

EXECUTE 

Syntax 

EXECUTE "str.expr" [[ASYNC | SYNC] ON connection [ON ERROR 

statements]] [PASSLIST list.num.expr] [RTNLIST list.num.expr] 

[CAPTURING dyn.array.var] [RETURNING dyn.array.var] [PASSCOM] 

Synonym 

PERFORM 

Description 

The UniBasic EXECUTE command executes an ECL or UniData SQL command 

from within a UniBasic program. 

You can execute multiple commands with a single EXECUTE statement by 

separating each command by attribute marks. When the EXECUTE statement 

executes, UniData separates each command and executes them in order. 

Note: The settings of UDT.OPTIONS affect the way ECL commands execute. For 

information about these options, see the UDT.OPTIONS Commands Reference. For 

information about UDT.OPTIONS that could affect that command, see the 

appropriate ECL command in the UniData Commands Reference. 

Reminder: When you compile EXECUTE and PERFORM in BASICTYPE P, a 

different parser is used. The P-type parser scans a file of commands that are defined 

in the Spectrum-SMA standards or in the McDonnell Douglas REALITY ® operating 

system. If the command is found in this file, it is parsed using the P-type parser. If the 

command is not found in the REALITY file, it is parsed as if the program had been 

compiled with BASICTYPE U. Because all REALITY commands are uppercase, using 

lowercase commands will always result in the use of the standard UniData parser. 

If you want to execute a standard UniData, UniQuery, or ECL command from within 

a program compiled with BASICTYPE P, use the UniBasic command 

UDTEXECUTE. 


Parameters 



str.expr Specifies a UniData command with appropriate parameters. If 

you pass a file name to PERFORM, you must use the actual file 

name, not a file variable (which is assigned in the OPEN 

statement). 





ON ERROR statements UniData no longer supports this parameter, but it remains for 


CAPTURING, 

dyn.array.var 

RETURNING, 

dyn.array.var 

The CAPTURING clause stores the output in a dynamic array 

instead of on the display terminal. Each line of the text becomes 

an attribute in the array. Output sent to the printer is not affected 

by this clause. 

The order of CAPTURING and RETURNING is 

interchangeable. 

The RETURNING clause captures error messages resulting 

from the command executed with PERFORM. This variable 

contains a string of error message numbers separated by spaces. 

If the executed command creates a spooler hold file, UniData 

also returns the hold file number in the same variable. 

EXECUTE Parameters 

EXECUTE 1-267


Reminder: The error message numbers you capture with RETURNING will vary, 

depending upon which version of UniData you are running. 

The ECL STACKCOMMON Command 





RTNLIST int.expr The RTNLIST clause must be an integer from 0–9, designating 

the select list to return to the calling program. You can use the 

resulting list with subsequent READNEXT statements or in the 

PASSLIST clause of an EXECUTE statement. If an expression 

is not given after RTNLIST, the generated select list replaces the 

contents of list 0. If RTNLIST is not specified, no list is returned. 

If you use EXECUTE to call a UniBasic program, no select list 

is returned even though you specify RTNLIST. On the other 

hand, PASSLIST is always effective and transfers a select list to 

the called program. 

PASSLIST int.expr The PASSLIST clause must evaluate to an integer 0, 1 or 2, 

designating the select list to be sent to the called program. If you 

do not specify int.expr, list 0 is assumed. 

The passed list can be the result of previous SELECT or 

GETLIST commands, or the result of the RTNLIST clause of a 

PERFORM statement. 

PASSCOM This parameter is provided for backward compatibility for 

releases before 3.1. 

EXECUTE Parameters (continued) 


unnamed common is passed to the executed program and back to the 

executing program. 


the unnamed common is not passed to the program you execute. Instead, 

unnamed common is saved, and the unnamed common of the called 

program is initialized to 0. When control is passed back to the calling 

program, unnamed common is restored to its value before the program call. 

Unnamed common is never passed to a phantom program.

Note: STACKCOMMON is always on in BASICTYPEs P and M. STACKCOMMON 

is off by default in BASICTYPEs R and U. 

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 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. The select list is then used to read records from the file. 

EXECUTE 'SELECT CLIENTS WITH COUNTRY = "Canada"' 

EXECUTE "SAVE.LIST 'canadians'" 

OPEN 'CLIENTS' TO CLIENT.FILE ELSE ABORT 

GETLIST 'canadians' SETTING LIST.CNT 

ELSE PRINT CLIENT:" SAVEDLISTS ID ‘canadians’ CANNOT BE 

FOUND";STOP 

PRINT @(-1) 

FOR I = 1 TO 22 

READNEXT ID ELSE EXIT 

READ REC FROM CLIENT.FILE, ID THEN 

PRINT @(5,I):REC:@(20,I):REC 

END ELSE 

PRINT "CANNOT FIND RECORD":ID 

END 

NEXT I 

CLEARSELECT 

END 

In the next example, the program segment executes a paragraph from within a 

UniBasic program using the EXECUTE statement: 

PARA = "PA":@AM:"DISPLAY HELLO" 

EXECUTE PARA 

This paragraph displays the word HELLO on the terminal screen. 

EXECUTE 1-269



COMMON, EXECUTESQL, MDPERFORM, PCPERFORM, UDTEXECUTE 

UniData 

STACKCOMMON – For more information, see the UniData Commands Reference. 


EXECUTESQL 

Syntax 

EXECUTESQL str.expr [ASYNC | SYNC] [ON connection [ON ERROR 

statements]] 

Description 

The UniBasic EXECUTESQL command executes a UniData SQL statement within 

a UniBasic program. 

If the UniData SQL statement includes a SELECT statement with the intent to 

process internal program items, the SELECT statement must contain a TO clause 

with a resulting file name. Otherwise, UniData displays the result of the statement. If 

you select only the @ID attribute, UniData stores the @IDs in a select list. If the 

UniData SQL statement includes a TO clause, the data is stored in the output file and 

is then available to the UniBasic program via the READNEXTTUPLE statement. 

Note: After you execute a SELECT statement and complete processing of the selected 

records, you must execute the CLEARSQL command to clear the select list and make 

all records in the file available for further processing. 

Parameters 



str.expr Specifies a valid UniData SQL statement for UniData to 

execute. 

EXECUTESQL Parameters 

EXECUTESQL 1-271


Examples 

In the following example, the program segment executes a UniData SQL command: 






ON ERROR statements UniData no longer supports this parameter, but it remains for 


EXECUTESQL Parameters (continued) 

OUT.COMMAND = "SELECT NAME, ADDRESS, CITY" 

OUT.COMMAND := " FROM CLIENTS;" 

EXECUTESQL OUT.COMMAND 

CLEARSELECT 

The following output displays on the terminal screen when you execute the preceding 

program: 

Page 1 

Name Address City 

------------------------------ ------------------------- --------- 

------ 

Paul Castiglione 45, reu de Rivoli Paris 

Fredrick Anderson 854, reu de Rivoli Paris 

Beverly Ostrovich 7925 S. Blake St. Sydney 

Cal di Grigorio 913 Montreal Ave. Regina 

Franklin Sears 213 Midland St. Perth 

Gino Lee 483 E. Silverman St. Fonthill 

JoAnn Casey 4024 South Ivywood Circle Omaha 

...

In the next example, the program segment executes the same UniData SQL command 

with a TO clause that stores the UniData SQL output in a file that you can access 

using the READNEXTTUPLE statement. (This program uses the CLIENTS file in 

the demo database.) 

OUT.COMMAND = "SELECT NAME, ADDRESS, CITY, STATE" 

OUT.COMMAND := " FROM CLIENTS TO SQL_INPUT;" 


DONE = 0 

FOR X = 1 TO 5 

READNEXTTUPLE CLIENT.INFO FROM "SQL_INPUT" ELSE STOP 

CONVERT @AM TO " " IN CLIENT.INFO 

PRINT CLIENT.INFO 

NEXT X 

CLEARSELECT 

END 

This program produces the following results: 

Paul Castiglione 45, reu de Rivoli Paris 

Fredrick Anderson 854, reu de Rivoli Paris 

Beverly Ostrovich 7925 S. Blake St. Sydney NSW 

Cal di Grigorio 913 Montreal Ave. Regina Saskatchewan 

Franklin Sears 213 Midland St. Perth 

In the next example, the UniData SQL statement selects an @ID only. UniData uses 

a select list instead of storing the output. In this case, the UniData SQL command 

does not require a TO clause, and the UniBasic READNEXT statement processes the 

IDs selected. 

OPEN 'CLIENTS' TO CLIENT.FILE ELSE PRINT 'Open Error.' 

OUT.COMMAND = "SELECT @ID" 

OUT.COMMAND := " FROM CLIENTS" 

OUT.COMMAND := " WHERE CITY = 'Paris';" 


DONE = 0 

LOOP 

READNEXT @ID ELSE DONE = 1 

UNTIL DONE DO 

GOSUB PROCESS.RECS 

REPEAT 

CLEARSELECT 

PROCESS.RECS: 

*print records for clients in Paris." 

READ REC FROM CLIENT.FILE,@ID 

THEN PRINT REC 

RETURN 

END 

EXECUTESQL 1-273

The program output is: 


Paul}Castiglione}Chez Paul}45, reu de 

Rivoli}Paris}}75008}France}3342425544|3342664857}Work|Fax 

Fredrick}Anderson}Otis Concrete}854, reu de 

Rivoli}Paris}}75008}France}3342482815|3342481924}Work|Fax 

Antonette}Larnelle}Monde Cable}19, rue Jean 

Goujon}Paris}}75008}France}3438291902|3438295512}Work|Fax 

Pierre}Edmond}JT Engineering}70, avenue 

d'Iena}Paris}}75016}France}3391928392|3391992193}Work|Fax 

Pierre}Logni}Wine College}70, avenue 

d'Iena}Paris}}75016}France}3393688924|3393688523}Work|Fax 

Omar}Saulnier}Maurice Salon}4, avenue 

Valencia}Paris}}75016}France}3348756898 |3348589782 }Work|Fax 

David}Silvers}Qinton Systems}9, avenue 

Valencia}Paris}}75016}France}3441831291|3441830107}Work|Fax 

Fernando}Ducrot}Monde Cable}19, rue Jean 

Goujon}Paris}}75008}France}3344587968|3344668871}Work|Fax 



EXECUTE, READNEXT, READNEXTTUPLE 

UniData SQL 

For more information about UniData SQL commands, see the UniData SQL 

Commands Reference.

EXIT 

Syntax 

EXIT 

Description 

The UniBasic EXIT command terminates a FOR/NEXT or LOOP/REPEAT 

structure and transfers control to the following statement. As with the CONTINUE 

statement, EXIT forms well structured programs. 

Tip: Use EXIT in structured programs instead of GOTO. This makes the code easier 

to read and maintain. 

Example 

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 



CONTINUE, FOR/NEXT, LOOP/REPEAT 

EXIT 1-275

EXP 

Syntax 

EXP(expr) 

Description 

The UniBasic EXP function raises e to the power of expr. e is approximately 

2.71828. expr must be numeric. The function e x is its own derivative. If y = e x , then 

x is the natural logarithm of y. 

If exp is too large or too small, a warning message is printed and 0 is returned. If exp 

is an empty string, the empty string is returned. 

Example 

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) 



LN 


EXTRACT 

Syntax 

EXTRACT(dyn.array.expr, attrib.expr,[val.expr [,subval.expr]]) 

dyn.array.expr 

Description 

The UniBasic EXTRACT function retrieves data from an attribute, value, or 

subvalue in a dynamic array. The dynamic array itself remains unchanged. You can 

use either of the preceding syntax forms. 

Parameters 



dyn.array.expr Specifies a dynamic array from which to retrieve the data. 

attrib.expr Specifies an attribute of the dynamic array from which to retrieve the 

data. If the value of attrib.expr is less than 1, UniData uses 1. 

val.expr Specifies a value of attrib.expr from which to extract the data. If the 

values of val.expr and subval.expr are 0, or if they do not appear in the 

EXTRACT function, UniData retrieves an attribute. 

subval.expr Specifies a subvalue of the value specified by val.expr in the attribute 

specified by attrib.expr, from which to retrieve data. 

If the values of val.expr and subval.expr are 0, UniData retrieves an 

attribute. If the value of subval.expr is 0, or if it does not appear in the 

EXTRACT function, UniData retrieves a value. 

EXTRACT Parameters 

EXTRACT 1-277

Examples 

The following program segment is taken from the sample program in Appendix A, 

“Sample Program,” in Developing UniBasic Applications. The variable ENTRY is 

used to extract the user-requested values from the ORDERS record. 


DISPLAY_DATA: 

* Display the current information in the desired record. This is 

* determined by the number the user entered (ORDER_NUMBER). 

... 

NUM_ENTRIES = DCOUNT(ORDER.REC,@VM) 


PRODUCT_NUMBER = ORDER.REC 

COLOR = ORDER.REC 

QUANTITY = ORDER.REC 

PRICE = OCONV(ORDER.REC,"MD2$,") 

In the following example, the program segment assigns the string Joan to the variable 

MID. Joan is the second attribute in the dynamic array ARR. The value and subvalue 

expressions are 0, resulting in the extraction of an attribute. 

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) 



DEL, INSERT, REMOVE, REPLACE, SUBSTRINGS

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. FIELD supports multibyte languages. 

Parameters 



string.expr Specifies the string expression to search. 

delim.expr Specifies the field delimiter. 

field.expr Specifies the field at which to begin the search. 

,rep.expr Specifies the number of fields to return. If you do not specify rep.expr, or it 

is less than 1, UniData returns a default of 1 substring. 

FIELD Parameters 

Examples 

In the following example, the program segment assigns the third value (“Guy”) in the 

array ARR to the array NARRAY: 

ARR = "#999":@VM:"Charlemagne":@VM:"Guy":@VM:"Pierre" 

NARRAY = FIELD(ARR,@VM,2,1) 

FIELD 1-247

In the next example, the program segment assigns the two fields following the third 

occurrence of the delimiter “,” in the variable ARR to NARRAY. UniData stores the 

value 5,8 in NARRAY. 

ARR = "10,10,5,8,7,12,15,8" 

NARRAY = FIELD(ARR,",",3,2) 

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. UniData stores the 

value Smith in LNAME. 

NAME = "Harry Smith" 

LNAME = FIELD(NAME," ",2) 



COL1, COL2, INDEX 


FIELDSTORE 

Syntax 

FIELDSTORE(str.expr,delimiter,b.pos,option,new.expr) 

Description 

The UniBasic FIELDSTORE function inserts an expression and an appropriate 

delimiter into a string. 

Parameters 



str.expr Specifies the target string. 

delimiter Specifies the character that delimits fields in str.expr. 

b.pos Specifies the occurrence of the delimiter at which to insert. 

If the number of delimiters is less than b.pos, UniData inserts the appropriate 

number of spaces and delimiters. 

option Specifies whether FIELDSTORE will insert before, insert after, or replace 

the field at b.pos. Refer to the following FIELDSTORE Options table for 

further details. 

new.expr Specifies the expression (with its associated delimiter) to insert before or 

after the specified delimiter. 

FIELDSTORE Parameters 

FIELDSTORE 1-249

Options 

The value of option determines the operation to be executed. The following table 

describes these options and their results. 


Examples 

In the following example, the program segment inserts AR in the string ASTATES. 

After execution, ASTATES contains the string “AL:AK:AR:AZ”. 


If option > 0 UniData replaces the number of substrings specified in option. 

If option = 0 UniData inserts new.expr at the position indicated by b.pos. 

If option < 0 UniData deletes the number of substrings specified in option, and inserts 

new.expr at the location indicated by b.pos. 

FIELDSTORE Options 

ASTATES = 'AL:AK:AZ' 

ASTATES = FIELDSTORE(ASTATES,':',3,0,'AR') 

The following program segment compiles and runs only when null value handling is 

on. The program segment inserts AR, and then inserts the null value into ASTATES. 

It calls the externally cataloged subroutine PRINT.SETUP to convert the null value 

to a printing character, and then prints the converted ASTATES. (PRINT.SETUP is 

shown under CHANGE.) 

PRT.STR = '' 

ASTATES = 'AL:AK:AZ' 

ASTATES = FIELDSTORE(ASTATES,':',3,0,'AR') 

PRINT "ASTATES = ":ASTATES 

ASTATES = FIELDSTORE(ASTATES,':',3,0,@NULL) 

STR = ASTATES 

CALL PRINT.SETUP(STR,PRT.STR) 

PRINT "ASTATES = ":PRT.STR 

This program prints the following: 

ASTATES = AL:AK:AR:AZ 

ASTATES = AL:AK:@NULL:AR:AZ

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 new.expr 

(orange,black) is to be inserted in the same position. After processing, COLORS 

contains the string “yellow,blue,red,green,orange, black,white”. 

COLORS = 'yellow,blue,red,green,ugly,white' 

COLORS = FIELDSTORE(COLORS,',',5,-1,'orange,black') 



INS, INSERT 

FIELDSTORE 1-251

FILEINFO 

Syntax 

FILEINFO(file.var, code) 

Description 

The FILEINFO function returns information about the configuration of a file. 

Parameters 


Paramete 

r Description 


file.var Specifies the file to be analyzed. 

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 indicates the information requested. The following table describes the codes and 

the return values of the function. 

Code 

Information 

Requested File Type Return Value 

0 File open status ALL 1= Open 

0= Not open 

2 Full path name of file ALL Pathname of file 

3 File type HASHED 

DYNAMIC 

DIRECTORY 

SEQUENTIAL 

NFA 

OS 

EDA 

4 Hashing file type HASH & DYN 

(KEYONLY) 

HASH & DYN 

(KEYDATA) 

OTHERS 

5 Modulo of file HASH 

DIRECTORY 

DYNAMIC 

OTHERS 

6 Minimum modulo of 

file 

7 Group size of file HASH & DYN 

OTHERS 

8 Block size of file HASH & DYN 

OTHERS 

FILEINFO Codes 

2 

3 

4 

5 

7 

8 

13 

Hash type (0 or 1) 

Hash type (32 or 33) 

Modulo 

0 

Current modulo 

Not applicable 

DYNAMIC Minimum modulo 

(Block size/1024)-1 


Block size 


FILEINFO 1-253

Code 

9 Merge factor 

percentage 

10 Split factor 

percentage 

11 Current load 

percentage 

13 Does file contain 

alternate key indexes? 


Information 


14 Next line number to 

read or write 

DYNAMIC 

OTHERS 

DYNAMIC 

OTHERS 

DYNAMIC 

OTHERS 

HASH & DYN 

OTHERS 

SEQUENTIAL 

OTHERS 

17 Filename HASH & DIR 

& DYNAMIC 

OTHERS 

18 Block size of file HASH & DIR 

& DYNAMIC 

OTHERS 

Merge factor 


Split factor 


Percent result of the 

formula: 

(keyspace(grp) 

*100)/blksize 


1= yes; 2 = no 


Next line number 


VOC entry name 


Block size 


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 SETINDEX 

statement was applied 

ALL VOC entry name 

FILEINFO Codes (continued)

Code 

21 Index record read by 

last browsing 

statement, such as 

READFWD and 

READBCK. 

22 File type: recoverable 

or nonrecoverable 

24 Type of Replication 

file 

ALL Key value 

ALL 1 – Recoverable 

0 – Nonrecoverable 

ALL 0 – File is not a replication 

object 

1 – File is a publishing 

object 

2 – File is a subscribing 

object 

27 Is the file encrypted? ALL 0 – File is not encrypted 

1 – File is encrypted 

28 Type of file 

encryption 

Information 


ALL Returns a dynamic array 

containing the following 

information: 

? For a file encrypted with 

the WHOLERECORD 

option: 

-1@SM@SM 

? For a file encrypted at 

the field level: 

@SM@SM@ 

SM 

? Returns an empty string 

if the file is not 

encrypted. 

FILEINFO Codes (continued) 

FILEINFO 1-255

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, 

MATWRITEU, WRITEU, and WRITEVU statements. Other file input/output 

commands ignore FILELOCK. 

Reminder: UniBasic locks are advisory only. For more information, see Developing 

UniBasic Applications. 

Parameters 




file.var Specifies the file to lock. 


file. If no default file is open, a fatal error occurs. 



ON ERROR statements Specifies statements to perform if the FILELOCK statement 

fails with a fatal error condition because the file is not open. 


terminates abnormally. 

LOCKED statements Specifies statements to execute if the file is already locked. 

FILELOCK Parameters

STATUS Function Return Values 

After you execute of the FILELOCK command, the UniBasic STATUS function 

returns 0 if the file was locked successfully. If the file was already locked, and if the 

LOCKED clause was included in the FILELOCK statement, STATUS returns the 

user number of the process that locked the file. 

Example 

In the following example, the FILELOCK statement locks the file STAT, preventing 

lock-checking commands from accessing this file: 

FILELOCK STAT LOCKED STOP 



FILEUNLOCK, RECORDLOCKED, RELEASE 

FILELOCK 1-257

FILEUNLOCK 

Syntax 

FILEUNLOCK [file.var] [ON ERROR statements] 

Description 

The UniBasic FILEUNLOCK command unlocks a file previously locked with a 

FILELOCK command. 

Parameters 



Example 

In the following example, the FILEUNLOCK statement unlocks the file referred to 

by the file variable INVENTORY.FILE: 

FILEUNLOCK INVENTORY.FILE 


file.var Specifies the file to unlock. 





ON ERROR statements Specifies statements to perform if the FILEUNLOCK statement 

fails with a fatal error condition because the file is not open. 


terminates. 

FILEUNLOCK Parameters



FILELOCK, RECORDLOCKED, RELEASE 

FILEUNLOCK 1-259

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. FIND returns the attribute, value, and subvalue position of the found 

string. The expression must match the entire array element to make a match. 

Parameters 




expr Specifies the expression to find. expr must be either a numeric value or a 

string value. 

dyn.array Specifies the dynamic array in which to find expr. 

,occur Specifies the occurrence of expr to find. The default is 1 (the first 

occurrence). 

FIND Parameters


f,v,s Specifies variables in which to place the position of expr: 

f – Attribute 

v – Value 

s – Subvalue 

If the attribute found has neither multivalues nor subvalues, then v and s, if 

specified, are set to 0. If only multivalues are present, s is set to 0. If only 

subvalues exist, v is also set to 0. 

THEN 

statements 

ELSE 

statements 

For more information about writing THEN...ELSE parameters, see Developing 

UniBasic Applications. The UniBasic FIND and LOCATE commands are compared 

in this manual. 

Examples 

Specifies statements to execute if the expr is found in the array. END is 

required when statements extend over more than one line. Either a THEN 

statement or an ELSE statement is required. 

Specifies statements to execute if the expr is not found in the array. END is 

required when statements are multiline. Either a THEN statement or an 

ELSE statement is required. 

FIND Parameters (continued) 

In the following example, the program segment searches for an occurrence of 31 in 

the string DA. This results in F=3, V=1, and S=0 because 31 is found in the third 

attribute as the first multivalue, and this attribute has no subvalues. 

001: DA = 1:@AM:2:@AM:31:@VM:32:@VM:41:@VM:41:@VM:42:@VM:43 

002: FIND 31 IN DA SETTING F,V,S THEN 

003: PRINT "F=":F:" V=":V:" S=":S 

004: END ELSE 

005: PRINT "NOT FOUND" 

006: END 

In the next example, the program segment searches for the second occurrence of 41 

in the string DA. This results in F=3, V=4, and S=0 because the second occurrence 

of 41 is found in the third attribute as the fourth multivalue, and this attribute has no 

subvalues. 

DA = 1:@AM:2:@AM:31:@VM:32:@VM:41:@VM:41:@VM:42:@VM:43 

FIND 41 IN DA,2 SETTING F,V,S ELSE PRINT "NOT FOUND" 

FIND 1-261



[], FINDSTR, LOCATE 


FINDSTR 

Syntax 

FINDSTR substr IN dyn.array[,occur] SETTING f[,v[,s]] {THEN statements | 

ELSE statements} 

Description 

The UniBasic FINDSTR command determines the position of a given substring in a 

dynamic array. FINDSTR supports multibyte languages. 

Parameters 



substr Specifies the substring to find. substr must be either a numeric value 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). 

FINDSTR Parameters 

FINDSTR 1-263


Examples 

In the following example, the program segment searches for 3 in the string DA. This 

results in F=3, V=1, and S=0 because 3 is found in the third attribute as the first multivalue, 

and this attribute has no subvalues. 


f,v,s Specifies variables in which to place the position of substr: 

f – Attribute 

v – Value 

s – Subvalue 

If the attribute found has neither multivalues nor subvalues, then v and s, 

if specified, are set to 0. If only multivalues are present, s is set to 0. If only 

subvalues exist, v is also set to 0. 

THEN 

statements 

ELSE 

statements 


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, and S=0 because 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" 



FIND, LOCATE 

Specifies statements to execute if the substr is found in the array. Either a 

THEN statement or an ELSE statement is required. 

Specifies statements to execute if the substr is not found in the array. Either 

a THEN statement or an ELSE statement is required. 

FINDSTR Parameters (continued)

FLUSH 

Syntax 

FLUSH 

The FLUSH command flushes output to the terminal when UDT.OPTIONS 

46 is on. 

Note: For more information about UDT.OPTIONS 46, see the UDT.OPTIONS 


FLUSH 1-265

FMT 

Syntax 

FMT(expr, "len [f.char] {L | R | T | C} [n] [$] [,] [Z] [mask]") 

FMT(expr, "{L | R | T | C} # len [f.char] [n] [$] [,] [Z] [mask]") 

expr "[L | R | T | C] # len [f.char] [n] [$] [,] [Z] [mask]" 

FMT(expr, pattern.var) 

Description 

The UniBasic FMT function formats data in expr for display purposes. FMT can 

format a dynamic array that contains multivalues. The statement can be no longer 

than 2,046 characters. 

In the first form of the syntax, L, R, C, or T and len are required. 

The second form is the same as the first form with the elements in a different order. 

The third form does not include the keyword FMT, but the elements are in the same 

order as in the second form. 

In the fourth form, you provide the pattern format in a variable, pattern.var. 

Note: The FMT function can produce different results based on the BASICTYPE 

setting. The parameter descriptions that follow represent BASICTYPE U. 


Parameters 



len Specifies the total number of single-byte characters to appear in the output 

string. 

f.char Specifies a single-byte fill character to be used if the formatted string is not 

long enough to fill len; the default is a space. Cannot be a multibyte character. 

Prefix a numeric f.char with \ to indicate it is the fill character. 

L Specifies left-justification in a string of len spaces. If the text is longer than 

len, the text is broken in len intervals. Has no effect in multibyte languages. 

R Specifies right-justification in a string of len spaces. Has no effect in 

multibyte languages. 

C Specifies centered text in the column of width len. Has no effect in multibyte 

languages. 

T Specifies text justification. If data must be broken to fit in a column, it is 

justified on a word basis (from space to space). Has no effect in multibyte 

languages. 

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 before the formatted string. Valid for numeric data only. 

, Prints numbers with commas separating each level of thousands. Valid for 

numeric data only. 

Z Specifies the suppression of leading zeros. 

mask Specifies a pattern mask composed of numbers and other characters. 

Numeric data is placed sequentially in the mask before justification. 

FMT Parameters 

FMT 1-267


After you execute FMT, the STATUS function returns one of the values described in 

the following table. 


0 Successful completion. 

Examples 

In the following example, the program segment prints the variable SS.NUM as a 

formatted string using a pattern mask. The result printed is a string with 11 characters, 

left-justified:“543-70-4128”. 


1 String expression is invalid or exceeds the allowable string size. 

2 Conversion code is invalid. 


SS.NUM=543704128 

PRINT FMT(SS.NUM,"11L###-##-####") 

In the next example, the program segment prints the variable NUM as a 12-character, 

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 rightjustified, 

eight column string: 

STR = STR "R#8"

In the next example, the program segment uses a variable to specify the pattern 

format. UniData formats STR according to the variable PATTERN: 

PATTERN = "12R2$," 

STR = STR PATTERN 

FMT 1-269

FOOTING 

Syntax 

FOOTING [ON num.expr] str.expr ['option']... 

Description 

The UniBasic FOOTING command causes the specified string to print or display at 

the bottom of each page of a report. You can specify a footer of any length. The ECL 

LIMIT command has no effect on this command. 

Note: Turn on UDT.OPTION 64 to force the footing to appear on the last page or 

screen. With this option turned off, the footing does not appear on the last page or 

screen. For more information about UDT.OPTION 64, see the UDT.OPTIONS 


The PRINTER command directs the output of a FOOTING command not sent to a 

print file as follows: 


PRINTER OFF causes a report, together with its footings, to appear on the 

user’s terminal screen. 

PRINTER ON causes all subsequent footings, headings, and PRINT output 

to be sent to the destination specified by the current SETPTR setting.

Parameters 



ON num.expr Specifies a print file to which you want to send the footing: 0–254. 

str.expr Specifies the string to display at the bottom of each page. 

option... option must be enclosed in single quotation marks. You can place 

option(s) anywhere in the footing expression. option can be any of the 

following: 

ASCII code – Passes to the printer or file code controlling paging 

characteristics. 

P or S – Prints current page number. 

N – Suppresses the pagination prompt 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 Parameters 

Examples 

In the following example, the program statement produces a footing using a character 

string: 

FOOTING "Copyright 1999, Genius, Inc." 

In the next example, the program statement prints Page and the current page number. 

It advances one line and then prints Paul’s Produce. Notice the two single quotation 

marks in the middle of the strings. They are necessary to print a single apostrophe in 

the footer. The ON 2 clause sends the footing to print file 2. 

FOOTING ON 2 "Page 'PL'Paul''s Produce" 

FOOTING 1-271



GETPTR, HEADING, PRINTER 

UniData 

SETPTR – For information, see the UniData Commands Reference. 


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 a select list 

that you can use with READNEXT statements or other list processing commands 

such as external LIST statements. 

Parameters 



dynamic.array.var Specifies a dynamic array from which to create a 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 four records in the CLIENTS file: 

ARRAY.LIST = 9999:@AM:10034:@AM:9980:@AM:10015 

FORMLIST ARRAY.LIST TO 0 

PRINT "PROCESSING THE FOLLOWING ITEMS:" 

PERFORM "LIST CLIENTS NAME COMPANY" 

END 

FORMLIST 1-273

This program segment produces the following results: 


LIST CLIENTS NAME COMPANY 17:33:03 Apr 27 1999 1 

CLIENTS... Name.......................... Company 

Name.................. 

9999 Paul Castiglione Chez Paul 

10034 Fredrick Anderson Otis Concrete 

9980 Beverly Ostrovich Riley Architects 

10015 Cal di Grigorio Regina Flooring 

4 records listed 



DELETELIST, READLIST, SELECT, SELECTINDEX, SELECTINFO, 

WRITELIST 

UniQuery 

DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST – For information, see 


UniData SQL 

SELECT – For information, see the UniData SQL Commands Reference.

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 incrementing 

a variable over a range until it reaches the end of the range, or until the 

condition in the WHILE or UNTIL clause is achieved. You can nest FOR/NEXT 

constructions. Each FOR statement must end with a NEXT statement. 

FOR/NEXT should be constructed so termination occurs based on the WHILE or 

UNTIL condition. Use the CONTINUE statement to transfer control to the next 

iteration of the command. 

Parameters 



var Specifies the variable to increment. 

val1 Specifies the beginning of the range for incrementing var. 

val2 Specifies the end of the range for incrementing var. 

STEP val3 Specifies the change to use in incrementing var. The increment can be 

negative or positive, making the variable decrease or increase. 

FOR/NEXT Parameters 

FOR/NEXT 1-275


Examples 


“Sample Program,” in Developing UniBasic Applications. This segment prints multivalues 

from the ORDERS file when a client has ordered multiple items. 


statements Specifies the statements to carry out for each loop. 

UNTIL | 

WHILE expr 

statements 

Specifies a condition, expr, to test after each loop. If the UNTIL keyword 

is used, the loop continues until expr is true. If the WHILE keyword is 

used, the loop continues until expr is not 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. The optional var is the same variable as in the beginning of the 

FOR/NEXT statement. 

FOR/NEXT Parameters (continued) 

DISPLAY_DATA: 



. 

. 

. FOR ENTRY = 1 TO NUM_ENTRIES 

PRODUCT_NUMBER = ORDER.REC 

COLOR = ORDER.REC 

QUANTITY = ORDER.REC 


IF PRODUCT_LINE = '' THEN 

PRODUCT_LINE = PRODUCT_NUMBER "R#10" 

COLOR_LINE = COLOR "R#10" 

QUANTITY_LINE = QUANTITY "R#10" 

PRICE_LINE = PRICE "R#10" 

END ELSE 

PRODUCT_LINE := " ":PRODUCT_NUMBER "R#10" 

COLOR_LINE := " ":COLOR "R#10" 

QUANTITY_LINE := " ":QUANTITY "R#10" 

PRICE_LINE := " ":PRICE "R#10" 

END 

NEXT ENTRY

In the following example, the program segment prints the string 10,8,6,4,2,. The loop 

terminates before printing 0 because 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 

condition 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, I is less than K, satisfying the 

condition 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 



CASE, LOOP/REPEAT 

FOR/NEXT 1-277

FUNCTION 

Syntax 

FUNCTION function.name [([MAT] arg.1[, [MAT] arg.2]...)] 

RETURN var 

Description 

The UniBasic FUNCTION command begins the definition of a user-written 

function. The FUNCTION command must be the first noncomment line in the file, 

which must be cataloged locally or globally. 

The cataloged file name must be included in the DEFFUN statement in the calling 

program. 

The calling program must specify the same number and type of arguments in the 

calling statement as are included in the FUNCTION statement. 

Note: UniData triggers are UniBasic subroutines or functions that are called when 

a user attempts to update or delete a record. For more information about coding a 

UniBasic function that is called by a trigger, see Developing UniBasic Applications. 


Parameters 



function.name Specifies the name of the function (for documentation purposes 

only). It need not be the same as the name used to call the 

function. 

You must include this function’s cataloged file name in the 

DEFFUN statement in the calling program. 

(MAT arg.1 ,MAT 

arg.2...) 

Examples 

Specifies the arguments to be passed from the calling program. 

Arguments must be enclosed in parentheses and separated by 

commas. Precede an argument with MAT to indicate that the 

argument is an array. Up to 254 arguments can be passed. 

RETURN var Returns control to the calling program. Can pass back an 

argument. 

FUNCTION Parameters 

The following function performs calculations on a dimensioned array, returning 

values in the function arguments and return value, r. The name of the cataloged file 

that contains this function definition is yourfunc. This name must be used in the 

DEFFUN statement in the calling program. Notice that the function definition uses 

yet a different name (anotherfunc). The name anotherfunc is not referenced 

anywhere. 

FUNCTION anotherfunc(a, MAT b, c) ;* Start function 

definition. 

DIM b(-1) ;* Declare array. 

r = 0 ;* Initialize return value. 

c = 1 ;* Initialize value passed 

back. 

FOR i = 1 TO a ;* To the upper bound passed 

in: 

r += b(i) ;* Sum array members. 

c *= b(i) ;* Multiply array members. 

NEXT i 

RETURN r ;* Return value. 

FUNCTION 1-279

The following program calls the preceding function. Because the function is called 

myfunc within this program, the CALLING clause is included in the DEFFUN 

statement to identify the cataloged program file yourfunc. Note that values in 

arguments a and b are passed back, although they are not used by the program. 


DEFFUN myfunc(a, MAT b, c) CALLING "yourfunc" ;* Declare function. 

DIM b(10) ;* Define array. 

a = 2 ;* Set upper bound. 

FOR i = 1 TO a ;* Initialize array. 

b(i) = i 

NEXT i 

PRINT "r from FUNCTION: ":myfunc(a, MAT b, c) 

PRINT "c from FUNCTION: ":c 

The program runs and prints out the following text: 

:RUN BP FUNCTION.CALL 

r from FUNCTION: 3 

c from FUNCTION: 2 



DEFFUN

GARBAGECOLLECT 

Syntax 

GARBAGECOLLECT 

Description 

The UniBasic GARBAGECOLLECT command releases all reserved but nonactive 

memory allocated for UniBasic variables. 

1-281

GE 

Syntax 

expr1 GE expr2 

Synonyms 

#, >= 

Description 

The UniBasic >= relational operator tests whether expression expr1 is greater than or 

equal to expr2. 



statements like the following: 


IF VAR1 GE VAR2 THEN GOSUB SUB1 

DO UNTIL VAR1 >= VAR2 

Example 

In the following example, the program segment tests whether A is greater than or 

equal to B. Because 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



GES 

1-283

generateKey 

Syntax 

generateKey(priveKey, pubKey, format, keyLoc, algorithm, keyLength, passPhrase, 

paramFile) 



Description 

The generateKey() function generates a public key cryptography key pair and 

encrypts the private key. You should then put it into an external key file protected by 

the provided pass phrase. UniData SSL sessions can use the protected private key 

later to secure communication. The public key will not be encrypted. 

The generated private key will be in PKCS #8 form and is encoded in either PEM or 

DER format specified by format. The generated public key is in traditional form. If 

keyLoc is 1, the resulted key is put into a dynamic array in privKey and pubKey. 

Otherwise, they are put into OS level files specified by privKey and pubKey. 

To make sure the private key is protected, you must provide a pass phrase. UniData 

uses a one-way hash function to derive a symmetric key from the pass phrase to 

encrypt the generated key. When installing the private key into a security context with 

the setPrivateKey() function, or generating a certificate request with the generate- 

CertRequest() function, you must provide this pass phrase to gain access to the 

private key. 

For detailed information about the generateKey function, see UniBasic Extensions. 


Parameters 



privKey A string storing the generated private key or name of the file storing the 

generated private key. 

pubKey A string storing the generated public key or name of the file storing the 

generated public key. 

format 1 - PEM 

2 - DER 

keyLoc 1 - Put the key into string privKey/pubKey. 

2 - Put the key into a file. 

algorithm 1 - RSA 

2 - DSA 

keyLength Number of bits for the generated key. Between 512 and 2048. 

passPhrase A string storing the pass phrase to protect the private key. 

paramFile A parameter file needed by DSA key generation. 

generateKey Parameters 


Return 

Code Status 

0 Success. 

1 Key pair cannot be generated. 

2 Unrecognized key file format. 

3 Unrecognized encryption algorithm. 

4 Unrecognized key type or invalid key length (must be between 512 and 

2048). 

5 Empty pass phrase. 

generateKey Return Codes 

1-285

Return 

Code Status 


6 Invalid DSA parameter file. 

7 Random number generator cannot be seeded properly. 

8 Private key cannot be written. 

generateKey Return Codes (continued)

GES 

Syntax 

GES(array1,array2) 

Description 

The UniBasic GES function compares each value in array1 to its corresponding 

value in array2. UniData returns an array with 1 in each position where the value in 

array1 is greater than or equal to the value in the corresponding position in array2. 

UniData returns 0 in each position for values that are less than array2. 

Example 

In the following example, the program segment compares ARRAY1 to ARRAY2 and 

returns ARRAY3. ARRAY3 then contains 1}1}1}0}0. 

ARRAY1 = 10:@VM:20:@VM:30@VM:40:@VM:50 

ARRAY2 = 9:@VM:10:@VM:30:@VM:50:@VM:60 

ARRAY3 = GES(ARRAY1,ARRAY2) 

1-287

GET 

Syntax 

GET[X] var[,length] [SETTING count.var] FROM line.expr [UNTIL term.expr] 

[RETURNING term.var] [WAITING seconds] 

[THEN statements |ELSE statements] 

Description 

The UniBasic GET command receives unprompted input from an attached line. 

UniData accepts all control characters, including the carriage return and line feed as 

input characters. All data read from the attached line is placed in var. GET supports 

multibyte languages. 

Performance of the GET statement varies according to the termination conditions 

specified, and whether the THEN or ELSE clauses are specified. 

Input from the attached line is terminated in four ways: 

UniData has read the number of characters specified in length. 

After a single character is read (when length and UNTIL are not coded). 

When any character you specify in term.exp is encountered in input. 

When UniData reads the record mark character, @RM, and the number of 

seconds has elapsed. 

Note: UniData never executes the ELSE clause if you include UNTIL without 

WAITING or length. 

If you code the WAITING clause, UniData executes the ELSE clause only after the 

number of seconds specified for timeout. If the input is terminated for any other 

reason, UniData executes the THEN clause. 

In special cases, UniData executes the ELSE clause if the line has not been attached 

before executing the GET statement. 


Parameters 



X Specifies that GET return var as hexadecimal. 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 the number of characters to accept as input from the 

attached line. The default is one character unless you use 

UNTIL in the statement. 

SETTING count.var count.var is the number of characters received from the 

attached line. 

FROM line.expr line.expr is the attached line receiving input. 

UNTIL term.expr term.expr is a string of characters, any of which terminate 

input. The terminating character does not appear in the 

returned text variable. 

If you use UNTIL and do not specify term.expr, any number of 

characters is accepted. Characters often used for the UNTIL 

clause are carriage return and line feed. 

RETURNING term.var Assigns the character that terminates the input to term.var. 

Input terminates due to: 

Reaching the maximum number of characters. 

Timeout. 

Record mark encountered in input. In this case, term.var 

contains an empty string. 

WAITING seconds Specifies the number of seconds to wait before UniData times 

out. 

THEN 

statements | ELSE 

statements 

If the line is not attached, UniData performs the ELSE clause. 

If the line is not attached and there is not an ELSE clause, a 

runtime error displays and the user enters the UniBasic 

debugger. 

GET Parameters 

1-289

Example 

In the following example, the program segment waits 15 seconds for 10 characters of 

input from line 0. If time expires before 10 characters are received from the attached 

line, UniData stops receiving, returns the data received, and performs the ELSE 

clause. 


GET TMP,10 FROM 0 WAITING 15 

ELSE PRINT "Input time has expired" 



SEND 

UniData 

PROTOCOL – For information, see the UniData Commands Reference.

getCipherSuite 

Syntax 

getCipherSuite(context,ciphers) 



Description 

The getCipherSuite() function obtains information about supported cipher suites, 

their version, usage, strength and type for the security context you specify. The result 

is put into the dynamic array ciphers, with one line for each cipher suite, separated 

by a field mark (@FM). The format of the string for one cipher suite is as follows. 

Suite, version, key-exchange, authentication, encryption, digest, 

export 

Refer to the cipher tables in UniBasic Extensions for definitions of all suites. The 

following is an example of a typical Suite. 

EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 

export 

The suite is broken down as follows. The suite name is EXP-DES-CBC-SHA. It is 

specified by SSLv3. The Key-exchange algorithm is RSA with 512-bit key. The 

authentication is also done by RSA algorithm. The Data encryption uses DES (Data 

Encryption Standard, an NIST standard) with CBC mode. MAC (Message Authentication 

Code, a hash method to calculate message digest) will be done with SHA-1 

(Secure Hash Algorithm 1, also an NIST standard) algorithm. The suite is exportable. 

UniData only retrieves those methods that are active for the protocol. 

1-291

Parameters 






ciphers A Dynamic array containing the cipher strings delimited by @FM. 

getCipherSuite Parameters 

Return 

Code Status 

0 Success. 


2 Unable to obtain information. 

Return Code Status

GETENV 

Syntax 

GETENV(var | "envir.var") 

Description 

The UniBasic GETENV function returns the contents of the UNIX, or Windows 

platform environment variable. If you include the environment variable explicitly (as 

opposed to including it in a variable), you must enclose it in quotation marks. 

Examples 

In the following example, the program statement retrieves the value of UDTBIN in 

X: 

X = GETENV("UDTBIN") 

In the next example, the program retrieves the value of UDTBIN in X, but uses a 

variable to define UDTBIN: 

VAR = "UDTBIN" 

X = GETENV(VAR) 

1-293

getHTTPDefault 

Syntax 

getHTTPDefault(option, value) 



Description 

The getHTTPDefault function returns the default values of the HTTP settings. See 

the section under setHTTPDefault for additional information. 

Parameters 

The following table describes each parameter of the syntax: 



option Currently, the following options are defined: 

PROXY_NAME 

PROXY_PORT 

VERSION 

BUFSIZE 

AUTHENTICATE 

HEADERS 

value A string containing the appropriate option value. 

getHTTPDefault Parameters


Return 

Code Status 

0 Success. 

1 Invalid option. 


1-295

GETLIST 

Syntax 

GETLIST list.name [,acct.name] [TO list.num] [SETTING count.var] 

{THEN | ELSE} statements [END] 

Description 

The UniBasic GETLIST command restores a select list from a saved list. 

Tip: Use GETLIST to access a list without having to issue multiple SELECT or 

SSELECT commands. 

Parameters 




list.name Specifies the saved list. 

acct.name Specifies a full path of a directory where the list resides if 

list.name is not in the current account. 

TO list.num Specifies the number of the active list. list.num can be 0 through 

9. The default list is 0. 

SETTING count.var Specifies a variable to contain the number of elements the 

GETLIST command generates. 

THEN | ELSE 

statements 

Specifies statements to execute if the command succeeds 

(THEN) or fails (ELSE). Either a THEN or an ELSE statement 

is required. END is required to terminate multiline statements. 

GETLIST Parameters

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 is not 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 creates a select list and saves it. GETLIST 

then retrieves the saved list to active list 0 (the default). The program then uses the 

IDs in list 0 to retrieve the first 22 Canadian clients. 




GETLIST 'canadians' 

ELSE PRINT "SELECT LIST CANNOT BE FOUND";STOP 

PRINT @(-1) 

FOR I = 1 TO 22 




END ELSE 


END 

NEXT I 

CLEARSELECT 

END 



DELETELIST, FORMLIST, READLIST, READNEXT, SELECT, SELECT- 

INDEX, SELECTINFO, WRITELIST 

UniQuery 



1-297

UniData SQL 



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. 

Tip: GETPTR can store the values associated with a print unit so those values can be 

reset to their initial values at the end of a process. 

GETPTR Function Return Values 

The GETPTR function returns a string containing the same set of values as specified 

in the ECL SETPTR function, including the print unit and the options. The following 

table describes these values. 

Return Description 

unit The number assigned to a given printer through UniData, from 0 through 

255. (The default is 0.) 

width The number of characters per line, from 0 to 256 characters. 

length The number of lines per page, from 1 to 32,767 lines. 

topmargin The number of lines to leave blank at the top of each page, from 0 to 25. 

bottommargin The number of lines to leave blank at the bottom of each page, from 0 to 

25. 

mode Destination of output. For mode values, see SETPTR in the UniData 


options Print options such as BANNER, COPIES, NHEAD, and FORM. For 

option values, see SETPTR in the UniData Commands Reference. 

GETPTR Function Return Values 

1-299


After you execute GETPTR, the STATUS function returns one of the values 


Example 

In the following example, the program segment assigns the printer settings to the 

variable PRINTER.STRING: 

PRINTER.STRING = GETPTR(1) 


UniData 




0 If success. 

1 If there are no more rows. 

2 Other error. 

STATUS Function Return Values

GETPU 

Syntax 

GETPU(unit.number) 

Description 

The UniBasic GETPU function returns the full path of the current print or hold file 

ID created by the current user process. unit.number is the number of the logical 

printer unit. 

Tip: Use the ECL SETPTR command to determine the current printer unit of your 

system. 



GETPTR 

UniData 


1-301

GETQUEUE 

Syntax 

GETQUEUE() 

Description 

The UniBasic GETQUEUE function returns a dynamic array containing information 

about all records currently locked and waiting to be released. 

UniBasic commands that check for locks, such as READU and READVU, cause 

processes to wait for locks to be released before proceeding. 

This command delivers the same information as the ECL command LIST.QUEUE, 

but in a different format. A value mark separates these pieces of information. An 

attribute mark separates the information about different locks. 

If GETQUEUE is successful, UniData sets @SYSTEM.RETURN.CODE to the 

number of locks waiting to be released. If unsuccessful, UniData sets 

@SYSTEM.RETURN.CODE to -1. 

Note: UniBasic locks are advisory only. For more information, see Developing 


GETQUEUE Function Return Values 

The GETQUEUE function returns the values described in the following table. 



UDTNO The number of the UniData process that locked the file. 

USERNBR The ID of the process that ran the UniData application that locked the 

file. 

UID The user ID of the user who ran the UniData application that locked the 

file. 

GETQUEUE Function Return Values


USERNAME The user name of the user who ran the UniData application that locked 

the file. 

TTY The terminal ID of the user who ran the UniData application that locked 

the file. 

FILE NAME The name of the locked file. 

INBR The i-node number used by the locked file. 

For Windows platforms, this value consists of the high integer and low 

integer of the i-node used by the locked file. The high integer and the 

low integer are separated by a space. 

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. 

GETQUEUE Function Return Values (continued) 

1-303

GETREADU 

Syntax 

GETREADU() 

Description 

The UniBasic GETREADU function returns a dynamic array containing information 

about all records that have been locked by any UniBasic or ECL command 

that updates any record. 

This command delivers the same information as the ECL command LIST.READU, 

but in a different format. A value mark separates these pieces of information. An 

attribute mark separates the information about different locks. 

If GETREADU is successful, UniData sets @SYSTEM.RETURN.CODE to the 

number of locks set. If unsuccessful, UniData sets @SYSTEM.RETURN.CODE to 

-1. 

Note: UniBasic locks are advisory only. For more information, see the Developing 


GETREADU Function Return Values 


The GETREADU function returns the values described in the following table. 


UDTNO The number of the UniData process that locked the file. 

USERNBR The ID of the process that ran the UniData application that locked the 

file. 

UID The user ID of the user who ran the UniData application that locked the 

file. 

USERNAME The user name of the user who ran the UniData application that locked 

the file. 

TTY The terminal ID of the user who ran the UniData application that locked 

the file. 

FILE NAME The name of the locked file. 

INBR The i-node number used by the locked file. 

For Windows platforms, this value consists of the high integer and low 

integer of the inode used by the locked file. The high integer and the low 

integer are separated by a space. 

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. 

TIME The time the lock was set. 

DATE The date the lock was set. 

GETREADU Function Return Values 

1-305

getResponseHeader 

Syntax 

getResponseHeader(request_handle, header_name, header_value) 



Description 

This function gets a specific response header value from response headers returned 

by submitRequest(). It can be used to query if a specific header, for example, 

Content-encoding, is present in the response. 

Parameters 






header_name A string containing a response header name. 

header_value The value of the header, if present. Otherwise, an empty string. 

getResponseHeader Parameters 


0 Success. 


2 Header not found. 

get ResponseHeader Return Code

getSocketInformation 

Syntax 

getSocketInformation(socket_handle, self_ or_ peer, socket_info) 



Description 

Use the getSocketInformation function to obtain information about a socket 

connection. 

Parameters 



socket_handle The handle to the open socket. 

self_ or_ peer Get information on the self end or the peer end of the socket. Specify 0 

to return information from the peer end and non-zero for information 

from the self end. 

socket_info Dynamic Array containing information about the socket connection. 

For information about the elements of this dynamic array, see the 


getSocketInformation Parameters 

1-307

The following table describes each element of the socket_info dynamic array. 



Element Description 

1 Open or closed 

2 Name or IP 

3 Port number 

4 Secure or Non-secure 

5 Blocking mode 

getSocketInformation Parameters 


0 Success. 


getSocketInformation Return Codes

getSocketOptions 

Syntax 

getSocketOptions(socket_handle, Options) 



Description 

The getSocketOptions function gets the current value for a socket option associated 

with a socket of any type. 

1-309

Parameters 



The following table describes the available options (case-sensitive) for 

getSocketOptions(). 


socket_handle The socket handle from openSocket(), acceptSocket(), or 

initServerSocket(). 

options A Dynamic Array containing information about the socket options and 

their current settings. When querying for options, the dynamic array is 

configured as: 

optName1 

optName2 

optName... 

When the options are returned, the dynamic array is configured as: 

optName1optValue1a[optValue1b] 


optName3... 

Where optName contains an option name string listed below. The first 

optValue describes if the option is ON or Off and must be one of two 

possible values: “1” for ON or “2” for OFF. The second optValue is 

optional and may hold additional data for a specific option. Currently, 

for option “LINGER”, it contains the delayed time (in milliseconds) 

before closing the socket. 

getSocketOptions Parameters 


DEBUG Enable/disable recording of debug information. 

REUSEADDR Enable/disable the reuse of a location address (default). 

KEEPALIVE Enable/disable keeping connections alive. 

DONTROUTE Enable/disable routing bypass for outgoing messages. 

LINGER Linger on close if data is present. 

getSocketOptions Options


BROADCAST Enable/disable permission to transmit broadcast messages. 

OOBINLINE Enable/disable reception of out-of-band data in band.. 

SNDBUF Get buffer size for output (default 4KB). 

RCVBUF Get buffer size for input (default 4KB). 

TYPE Get the type of the socket. 

ERROR Get and clear error on the socket. 

getSocketOptions Options (continued) 



0 Success. 


getSocketOptions Return Codes 

1-311

GETUSERGROUP 

Syntax 

GETUSERGROUP(uid) 

Description 

For UNIX, the UniBasic GETUSERGROUP function returns the group number for 

the user ID you specify by uid. For Windows platforms, it returns 0. 

Examples 

In the following example, the program statement assigns the user group to variable X: 

X = GETUSERGROUP(@UID) 

In the next example, the program statement assigns the user group for 1023 to 

variable X: 

X = GETUSERGROUP(1023) 



GETUSERID, GETUSERNAME 


GETUSERID 

Syntax 

GETUSERID(user.name) 

Description 

The UniBasic GETUSERID function returns the user ID for a user name. For UNIX, 

this is the system-recognized user ID. For Windows platforms, the returned user ID 

is meaningful in UniData only. 

Example 

In the following example, the program statement assigns the user ID for “John” to 

variable X: 

X = GETUSERID("John") 



GETUSERGROUP, GETUSERNAME 

1-313

GETUSERNAME 

Syntax 

GETUSERNAME(uid) 

Description 

The UniBasic GETUSERNAME function returns the user name for a user ID. To 

obtain the ID of the current user, use the UniBasic @UID variable (or, for UNIX, 

enter “id” at the UNIX prompt). After you obtain the user ID, you can specify it 

explicitly in the GETUSERNAME function. 

Examples 

In the following example, the program statement assigns the user name to variable X: 

X = GETUSERNAME(@UID) 

In the next example, the program statement assigns the user name for 1023 to variable 

X: 

X = GETUSERNAME(1023) 



GETUSERGROUP, GETUSERID 


GOSUB 

Syntax 

GOSUB label[:] 

Description 

The UniBasic GOSUB command transfers program control to an internal subroutine. 

UniData requires a valid statement label. Control returns to the main program when 

the RETURN statement is encountered in the subroutine. 

Examples 


“Sample Program,” in Developing UniBasic Applications. This is an example of 

subroutines used in structured programming style. 

*-------------- Main Logic ----------------------------- 

GOSUB INITIALIZE 

LOOP 

GOSUB DISPLAY_SCREEN 

GOSUB GET_ORDER_NUMBER 

UNTIL ORDER_NUMBER[1,1] = 'Q' 

GOSUB DISPLAY_DATA 

IF RECORD_FOUND THEN GOSUB GET_RECORD_COMMAND 

RELEASE 

REPEAT 

GOSUB EXIT 

In the next example, the program segment prints: 

“Now we go to the subroutine.” 

“Now in subroutine BRANCHOUT.” 

1-315


“Back from subroutine BRANCHOUT.” 

PRINT "Now we go to the subroutine." 

GOSUB BRANCHOUT 

PRINT "Back from subroutine BRANCHOUT." 

STOP 

BRANCHOUT: 

PRINT "Now in subroutine BRANCHOUT." 

RETURN 

END 



GOTO, ON/GOSUB, RETURN

GOTO 

Syntax 

GOTO label [:] 

Synonym 

GO 

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. After 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. 

You cannot use the UniBasic RETURN command in conjunction with a GOTO 

statement. 

Tip: Use GOSUB instead of GOTO to make your programs easier to follow and 

maintain. 

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 

1-317



GOSUB, ON/GOTO 


GROUP 

Syntax 

GROUP(str, delim, start, rtn.num) 

Description 

The UniBasic GROUP function extracts the number of continuous groups you 

specify from the given string. 

GROUP functions similar to option G of the OCONV Group (G) function (group 

extraction conversion), but allows any single character, including a system delimiter, 

null value, number, or minus sign (-) as a delimiter. Another difference is that 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 finishes after the entire remaining string is exhausted. 

GROUP Parameters 

1-319

Examples 

In the following example, the program statement assigns 1231 to the variable A: 


A = GROUP("123124125126","2",1,2) 

In the next example, the program segment prints “Boulder” because it is the second 

group separated by ‘:’, and only one group is returned: 

ST = "Denver:Boulder:Aurora:Littleton" 

PRINT GROUP(ST,':',2,1) 



FIELD, OCONV Group (G)

GROUPSTORE 

Syntax 

GROUPSTORE substr IN str USING start.num,replace.num [,delimiter] 

Description 

The UniBasic GROUPSTORE command inserts a given substring or portion of a 

substring into a string, and replaces all, part, or none of the string. The string can be 

delimited by the single character delimiter. The unit of replacement is called an 

element in this section. 

Parameters 



substr Specifies the substring you want to insert into the string. substr can contain 

any combination of numeric, alphabetic, or special characters. 

str Specifies the target string into which substr is inserted. 

GROUPSTORE Parameters 

1-321


The replace.num option controls whether GROUPSTORE replaces all, part, or none 

of the substring. The following table describes these options. 


start.num Specifies the position from which to begin replacing elements of the string. 

start.num must be at least 1. If you specify a value of less than 1, start.num 

defaults to 1. If start.num is negative and replace.num is not negative, 

UniBasic uses the absolute value of start.num. 

If start.num is greater than the number of elements in the target string, 

UniBasic appends the substr to the end of the string with the appropriate 

number of delimiters in between. 

replace.num Specifies the number of elements in the string to replace with elements of 

substr. 

Refer to the next table for values for replace.num. 

,delimiter Specifies a single ASCII character to use as a delimiter. The default 

delimiter is @AM. If you specify more than one character for delimiter, 

UniBasic uses the first character. 

replace.nu 

m Value Description 

GROUPSTORE Parameters (continued) 

> 0 The first replace.num elements of the substr replaces elements of the string 

starting from the position specified by start.num. If the string contains fewer 

than replace.num elements starting from start.num, the replacement stops 

after the string is exhausted. 

0 The entire substr is inserted before the start.num position in the string. 

< 0 The number of elements specified in replace.num are deleted starting at 

start.num, and substr replaces them. 

If both start.num and replace.num are less than 0, replacement does not take 

place. Only the number of elements specified in replace.num are deleted, 

starting at start.num. 

GROUPSTORE Replace Number Values

Examples 

In the following example, the program segment assigns the value stored in string 

SUB in string A. Because the starting number is 2, and no delimiter is specified, 

UniData uses the attribute mark (@AM) 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" 

In the next example, the program segment replaces both values in the third attribute 

in A with SUB. Though the replacement number is 2, UniData replaces only one 

attribute because SUB has only one element. 


SUB = "###" 



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" 



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 


A = "mv1":@AM:"sub1":@AM:"sub2":@VM:"GHI" 

1-323

This next example compiles and runs only with null value handling turned on. The 

program segment replaces the third element with three asterisks. This program 

segment calls the externally cataloged subroutine PRINT.SETUP, which converts the 

null value and UniData delimiters to printable characters, and then prints the 

converted string. 


PRT.STR = '' 

A 

="123":@AM:"ABC":@AM:"456":@VM:"DEF":@VM:@NULL:@AM:"012":@VM:@NULL 

:@VM:"GHI" 

SUB = "***" 

GROUPSTORE SUB IN A USING 3,1,@VM 

STR = A 

CALL PRINT.SETUP(STR,PRT.STR) 

PRINT "A = ":PRT.STR 

This program segment prints: 

A = 123@AMABC@AM456@VMDEF@VM***@VM@NULL@VMGHI

GT 

Syntax 

expr1 GT expr2 

Synonym 

> 

Description 

The UniBasic relational operator GT tests whether expression expr1 is greater than 

expr2. 



statements such as the following: 

IF VAR1 GT VAR2 THEN GOSUB SUB1 

DO UNTIL VAR1 > VAR2 

Example 

In the following example, the program segment tests whether A is greater than B. 

Because 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 

1-325



GTS 


GTS 

Syntax 

GTS(array1,array2) 

Description 

The UniBasic GTS function compares each value in array1 to its corresponding 


array1 is greater than the value in the corresponding position in array2, and 0 in each 

position for values that are less than array2. 

Example 





ARRAY3 = GTS(ARRAY1,ARRAY2) 

1-327

HASH 

Syntax 

HASH(rec.key,modulo,type) 

Description 

The UniBasic HASH function determines to which group a particular record key is 

hashed, depending on the modulo and the file type. 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, HASH returns the group 

number 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 For the file being tested, specifies static or dynamic and hash type, as determined 

when the file was created. You can use the following types: 

0 – Test a static file with hash type 0 

1 – Test a static file with hash type 1 

64 – Test a dynamic file with hash type 0 

65 – Test a dynamic file with hash type 1 

HASH Parameters

HEADING 

Syntax 

HEADING [ON expr] str.expr ['option']... 

Description 

The UniBasic HEADING command prints a string you specify at the top of each 

report page on the current print device. 

Note: The HEADING command clears the screen before displaying a report. 

HEADING 1-328

Parameters 



Examples 

In the following example, the HEADING statement sends a heading to print file 3: 

“current page number Shareholders Report current date”. 


ON expr Directs UniData to send output to print file expr. As many as 31 print files 

can be active at a time. The print files can have identifiers of 0–254. 

str.expr Specifies a string to print at the top of each report page. You can use special 

characters, such as unmatched single and double quotation marks, in 

str.expr. 

'option' option must be enclosed in single quotation marks. You can place option(s) 

anywhere in the heading expression. option can be any of the following: 

ASCII code – Passes code controlling paging characteristics. 

P or S – Prints current page number. 

N – Suppresses the pagination prompt after each page. 

L – Advances one line. Used for 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. 

W – Causes a page to fill completely before breaking and printing the 

heading when the HEADING statement is first encountered. If you do not 

specify W, UniData creates a new page break when it first encounters the 

HEADING statement. 

HEADING Parameters 

HEADING ON 3 "'P' Shareholders Report 'D'" 

In the next example, the HEADING 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. 



FOOTING, GETPTR, PRINTER 

UniData 


HEADING 1-330

HUSH 

Syntax 

HUSH {ON | OFF | expr} [SETTING pre.status.var] 

Description 

The UniBasic HUSH command enables or disables terminal output. 

Parameters 




ON Disables the terminal output. 

OFF Enables the terminal output. 

expr Disables the terminal output if expr is not 0. Enables terminal output if 

expr is 0. expr must be a numeric value. 

SETTING 

pre.status.var 

The SETTING clause sets the previous terminal status (1 for ON and 0 for 

OFF) to pre.status.var. 

HUSH Parameters

Example 

In the following example, the program segment prints 1 and -1 on the terminal screen 

because the HUSH command enables the terminal (A + B evaluates to 0). The second 

PRINT statement produces nothing on the screen because HUSH ON is set. The third 

PRINT command prints C = 1 on the screen because 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 

HUSH 1-332

ICONV 

Syntax 

ICONV(expr,conv.code.expr) 

Description 

The UniBasic ICONV function converts string or numeric data to internal representation 

format based on conversion codes. ICONV supports multibyte languages. If 

the input value or conversion code is invalid, UniData returns the input value. 

With null value handling turned on, the presence of the null value in data produces a 

result of the null value, and the STATUS function return value is set to 5. 

Note: In BASICTYPE P, ICONV returns an empty string if UDT.OPTIONS 56 is on 

and the input value or conversion code is invalid. 

Parameters 




expr Specifies the expression (a string or numeric data) to convert. 

conv.code.expr Specifies an internal representation format to use when converting expr. 

ICONV Parameters

The following table summarizes the valid conversion codes. A detailed discussion of 

each follows under separate headings. 

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. 

ME Masked extended. 

ML Left justify. 

MP Packed decimal. 

MP1 Convert to packed decimal without truncating at the first CHAR(0) or altering 

this character. 

MO Octal. 

MR Right justify. 

MT System time. 

MX Hexadecimal. 

P Pattern match. 

R Range. 

S SOUNDEX. 

T Text extraction. 

Tfile File translation. 

ICONV Codes 

ICONV 1-334


After you execute ICONV, the STATUS function returns one of the values described 

in the following table. 

Examples 

The following program segment demonstrates the date and time conversions: 


ORDER.REC = ICONV(ORDER_DATE,"D") 

ORDER.REC = ICONV(ORDER_TIME,"MT") 


“Sample Program,” in Developing UniBasic Applications. It demonstrates the 

alternate syntax that does not use the ICONV function name. This code right-justifies 

a string of 10 characters so that the data lines up on the right. 

PRODUCT_LINE := " ":PRODUCT_NUMBER "R#10" 

COLOR_LINE := " ":COLOR "R#10" 

QUANTITY_LINE := " ":QUANTITY "R#10" 

PRICE_LINE := " ":PRICE "R#10" 



OCONV 


0 Successful conversion. 

1 Invalid input data. 

2 Invalid conversion specification. 

3 Invalid date for “D” conversion code only. 

5 Null value if null value handling is turned on. 


ICONV Date (D) 

Syntax 

ICONV(ext.date, "D [y] [c]") 

Description 

The ICONV date (D) function converts display representations of dates into simple 

integer internal format. Internal date format is the number of days before or since 

December 31, 1967. If the input value or conversion code is invalid, UniData returns 

the input value. 

Note: UniData ignores leading and trailing spaces around the input date. 

In BASICTYPE P, ICONV returns an empty string if UDT.OPTIONS 56 is on and the 

input value or conversion code is invalid. 

Parameters 


Paramete 

r Description 

ext.date Specifies the date, in display format, to convert to internal format. Valid 

delimiters include the slash, comma, hyphen, and period. 

D Indicates a date conversion. 

y c The ICONV function does not use y and c, but they are accepted to maintain 

consistency with the OCONV Date (D) function. 

ICONV Date Parameters 

Points to Remember When Entering Dates 

To avoid unexpected results when you convert dates into internal date format by 

using ICONV, be aware of the following: 

ICONV Date (D) 1-336


If you do not enter a year, UniData defaults to the current year. For example, 

if you enter 12/1 and the year is 1996, UniData stores 10563 (12/1/96). 

If you enter a number between 1 and 12 for month, UniData defaults to the 

first day of the month in the current year. For example, if you enter just 12 

during 1996, UniData stores 10563 (12/1/96). 

Any two-digit year entered in the range 00–29 defaults to the twenty-first 

century. For example, UniData interprets 12/31/29 as December 31, 2029. 

Any two-digit year entered in the range 30–99 is considered to be 1930– 

1999. 

Converting More Than Once 

Depending on the date range, if an application performs ICONV on an already 

converted date, UniData could produce unexpected results. Dates that convert into 

four- or five-digit internal formats and meet the following conditions fall into this 

category: 

The first two digits are 10, 11, or 12. 

The second two digits are 01 through 31. 

The fifth digit is any number from 0 through 9. Where there is no fifth digit, 

UniData assigns the current year. 

For example, assuming 5/28/95 is the input, the code segment shown on the left 

results in the displays on the right: 

INPUT VAR 

VAR=ICONV(VAR,'D') 

PRINT VAR 10010 

PRINT OCONV(VAR,'D') 28 MAY 1995 

VAR=ICONV(VAR,'D') 

PRINT VAR 11963 

PRINT OCONV(VAR,'D') 01 OCT 2000 

The first ICONV returns a value of 10010. OCONV correctly returns the external 

format. The date matches the initial entry. However, the second ICONV accepts the 

internal format, 10010, as input; UniData translates this as October 1, 2000, and 

ICONV returns an internal format of 11963. The final OCONV returns 01 OCT 2000. 

Note: To prevent the preceding scenario, you can make all numeric input of fewer 

than six characters invalid by turning UDT.OPTIONS 82 on. However, your 

applications will no longer be able to process the abbreviated input dates.


After you execute ICONV D, the STATUS function returns one of the values 



0 Successful conversion of a valid date. 

1 Invalid input date. 


3 Date was converted correctly, but month and day were inverted in input value. 


Note: After you execute the ICONV D function, the STATUS function returns a code 

indicating the execution status of the conversion of the last array element only. 

Examples 

The following table describes common date conversions and their results. 

Value Code Result 

09/15/85 D 6468 

12/31/67 D 0 

December 31, 1967 D 0 

01/29/1988 D 7334 

Common Date Conversions 

In the following example, the program segment prints the date in internal and display 

format: 

INPUT IN_DATE 

INTERNAL = ICONV(IN_DATE,"D") 

OUTPUT = OCONV(INTERNAL, "D4/") 

PRINT IN_DATE,INTERNAL,OUTPUT 

ICONV Date (D) 1-338

The following table describes various dates you can input in the previous program 

and their conversions. 



DATE, OCONV Date (D), TIMEDATE 


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 Group (G) 

Syntax 

ICONV(str.expr, "G[m]*n") 

Description 

The ICONV group (G) function extracts one or more strings separated by a delimiter. 

If the input value or conversion code is invalid, UniData returns the input value. 



Parameters 



str.expr Indicates a string separated by a delimiter. 

G Group extraction code. 

m Indicates the number of strings to skip. If m is omitted, no strings are 

skipped. 

* Specifies any single nonnumeric character that is the delimiter. A minus sign 

(-) is not valid. UniData system delimiters are valid also. 

n The number of strings to be extracted. 

ICONV Group (G) Parameters 

Example 

In the following example, the program segment prints (303): 

X = "(303)+555+0988" 

PRINT ICONV(X,"G0+1") 

ICONV Group (G) 1-340



OCONV Group (G) 


ICONV Length (L) 

Syntax 

ICONV(str.expr, "Ln[,m]") 

Description 

The ICONV length (L) function extracts a string of a specified length or that falls 

within a range of acceptable lengths. If the input value or conversion code is invalid, 

UniData returns the input value. 



Parameters 



str.expr Indicates a string to be searched. 

L Length conversion code. 

n Specifies the number of characters the string must match to be extracted. 

When m is present, n is the shortest string to be extracted. 

m Specifies the longest string to be extracted. 

ICONV (L) Conversion Parameters 

ICONV Length (L) 1-342

Example 

In the following example, the program segment prints “123” and an empty string 

because the value of X has fewer than five characters and more than three: 

X = 123; Y = 456789 

PRINT ICONV(X,"L3,5") 

PRINT ICONV(Y,"L3,5") 



OCONV Length (L) 


ICONV Masked Character (MC) 

Syntax 

ICONV(expr, "MC [A | /A | B | /B | C | U | L | T | N | /N | P| X[D] | D | D[X] | X]") 

Description 

The ICONV masked character (MC) function provides many conversion functions 

that retrieve and/or convert values in strings and arrays. This function performs the 

same conversions and extractions as OCONV Masked Character (MC). UniData 

returns the input value if either the value to be converted or the conversion code is 

invalid. 



Parameters 


Parameters Description 

expr The expression to be searched or converted. 

A Extracts all alphabetic characters. 

/A Extracts all nonalphabetic characters. 

B Extracts all alphabetic and numeric characters. 

/B Extracts all special characters (not alphabetic nor numeric). 

C;x;y Converts all occurrences of substring x to substring y. 

U Converts data to uppercase. 

L Converts characters to lowercase. 

ICONV Masked Character (MC) Parameters 

ICONV Masked Character (MC) 1-344


Example 

You can use ICONV to remove special characters in a formatted price. For example, 

the following program segment extracts 1234 from $12.34: 


T Converts to initial cap style. The first letter of each word is uppercase, and 

all other letters are lowercase. Space and tab are word separators. 

N Extracts all numeric characters (0–9). 

/N Extracts all nonnumeric characters. 

P Converts all nonprinting characters to tildes (~). 

X[D] or D Assumes input is in decimal; converts to hexadecimal. 

D[X] or X Assumes input is in hexadecimal; converts to decimal. 

NEW.PRICE = ICONV("$12.34","MCN") 

PRINT NEW.PRICE 



ICONV Masked Character (MC) Parameters (continued) 

ALPHA, CONVERT, DOWNCASE, NUM, OCONV Masked Character (MC), 

UPCASE

ICONV Masked Decimal (MD) 

Syntax 

ICONV(num.expr, "MDn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] 

[,] [$] [-| < | E | C | D] [P] [Z] [T] [xc]") 

Description 

The ICONV masked decimal (MD) function converts a decimal number to internal 

format after rounding, as specified by f. If the input value or conversion code is 

invalid, UniData returns the input value. 



The ICONV MD, ML, and MR functions have the same result. They exist separately 

to maintain consistency with the OCONV MD, ML, and MR functions, which produce 

different results. 

Parameters 



num.expr The decimal number to be converted. num.expr can be any numeric value 

with or without a decimal. 

n The ICONV function ignores n (for example, if you specify MD32, UniData 

ignores the 3), but it is included in the syntax to maintain consistency with 

the OCONV Masked Decimal (MD) function. 

ICONV Masked Decimal (MD) Parameters 

ICONV Masked Decimal (MD) 1-346


Examples 

In the following example, UniData converts the value 12.339 to 1234 by rounding to 

two decimal places and converting to internal format: 


f Scales the input value num.expr by moving the decimal point f places to the 

right. If omitted, f defaults to the value assigned to n (for example, if you 

specify MD2, UniData reads it as MD22, and then ignores the first 2). 

dec_symbl You can specify a symbol to represent the decimal point in the input number 

by including dec_symbl. An example is provided in the following section. 

[prefix], 

[thsnd_mark], 

[suffix]] ] [,] 

[$] [-| < | E | 

C | D] [P] [Z] 

[T] [(xc)] 

INTERNAL.VAL = ICONV("12.339","MD2") 

The following example demonstrates how to specify that an alternate symbol is used 

to represent the decimal point in the input number. This example prints 12350. 

PRINT ICONV("123@499","MD2[,,@]") 

END 



The ICONV function ignores these options, but they are included in the 

syntax to maintain consistency with the OCONV Masked Decimal (MD) 

function. 

ICONV Masked Decimal (MD) Parameters (continued) 

OCONV Masked Decimal (MD)

ICONV Left Justify (ML) 

Syntax 

ICONV(num.expr, "MLn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] 

[,] [$] [C] [Z] [(mask)]") 

Description 

The ICONV left justify (ML) function converts a decimal number to internal format 

after rounding, as specified by f. If the input value or conversion code is invalid, 







Parameters 



num.expr Decimal number to be converted. num.expr can be any numeric value with 

or without a decimal. 

n The ICONV function ignores n (for example, if you specify ML32, 

UniData ignores the 3), but it is included in the syntax to maintain 

consistency with the OCONV Left Justify (ML) function. 

ICONV Left Justify (ML) Parameters 

ICONV Left Justify (ML) 1-348


Example 

In the following example, UniData converts the value 12.339 to 12339 based on the 

ML3 conversion code: 


f Scales the input value expr by moving the decimal point f places to the right. 

If omitted, f defaults to the value assigned to n (for example, if you specify 

ML2, UniData reads it as ML22, and then ignores the first 2). 


by including dec_symbl. For an example, see the following section. 

[prefix], 

[thsnd_mark], 

[suffix]] ] [,] 

[$] [C] [Z] 

[(mask)] 

INTERNAL.VAL = ICONV("12.339","ML3") 

The following example demonstrates how specify an alternate symbol to represent 

the decimal point in the input number. This example prints 12350. 

PRINT ICONV("123@499","ML2[,,@]") 

END 



OCONV Left Justify (ML) 


syntax to maintain consistency with the OCONV Left Justify (ML) 

function. 

ICONV Left Justify (ML) Parameters (continued)

ICONV Packed Decimal (MP) 

Syntax 

ICONV(expr, "MP") 

Description 

The ICONV packed decimal (MP) function converts an integer expr into packed 

decimal representation by compressing two digits of the integer into one byte. 

UniData returns the input value if either the value to be converted or the conversion 

code is invalid. 

Tip: Use this function to conserve disk space. 

In BASICTYPE P, ICONV returns an empty string if UDT.OPTIONS 56 is on and the 




OCONV Packed Decimal (MP) 

ICONV Packed Decimal (MP) 1-350

ICONV Packed Decimal (MP1) 

Syntax 

ICONV(expr, "MP1") 

Description 

The ICONV packed decimal (MP1) function converts an integer expr in packed 

decimal representation into its display format without truncating at the first CHAR(0) 

character or altering CHAR(0). If the input value or conversion code is invalid, 






OCONV Packed Decimal (MP1) 


ICONV Right Justify (MR) 

Syntax 

ICONV(num.expr, "MRn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] 

[$] [C] [Z] [(mask)]") 

Description 

The ICONV right-justify (MR) function converts a decimal number to internal 

format after rounding, as specified by f. If the input value or conversion code is 







Parameters 



num.expr Decimal number to be converted. num.expr can be any numeric value with 

or without a decimal. 

n The ICONV function ignores n (for example, if you specify MR32, 

UniData ignores the 3), but it is included in the syntax to maintain consistency 

with the OCONV Right Justify (MR) function. 

ICONV Right Justify (MR) Parameters 

ICONV Right Justify (MR) 1-352


Example 

In the following example, UniData converts the value 12.339 to 1234 based on the 

MR2 conversion code: 


f Scales the input value expr by moving the decimal point f places to the right. 

If omitted, f defaults to the value assigned to n (for example, if you specify 

MR2, UniData reads it as MR22, and then ignores the first 2). 


by including dec_symbl. An example is provided in the following section. 

[prefix], 

[thsnd_mark], 

[suffix] [,] [$] 

[C] [Z] 

[(mask)] 

INTERNAL.NUM = ICONV("12.339","MR2") 

The following example demonstrates how to specify that an alternate symbol is used 

to represent the decimal point in the input number. This example prints 12350. 

PRINT ICONV("123@499","MR2[,,@]") 

END 



OCONV Right Justify (MR) 


syntax to maintain consistency with the OCONV Right Justify (MR) 

function. 

ICONV Right Justify (MR) Parameters (continued)

ICONV Time (MT) 

Syntax 

ICONV(str.expr, "MT [H] [S] [c]") 

Description 

The ICONV time (MT) function converts the time of day from display format into 

internal format. The value of the internal format is the number of seconds since 

midnight (00:00:01 as 1, and 24 as 86400). 



Parameters 



str.expr Time input must be in the form HH:MM:SS. 

MM and SS are not required and, if you do not specify them, UniData 

assumes the values to be zero. You must use a separating character (any 

nonnumeric character, such as a colon or comma) between units (for 

example, HH, MM, SS). The suffixes AM, PM, A, and P also are accepted 

at the end of the string. UniData hours are the same as standard hours, with 

12PM as noon (12:00:00) and 12AM as midnight (00:00:00). 

A value greater than 24:00:00 (for example, 24:00:01) results in an invalid 

conversion. 

H S c The remaining options are ignored but are allowed to maintain consistency 

with the OCONV Time (MT) function. 

ICONV Time (MT) Parameters 

ICONV Time (MT) 1-354

Example 

The following table describes the time conversion code and the resulting value. 



DATE, OCONV Time (MT), TIME, TIMEDATE 


Value 

Code 

Specificati 

on Result 

12:30 MT 45000 

12AM MT 0 

12PM MT 43200 

ICONV Time Examples

ICONV Hex (MX | HEX), Octal (MO), Binary 

(MB) 

Syntax 

ICONV(num.expr, ["HEX | MX [0C] | MO [0C] | MB [0C]"]) 

Description 

The ICONV hex (MX), octal (MO), and binary (MB) functions convert a number 

from one of three numbering systems to decimal value. UniData returns the input 

value if either the value to be converted or the conversion code is invalid. 



Parameters 



num.expr Specifies the decimal value, in display format, to convert to an alternate 

numbering system. 

HEX | 

MX [0C] 

Indicates conversion from hexadecimal (base 16). The optional 0C specifier 

converts into ASCII character rather than decimal value. HEX is equivalent 

to MX0C. 

MO [0C] Indicates conversion from octal (base 8). The optional 0C converts to ASCII 

character rather than decimal value. 

MB [0C] Indicates conversion from binary (base 2). The optional 0C converts to 

ASCII character rather than decimal value. 

ICONV Numbering System Conversion Parameters 

ICONV Hex (MX | HEX), Octal (MO), Binary (MB) 1-356

The following table lists conversion codes to be used with ICONV to convert from 

other numbering systems to decimal value or ASCII character. 

ICONV conversions into other numbering systems produce multiple characters in the 

target numbering system: 


Hexadecimal – One ASCII character produces two hexadecimal characters. 

For example, ASCII character “0” is equal to hexadecimal “30”. 

Octal – One ASCII character produces three octal characters. For example, 

ASCII character “0” is equal to octal “060”. 

Binary – One ASCII character produces eight binary characters. For 

example, ASCII character “0” is equal to octal “00110000”. 

Examples 

From To Function 

Binary Decimal value ICONV MB 

Binary ASCII character ICONV MB0C 

Octal Decimal value ICONV MO 

Octal ASCII character ICONV MO0C 

Hexadecimal Decimal value ICONV MX 

Hexadecimal ASCII character ICONV MX0C 

ICONV HEX 

ICONV Options for Converting from Alternate Numbering Systems 

The following table demonstrates some ICONV MO, MX, and MB conversion codes 

and their results. 

Input Code Result 

123123 MO 42579 (decimal) 

123123 (octal) MO0C SS (ASCII characters) 

Examples of Numbering System Conversions




100 (hexadecimal) MX 256 (decimal) 

101010101010 (binary) MB 170 (decimal) 

4B (hexadecimal) MX 75 (ASCII characters) 

Examples of Numbering System Conversions (continued) 

CHAR; OCONV Hex (MX | HEX), Octal (MO), Binary (MB); SEQ 

ICONV Hex (MX | HEX), Octal (MO), Binary (MB) 1-358

ICONV Pattern Match (P) 

Syntax 

ICONV(str.expr, "P(op)[;(op).....]") 

Description 

ICONV pattern match (P) function performs the same function as the OCONV 

pattern match (P) function. For information, see OCONV Pattern Match (P). 


ICONV Range (R) 

Syntax 

ICONV(num.expr, "Rndm[;ndm.....]") 

Description 

The ICONV range (R) function returns only those data values that fall within a 

specified range of decimal values. When including a negative range, you must 

specify the highest negative number first. If range specifications are not met, UniData 

returns an empty string. If the input value or conversion code is invalid, UniData 

returns the input value. 



Parameters 



num.expr Indicates a string to be searched. 

n Specifies the smallest number to be extracted. 

d Specifies a delimiter separating numbers in a range. Any character except 

system delimiters can be used to separate the numbers in a range. However, 

the minus sign (-) should not be used as a delimiter because it refers to a 

negative number in the range. 


; Separates multiple ranges. 

ICONV Range (R) Parameters 

ICONV Range (R) 1-360

Example 

In the following example, the program segment prints “123” and a blank line because 

X is within the range and Y is not: 

X = 123; Y = 456789 

PRINT ICONV(X,"R100,200") 

PRINT ICONV(Y,"R100,200") 



OCONV Range (R) 


ICONV SOUNDEX (S) 

Syntax 

ICONV(str.expr, "S") 

Description 

The ICONV SOUNDEX (S) function converts string or numeric data specified by 

str.expr to phonetic format based on SOUNDEX conversion codes. The S conversion 

code can be used in an ICONV virtual attribute formula. If the input value or 

conversion code is invalid, UniData returns the input value. 

For more information about SOUNDEX conversion codes, see the SOUNDEX 

command. 



Example 

The following example is virtual attribute, SDX_LNAME, that converts the value of 

the variable LNAME to its SOUNDEX expression: 

ICONV(LNAME,"S") 



OCONV SOUNDEX (S), SOUNDEX 

ICONV SOUNDEX (S) 1-362

ICONV Text Extraction (T) 

Syntax 

ICONV(str.expr, "T[m,]n") 

Description 

The ICONV text extraction (T) function extracts a substring from a string. If the 

input value or conversion code is invalid, UniData returns the input value. 



Parameters 





m Extracts a contiguous string of characters starting from character m. 

n Extracts a contiguous string of characters of length n. 

ICONV Text Extraction (T) Parameters

Examples 

The following table describes some ICONV text extraction codes and their results. 




QRSTUV “T3” TUV 

DAMN THE 

TORPEDOES 

CONVERSION IS THE 

KEY 

“T3,5” MN TH 

[], FIND, FINDSTR, OCONV Text Extraction (T) 

“T1,9” CONVERSIO 

457 COLORADO 

BLVD 

“T4,7” [space]COLORA 

ICONV Text Extraction Examples 

ICONV Text Extraction (T) 1-364

ICONV File Translation (Tfile) 

Syntax 

ICONV(rec.id, "T[DICT] [filename;cn;I-Attribute;O-Attribute]") 

Description 

The ICONV file translation (Tfile) function performs the same action as OCONV 

file translation (Tfile). For information, see OCONV File Translation (Tfile). 


ICONVS 

Syntax 

ICONVS(dyn.array.expr, conv.code.expr) 

Description 

The UniBasic ICONVS function converts string or numeric data from display format 

to internal format, based on a conversion code, for each element of a dynamic array. 





With null value handling turned on, the presence of the null value in data produces a 

result of the null value, and the STATUS function return value is set to 5. 

Note: ICONVS conversion codes are the same as ICONV conversion codes. For 

information about conversion codes, refer to ICONV. 

Parameters 



dyn.array.expr Specifies a dynamic array, each element of which to convert. 

conv.code.expr Specifies a code to use in converting each element of the dynamic array. 

ICONVS Parameters 

ICONVS 1-366


After you execute ICONVS, the STATUS function returns one of the values 


Example 

In the following example, the program segment converts each element of ARR1 to 

internal format: 


ARR1 = "$12.34":@VM:5678:@VM:9876 

ARR2 = ICONVS(ARR1,"MR2") 

PRINT ARR2 

END 

This program segment prints the following converted array elements: 

1234 567800 987600 

Note: The blanks in the number are value marks, which are nonprinting characters. 

The value marks could display as some other character on your terminal screen. 



ICONV, OCONVS 


0 Successful conversion. 

1 Invalid input data. 


3 Invalid date for “D” conversion code only. 

5 Null value if null value handling is turned on. 


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, UniData executes the first group of 

statements. If expr is false, UniData executes the second group of statements. 

Points to Remember when Writing IF/THEN/ELSE 

Statements 

The ELSE clause is optional. 

An IF/THEN/ELSE structure can occupy either a single line or several lines. When 

coding single- line and multiline statements: 

The single-line form does not require an END before the ELSE. 

In the multiline form, each clause must contain at least one statement. If you 

do not want to take any action, use the NULL command. THEN and ELSE 

clauses must be delimited by END. 

IF/THEN/ELSE 1-368


A single-line statement that includes the INPUT command as a part of the 

THEN clause might not produce the results you expect. For example, the 

following statements produce no output: 

IF X = 1 THEN INPUT TEST ELSE PRINT "X NE 1" 

To correct this problem, enter each clause of the statement on a separate line, 

or use the IN() function to obtain input from theterminal or input queue. 

With null value handling turned on, a test on expr that is the null value returns false. 

For an overview of how the null value affects UniBasic, see Developing UniBasic 

Applications. 

Tip: You can nest IF/THEN/ELSE statements, but a CASE statement might be more 

efficient. 

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 GOSUB REORDER 

In the next example, the program segment compares INCOME to TARGET. UniData 

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 



CASE, LOOP/REPEAT, NULL

IN 

Syntax 

IN( ) 

Description 

The UniBasic IN function captures raw data from an input queue or from a terminal. 

Tip: IN can capture function, arrow, and other special keys from the keyboard. 

Example 

In the following example, the program segment assigns the value y to ANSWER: 

DATA y 

ANSWER = IN() 



DATA, INPUT, INPUT @, INPUTTRAP, SYSTEM 

IN 1-370

INDEX 

Syntax 

INDEX(str.expr1,str.expr2,num.expr) 

Description 

The UniBasic INDEX function returns the starting position of the num.expr occurrence 

of str.expr2 within str.expr1. INDEX supports multibyte languages. 

Parameters 



Examples 

In the following example, the program segment searches STR.VAR for the second 

occurrence of the letter t and returns that location in the variable LOC. In this 

example, it returns a value of 8. 


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 

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)



COL1, COL2, FIELD 

INDEX 1-372

INDICES 

Syntax 

INDICES(file.var[, index.name.expr]) 

Description 

The UniBasic INDICES function returns one of the following: 


Names of alternate key indexes. 

Information about a particular alternate key index. 

Retrieving Names of Alternate Key Indexes 

If you specify only file.var, the INDICES function returns a dynamic array containing 

the alternate key index names for all indexes in the file you specify. The index names 

are not returned in any particular order. Index names are separated by attribute marks. 

Note: If the index you specify does not exist, the function returns an empty string. 

Retrieving Information About Indexes 

If you specify the name of an alternate key index (indexname.expr), the INDICES 

function returns information about that index in a dynamic array, which consists of 

six attributes: 

Attribute 1 – Four values representing the following information in this 

order: 

Type of key (I or D). 

Build required (1 or “ ”). 

No meaning. 

Automatic update enabled (1 or “ ”). 

Attribute 2 – Location of the alternate key in the record. 

Attribute 3 – An ASCII string with the time stamp of the last time the index 

was built (updated by BUILD.INDEX).

Attributes 4 and 5 – Empty. 

Attribute 6 – Type of attribute: 

S for singlevalued. 

M for multivalued. 

MS for multi-subvalued. 

Parameters 



file.var Specifies the file about which to return index information. 

, index.name.expr Specifies an alternate key index about which to return 

information. 

INDICES Parameters 



SELECTINDEX, SETINDEX 

UniData 

BUILD.INDEX, CREATE.INDEX – For information, see the UniData Commands 


INDICES 1-374

initSecureServerSocket function 

Syntax 

initSecureServerSocket(name_or_IP, port, backlog, svr_socket, context) 

Description 

Use the initSecureServerSocket() function to create a secured connection-oriented 

stream server socket. It does exactly the same as the initServerSocket() function 

except that the connection will be secure. 

Once the server socket is opened, any change in the associated security context will 

not affect the opened socket. 

Parameters 




name_or_IP DNS name (x.com) or IP address of a server or empty. Empty is 

equivalent to INADDR_ANY which means the system will 

choose one for you. Generally, 

this parameter should be left empty. 

port Port number. If the port number is specified as a value



0 Success. 

1 - 41 See Socket Function Error Return Codes. 

101 Invalid security context handle. 


initSecureServerSocket function 1-376

initServerSocket 

Syntax 

initServerSocket(name_or_IP, port, backlog, svr_socket) 



Description 

Use the initServerSocket function to create a connection-oriented (stream) socket. 

Associate this socket with an address (name_or_IP) and port number (port), and 

specify the maximum length the queue of pending connections may grow to. 

Parameters 




name_or_IP DNS name (x.com) or IP address of a server or empty. Empty is equivalent 

to INADDR_ANY which means the system will choose one for 

you. Generally, this parameter should be left empty. 




0 Success. 


initServerSocket Return Codes 

initServerSocket 1-378

INMAT 

Syntax 

INMAT( ) 

INMAT(array.name) 

Description 

The UniBasic INMAT function, in the first form, returns the number of elements 

(rows) in a dimensioned array. The second form returns the current dimension of the 

dimensioned array array.name. If the dimensioned array has two dimensions, the 

bounds are separated by value marks. 

After you open a file, the value of INMAT contains the number of modulos that make 

up the file. Subsequent file operations using dimensioned array commands also set 

the value returned by INMAT. 


INMAT is set by the dimensioned array-oriented commands, as shown in the 


Command Meaning 


DIM 0 – The array was created. 

1 – Not enough memory was available to create the array. 

INMAT Function Return Values

Command Meaning 

MATREAD 

MATREADL 

MATREADU 

MATPARSE 

Examples 

In the following example, the program segment fills the array MAIN.MAT with 

values from REC. If a sufficient number of elements are available in the target array, 

the value of INMAT is set to the number of elements filled. If the number of values 

exceeds the number of elements in the target array, excess data is lumped in the 0 

position, and 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 the following: 

23}14 

9 

n – The number of attributes loaded into the array. 

0 – More attributes existed in the record than elements existed in the array. 

Excess data is stored in the 0,0 element. 

OPEN n – The number of modulos in the file. 

0 – The file opened is a directory (DIR type). 

OSBWRITE n – The number of bytes written to a file or named pipe. 

INMAT Function Return Values (continued) 

INMAT 1-380



DIM, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, 

MATWRITE, MATWRITEU 


INPUT 

Syntax 

INPUT var [,length [ _ ]] [:] [{FOR | WAITING} time.expr] [UNFILTERED] 

[THEN statements | ELSE statements] 

INPUT var [,-l] [{FOR | WAITING} time.expr] [UNFILTERED] [THEN 

statements | ELSE statements] 

Description 

The UniBasic INPUT command requests data from an input queue or from the 

terminal screen. INPUT supports multibyte languages. 

If INPUT is successful, UniData sets @SYSTEM.RETURN.CODE to 0. If unsuccessful 

(the INPUT statement with a FOR or WAITING clause timed out), UniData 

sets @SYSTEM.RETURN.CODE to -1. 

One variable is read by each INPUT statement. If you press ENTER in response to 

an INPUT statement, an empty string is assigned to the variable. 

Tip: Precede INPUT with a PRINT statement to display a prompt. 

UDT.OPTIONS 83 enables the escape character (usually ASCII code 27) to be 

accepted by INPUT while screening out or converting other control characters. 

THEN | ELSE is associated with the WAITING clause except in the case described 

in the following warning note. 

INPUT 1-382

Warning: Processing differs when you include INPUT within a single-line 

IF/THEN/ELSE statement, which is illustrated by the following program segment: 

RESP = 5 

IF RESP = 10 THEN INPUT TEST ELSE PRINT "NO INPUT" 

END 

This program produces no output because UniData interprets the ELSE as being a 

part of the INPUT statement, even though no WAITING clause is included. To avoid 

this, place the INPUT statement on its own line, as shown in the following example: 

RESP = 5 

IF RESP = 10 THEN 

INPUT TEST 

END ELSE 

PRINT "NO INPUT" 

END 

Parameters 




var Specifies a variable to receive the input. In the first form, if data 

(received by a DATA statement) is present in an input queue, INPUT 

assigns the next value to the variable var. If a DATA statement was not 

executed, INPUT prompts the user for input by displaying a question 

mark on the terminal. 

,length Specifies the maximum number of characters accepted. 

_ UniData waits for the user to press ENTER before processing data input 

at the keyboard. If the underscore is not included, UniData stops 

accepting input when the user enters the maximum number of characters. 

Use the underscore parameter to allow the user to backspace after 

entering the maximum number of characters. For example, if you specify 

“INPUT X,5_”, the user can backspace to modify the entry after entering 

five characters. 

INPUT Parameters


: Normally, when a user types something and presses ENTER in response 

to an INPUT statement, UniData issues a line feed. The : parameter 

inhibits this line feed. 

,-l UniData checks the type-ahead buffer. The following values are returned 

in var: 

1 – Data is present in the buffer. 

0 – No data is present in the type-ahead buffer. 

Use the -1 parameter to periodically check for input in an application that 

runs continuously. 

FOR | 

WAITING 

time.expr 

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 is 

read. 

DATA 10,20,30,40,50 

INPUT TEST 

Specifies the length of time to wait for input. If you do not enter the input 

before the wait period expires, var does not change, and the ELSE clause 

executes. If no ELSE nor THEN clause exists, the session terminates at 

the end of the wait period. 

UNFILTERED Sets INPUT to capture raw characters (such as backspace, up arrow, 

down arrow, or ENTER) from the keyboard. 

THEN 

statements 

ELSE 

statements 

Specifies statements to execute when input is received within the time 

specified in the FOR | WAITING clause and input is not an empty string. 

Specifies statements to execute if no input is received by the time 

specified in the FOR | WAITING clause or if the input is an empty string. 

INPUT Parameters (continued) 

In the next example, the program statement prints the prompt “Enter name:”. The 

INPUT statement then enables the user to enter any number of characters, stopping 

only when the user presses ENTER. The first 10 characters the user enters are 

assigned to the variable NAME. 

PRINT "Enter name: "; INPUT NAME,10_ 

INPUT 1-384

In the next example, the INPUT statement with the -1 parameter checks the typeahead 

buffer. If S.FLAG is 0, the buffer is empty. If it is 1, the buffer contains data. 

In the latter case, UniData prints the current value of RECS.PROCESSED. 


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" 



CLEARINPUT, DATA, IN, INPUT @, INPUTERR, INPUTIF, INPUTNULL, 

INPUTTRAP, PROMPT, SYSTEM

INPUT @ 

Syntax 

INPUT @ (col,row | option) [ , | : ] var [,length] [ _ ] [mask] [{FOR | WAITING} 

time.expr] [UNFILTERED] [THEN statements | ELSE statements] 

Description 

The UniBasic INPUT @ command places the cursor at a specific location on the 

terminal screen and prompts the user for input. INPUT @ supports multibyte 

languages. 

Tip: The UniBasic @ function also positions the cursor on the terminal screen, but 

does not accept input as does INPUT @. 

If INPUT @ is successful, UniData sets @SYSTEM.RETURN.CODE to 0. If unsuccessful 

(the INPUT @ statement with a FOR or WAITING clause timed out), 

UniData sets @SYSTEM.RETURN.CODE to -1. 

Parameters 



col,row Specifies the column and row on the screen at which the cursor is to 

be placed for input. 

: Normally, when you type a value and press ENTER in response to an 

INPUT statement, UniData issues a line feed. The : parameter inhibits 

this line feed. 

var Specifies a variable to receive the input data. 

,length Specifies the maximum number of characters accepted. 

INPUT @ Parameters 

INPUT @ 1-386



_ UniData waits for you to press ENTER before processing data input at 

the keyboard. If you do not use the underscore parameter, UniData 

stops accepting input when you exceed the maximum number of 

characters. 

Use the underscore parameter you want the capability of backspacing 

after entering the maximum number of characters. For example, if you 

specify “INPUT X,5_”, you can backspace to modify the entry after 

entering five characters. 

mask Specifies a format or conversion mask. For format options and instructions 

about building a conversion mask, see OCONV Masked Decimal 

(MD). 

FOR | WAITING 

time.expr 

Specifies the amount of time to wait for input. If the input is not 

entered when this period expires, var does not change, and the ELSE 

clause executes. If no ELSE nor THEN clause exists, the session 

terminates at the end of the wait time. 

UNFILTERED Sets INPUT @ to capture raw characters (such as backspace, up arrow, 

down arrow, or RETURN) from the keyboard. 

THEN 

statements | 

ELSE statements 

If the ECL TIMEOUT command has been executed: 

THEN executes if the input variable contains at least one character. 

ELSE executes if the input variable contains an empty string. If no 

ELSE clause is coded, UniData logs you out and displays the ECL 

prompt. 

If the ECL TIMEOUT command has not been executed, the program 

waits indefinitely for input. 

INPUT @ Parameters (continued)

Examples 

The following example is taken from the sample program in Appendix A, “Sample 

Program,” in Developing UniBasic Applications. Notice that the DISPLAY 

command is combined with the UniBasic @ function to clear the screen and display 

messages. Then INPUT @ accepts the user’s response (a corrected price). 

ALTER_RECORD: 

* Create a new screen, and allow PRICE and ADDRESS to be changed. 

* Initialize variables and draw the screen 


DISPLAY @(-1):@(15,5):"Alter ORDER": 

DISPLAY @(10,8):"(Press RETURN to leave un-changed)" 

DISPLAY @(8,9):"Old Price":@(42,9):"New Price (Enter 2 decimal 

places)" 

* Change the PRICE field (if desired) 


NEW.PRICE = "" 


INPUT @(45,9+ENTRY):NEW.PRICE 

Later in the same sample program, the @ function is again combined with DISPLAY 

to paint the screen with prompts. After all prompts have been displayed, INPUT @ 

returns the cursor to the end of the first line, accepting input on that line before 

moving to the end of the next. In this manner, it accepts input at the end of each line 

in turn. 

* Display the current ADDRESS information 

DISPLAY @(21,12):"Change Address to: ": 

DISPLAY @(21,13):"Street Line1: ":@(40,13):ADDRESS 

DISPLAY @(21,14):"Street Line2:" 

DISPLAY 

@(40,14):ADDRESS:@(21,15):"City:":@(40,15):CLIENT.REC 

DISPLAY @(21,16):"State:": 

DISPLAY 

@(40,16):CLIENT.REC:@(21,17):"Zip:":@(40,17):CLIENT.REC 

* Accept INPUT to change values of address 

INPUT @(40,13):STREET1 

IF STREET1 = '' THEN STREET1 = CLIENT.REC 

INPUT @(40,14):STREET2 

IF STREET2 = '' THEN STREET2 = CLIENT.REC 

INPUT @(40,15):CITY 

IF CITY = '' THEN CITY = CLIENT.REC 

INPUT @(40,16):STATE 

IF STATE = '' THEN STATE = CLIENT.REC 

INPUT @(40,17):ZIP 

IF ZIP = '' THEN ZIP = CLIENT.REC 

INPUT @ 1-388



CLEARINPUT, DATA, IN, INPUT, INPUTERR, INPUTIF, INPUTNULL, 

INPUTTRAP, PROMPT, SYSTEM 

UniData 

TIMEOUT – For information, see the UniData Commands Reference. 


INPUTCLEAR 

INPUTCLEAR is a synonym for the CLEARINPUT command. For more information, 

see CLEARINPUT. 

Synonym 

CLEARINPUT 

INPUTCLEAR 1-390

INPUTERR 

Syntax 

INPUTERR error.expr 

Description 

The UniBasic INPUTERR command displays an error message at the bottom line of 

the terminal screen. error.expr can be any valid UniBasic statement, including a 

literal string enclosed in quotation marks. 

Tip: Use INPUTERR to prompt for errors when soliciting data with an INPUT 

statement. 

The next INPUT command erases previous error messages printed on the bottom line 

of the screen. The UniBasic program must control the movement of the cursor so it 

does not enter the bottom line. 

Note: INPUTERR sends output to the screen regardless of PRINTER on/off status. 

Example 

In the following example, the program segment prints an error message at the bottom 

of the screen if the input does not match the pattern mask: 


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



INPUT, INPUT @ 

INPUTERR 1-392

INPUTIF 

Syntax 

INPUTIF var [THEN statements] [ELSE statements] 

Description 

The UniBasic INPUTIF command retrieves input from the type-ahead buffer and 

assigns the input to a variable. 

Parameters 





CLEARINPUT, INPUT, INPUT @, PROMPT, SYSTEM 


var Specifies the target variable for input data. 

THEN statements Executes statements if data is available in the type-ahead buffer. 

ELSE statements Executes statements if data is not available in the type-ahead 

buffer. 

INPUTIF Parameters

INPUTNULL 

Syntax 

INPUTNULL 'expr' 

Description 

The UniBasic INPUTNULL command enables you to change the default 

INPUTNULL character from the default, underscore, to any other single character. 

When you enter the INPUTNULL character in response to an INPUT or INPUT @ 

prompt, UniData stores an empty string in place of the character entered. expr 

specifies the character to serve as the INPUTNULL character for this session. 

Note: You must enclose expr in quotation marks. 

Example 

In the following example, the pound sign (#) is set as the new INPUTNULL 

character: 

PROMPT "" 

INPUTNULL "#" 

PRINT @(-1):@(0,10):"Enter a character: " 

INPUT @(20,10):inpt 

PRINT "Input is ":inpt 

PRINT "SEQ = ":SEQ(inpt) 

PRINT "LEN = ":LEN(inpt) 

The preceding program segment results in the following output when user input is an 

underscore character: 

Enter a character: _ 

Input is _ 

SEQ = 95 

LEN = 1 

INPUTNULL 1-394

INPUTTRAP 

Syntax 

INPUTTRAP string.expr GOSUB label [:] [,label [:]] 

INPUTTRAP string.expr GOTO label [:] [,label [:]] 

Description 

The UniBasic INPUTTRAP command sets a trap for a particular character or 

characters in a program. INPUTTRAP enables you to specify characters which, if 

entered at an INPUT or INPUT @ statement, will branch to another statement label. 

Parameters 




string.expr Specifies the user input upon which to branch to another statement label. To 

set a trap for both uppercase and lowercase characters, use the following 

pattern INPUTTRAP ‘Xx’, as in the following: INPUTTRAP ‘Aa’ GOSUB 

10,10. 

GOSUB 

GOTO 

These keywords direct program execution to execute or branch to a specified 

label in the program. 

GOSUB ensures that program execution returns to the statement below the 

subroutine call. 

GOTO is a branch only, and does not return processing to the calling routine. 

These keywords operate just like the commands of the same names. For 

more information about the GOTO and GOSUB commands, see their entries 

in this manual. 

label Specifies the label to which to branch. 

INPUTTRP Parameters

Example 

In the following example, the program statement performs a GOSUB to label ASUB 

if the user enters H or to label BSUB if the user enters B: 

INPUTTRAP 'HB' GOSUB ASUB,BSUB 

INPUT@ (10,10) VALUE 



IN, INPUT, INPUT @, INPUTERR 

INPUTTRAP 1-396

INS 

Syntax 

INS expr BEFORE dyn.array 

Description 

The UniBasic INS command inserts an expression with the appropriate delimiter 

before the specified attribute, value, or subvalue mark in a dynamic array. 

Note: UniData does not insert a delimiter at the end of the array. 

Parameters 



Examples 

In the following example, the program segment inserts Zelda, with a new attribute 

mark, before the second attribute: 


expr Specifies an expression to insert. 

dyn.array 

 

ARRAY = "H.L. Mencken":@AM:"John":@AM:"Mary" 

INS "Zelda" BEFORE ARRAY 


Specifies a dynamic array and attribute, value, and subvalue at which to 

insert the expression. If any one of these expressions is -1, UniData inserts 

the expr as the last element in the array position. 

INS Parameters 

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 

because val.expr is -1: 

ARRAY = "Carmen":@AM:"Sally":@AM:"Billy":@AM:"Mark" 

INS "Stephen" BEFORE ARRAY 


ARRAY="Carmen":@AM:"Sally":@AM:"Billy":@AM:"Mark":@AM:"Ste 

phen" 



FIELDSTORE, INSERT 

INS 1-398

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 can append data by 

using the short version of the REPLACE function. 

Parameters 



dyn.array.expr, 

attrib.expr, 

val.expr, 

subval.expr, 

Elements in dyn.array.expr,attrib.expr,val.expr, and subval.expr can be any of the 

following three types. 


Specifies a dynamic array and attribute, value, and subvalue of that 

dynamic array at which to insert the expression. For more information 

about the type of insertions available, see the following table. 

insert.expr Specifies the string to insert. 

INSERT Parameters 

If the element is: then insert expr: 

a positive number after delimiter, before data. 

-1 (attrib.expr,val.expr, subval.expr) after the position indicated. 

0 (val.expr, subval.expr) at the next higher level. 

Determining Insertion Points

Examples 

In the following example, the program statement inserts HARRY at the end of the 

values 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') 

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 specifies Alias in the second attribute 

position: 

ARRAY = "#111":@AM:"Jones":@AM:"Smith" 

ARRAY2 = INSERT(ARRAY,2,0,0,"Alias") 

When you execute this program segment, UniData inserts Alias in the second 

attribute position: 

ARRAY2 = "#111":@AM:"Alias":@AM:"Jones":@AM:"Smith" 



DEL, FIELDSTORE, INS, REMOVE, REPLACE, SUBSTRINGS 

INSERT 1-400

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 decimals. 

Example 

In the following example, the program segment prints 1, which is the integer part of 

the number 1.734: 

A = 1.734 

PRINT INT(A) 


ISMB 

Syntax 

ISMB() 

Description 

The UniBasic ISMB function returns a code indicating whether the currently 

installed language is made up of a single-byte or multibyte character set. 

This function returns 0 to indicate a single-byte character set, or 1 for a multibyte 

character set. For example, if you execute the ISMB function in a UniData session 

for which the language is English, the function returns 0. If you execute this function 

in a UniData session for which the language is Japanese, the function returns 1. 



BYTELEN, CHARLEN, DISPLAYWIDTH, LEN, MBLEN 

ISMB 1-402

ISNV 

Syntax 

ISNV(expr) 

Description 

The UniBasic ISNV function tests an expression for the null value. If expr is the null 

value, this function returns a code of 1. If the expression is not null, or if it contains 

a null value as well as other characters, this function returns a code of 0. 

Note: The udtconfig parameter NULL_FLAG must be on for a program that contains 

ISNV to compile. With this flag on, the null value represents an unknown value (represented 

by @NULL in UniBasic programs), as opposed to an empty string 

(represented as “”). IBM recommends that you use @ variables to represent UniData 

delimiters and the null value because the ASCII value used to represent these 

characters can vary with language group. 

Examples 

The following program example demonstrates testing for the null value in a variable: 


A=@NULL 

IF ISNV(A) THEN PRINT "A is the null value." 

This program results in the following output: 

A is the null value. 

The following program uses the function ISNV to determine if a string consists of the 

null value: 

PRINT "1.a ISNV(@NULL) = ":ISNV(@NULL) 

PRINT "2.a NOT(ISNV(@NULL)) = ":NOT(ISNV(@NULL)) 

A = "abc":@NULL:"def" 

PRINT "1.b ISNV('abc':@NULL:'def') = ":ISNV(A) 

PRINT "2.b NOT(ISNV('abc':@NULL:'def')) = ":NOT(ISNV(A))

This program produces the following results. Notice that ISNV executed on a string 

containing the null value and other characters produces a negative result (0). 

1.a ISNV(@NULL) = 1 

2.a NOT(ISNV(@NULL)) = 0 

1.b ISNV('abc':@NULL:'def') = 0 

2.b NOT(ISNV('abc':@NULL:'def')) = 1 



ISNVS 

ISNV 1-404

ISNVS 

Syntax 

ISNVS(dynamic.array) 

Description 

The UniBasic ISNVS function tests dynamic array elements to see if any of them is 

the null value. This function is meaningful only when null value handling is on. It 

returns an array with 0 or 1 in each element. If the array element is the null value, this 

function returns a code of 1. If the element is not null, or if it contains the null value 

as well as other characters, this function returns a code of 0. 

Note: The udtconfig parameter NULL_FLAG must be on for a program that contains 

ISNVS to compile. With this flag on, the null value represents an unknown value 

(represented BY @NULL in UniBasic programs), as opposed to an empty string 

(represented as “”). IBM recommends that you use @ variables to represent UniData 

delimiters and the null value because the ASCII value used to represent these 

characters can vary with language group. 

Example 


The following program demonstrates the ISNVS function by printing 

the return values stored in array D: 

B=@FM:"stereo":@FM:@NULL:@FM:"234":@FM 

D=ISNVS(B) 

STG=B 

GOSUB PRINT.SETUP 

PRINT "Dynamic array = " 

PRINT PRT.STG 


PRINT "D = ":D 

NEXT X 

PRINT.SETUP: 


PRT.STG = CHANGE(PRT.STG, @FM, "@FM") 



RETURN

This program results in the following output: 

Dynamic array = 

@FMstereo@FM@NULL@FM234@FM 

D = 0 

D = 0 

D = 1 

D = 0 



ISNV 

ISNVS 1-406

ITYPE 

Syntax 

ITYPE(itype.expr) 

Description 

The UniBasic ITYPE function enables a UniBasic program to execute a UniData 

virtual attribute from the dictionary of a UniData file. The value of the function is the 

same as if it were run using UniQuery or UniData SQL. 

Note: ITYPE generally requires you to open both the dictionary and data portions of 

the file. Before you use this function, you must compile the dictionary of the file by 

using the ECL COMPILE.DICT or CD command. 

In most cases, you also must assign the @ID and @RECORD variables. These 

variables resolve the value of the ITYPE function. However, if neither the ID of the 

file nor the data from the record is used in the ITYPE, you do not need to assign these 

variables. 

Note: Conversion or formatting codes in the dictionary record of the virtual attribute 

does not affect the value ITYPE returns. 

Examples 

The following virtual attribute exists in the dictionary file of the demonstration 

database file ORDERS: 

YV 

PRICE*QTY; SUM(SUM(@1)) 

MD2,$ 

Grand Total 

14R 

S 


The following program segment opens both the ORDERS file and the dictionary of 

the ORDERS file, then reads the compiled virtual attribute into the program variable 

GRAND_TOTAL. After prompting for an order number and reading the record, the 

virtual attribute is evaluated with the ITYPE function. In this case, it performs a 

summation on the value of GRAND_TOTAL in @RECORD. ITYPE does not 

invoke the conversion and format functions in the dictionary item. 

OPEN 'ORDERS' TO ORDERS.FILE ELSE STOP 

OPEN 'DICT','ORDERS' TO DICT.ORDER ELSE STOP 

READ GRAND_TOTAL FROM DICT.ORDER,'GRAND_TOTAL' ELSE 

PRINT 'DICTIONARY ITEM GRAND_TOTAL NOT FOUND' 

STOP 

END 

LOOP 

PRINT 'Enter order number ': 

INPUT ORDER.ID 

WHILE ORDER.ID DO 

@ID = ORDER.ID 

READ @RECORD FROM ORDERS.FILE,ORDER.ID ELSE 

PRINT 'ORDER NOT FOUND' 

@RECORD = '' 

END 

IF @RECORD THEN 

TOT.AMT = ITYPE(GRAND_TOTAL) 

TOT.AMT = OCONV(TOT.AMT,'MD2,$') 

PRINT "Total accounts receivable is ":TOT.AMT 

END 

REPEAT 



CALCULATE 

UniData 

COMPILE.DICT – For information, see the UniData Commands Reference. 

Virtual attributes – For information, see Using UniData. 

ITYPE 1-408

LE 

Syntax 

expr1 LE expr2 

Synonyms 

#>, =



LES 

LE 1-409

LEN 

Syntax 

LEN(str.expr) 

Description 

The UniBasic LEN function returns the length of character expression str.expr. LEN 


With null value handling on, the null value has a length of one byte. 

Examples 

In the following example, the program segment displays 14, the length of the string 

NAME: 

NAME = "Arthur Fiedler" 

PRINT LEN(NAME) 

The following figure illustrates a string that indicates below each “character” the 

number of bytes required to store that character. The string contains eight bytes. 

Therefore, LEN would return 8 for this string. 

Number 

of bytes 


2 3 1 2



BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LENS, MBLEN 

LEN 1-411

LENS 

Syntax 

LENS(dyn.array) 

Description 

The UniBasic LENS function returns the length of the values within each element of 

a dynamic array. LENS supports multibyte languages. 

With null value handling on, the null value has a length of one byte. 

Example 

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. 



BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LEN, MBLEN

LES 

Syntax 

LES(array1,array2) 

Description 

The UniBasic LES function compares each value in array1 to its corresponding 


array1 is less than or equal to the value in the corresponding value in array2, and 0 

in each position when the value in array1 is greater than that in array2. 

Example 





ARRAY3 = LES(ARRAY1,ARRAY2) 

LES 1-413

LISTUSER 

Syntax 

LISTUSER() 

Description 

The LISTUSER function returns information about UniData processes currently 

running in a dynamic array. 

In the event a UniData user session aborts through a power failure or other abnormal 

circumstance, UniData registers the aborted process as an active user, and it appears 

as such in the LISTUSER array. Eventually, the cleanupd daemon will detect these 

processes and remove the aborted process from the user list. 

LISTUSER Dynamic Array (UNIX) 

The following table describes the information in the LISTUSER array, by position. 



UDTNO Sequential number UniData assigns to each user. 

USRNBR System-level process ID (pid) assigned to a UniData session. 

UID System-level ID assigned to a user. 

USRNAME Login name of the user. 

USRTYPE Type of process the user is running. 

TTY Device ID. 

TIME Time the user process started. 

DATE Date the user process started. 

LISTUSER Array

Example 

The following example displays the output from the LISTUSER function on UNIX: 

1}5131}0}root}udt}pts/1}10:20:03}Oct 16 2002 

LISTUSER Dynamic Array (Windows Platforms) 

The following table lists the LISTUSER command display attributes. 


UDTNO Sequential number UniData assigns to each user. 

USRNBR Process ID of the UniData session. 

UID Windows ID of the user. 

USRNAME Login name of the user. 

USRTYPE Type of process the user is running. 

TTY Session identifier, formed by concatenating the string “pts/” and the 

UDTNO. 

IP-ADDRESS Location where the session is logged in; either “Console” or a valid IP 

address. 

TIME The time at which the user process started. 

DATE The date on which the user process started. 

LISTUSER Display Attributes 

LISTUSER 1-415

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. 

Example 

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) 



EXP 


loadSecurityContext 

Syntax 

loadSecurityContext(context, name, passPhrase) 



Description 

The loadSecurityContext() function loads a saved security context record into the 

current session. 

The name and passPhrase parameters are needed to retrieve and decrypt the saved 

context. UniData creates an internal data structure and returns its handle in the 

context parameter. 

Parameters 



context The handle to be returned. 

name String containing the name of the file storing the security contents. 

PassPhrase String containing the passPhrase needed to decrypt the saved data. 

loadSecurityContext Parameters 

loadSecurityContext 1-417


Return 

Code Status 

0 Success. 


1 Context record does not exist. 

2 Context record could not be accessed (e.g. wrong password). 

3 Invalid content (file was not saved by the saveSecurityContext() 

function). 

4 Other problems that caused context load failure. Refer to the log file for 

more information. 

loadSecurityContext Return Codes

LOCATE 

Syntax 

LOCATE element IN dyn.array[,var] 

[BY search.type] SETTING location [THEN statements END] 

ELSE statements END 

For backward compatibility, UniData supports the following alternate syntax: 

LOCATE(element,dyn.array [,attrib.expr[,val.expr[,subval.expr]]];location 

[;search.type]) [THEN statements] [END] ELSE statements 

Description 

The UniBasic LOCATE command locates an element within a dynamic array. For 

LOCATE to be successful, the search string, element, must match the entire array 

element (including any associated lower-level elements). LOCATE does not modify 

the data in the array. 

Note: UDT.OPTIONS 85 changes the sort order for an array of mixed negative and 

positive numbers. With UDT.OPTIONS 85 on, negative and positive numbers are 

sorted in numeric order regardless of sign. This is effective for the first form of the 

syntax only. 

LOCATE 1-419

Parameters 




element Specifies the string to search for. element can be a variable, array 

element, function, or literal. 

dyn.array 

Specifies a dynamic array and level (attribute, value, or 

subvalue) to search. The search operates as follows: 

The search begins at the lowest level specified. 

Only the specified level is searched. 

Returns the position of the located string relative to the 

beginning of the search. 

1 in attrib.expr causes a search starting with the first attribute in 

the file. 

0 in any expression is treated as 1. 

If the arguments cause the search to begin beyond the end of the 

dynamic array, the ELSE clause executes. 

See also the LOCATE in BASICTYPEs U, P, and M table. 

,var Specifies the attribute, value, or subvalue in the array at which 

to begin the search. 

BY search.type Selects a type of search appropriate for the physical arrangement 

of a sorted array. 

AL – Ascending, contents left-justified. 

AR – Ascending, contents right-justified. 

DL – Descending, contents left-justified. 

DR – Descending, contents right-justified. 

When UniData first retrieves the data, it sorts the data in the 

requested order. 

Do not use a BY clause in a LOCATE statement on an unsorted 

array. The search could terminate before checking all elements. 

UDT.OPTIONS 85 modifies the sort to place negative numbers 

first rather than sort them in ASCII order. 

LOCATE Parameters


SETTING location Returns the location of the string. If the search is not successful, 

execution depends on the presence of the BY clause: 

If the BY clause is included, the array is assumed to be sorted, 

and a location is returned indicating where the element should be 

inserted to maintain the array in sorted order. 

If the BY clause is not included, the array is assumed to be 

unsorted, and the location returned is of the last element plus 

one. 

THEN statements END THEN (optional) is executed when the search is successful. 

Multiple line THEN or ELSE statements require an END 

keyword. 

ELSE statements END ELSE (required) is executed if the search is unsuccessful. 

Multiple line THEN or ELSE statements require an END 

keyword. 

Note: The syntax for BASICTYPEs P and M differs in the number of array elements 

you can include and the search driven by those elements. Syntax variants for P and 

M are as follows: 

LOCATE element IN dyn.array [BY search.type] 

SETTING location [THEN statements END] ELSE statements END 

and 

LOCATE Parameters (continued) 

LOCATE(element,dyn.array [,attrib.expr[,val.expr]];location [;search.type]) 

[THEN statements] [END] ELSE statements 

LOCATE 1-421

LOCATE in BASICTYPEs U, P, and M 

The following table compares the searches performed in BASICTYPEs U, P, and M. 

Examples 


“Sample Program,” in Developing UniBasic Applications. LOCATE returns the 

position of the order number to be deleted. 


LOCATE Parameter in BASICTYPE U in BASICTYPEs P and M 

no expr Performs no search; invalid 

syntax. 

attrib.expr Searches the attribute 

specified; match must 

include associated values 

and subvalues. 

val.expr Searches the value specified; 

match must include 

associated subvalues. 

subval.expr Searches subvalues 

associated with the specified 

value; begins with the 

specified subvalue. 

Comparison of BASICTYPEs U, P, and M 

Searches all attributes; match 

must include associated values 

and subvalues. 

Searches values associated with 

the specified attribute; match 

must include associated 

subvalues. 

Searches subvalues associated 

with the specified value. 

Performs no search; invalid 

syntax. 






END 


END

In the following example, the program statement searches the entire array, FILMS, 

element by element, for the literal string “BATMAN.” If the search is successful, 

UniData assigns the location of the element to the variable NDX. If UniData does not 

find the string, it sets NDX to the location of the last value plus 1, and it executes the 

STOP command. The LOCATE command performs the search on the attribute level. 

LOCATE "BATMAN" IN FILMS SETTING NDX ELSE STOP 

Because the LOCATE statement compares the entire element (including associated 

lower-level elements), a match will not be successful on either of the following 

arrays: 

or 

"CARMEN":@AM:"BATMANII":@AM:"JAWS" 

"CARMEN":@AM:"BATMAN":@VM:"KEATON":@VM:"DEVITO"@VM:"CARREY 

":@AM:"JAWS" 

In the next example, the program segment prints “BATMAN IS IN POSITION 2 IN 

THE ARRAY”: 

FILMS = "CARMEN":@AM:"BATMAN":@AM:"JAWS" 

LOCATE "BATMAN" IN FILMS SETTING NDX ELSE 

PRINT "NOT FOUND" 

STOP 

END 

PRINT "BATMAN IS IN POSITION ":NDX:" IN THE ARRAY" 

In the next example, the program segment searches the array FILMS, starting at 

attribute 2, value 2, for the contents of the variable DEVITO. UniData assumes the 

array elements are in ascending order and left-justified. 

LOCATE DEVITO IN FILMS BY "AL" SETTING NDX THEN 

PRINT "THIS TITLE IS IN THE LIBRARY" 

END ELSE 

PRINT "TITLE NOT FOUND, TRY AGAIN." 

END 

When executed on the following array, DEVITO is located in position 3 in the array 

at the value level, and UniData executes the first PRINT statement: 

"CARMEN":@AM:"BATMAN":@VM:"KEATON":@VM:"DEVITO"@VM:"CARREY 

":@AM:"JAWS" 

LOCATE 1-423

However, in the following array, the LOCATE command does not find DEVITO, and 

UniData executes the second PRINT statement: 


"CARMEN":@AM:"BATMAN":@VM:"KEATON"@VM:"CARREY":@AM:"BATMAN 

III": @VM:"KILMER":@VM:"DEVITO"@AM:"JAWS" 



FIND, FINDSTR

LOCK 

Syntax 

LOCK resource.num {THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic LOCK command reserves a computer resource (such as a device or 

file) for the current user process. 

The lock is associated with resource.num, not the resource itself. Therefore, a 

command that does not check for locks against the resource number will access the 

resource even if it is locked. For example, an installation might assign locks 1 

through 4 to four system printers. When an application needs to reserve printer 1, the 

application executes LOCK 1. For lock effectiveness, all other applications must 

check for locks before accessing the resource. 

Resources are not automatically unlocked by the termination of the locking program. 

The UniBasic UNLOCK or ECL QUIT commands must release them. Otherwise, 

you can release resources by executing the ECL CLEAR.LOCKS command at 

UniData level. 

For more information about UniData locks, see Developing UniBasic Applications. 

LOCK 1-425

Parameters 



Examples 

In the following example, the program statement reserves resource 12 if another 

program is not using it. If resource 12 is already in use, the current program suspends 

execution and waits until UniData unlocks resource 12. 

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. 


resource.num Specifies a number associated with a resource. resource.num can 

be any number from 0 through 63. 

For assistance in assigning resource numbers, see your system 

administrator. 

THEN statements END Specifies statements to execute if the LOCK statement executes 

successfully. 

ELSE statements END Specifies statements to execute if another user has reserved the 

resource (using the same resource number) so that 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 waits until that 

resource is released. 

Use the ECL command DEFAULT.LOCKED.ACTION BELL 

to make the terminal beep while you wait for UniData to release 

the lock. 

LOCK Parameters 

T1 = 44; T2 = 45 

LOCK T1 ELSE LOCK T2 ELSE STOP



UNLOCK 

UniData 

CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS, 

DEFAULT.LOCKED.ACTION – For information, see the UniData Commands 


LOCK 1-427

LOOP/REPEAT 

Syntax 

LOOP 

[statements] 

[UNTIL expr [DO] 

statements] 

[WHILE expr [DO] 

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 whether you use the WHILE or 

UNTIL clause. statements can precede and/or follow the test condition. If space 

permits, you can write the structure on one line. Otherwise, you can extend the 

structure on as many lines as necessary. REPEAT is required and finishes the LOOP 

operation. 

UniData executes the first set of statements on the first entry into the loop, and then 

evaluates the WHILE or UNTIL clause. If expr is true (using the WHILE keyword) 

or false (using the UNTIL keyword), UniData executes the second set of statements. 

If you have statements after a WHILE or UNTIL clause, the DO clause is required. 

Otherwise, it is optional. When the program execution reaches REPEAT, it returns to 

the first set of statements. 


Tip: IBM recommends that you construct loops that terminate based on the WHILE 

or UNTIL condition. The LOOP statement is flexible enough to incorporate almost 

any logical progression. Use the CONTINUE keyword to transfer control to the 

beginning of the next loop. 

Parameters 



expr Specifies an expression to check to for the UNTIL or WHILE 

clause. 

expr can be any valid statement that includes 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 

LOOP/REPEAT 1-429

Examples 


Program,” in Developing UniBasic Applications. This subroutine loops until the user 

enters a valid order number, or Q (the prompt for order number is already displayed 

on the screen). 


GET_ORDER_NUMBER: 

* Have the user enter a valid key to a record in the ORDERS file. 

LOOP 

DISPLAY @(15,6): 

INPUT ORDER_NUMBER 

ORDER_NUMBER = OCONV(ORDER_NUMBER,"MCU") 

IF NUM(ORDER_NUMBER) OR ORDER_NUMBER[1,1] = "Q" THEN 

VALID_ORDER_NUMBER = 1 

END ELSE 


MESSAGE = "Order # must be a Number, or the letter 'Q'" 

CALL DISPLAY_MESSAGE(MESSAGE) 

END 

UNTIL VALID_ORDER_NUMBER 

REPEAT 

In the next example, the program segment prints and increments POS until it 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 program executes the top statement and the 

loop stops because the condition (C > 8) is met. The program continues execution at 

the statement following REPEAT. The program does not execute the second 

statement on the final iteration. 

C = 0 

PRINT "Counting:" 

LOOP 

C = C+1 

UNTIL C > 8 DO 

PRINT "C = ":C 

REPEAT

The result of this program: 

Counting: 

C = 1 

C = 2 

C = 3 

C = 4 

C = 5 

C = 6 

C = 7 

C = 8 



CASE, CONTINUE, FOR/NEXT 

LOOP/REPEAT 1-431

LOWER 

Syntax 

LOWER(dyn.array.expr) 

Description 

The UniBasic LOWER function converts all attribute marks to value marks, and, in 

a dynamic array, it converts all value marks to subvalue marks. 

Example 

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" 



RAISE

LT 

Syntax 

expr1 LT expr2 

Synonym 

< 

Description 

The UniBasic LT relational operator tests whether expression expr1 is less than 

expr2. 



statements such as the following: 

IF VAR1 LT VAR2 THEN GOSUB SUB1 

DO UNTIL VAR1 < VAR2 

Example 

In the following example, the program segment tests whether A is less than B. 

Because A is less than B, the message “Less than” prints. 

A = 21 

B = 22 

IF A LT B THEN 

PRINT "Less than" 

END ELSE 

PRINT "Greater than" 

END 

LT 1-433



LTS 


LTS 

Syntax 

LTS(array1,array2) 

Description 

The UniBasic LTS function compares each element in array1 to its corresponding 


array1 is less than the value in the corresponding position in array2, and 0 in each 

position for values in array1 that are greater than those in array2. 

Example 





ARRAY3 = LTS(ARRAY1,ARRAY2) 

LTS 1-435

MAT 

Syntax 

MAT dim.array = expr 

MAT dim.array = MAT dim.array2 

Description 

The first form of the UniBasic MAT command assigns new values to all elements of 

a dimensioned array based on an expression. 

The second form assigns the contents of a dimensioned array to another dimensioned 

array. 

If you assign a dimensioned array the values of a second dimensioned array, the 

assignment proceeds from element to element in consecutive order. The program 

assigns the first element of the first array to the first element of the second array, then 

assigns the second element to the second element of the second array, and so on. The 

two arrays do not have to match in configuration of dimensions, but must contain the 

same number of elements. UniData does not alter the second dimensioned array in 

the assignment process. 

Use the DIM command to dimension all arrays before you assign new values to the 

elements. You can place MAT in any looping structure and assign the elements with 

a variable or function. 


Parameters 



dim.array Specifies a dimensioned array to receive new values. 

expr Specifies the value to assign to the array elements. expr can be any 

UniBasic expression. 

expr can be an empty string, a formula, a single value, a literal string, or a 

function. 

dim.array2 Specifies a dimensioned array from which to assign values. 

MAT Parameters 

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 dimensioned array 

FEE2 to the dimensioned array 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 arrays contain the following values before the assignment: 

dimensioned array FEE1 dimensioned array FEE2 

1 2 3 4 

5 6 7 8 

10 11 

12 13 

14 15 

16 17 

MAT 1-437

the values assigned to FEE1 would be: 

Notice how the elements are assigned: from left to right, top to bottom, element by 

element. UniData maintains all values in dimensioned array FEE2. The positions are 

shifted to fit the dimensions of dimensioned array FEE1. 



DIM, INMAT, MATBUILD, MATPARSE, MATREAD, MATREADL, 

MATREADU, MATWRITE, MATWRITEU 


dimensioned array FEE1 

10 11 12 13 

14 15 16 17

MATBUILD 

Syntax 

MATBUILD dyn.array FROM dim.array [,start.num [,end.num [USING delim]]] 

Description 

The UniBasic MATBUILD command generates a dynamic array from a dimensioned 

array based on specified starting and ending positions and the delimiter given. 

The dimensioned array can be multidimensional. The statement retrieves elements 

from the multidimensional array according to the order in which its elements are 

stored. 

Parameters 



dyn.array Specifies the dynamic array to be created. 

FROM dim.array Specifies the dimensioned array from which to build the dynamic 

array. 

MATBUILD Parameters 

MATBUILD 1-439


Examples 

In the following example, A is a dimensioned array with five elements: 


,start.num Specifies the starting position in the dimensioned array. If start.num 

is less than or equal to 0, UniData defaults to 1. The dynamic array 

is not generated if start.num is greater than end.num. 

,end.num Specifies the ending position in the dimensioned array. 

If end.num is less than or equal to 0, or if it is beyond the end of the 

dimensioned array, UniData retrieves data to the end of the 

dimensioned array. 

USING delim The USING clause specifies the delimiter delim in the dyn.array 

generation. If you do not specify delim, or if you specify an empty 

string, delim defaults to @AM (attribute mark). If you specify more 

than one character, only the first character is used. UniData inserts 

delim between the elements if dyn.array. 

A(1)=11, A(2)=22, A(3)=33, A(4)=44, and A(5)=55 

The following program statement: 

MATBUILD NEW.ARRAY FROM A ,2,4 

generates the following dynamic array: 

NEW.ARRAY = "22":@AM:"33":@AM:"44" 

The next program statement: 

MATBUILD ARRAY FROM A ,1 USING ',' 

generates the following dynamic array: 

ARRAY = "11,22,33,44,55" 

MATBUILD Parameters (continued)



DIM, INMAT, MAT, MATPARSE, MATREAD, MATREADL, MATREADU, 


MATBUILD 1-441

MATCH 

Syntax 

var MATCH "[~] len [X, A, N] [text]" 

Synonym 

MATCHES 

Description 

The UniBasic MATCH or MATCHES function determines if a variable matches a 

specific pattern of characters, numbers, or a literal string. If var matches the pattern, 

MATCH or MATCHES returns 1. If var does not match the pattern, MATCH or 

MATCHES returns 0. 

Tip: You can mix codes and literal strings. To differentiate between the two, enclose 

the literal in single quotation marks within the larger pattern, which is enclosed in 

double quotation marks. 

Parameters 




var Specifies the variable to compare with the MATCH expression. 

~ Reverses the pattern. To match 4N, a string must contain four numeric 

characters. To match ~4N, a string must contain four characters that are not 

all numeric. 

len Specifies the number of characters to match. 

X Specifies that characters can be of any type. 

MATCH Parameters


A Specifies that only alphabetic characters match the pattern. 

N Specifies that only numbers match the pattern. 

text Specifies a literal string to search for. Enclose this literal text within single 

quotation marks if combined with a pattern (made up of X, A, and N). 

Examples 

MATCH Parameters (continued) 

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" 

The following program accepts as input a pattern to match and a string to search: 

PRINT "This program tests the MATCH function" 

PRINT "Enter pattern ": 

INPUT pattern 

PRINT "Enter string to match": 

INPUT string1 

answer = string1 MATCH pattern 

PRINT \"\ : answer : \"\ 

In the following test executions of the preceding program, the user tests for a string 

that consists of three alphabetic characters followed by the literal “3A”. The literal 

(3A) is enclosed in quotation marks to differentiate it from the pattern 3A. 

:RUN BP match.test 

This program tests the MATCH function 

Enter pattern ?3A'3A' 

Enter string to match?AAA3A 

"1" 

:RUN BP match.test 

This program tests the MATCH function 

Enter pattern ?3A'3A' 

Enter string to match?3AAAA 

"0" 

MATCH 1-443

MATCHFIELD 

Syntax 

MATCHFIELD(str.expr,"[~] {len [X | ,A | ,N]} [text]", field.expr) 

Description 

The UniBasic MATCHFIELD function returns a substring that matches a pattern or 

literal. If no match is made, UniData returns an empty string. MATCHFIELD 


You can mix the codes and a text string to search for specific patterns separated by 

characters. 

With null value handling on, if a function encounters the null value in a parameter 

when a number is expected (field.expr), a warning message displays and UniBasic 

uses 0. 

Parameters 


Paramete 

r Description 


str.expr Specifies the variable to compare with the MATCH expression. 

~ Inverses the pattern. To match 4N, a string must contain four numeric 

characters. To match ~4N, a string must contain four characters that are not 

numeric. 

len Specifies the number of characters to match. 

X Specifies that characters can be of any data type. 

A Specifies that only alphabetic characters match the pattern. 

MATCHFIELD Parameters

Paramete 

r Description 

N Specifies that only numbers match the pattern. 

text Specifies a literal string to search for. 

field.expr Specifies a portion of the str.expr to return. Each code segment is considered 

to be a field for the purposes of field.expr. 

Examples 

MATCHFIELD Parameters (continued) 

In the following example, the program segment returns the value 56 because the 

entire string matches the specified criteria, and the third field contains the number 56: 

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 

MATCHFIELD 1-445

MATPARSE 

Syntax 

MATPARSE dim.array FROM str.expr, delim.expr 

Description 

The UniBasic MATPARSE command distributes elements of a delimited string or 

dynamic array to consecutive elements of a dimensioned array. Delimiters can be the 

standard UniData delimiters or any other ASCII character. 

When you specify an alternate delimiter, UniData returns a two-dimensional array. 

The delimited string is placed in the first dimensioned array element, and the 

delimiter is placed in the second element. When UniData encounters two delimiters 

in a row, both are placed in the first element. 

Note: BASICTYPEs P and R do not support the 0,0 element in dimensioned arrays. 

If more elements are delimited in the string than can be placed in the dimensioned 

array, a runtime error results and data is lost. 

Parameters 




dim.array Specifies the target dimensioned array. 

str.expr Specifies a delimited string to place in the dimensioned array. 

delim.expr Specifies the delimiter to use for parsing str.expr. You can use any ASCII 

character including commas or spaces. 

MATPARSE Parameters


After you execute MATPARSE, the INMAT function returns one of the values 



n The number of elements loaded into the array. 

0 The array was too small to contain all elements in the string. All excess data 

(including delimiters) is placed in the 0,0 element. 


Examples 

In the following example, the program segment fills the dimensioned array ALPHA 

with consecutive characters from a literal string. An empty string is the delimiter, 

causing one character to be assigned to each dimensioned array cell. In this case, the 

value returned by the INMAT function would be 7. 

DIM ALPHA(7) 

MATPARSE ALPHA FROM "ABCDEFG","" 

The preceding program segment produces the following dimensioned array: 

ALPHA(1) = "A" 

. 

. 

. 

ALPHA(7) = "G" 

In the next example, the program segment dimensions the dimensioned array 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 array is dimensioned with four elements. 

After the MATPARSE 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) 

MATPARSE 1-447

The preceding program segment produces the following dimensioned array: 

T(0) = 443 

T(1) = 123 

T(2) = 33 

T(3) = 199 

T(4) = 821 



DIM, INMAT, MAT, MATBUILD, MATREAD, MATREADL, MATREADU, 



MATREAD 

Syntax 

MATREAD dim.array [FROM [file.var,]record.ID.expr [ON ERROR statements] 

{THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic MATREAD command assigns the values found in successive attributes 

of a record to corresponding elements of a dimensioned array — regardless of 

lock status. 

You must use the DIM command to create a dimensioned array before you execute 

MATREAD. 

Note: This command does not check for locks. If you are operating in a multiuser 

environment, you must use record locks to prevent users from overlaying data 

updated by others. For more information about the UniBasic record locking, see 

Developing UniBasic Applications. 

Parameters 



dim.array Specifies the dimensioned array into which the values are read. 

FROM file.var, Specifies the file from which to read. 


file. If no default file is open, a fatal READ error occurs. 



record.ID.expr Specifies the record from which to read. 

MATREAD Parameters 

MATREAD 1-449



After you execute MATREAD, the INMAT function returns one of the values 


Note: BASICTYPEs P and R do not support the 0,0 element. If more attributes are 

read from the file than can be placed in the dimensioned array, a runtime error results 

and data is lost. 

Examples 

In the following example, the program segment reads the record with ID NAMES 

from the CUSTFILE, and assigns the elements to the dimensioned array TEST. If the 

program does not find the record, it assigns the value 0 to the variable FOUND. 


ON ERROR statements Specifies statements to execute if the MATREAD statement fails 

with a fatal error because the file is not open, an I/O error occurs, 

or UniData cannot find the file. 

If you do not specify the ON ERROR clause and a fatal error 

occurs, the program terminates. 

THEN statements END THEN executes if the read is successful. END is required to 

terminate multiline THEN statements. 

ELSE statements END ELSE executes if the read is not successful or the record (or ID) 

does not exist. END is required to terminate multiline ELSE 

statements. 

Value Meaning 

MATREAD Parameters (continued) 

n The number of attributes loaded into the array. 

0 The array was too small to contain all attributes in the record. The excess data 

(including delimiters) is placed in the 0,0 element. 


DIM TEST(10,10) 

MATREAD TEST FROM CUSTFILE,"NAMES" ELSE FOUND = 0

In the next example, the program segment reads the record with ID NAMES and 

assigns the data from the record to the dimensioned array TEST: 

OPEN "CUSTFILE" TO CF ELSE STOP "NO CUSTFILE" 

MATREAD TEST FROM CF,"NAMES" ELSE FOUND = 0 

In the next example, the MATREAD statement includes multiline THEN and ELSE 

clauses: 

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 



DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREADL, MATREADU, 


MATREAD 1-451

MATREADL 

Syntax 

MATREADL dim.array FROM [file.var,]record.ID.expr [ON ERROR statements] 

[LOCKED statements] {THEN statements [END] | ELSE statements [END]} 

MATREADL dim.array FROM [file.var,]record.ID.expr [LOCKED statements] 

[ON ERROR statements] {THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic MATREADL command assigns the values found in successive attributes 

of a record to corresponding elements of a dimensioned array. MATREADL 

checks for locks and will not read a record locked with an exclusive (U) lock. If the 

record is available, MATREADL reads and sets a shared (L) lock on it. 

Note: UniBasic locks are advisory only. They prevent access by other lock-checking 

commands only. For more information about UniBasic locks, see Developing 


Parameters 





FROM file.var, Specifies the file from which to read. 





record.ID.expr Specifies the record from which to read the attributes. 

MATREADL Parameters


ON ERROR statements Specifies statements to execute if the MATREADL statement 

fails with a fatal error because the file is not open, an I/O error 

occurs, or UniData cannot find the file. 



LOCKED statements Specifies statements to execute if the record is locked by another 

user. If you do not specify a LOCKED clause, the program waits 

until UniData releases the lock on the record. You can place the 

LOCKED clause after the FROM clause. 


to make the terminal beep while you wait for UniData to unlock 

the record. 





statements. 


After you execute MATREADL, the INMAT function returns one of the values 



MATREADL Parameters (continued) 


0 The array was too small to contain all attributes in the record. The excess data 

(including delimiters) is placed in the zero element. 


Note: BASICTYPEs P and R do not support the 0,0 element. If UniData reads more 

attributes from the file than it can place in the dimensioned array, a runtime error 

results and data is lost. 

MATREADL 1-453

Example 

In the following example, the program segment reads a tape record with the ID 

specified in TAPE.ID from the TAPES.FILE. If the program finds the record, it 

transfers control to the subroutine TAPE.PROCESS. Otherwise, the program 

displays a message and aborts. If the record is locked with an exclusive lock, the 

program does not execute the subroutine. Instead, it displays the message “RECORD 

LOCKED” and waits for the lock to be released. 


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 



DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADU, 


UniData 

DEFAULT.LOCKED.ACTION – For more information, see the UniData Commands 


MATREADU 

Syntax 

MATREADU dim.array FROM [file.var,] record.ID.expr [ON ERROR statements] 


MATREADU dim.array FROM [file.var,] record.ID.expr [LOCKED statements] 


Description 

The UniBasic MATREADU command assigns the values found in successive attributes 

of a record to corresponding elements of a dimensioned array. MATREADU 

checks for locks and will not read a locked record. If the record is available, 

MATREADU reads and sets an exclusive (U) lock on it. 

Note: UniBasic locks are advisory only. They prevent access by other lock-checking 

commands only. For more information about UniBasic locks, see Developing 


BASICTYPEs P and R do not support the 0,0 element. If UniData reads more attributes 

from the file than it can place in the dimensioned array, a runtime error results 

and data is lost. 

MATREADU 1-455

Parameters 





FROM file.var Specifies the file from which to read. 





record.ID.expr Specifies the record from which to read the attributes. 

ON ERROR statements Specifies statements to execute if the MATREADU statement 







until the lock on the record is released. You can place the 



to beep the terminal while waiting for the record to be unlocked. 





statements. 

MATREADU Parameters


After you execute MATREADU, the INMAT function returns one of the values 




0 The array was too small to contain all attributes in the record. All excess data 

(including delimiters) is placed in the zero element. 


Examples 

In the following example, the program segment reads the record with ID “NAMES” 

from the CUST file. Because no LOCKED clause is provided, the program waits for 

access if the record is locked by another user. 

DIM TEST(10,10) 

MATREADU TEST FROM CUST,"NAMES" ELSE GOSUB 105 

In the next example, the program segment reads the record with the ID CUST.ID and 

assigns each attribute to successive elements in the dimensioned array CUST.REC. 

If the record is found, UniData executes the THEN clause. If the record is locked, 

UniData displays RECORD LOCKED and waits for the lock to be released. If the 

record is not found, UniData displays RECORD NOT FOUND FOR CUSTOMER 

and the customer ID. 

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 

MATREADU 1-457



DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, 


UniData 




MATWRITE 

Syntax 

MATWRITE dim.array {ON | TO file.var,} record.ID.expr 

[ON ERROR statements] 

Description 

The UniBasic MATWRITE command writes successive elements of a dimensioned 

array to the corresponding attributes of a record. 

If the dimensioned array size exceeds the number of attributes in the target record, 

the MATWRITE command does not write the trailing spaces. If the 0 element is not 

empty, the command writes the contents of the element after the final element in the 

record (as element N+1). 

Note: This command must be preceded by MATREADU or another locking command 

to prevent the type of inconsistency that results when multiple users access files at the 

same time. For more information, see Developing UniBasic Applications. 

Parameters 



dim.array Specifies the dimensioned array from which to assign the values 

read to the successive attributes of the record record.ID.expr. 

You must name and dimension an array before you can use it in 

the MATWRITE statement. 

MATWRITE Parameters 

MATWRITE 1-459



After you execute MATWRITE, the STATUS function returns one of the values 


Example 

In the following example, the program segment writes the dimensioned array 

RECEIPTS to the file REC87 as a record with ID “RENTALS”: 


ON | TO file.var, Specifies the file on which to write the record. You must specify 

an ON or TO clause. 

record.ID.expr Specifies the record on which to write the attributes. 

ON ERROR statements Specifies statements to execute if MATWRITE fails with a fatal 

error because the file is not open, an I/O error occurs, or UniData 

cannot find the file. 




MATWRITE Parameters (continued) (continued) 

0 The record was locked before MATWRITE executed. You are in danger of simultaneously 

updating a record being updated by another user. 

-2 The record was not locked before MATWRITE executed. 


COMMON RECEIPTS(12) 

MATWRITE RECEIPTS ON REC87,"RENTALS"




MATREADU, MATWRITEU 

MATWRITE 1-461

MATWRITEU 

Syntax 

MATWRITEU dim.array {ON | TO} [file.var,] record.ID.expr 


Description 

The UniBasic MATWRITEU command writes successive elements of a dimensioned 

array to the corresponding attributes of a specified record. MATWRITEU 

does not release locks set by READU, READVU, or MATREADU statements. 



Parameters 




dim.array Specifies the dimensioned array from which to assign the values read 

to the successive attributes of the record record.ID.expr. 

You must name and dimension an array before you can use it in the 

MATWRITE statement. 

ON | TO file.var, Specifies the target file. You must specify an ON or TO clause. 

record.ID.exp Specifies the target record. 

ON ERROR 

statements 

Specifies statements to execute if MATWRITEU fails with a fatal 

error because the file is not open, an I/O error occurs, or UniData 


If you do not specify the ON ERROR clause and a fatal error occurs, 

the program terminates. 

MATWRITEU Parameters


After you execute MATWRITEU, the STATUS function returns one of the values 


Value Meaning 

0 The record was locked before MATWRITEU executed. You are in danger of 

simultaneously updating a record being updated by another user. 

-2 The record was not locked before MATWRITEU executed. 


Example 

In the following example, the program statement writes the dimensioned array 

NEW.CLIENTS to the file CLIENTS as a record with an ID of ‘050887’. If the record 

is locked, UniData maintains the lock. 

MATWRITEU NEW.CLIENTS TO CLIENTS,'050887' 




MATREADU, MATWRITE 

MATWRITEU 1-463

MAXIMUM 

Syntax 

MAXIMUM(dyn.array.var) 

Description 

The UniBasic MAXIMUM function returns the largest numeric value found in a 

dynamic array. This function ignores nonnumeric elements. If the array you specify 

contains only nonnumeric elements, MAXIMUM returns an empty string. If an 

element is empty, UniData treats it as 0. 

UniData treats all system marks (attribute, value, and subvalue marks) 

indiscriminately. That is, any value between two marks of any kind is taken as an 

element with respect to this function. 

Examples 

In the following example, the program segment prints 22: 


X = "12":@VM:"2":@FM:"dd":@FM:"9":@FM:"22" 

PRINT MAXIMUM(X) 

In the next example, the program segment prints 0 because W contains an empty 

element and no other numeric elements exist: 

W = "A":@FM:"B":@VM:"":@SM:"C" 

PRINT MAXIMUM(W) 



MINIMUM

MBLEN 

Syntax 

MBLEN (str.expr) 

Description 

The UniBasic MBLEN function returns the number of bytes in the first character of 

a string. 

Example 

The following figure illustrations a string that indicates below each “character” the 

number of bytes required to display that character. MBLEN returns 2 for this string, 

which indicates that the first character is made up of two bytes. 

Number 

of bytes 



2 3 1 2 

BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LEN 

MBLEN 1-465

MDPERFORM 

Syntax 

MDPERFORM str.expr [CAPTURING, dyn.array.var] 

[RETURNING, dyn.array.var] [RTNLIST int.expr] [PASSLIST int.expr] 

[PASSCOM] 

MDPERFORM str.expr [RETURNING, dyn.array.var] 

[CAPTURING, dyn.array.var] [RTNLIST int.expr] [PASSLIST int.expr] 

[PASSCOM] 

Description 

The UniBasic MDPERFORM command executes various UniData commands, 

sentences, or paragraphs within a UniBasic program while transferring lists to and 

from the executed commands. 

You can nest MDPERFORM. For example, in program A an MDPERFORM 

statement, which has a “CAPTURING var1” clause, invokes program B. Program B 

contains a second MDPERFORM statement that also has a “CAPTURING var2” 

clause. The output of programs A and B is sent to var1 and var2 respectively. 

You can nest only two MDPERFORM statements. To increase the number of nested 

levels: 

For the entire system – Enter a higher number for the udtconfig file variable 

MAX_CAPT_LEVEL. 

For this process only – Enter a higher number for the environment variable 

MAX_CAPT_LEVEL. 

Note: MDPERFORM does not pass select lists unless you explicitly specify them. In 

this way, you maintain full control and protection over them. 

STACKCOMMON 






unnamed common is passed to the executed program and back to the 

executing program. 


unnamed common is not passed to the program you execute. Instead, 

unnamed common is saved, and the unnamed common of the called 

program is initialized to 0. When control is passed back to the calling 

program, unnamed common is restored to its value before the program call. 

Unnamed common is never passed to a phantom program. 

Note: STACKCOMMON is always on in BASICTYPEs P and M. The default setting 

for STACKCOMMON is off in BASICTYPEs R and U. 

Parameters 



str.expr Specifies a UniData command with appropriate parameters. If you pass 

a file name to MDPERFORM, you must use the actual file name, not a 

file variable (which is assigned in the OPEN statement). 

CAPTURING, 

dyn.array.var 

RETURNING, 

dyn.array.var 

The CAPTURING clause stores the output in a dynamic array instead 

of on the display terminal. Each line of the text becomes an attribute in 

the array. Output sent to the printer is not affected by this clause. 

The RETURNING clause captures error messages resulting from the 

command executed with MDPERFORM. This variable contains a 

string of error message numbers separated by spaces. If the executed 

command creates a spooler hold file, UniData also returns the hold file 

number in the same variable. 

MDPERFORM Parameters 

MDPERFORM 1-467


Examples 

In the following example, the program segment lists all the items in the VOC file and 

returns the result in select list 2: 


RTNLIST int.expr The RTNLIST clause must evaluate to an integer 0–9, designating the 

list to return to the calling program. You can use the resulting list with 

subsequent READNEXT statements or in the PASSLIST clause of a 

MDPERFORM statement. If you do not include an expression after 

RTNLIST, the generated list replaces the contents of list 0. If you do not 

specify RTNLIST, the MDPERFORM command does not return a list. 

PASSLIST 

int.expr 

The PASSLIST clause must evaluate to an integer 0, 1, or 2, 

designating the select list to be sent to the called program. If you do not 

specify int.expr, UniData assumes list 0. 

The passed list can be the result of previous SELECT or GETLIST 

commands, or the RTNLIST clause of an MDPERFORM statement. 

PASSCOM This parameter is provided for backward compatibility for releases 

before 3.1. 

MDPERFORM Parameters (continued) 

list_var = 2 

MDPERFORM "list dict VOC all" RTNLIST list_var 

In the next example, the program segment performs a selection on the CUSTOMER 

file, passes the result back in select list 1, and 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 

conditions generated by MDPERFORM. According to the value of input_var, one of 

three UniQuery commands is 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 





END CASE 

In the next example, the program segment performs the command stored in cmd3, 

passing the list specified by list_var, and sends output to a dynamic array cpt_var: 

MDPERFORM cmd3 PASSLIST list_var CAPTURING cpt_var 



COMMON, EXECUTE, EXECUTESQL, PCPERFORM, UDTEXECUTE 

UniData 

STACKCOMMON – For more information, see the UniData Commands Reference. 

MDPERFORM 1-469

MINIMUM 

Syntax 

MINIMUM(dyn.array.var) 

Description 

The UniBasic MINIMUM function returns the smallest numeric element found in a 

dynamic array. 

UniData ignores nonnumeric elements with this function. If dyn.array.var contains 

only nonnumeric elements, the function returns an empty string. If an array element 

is empty, it is treated as 0. 

All system marks (attribute, value, and subvalue marks) are treated indiscriminately. 

That is, any value between two marks is taken as an element. 

Examples 

In the following example, the program segment prints 2: 


X = "12":@VM:"2":@AM:"dd":@AM:"9":@AM:"22" 

PRINT MINIMUM(X) 

In the next example, the program segment assigns U an empty string because V 

contains only nonnumeric elements: 

V = "":@AM:"assignment":@AM:"test" 

U = MINIMUM(V) 



MAXIMUM

MOD 

Syntax 

MOD(num.expr1, num.expr2) 

Synonym 

REM 

Description 

The UniBasic MOD and REM functions return the remainder of the division of 

num.expr2 into num.expr1. These functions divide integers and decimals. The sign of 

the result is the same as that of num.expr1. 

The formula used by MOD and REM is: 

REM(x,y) = x - (INT(x/y) * y) 

where x and y are numeric expressions. The first expression, x, is divided by y, and 

INT truncates the result. UniData multiplies the resulting integer by y, and subtracts 

the result from the value of x. 

Note: The value of num.expr2 cannot be 0. 

Example 

In the following example, the program segment assigns to Z the remainder of the 

division of Y into X. In this case, the remainder is 2. 

X = 12 ; Y = 5 

Z = MOD(X,Y) 

MOD 1-471

NE 

Syntax 

expr1 NE expr2 

Synonyms 

#, , >< 

Description 

The UniBasic NE relational operator tests whether expression expr1 is not equal to 

expr2. 


Tip: You can also use the # symbol to negate other relational operators. For example, 

the following statement uses the # symbol to negate the > symbol. In this case, if X is 

not greater than Y, the program branches to label 1000. 

IF X #> Y THEN GOSUB 1000 

Examples 


“Sample Program,” in Developing UniBasic Applications. In the first statement, if 

the variable NEW.PRICE is not equal to an empty string, the variable is written to the 

seventh element in array ORDER.REC. 


IF NEW.PRICE NE '' AND NUM(NEW.PRICE) THEN 

ORDER.REC = NEW.PRICE 


END



NES 

NE 1-475

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 

negative, NEG returns a positive value. 

Example 

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 



ABS 


NES 

Syntax 

NES(array1, array2) 

Description 

The UniBasic NES function compares each value in array1 to its corresponding 

value in array2. UniData returns an array with a one in each position where the value 

in 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. 

Example 


returns ARRAY3. ARRAY3 now contains 0}0}0}1}1. 



ARRAY3 = NES(ARRAY1,ARRAY2) 

NES 1-477

NFAUSER 

Syntax 

NFAUSER(“username”, “password”) 

Description 

Beginning at UniData 5.0, a Network File Access (NFA) connection from an NFA 

client requires a valid user name and password. If the client connection is made 

through udtelnet, this information is available and passed to the NFA server for 

connecting. If the session is a console session, the system prompts for the user name 

and password when a connection is requested, such as when you OPEN the first NFA 

file on a database. 

UniBasic now provides the NFAUSER function which enables you to set the user 

name and password in a UniBasic program. 

Parameters 



After running this function and providing a valid user name and password combination, 

an NFA connection no longer prompts for this information, regardless if it is 

from the console or via udtelnet. NFAUSER does not validate the user 

name/password combination, but registers them in an internal variable for later use. 


username A valid user name on the NFA server to which you are connecting. 

password The password corresponding to username. 

NFAUSER Parameters

NOCONVERT 

Syntax 

NOCONVERT {OFF | ON} 

Description 

The UniBasic NOCONVERT command controls the conversion of the special 

character CHAR(0). The following UniBasic commands read and write non-UniData 

files or tapes and convert CHAR(0) to CHAR(128) on input. They also convert 

CHAR(128) to CHAR(0) on output. This can cause problems under some circumstances, 

especially if you use the character CHAR(128) in an application or in stored 

data. NOCONVERT provides a way of switching the conversion OFF or ON. The 

default is OFF. 

The following UniBasic commands convert CHAR(0) and CHAR(128) when 

NOCONVERT is turned on: 

OSBREAD, OSBWRITE, OSREAD, OSWRITE, READT, WRITET 

Note: The PRINT and CRT functions do not work with strings that contain CHAR(0). 

Warning: Do not use UniBasic READ and WRITE commands to open or modify 

binary data in DIR-type files (for example, BP). Doing so can corrupt data in the file. 

Instead, use OSREAD or OSBREAD after executing the UniBasic NOCONVERT 

command. 

The following functions work with strings containing CHAR(0), regardless of the 

setting of the NOCONVERT command: 

Assignment (X = Y) 

Bracket function ([]) 

Substring assignment (A[1,3] = B) 

String concatenation (A:B) 

CHAR 

CONVERT 

COUNT 

NOCONVERT 1-479

DCOUNT 

INDEX 

LEN 

SEQ 

SWAP 


NOT 

Syntax 

NOT(expr) 

Description 

The UniBasic NOT Boolean operator inverts the logical result of the argument expr. 

If the expression is true, the function returns 0 (false). If the expression is not true, 

the function returns 1 (true). 

Example 

In the following example, the program segment compares X to Y (false because X is 

not greater than Y) and inverts the result, evaluating to true instead. Next, the THEN 

statement executes, sending program control to the label specified by RETRY. 

X = 1 ; Y = 2 

IF NOT(X > Y) THEN GOSUB RETRY: 



#, NOTS 

NOT 1-481

NOTS 

Syntax 

NOTS(dyn.array) 

Description 

The UniBasic NOTS Boolean operator inverts the logical result of each element of a 

dynamic array. If the element is true, the operator returns 0 (false) in the corresponding 

position of the new array. If the expression is not true, the operator returns 

1 (true) in the corresponding position of the new array. 

Example 

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) 


NULL 

Syntax 

NULL 

Description 

The UniBasic NULL command acts as a dummy statement. You can use the NULL 

statement anywhere a statement is required. 

Tip: Use NULL when a statement or command clause is mandatory, but you do not 

want to initiate any action. 

Example 

In the following example, if the length of the variable NAME$ is zero, the program 

prints nothing: 

PRINT "NAME: ": ; INPUT NAME$ 

BEGIN CASE 

CASE LEN(NAME$) = 0 

NULL 

CASE LEN(NAME$) > 0 

PRINT "HI, ":NAME$ 

END CASE 

NULL 1-483

NUM 

Syntax 

NUM(expr) 

Description 

The UniBasic NUM function determines if an expression is numeric. If expr is 

numeric, NUM returns 1. Otherwise, it returns 0. expr can be any valid UniBasic 

expression. The NUM function returns 0 for any multibyte character. 

With null value handling on, this function returns 1 for the null value. 

The nonnumeric characters in the following table produce a result of 1. 

Examples 

In the following example, the program segment prints 0 because VAR contains alphabetic 

characters: 

VAR = 'ABC' 

PRINT NUM(VAR) 

In the next example, the program segment prints 1 because VAR contains an integer: 

VAR = -123 

PRINT NUM(VAR) 


Character Description 

+ Plus sign 

- Negative sign 

. Decimal point 

Nonprinting Null value 

Nonnumeric Characters



ALPHA, ICONV Masked Character (MC), NUMS, OCONV Masked Character 

(MC) 

NUM 1-485

NUMS 

Syntax 

NUMS(dyn.array) 

Description 

The UniBasic NUMS function determines, for each element of an array, if that 

element is numeric. If the element is numeric, NUM returns 1 in the corresponding 

position of the new array. For nonnumeric and multibyte characters, it returns 0. 

With null value handling on, this function returns 1 for the null value. 

The nonnumeric characters in the following table produce a result of 1. 

Example 

In the following example, the program segment determines whether each element of 

array CHARACTERS is numeric. The resulting array B contains 1}1}1}0}0. 


Character Description 

+ Plus sign 

- Negative sign 

. Decimal point 

Nonprinting Null value 

Nonnumeric Characters 

CHARACTERS = 123:@FM:456:@FM:-789:@FM:"ABC":@FM:"CDE" 

B = NUMS(CHARACTERS)



ICONV Masked Character (MC), OCONV Masked Character (MC) 

NUMS 1-487

OCONV 

Syntax 

OCONV(expr, conv.code.expr) 

Description 

The UniBasic OCONV function converts string or numeric data from internal format 

to display format based on conversion codes. If the input value or conversion code is 

invalid, UniData returns the input value. OCONV supports multibyte languages. 

Note: In BASICTYPE P, OCONV returns an empty string if UDT.OPTIONS 56 is on 


Parameters 



The following table summarizes the valid conversion codes. A detailed discussion of 

each follows under separate headings. 


expr Specifies the expression, a string or numeric data, to convert. 

conv.code.expr Specifies an internal representation format to use when converting expr. 

OCONV Parameters 

Code Format 

D System date. 

G Extracts one or more strings separated by a delimiter. 

L Length. 

MB Binary. 

OCONV Codes



ICONV 

Code Format 

MC Masked character. 

MD Masked decimal. 

ML Left-justify. 

MP Packed decimal. 

MP1 Convert to packed decimal without truncating at the first CHAR(0) or 

altering this character. 

MO Octal. 

MR Right-justify. 

MT System time. 

MX Hexadecimal. 

P Pattern match. 

R Range. 

S SOUNDEX. 

T Text extraction. 

Tfile File translation. 

OCONV Codes (continued) 

OCONV 1-488

OCONV Date (D) 

Syntax 

OCONV(integer.exp, "D [y] [c] [fmt]") 

Description 

The OCONV date (D) function converts an integer in internal date format to date 

display format. If the input value or conversion code is invalid, UniData returns the 

input value. UniData ignores leading zeros in the input date. 

Note: The internal format of the date is the number of days before or after December 

31, 1967. Days before are represented as negative numbers. 

With UDT.OPTIONS 4 on, this command converts the text of dates to uppercase. For 

example, May 13 is converted to MAY 13. 

With UDT.OPTIONS 29 on, this command converts Sunday to 7 instead of 0. For 

information about UDT.OPTIONS, see the UDT.OPTIONS Commands Reference. 

In BASICTYPE P, OCONV returns an empty string if UDT.OPTIONS 56 is on and the 


Parameters 




integer.exp Indicates a date in internal format. 

OCONV Date (D) Parameters


y Number of digits to represent the year in the formatted date. 

c Delimiter separating day, month, and year. Can be a space, slash, period, 

comma, hyphen, or asterisk. 

fmt Format for date display. The following formats are available: 

mm dd yy[yy] 

day month year 

yy[yy] mm dd 

Combine the output format codes in the following table to format the date. 

The syntax for format codes is the following: 

[D | W | WA] [ [M] [Y] | Q | QA]] [J] [[,] {An | Zn} [[,] {An | Zn}...] 

Format Codes 

OCONV Date (D) Parameters (continued) 

The following table describes the valid output format codes. 


D Includes day in the output date. 

M Includes month in the output date. 

Y Includes year in the output date. 

Q Converts to quarter numeric format. 

QA Converts to quarter alphabetic format. 

W Valid for day only. Specifies numeric format. 

WA Valid for day only. Specifies alphabetic format. 

OCONV Date Output Format Codes 

OCONV Date (D) 1-490

Note: Following SMA standards, Monday is the first day of the week (1). If 

UDT.OPTIONS 29 is on, Sunday converts to 7 instead of 0. 


After you execute OCONV D, the STATUS function returns one of the values 


Examples 

The following statements are taken from the sample program in Appendix A, 

“Sample Program,” in Developing UniBasic Applications. It converts the date stored 

in internal format in the ORDERS file. The formatted date is in MM/DD/YYYY 

format. 



An Valid for day, quarter, and month only (WAn, QAn, and 

MAn respectively). A specifies alphabetic format, and n 

indicates number of characters. 

Zn Valid for month and day only. Z specifies numeric format; 

and n indicates number of digits. Z without a digit and Z0 

suppress zeros. 

J Displays the Julian date (the number of days since 

January 1). 

OCONV Date Output Format Codes (continued) 


0 Successful conversion of a valid date. 

1 The input date was invalid. 

2 The conversion code was invalid. 


ORDER_DATE = OCONV(ORDER.REC,"D4/")

In the following example, the program statement prints a three-character month 

name, a numeric day, and a four-digit year (suppressing zeros if necessary): 

PRINT OCONV(ORDER.REC, "DMDYA3,Z,Z4") 

In the following example, the program statement prints J 1970 4: 

PRINT OCONV(732,"dmywa1z3") 

Some sample format codes are applied in the following table. 

Input Value Conversion Code Output 

744 DDMY 13 Jan 1970 

744 DMDY 01 13 1970 

1006 D 02 Oct 1970 

1006 DDMY 02 10 1970 

1006 DDMYZ0,Z,Z 2 10 1970 

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 

7334 DW 5 

7334 DWA Friday 

7334 DQ 1 

7334 DQA Winter 

7334 DJY 029 1988 

OCONV Date Examples 

OCONV Date (D) 1-492



DATE, ICONV Date (D), TIMEDATE 

UniData 

DATE, DATE.FORMAT, SET.TIME – For information, see the UniData Commands 



OCONV Group (G) 

Syntax 

OCONV(str.expr, "G[m]x n") 

Description 

The OCONV group (G) function extracts one or more strings separated by a 

delimiter. If the input value or conversion code is invalid, UniData returns the input 

value. 



Parameters 


Paramete 

r Description 

str.exp Indicates a string separated by a delimiter. 

m Indicates the number of strings to skip. If m is omitted, no strings are skipped. 

x Specifies any single nonnumeric character to be the delimiter. UniData system 

delimiters are valid. Hyphen or minus sign is not valid. 

n The number of strings to be extracted. 

OCONV Group (G) Parameters 

Example 

In the following example, the program segment prints (303): 

X = "(303)+555+0988" 

PRINT OCONV(X,"G0+1") 

OCONV Group (G) 1-494



ICONV Group (G) 


OCONV Length (L) 

Syntax 

OCONV(str.expr, "Ln[,m]") 

Description 

The OCONV length (L) function extracts a string of a specified length or that falls 

within a range of acceptable lengths. If the input value or conversion code is invalid, 




Parameters 



str.exp Indicates a string to be searched. 

n Specifies the number of characters the string must match to be extracted. 

When m is present, n is the shortest string to be extracted. 


OCONV Length (L) Parameters 

Example 

In the following example, the program segment prints “123” and an empty string 

because X has fewer than five characters and more than three: 

X = 123; Y = 456789 

PRINT OCONV(X,"L3,5") 

PRINT OCONV(Y,"L3,5") 

OCONV Length (L) 1-496



ICONV Length (L) 


OCONV Masked Character (MC) 

Syntax 

OCONV(str.expr, "MC [A | /A | B | /B | C;x;y | U | L | T | N | /N | P | X[D] | D | D[X] 

| X]") 

Description 

The OCONV mask character (MC) function converts alphabetic characters to 

uppercase or lowercase, or extracts alphabetic or numeric characters from strings. 

This function performs the same conversions and extractions as ICONV MC. If the 




Parameters 



str.expr The expression to be searched or converted. 

A Extracts all alphabetic characters. 

/A Extracts all nonalphabetic characters. 

B Extracts all alphabetic and numeric characters. 

/B Extracts all special characters (not alphabetic nor numeric). 

C;x;y Converts all occurrences of substring x to substring y. 

U Converts data to uppercase. 

L Converts characters to lowercase. 

OCONV Masked Character (MC) Parameters 

OCONV Masked Character (MC) 1-498


Examples 

The following subroutine is taken from the sample program in Appendix A, “Sample 

Program,” in Developing UniBasic Applications. The subroutine converts user input 

to uppercase, then compares that input with Q to determine if the user is ready to quit 

the application. The user can enter any string starting with Q or q, or an order number. 


T Converts to initial cap style. First letter of each word is uppercase, and all 

other letters are lowercase. Space and tab are considered word separators. 

N Extracts all numeric characters (0-9). 

/N Extracts all nonnumeric characters. 

P Converts all nonprinting characters to tildes (~). 

X[D] or D Assumes input is in hexadecimal; converts to decimal. 

D[X] or X Converts input to hexadecimal. 

OCONV Masked Character (MC) Parameters (continued) 

GET_ORDER_NUMBER: 

* Have the user enter a valid key to a record in the ORDERS file. 

LOOP 

DISPLAY @(15,6): 

INPUT ORDER_NUMBER 

ORDER_NUMBER = OCONV(ORDER_NUMBER,"MCU") 

IF NUM(ORDER_NUMBER) OR ORDER_NUMBER[1,1] = "Q" THEN 


END ELSE 


MESSAGE = "Order # must be a Number, or the letter 'Q'" 

CALL DISPLAY_MESSAGE(MESSAGE) 

END 

UNTIL VALID_ORDER_NUMBER 

REPEAT 

The following statement, taken from the same sample program, extracts the numbers 

from user input. This use of OCONV removes the special characters the user might 

have entered in a formatted date. For example, the statement extracts 1234 from 

$12.34. 

NEW.PRICE = OCONV(NEW.PRICE,"MCN")



ALPHA, CONVERT, DOWNCASE, ICONV Masked Character (MC), NUM, 

UPCASE 

OCONV Masked Character (MC) 1-500

OCONV Masked Decimal (MD) 

Syntax 

OCONV(num.expr, "MDn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] 

[,] [$] [- | < | E | C | D] [P] [Z] [T] [xc]") 

Description 

The OCONV masked decimal (MD) function scales, rounds, and formats a number 

for display with up to nine decimal places. num.expr can be any numeric value. If the 



and the input value or the conversion code is invalid. 

Parameters 


Some parameters set the same values. Results are unpredictable if you make 

conflicting assignments. 



num.expr Indicates a number to be formatted. 

n Sets precision (the number of decimal places represented). It can be a 

number between 0 and 9. If n is less than the number of decimal points in the 

input data, the resulting value is rounded. 

f Scales the input value num.expr by moving the decimal point f places to the 

left. If omitted, f defaults to the value assigned to n (for example, if you 

specify MD2, UniData reads it as MD22). 

OCONV Masked Decimal (MD) Parameters


prefix], 

[thsnd_mark] 

, 

[dec_symbl], 

[suffix] 

The square brackets enclosing these parameters are required. 

prefix – Nonnumeric character(s) to precede the formatted number. For 

example, MD2[**] produces "**nnn...". 

thsnd_mark – Nonnumeric character(s) to delimit thousands. To specify a 

comma, enclose it in single quotation marks, and then use double quotation 

marks to enclose the conversion code. For example, " MD2[,',' ]" produces 

"...,nnn,nnn". 

dec_symbl – Alternate symbol to represent the decimal point. 

suffix – Nonnumeric character(s) to follow the formatted number. For 

example, MD2[, , ,**] produces "...nnn**". 

, Inserts commas to separate thousands, millions, and so forth. 

$ Precedes the output with a dollar sign ($). 

- Specifies the negative sign (for negative data) to precede negative numbers. 

< or E Specifies that negative data is surrounded by brackets. 

C Specifies that negative data is followed by CR, indicating a credit. 

D Specifies that negative data is followed by DB, indicating a debit. 

P Specifies that no scaling is performed if a decimal is present in the input 

value. 

Z Specifies that zeros are to be suppressed. 

T Specifies that the number is to be truncated, not rounded to the number of 

decimal places specified in n. 

xc Specifies that the character c is used to fill spaces left to the left of the 

number after output data is formatted. x indicates the size of the mask. 

OCONV Masked Decimal (MD) Parameters (continued) 

OCONV Masked Decimal (MD) 1-502

Examples 

The following table describes some OCONV masked decimal conversion codes and 

their results. 

The following statement is taken from the sample program in Appendix A, “Sample 

Program,” in Developing UniBasic Applications. It converts the price stored in 

internal format in the ORDERS file for display, including two decimal places, 

commas separating thousands of dollars, preceded by a dollar sign. 






12.339 MD3 0.012 

12.339 MD32 0.123 

1234 MD2,$ $12.34 

-1234 MD2$,- 

912391 MD2$,D $9,123.91DB 

456789 MD2$,11* $**4,567.89 

123.456 MD24P 123.46 

11111112339 MD12[@,*,,%] @111*111*123.4% 

OCONV Masked Decimal (MD) Examples 

ICONV Masked Decimal (MD)

OCONV Left Justify (ML) 

Syntax 

OCONV(str.expr, "MLn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] 

[C] [Z] [(mask)]") 

Description 

The OCONV left justify (ML) function scales, rounds, and formats a number, or leftjustifies 

it in a mask. str.expr can be any valid text or a numeric value with or without 

a decimal. If the input value or conversion code is invalid, UniData returns the input 

value. 

Note: The OCONV ML and MR functions produce the same output. However, 

formatting differs slightly in the following way: if a mask is specified that is larger 

than the formatted number, UniData left- or right-justifies the number within a 

“column” the width of the mask. 



Parameters 


Note: Some parameters set the same values. Results are unpredictable if you make 



str.expr Indicates a text string or number to be left-justified and formatted. 

n Sets precision (number of decimal places represented). It can be a 

number from 0 through 9. If n is less than the number of decimal points 

in the input data, the resulting value is rounded. 

f Scales the input value num.expr by moving the decimal point f places to 

the left. If omitted, f defaults to the value assigned to n (for example, if 

you specify ML2, UniData reads it as ML22). 

OCONV Left Justify (ML) Parameters 

OCONV Left Justify (ML) 1-504


[ [prefix], 

[thsnd_mark], 

[dec_symbl], 

[suffix] ] 

Examples 

In the following statement, UniData moves the decimal three places to the left 

(0.012339), rounds to three decimal places, and then prints 0.012: 

PRINT OCONV("12.339","ML3") 

In the following statement, UniData moves the decimal two places to the left 





example, ML2[**] produces "**nnn...". 

thsnd_mark – Nonnumeric character(s) to delimit thousands. To specify 

a comma, enclose it in single quotation marks, and then use double 

quotation marks to enclose the conversion code. For example, " ML2[,',' 

]" produces "...,nnn,nnn". 



example, ML2[, , ,**] produces "...nnn**". 

, Inserts commas to separate thousands. 

$ Precedes the number with a dollar sign ($). 

C Specifies negative data to be followed by CR indicating a credit. 

Z Suppresses zeros. 

mask Specifies a mask to be used for formatting. Use # to represent number 

placement. Include special characters as desired. 

Results are adversely affected if the mask contradicts other parameters. 

For example, placement of the decimal in the mask overrides n. 

OCONV Left Justify (ML) Parameters (continued) 

PRINT OCONV("12.339","ML32") 

In the following example, UniData converts the value 123456789 to 1234-56-789 

because it left-justifies it in the mask “####-##-####”: 

OUTPUT.VAL = OCONV("123456789","ML(####-##-####)")

In the following example, UniData converts the value 12.339 to 0.012 based on the 

ML3 external conversion: 

INTERNAL.VAL = OCONV("12.339","ML3") 



ICONV Left Justify (ML) 

OCONV Left Justify (ML) 1-506

OCONV Packed Decimal (MP) 

Syntax 

OCONV(expr, "MP") 

Description 

The OCONV packed decimal (MP) function converts an integer from packed 

decimal representation into display format. If the input value or conversion code is 






ICONV Packed Decimal (MP) 


OCONV Packed Decimal (MP1) 

Syntax 

OCONV(expr, MP1) 

Description 

The OCONV packed decimal (MP1) function converts an integer from packed 

decimal representation into its display format without truncating at the first CHAR(0) 

character or altering CHAR(0). If the input value or conversion code is invalid, 






ICONV Packed Decimal (MP1) 

OCONV Packed Decimal (MP1) 1-508

OCONV Right Justify (MR) 

Syntax 

OCONV(str.expr, "MRn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] 

[C] [Z] [(mask)]") 

Description 

The OCONV right justify (MR) function scales, rounds, and formats a number, or 

right-justifies it in a mask. str.expr can be any valid text or a numeric value with or 

without a decimal. If the input value or conversion code is invalid, UniData returns 

the input value. 

Note: The OCONV ML and MR functions produce the same output. However, 

formatting differs slightly in the following way: if you specify a mask that is larger 

than the formatted number, UniData left- or right-justifies the number within a 

“column” the width of the mask. 



Parameters 



Some parameters set the same values. Results are unpredictable if you make 



str.exp Indicates a text string or number to be right-justified and formatted. 

n Sets precision (number of decimal places represented). It can be a 

number from 0 through 9. If n is less than the number of decimal points 

in the input data, the resulting value is rounded. 

f Scales the input value num.expr by moving the decimal point f places 

to the left. If omitted, f defaults to the value assigned to n (for example, 

if you specify MR2, UniData reads it as MR22). 

[prefix], 

[thsnd_mark], 

[dec_symbl], 

[suffix] 



example, MR2[**] produces "**nnn...". 

thsnd_mark – Nonnumeric character(s) to delimit thousands. To 

specify a comma, enclose it in single quotation marks, and then use 

double quotation marks to enclose the conversion code. For example, " 

MR2[,',' ]" produces "...,nnn,nnn". 



example, MR2[, , ,**] produces "...nnn**". 

, Inserts commas to separate thousands. 

$ Precedes the formatted number with a dollar sign ($). 

C Specifies that a negative number is to be followed by CR, indicating a 

credit. 

Z Suppresses zeros. 

mask Specifies a mask to be used for formatting. Use # to represent number 

placement. Include special characters as desired. 

Results are adversely affected if the mask contradicts other parameters. 

For example, placement of the decimal in the mask overrides n. 

OCONV Right Justify (MR) Parameters 

If the conversion to display format is unsuccessful, UniData returns the original 

value. 

OCONV Right Justify (MR) 1-510

Examples 

In the following statement, UniData moves the decimal three places to the left 


PRINT OCONV("12.339","MR3") 

In the following statement, UniData moves the decimal two places to the left 



PRINT OCONV("12.339","MR32") 

In the following example, UniData converts the value 123456789 to 123-45-6789 

because it right-justifies it into the mask “####-##-####”: 

OUTPUT.VAL = OCONV("123456789","MR(####-##-####)") 


Program,” in Developing UniBasic Applications. It converts a price stored in internal 

format in the ORDERS file to display format, including two decimal places, commas 

separating thousands of dollars, and a preceding $. 


The following statement is taken from the same sample program. This statement 

displays the price right-justified and formatted with commas separating thousands of 

dollars and a preceding $ as in $12,386.34. The right justification aligns data on the 

right. 


In the following example, UniData converts the value 123456 to 1,234.56: 

OUTPUT.VAL = OCONV("123456","MR2$,") 



ICONV Right Justify (MR)

OCONV Time (MT) 

Syntax 

OCONV(num.expr, "MT [H] [S] [c]") 

Description 

The OCONV time (MT) function converts the internal time of day from an integer 

between 0 and 86400 (the number of seconds in a day) to display format. Time is 

output in the following form: 

HH MM [SS] 




Parameters 



num.expr Indicates a number to be converted. 

H Indicates that hours are to be formatted in 12-hour format with a.m. or p.m. 

suffixes. 

S Indicates that seconds are to be included in the output. 

c Specifies a delimiter to be placed between hours, seconds, and fractions of 

seconds. 

OCONV Time Conversion (MT) Parameters 

Note: A program that you can use to try out ICONV and OCONV conversion codes 

is provided in Developing UniBasic Applications.. 

OCONV Time (MT) 1-512



DATE, ICONV Time (MT), TIME, TIMEDATE 


OCONV Hex (MX | HEX), Octal (MO), Binary 

(MB) 

Syntax 

OCONV(str.expr, ["HEX | MX [0C] | MO [0C] | MB [0C]"]) 

Description 

The OCONV hex (MX), octal (MO), and binary (MB) functions convert from 

decimal or ASCII characters into other numbering systems. If the input value or 

conversion code is invalid, UniData returns the input value. 



Parameters 



str.exp Specifies the number to convert to an alternate numbering system. 

HEX | 

MX [0C] 

Indicates conversion to hexadecimal (base 16). The optional 0C converts 

from ASCII character rather than decimal value. HEX is equivalent to 

MX0C. 

MO [0C] Indicates conversion to octal (base 8). The optional 0C converts from ASCII 

character rather than decimal value. 

MB [0C] Indicates conversion to binary (base 2). The optional 0C converts from 

ASCII character rather than decimal value. 

OCONV Numbering System Conversion Parameters 

OCONV Hex (MX | HEX), Octal (MO), Binary (MB) 1-514

The following table indicates which parameters to use with OCONV to convert from 

decimal value or ASCII character to other numbering systems. 

Examples 

The following table demonstrates some OCONV MX, MO, and MB conversion 

codes and their results. 


From To Function 

Decimal value Binary OCONV MB 

Decimal value Octal OCONV MO 

Decimal value Hexadecimal OCONV MX 

ASCII character Binary OCONV MB0C 

ASCII character Octal OCONV MO0C 

ASCII character Hexadecimal OCONV MX0C 

OCONV HEX 

OCONV Options for Converting to Alternate Numbering Systems 


SS (ASCII character) MO0C 123123 (octal) 

256 (decimal) MX 100 (hexadecimal) 

0 (ASCII character) MX 4F (hexadecimal) 

5 (decimal) MB 00000101 (binary) 

33288 (decimal) MO 101010 (octal) 

Qat (ASCII character) MX0C 516174 

(hexadecimal) 

U (ASCII character) MB0C 01010101 (binary) 

OCONV Hex, Octal, and Binary Examples



CHAR, ICONV Hex (MX | HEX), Octal (MO), Binary (MB), SEQ 

OCONV Hex (MX | HEX), Octal (MO), Binary (MB) 1-516

OCONV Pattern Match (P) 

Syntax 

OCONV(str.expr, "P(op)[;(op).....]") 

Description 

The OCONV pattern match (P) function checks a string for a match with one of the 

patterns or strings specified in op. If the entire string does not match one of the 

patterns or strings, UniData returns an empty string. If the input value or conversion 

code is invalid, UniData returns the input value. OCONV pattern match performs the 

same function as the ICONV pattern match function. 



Parameters 


Paramete 

r Description 



op Specifies the pattern to search for in str.expr. 

nN – Integer followed by N tests for that number of numeric characters. 

nA – Integer followed by A tests for that number of alpha characters. 

nX – Integer followed by X tests for that number of alphanumeric characters. 

lit.str – Indicates a literal string to be searched for in str.expr. 

; Separates multiple patterns. 

OCONV Pattern Match (P) Parameters

Examples 

The following statement prints an empty string because the entire input string does 

not match a pattern or string specified in op: 

PRINT OCONV("abc123","P(3N);(abc)") 

The following statement prints “abc” because the input string matches the string 

provided in op: 

PRINT OCONV("abc","P(3N);(abc)") 

OCONV Pattern Match (P) 1-518

OCONV Range (R) 

Syntax 

OCONV(num.expr, "Rndm[;ndm.....]") 

Description 

The OCONV range (R) function returns only those data values that fall into a 

specified range of decimal values. When including a negative range, you must 

specify the highest negative number first. If range specifications are not met, UniData 

returns an empty string. If the input value or conversion code is invalid, UniData 




Parameters 




num.expr Indicates a string to be searched. 

n Specifies the smallest number to be extracted. 

d Specifies a delimiter separating numbers in a range. Any character except 

system delimiters can be used to separate the numbers in a range. 

Do not use the minus sign (-) as a delimiter because it refers to a negative 

number in the range. 


; Separates multiple ranges. 

OCONV Range (R) Parameters

Example 

In the following example, the program segment prints “123” and a blank line because 

X is within the range and Y is not: 

X = 123; Y = 456789 

PRINT OCONV(X,"R100,200") 

PRINT OCONV(Y,"R100,200") 



ICONV Range (R) 

OCONV Range (R) 1-520

OCONV SOUNDEX (S) 

Syntax 

OCONV(str.expr, "S") 

Description 

The OCONV SOUNDEX (S) function converts string or numeric data to phonetic 

format based on SOUNDEX conversion codes. You can use the S conversion code in 

a virtual attribute formula. If the input value or conversion code is invalid, UniData 


For more information on SOUNDEX conversion codes, see the SOUNDEX 

command. 



Parameters 


Example 

The following example is a virtual attribute (SDX_LNAME) that converts the value 

of the variable LNAME to its SOUNDEX expression: 

OCONV(LNAME,"S") 



str.expr Indicates a string to be converted. 

OCONV SOUNDEX (S) Parameters



ICONV SOUNDEX (S), SOUNDEX 

OCONV SOUNDEX (S) 1-522

OCONV Text Extraction (T) 

Syntax 

OCONV(str.expr, "T[m,]n") 

Description 

The OCONV text extraction (T) function extracts a substring from a string. If you 

omit m, extraction begins from the rightmost character, and n characters to the left are 

extracted. If you include m, extraction begins with the position specified, and n 

characters to the right are extracted. 




Parameters 





m Extracts a contiguous string of characters starting from character m. 

n Extracts a contiguous string of characters of length n. 

OCONV Text Extraction (T) Parameters

Examples 

The following table describes some OCONV text extraction codes and their results. 


1234567890 “T3” 890 

Three characters are extracted, counting 

to the left from 0. 

1234567890 "T1,3" 123 

Three characters are extracted, counting 

to the right from 1. 

DAMN THE TORPEDOES “T3,5” MN TH 

CONVERSION IS THE KEY “T1,9” CONVERSIO 

457 COLORADO BLVD “T4,7” [space]COLORA 

OCONV Text Extraction (T) Examples 



[], FIND, FINDSTR, ICONV Text Extraction (T) 

OCONV Text Extraction (T) 1-524

OCONV File Translation (Tfile) 

Syntax 

OCONV(rec.id, "T[DICT] [filename;cn;I-Attribute;O-Attribute]") 

Description 

The OCONV file translation (Tfile) function retrieves attributes from a file without 

the file being explicitly opened first. This function performs the same conversion as 

the ICONV file translation function. If the input value or conversion code is invalid, 




Parameters 




rec.id Specifies the ID of the record to be accessed. Can be a literal or a variable. 

DICT Include to access the dictionary file. 

filename Specifies the name of the file to be accessed (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 an empty string, return 

an empty string and print an error message. 

C – If the record does not exist, or if the attribute is an empty string, substitute 

id.expr for the value of the function. 

X – If the record does not exist, or if the attribute is an empty string, return 

an empty string. 

OCONV File Translation (Tfile) Parameters


n Indicates the number of the value of a multivalued attribute to retrieve. If n is 

not included, UniData retrieves all values of the attribute. 

I-Attribute Specifies the number of the attribute to be retrieved during input conversion. 

If I-Attribute is omitted, UniData retrieves the record ID. 

O-Attribute Number of the attribute to be retrieved during output conversion (OCONV). 

If the O-Attribute is omitted, UniData retrieves the record ID. 

Examples 

OCONV File Translation (Tfile) Parameters (continued) 

The first line of the following program segment reads the demo database file 

ORDERS, accessing the record with @ID 912, and retrieving the second attribute. 

OCONV T also converts the internal date to display format. The second line prints 

the value in that attribute. 

record.ret = OCONV("912","TORDERS;V;;2") 

PRINT "Record retrieved: ":record.ret 

END 

The following output is obtained by running the preceding program: 

Record retrieved: 12:30PM 

In the next example, the program statement translates the TAPE_ID to the TAPES file 

and returns the name of the tape: 

TAPE_ID = CUSTOMER.REC 

TAPE_NAME = OCONV("TAPE_ID","TTAPES;X;;1") 


ICONV File Translation (Tfile) 

OCONV File Translation (Tfile) 1-526

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. If the input value or conversion code is invalid, UniData returns the input 

value. 

Note: In BASICTYPE P, OCONVS returns an empty string if UDT.OPTIONS 56 is on 


OCONVS conversion codes are the same as OCONV conversion codes. For 

information about conversion codes, see OCONV. 

Parameters 




dyn.array.expr Specifies a dynamic array, each element of which to convert. 

conv.code.expr Specifies a code to use in converting each element of the 


OCONVS Parameters

Examples 

In the following example, the program segment converts each element of ARR1 to 

output format: 

ARR1 = 1234:@VM:5678:@VM:9876 

ARR2 = OCONVS(ARR1,"MR2$") 

PRINT ARR2 

END 

The preceding program segment prints the following output: 

$12.34 $56.78 $98.76 



OCONV, ICONVS 

OCONVS 1-528

ON/GOSUB 

Syntax 

ON expr GOSUB label[:][, label[:]...] 

Description 

The UniBasic ON/GOSUB command transfers program control to a subroutine label 

based on the value of expr. 

ON GOSUB can appear on one line, or it can be spread over as many successive lines 

as necessary. Labels must be separated by commas. 

When the program encounters a RETURN statement in the called subroutine, 

UniData transfers control to the statement immediately following ON GOSUB. If the 

subroutine contains a RETURN TO label statement, control resumes at the label 

specified in the RETURN statement. 

Note: In BASICTYPE M or P, if expr is nonnumeric or less than 1, UniData bypasses 

the GOSUB clause and the next program statement executes. 


Parameters 



expr Specifies a numeric expression. UniData evaluates the expression, and then 

truncates it to an integer. Control passes to a subroutine based on the 

following rules. 

If expr is less than or equal to 1, UniData transfers program control to the 

subroutine starting at the first label in the list. If the number is 2, UniData 

transfers control to the subroutine starting at the second label, and so forth. 

If expr is higher than the number of labels, UniData transfers control to the 

last label in the list. 

If expr is nonnumeric, control transfers to the first label. 

label Specifies a subroutine label or multiple subroutine labels. 

: Optional. A colon is required to identify a nonnumeric label in the statement 

label itself only, not in the reference to it in the ON/GOSUB statement. 

ON/GOSUB Parameters 

Examples 

In the following example, the program segment divides the variable BALANCE by 

100. If the result is less than or equal to 1, the program transfers control to subroutine 

U100. If the value is 2 or 3, it transfers control to U200 or U300 respectively. If the 

value is greater than or equal to 4, UniData 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, UniData transfers control to one of the five subroutines in the 

GOSUB clause. If the user response is nonnumeric or less than 1, UniData transfers 

control to the first subroutine. If the user enters a value greater than 5, UniData 

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 

ON/GOSUB 1-530



GOSUB, GOTO, ON/GOTO, RETURN 


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 one-way branch. If you use 

an ON GOTO statement to transfer control to a subroutine with a RETURN 

statement, the subroutine’s RETURN statement works if a previous GOSUB 

statement is still waiting for a RETURN statement in the subroutine. Otherwise, the 

program aborts with a runtime error. 

Tip: Use ON/GOSUB instead of ON/GOTO to make your programs easier to follow 

and maintain. 

ON/GOTO 1-532

Parameters 


Paramete 

r Description 

Note: In BASICTYPE M or P, if expr is nonnumeric or less than 1, UniData bypasses 

the GOTO clause and the next program statement executes. 

Example 

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, UniData 

transfers control to statement label 2500. If X is greater than or equal to 3, UniData 

transfers control to statement label YESNO. 

ON X GOTO TEST,2500, YESNO 



GOSUB, GOTO, ON/GOSUB 


expr Specifies a numeric expression. UniData evaluates the expression, and then 

truncates it to an integer. Control passes to a statement label based on the 

following rules: 

If expr is less than or equal to 1, UniData transfers program control to the label 

starting at the first label in the list. If the number is 2, UniData transfers control 

to the label starting at the second label, and so forth. 

If expr is higher than the number of labels, UniData transfers control to the last 

label in the list. 

If expr is nonnumeric, control transfers to the first label. 

label Specifies a statement label or multiple statement labels. 

: Optional. A colon is required to identify a nonnumeric label in the statement 

label itself only, not in the reference to it in the ON/GOTO statement. 

ON/GOTO Parameters

OPEN 

Syntax 

OPEN ["expr",] "filename" [READONLY] [TO file.var] [ON ERROR statements] 


Description 

The UniBasic OPEN command opens a UniData hashed data or dictionary file, so 

you can read, write, or delete records from it. The number of files you can open is 

determined by operating system and UniData configuration parameters. For information 

about file performance, see Administering UniData on UNIX or 

Administering UniData on Windows Platforms. 

Warning: Do not use UniBasic READ commands to open or modify binary data in 

DIR-type files (for example, BP). Doing so could corrupt data in the file. Instead, use 

OSREAD or OSBREAD after executing the UniBasic NOCONVERT command. 

Parameters 



expr Specifies the portion of file type to open: 

“” – UniData opens a data file. 

DICT – UniData open a dictionary file. 

filename Specifies the name of the file to open. 

READONLY Directs UniData to open the file for reading only. If the program 

attempts to write to a file opened in READONLY mode, UniData 

displays a runtime error message and does not update the file. For 

information about security procedures, see Administering UniData on 

UNIX or Administering UniData on Windows Platforms. 

OPEN Parameters 

OPEN 1-534



TO file.var Specifies a file variable in which to place a pointer to the opened file. 

If you do not specify file.var, the file you open becomes the default file. 

UniData performs all default file operations on this file. (Default file 

statements include all types of read, write, or delete when no file 

variable specified). 

A single default file can be declared in each UniBasic program or 

subroutine, and the default file is specific to the program or subroutine 

in which it is defined. If a main program opens a default file, and then 

calls an display subroutine that also opens a default file, UniData 

restores the original default file when returning to the main program. 

ON ERROR 

statements 

THEN statements 

END 

ELSE statements 

END 

The ON ERROR clause enables the program to continue to perform 

when a fatal error occurs such as when the file is not open, an I/O error 


If a VOC entry exists for a file that does not exist, the ON ERROR 

clause executes. However, if no VOC entry exists, the ELSE statement 

executes. 



THEN executes if the open is successful. END is required to terminate 

multiline THEN statements. 

ELSE executes if the OPEN is not successful or the record does not 

exist. 

If the file exists, but some other error occurs, the ELSE statement 

executes. However, if a file does not exist and no VOC entry exists, the 

ELSE statement executes. 

END is required to terminate multiline ELSE statements. 

OPEN Parameters (continued)


After you execute OPEN, the INMAT function returns one of the values described in 

the following table. 

Examples 

In the following example, the program statement opens the data file ACCREC in 

read-only mode. Because no file variable is specified, ACCREC becomes the 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 UniData 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 CLIENTS file to the file variable 

CLIENT. If it is not found, UniData executes the ELSE statements, printing an error 

and setting a flag to 1. 

OPEN 'CLIENTS' TO CLIENT ELSE 

PRINT 'NO CLIENT' 

OPEN.ABORT = 1 

END 

IF OPEN.ABORT THEN PRINT 'Aborting on open error';STOP 




n The number of modulos for the file. 

0 The file opened is a directory. 


CLOSE, DELETE, OPENSEQ, OSOPEN, READ, WRITE 

OPEN 1-536

openSecureSocket function 

Syntax 

openSecureSocket(name_or_IP, port, mode, timeout, socket_handle, context) 

Description 

Use the openSecureSocket() function to open a secure socket connection in a 

specified mode and return the status. 

This function behaves exactly the same as the openSocket() function, except that it 

returns the handle to a socket that transfers data in a secured mode (SSL/TLS). 

All parameters (with the exception of context) have the exact meaning as the 

openSocket() parameters. Context must be a valid security context handle. 

Once the socket is opened, any change in the associated security context will not 

affect the established connection. 

Parameters 




name_or_IP DNS name (x.com) or IP address of a server. 



timeout The timeout value, expressed in milliseconds. If you specify 

mode as 0, timeout will be ignored. 

socket_handle A handle to the open socket. 

context A handle to the security context 

openSecureSocket Parameters (continued) 

The following table describes the return status of each mode. 

Return 


0 Success. 

1-41 See Socket Function Error Return Codes. 


102 SSL/TLS handshake failure (unspecified, peer is 

not SSL aware). 

103 Requires client authentication but does not have 

a certificate in the security context. 

104 Unable to authenticate server. 


openSecureSocket function 1-538

OPENSEQ 

Syntax 

OPENSEQ [absolutepath | seq.filename,record.id] [READONLY] TO seq.file.var 

[ON ERROR statements] [LOCKED statements] {THEN statements [END] | ELSE 

statements [END]} 

OPENSEQ [absolutepath | seq.filename,record.id] [READONLY] TO seq.file.var 

[LOCKED statements] [ON ERROR statements] {THEN statements [END] | ELSE 


Description 

The UniBasic OPENSEQ command opens a sequential file for access, starting at the 

specified record. UniData limits to 150 the number of sequential files you can open 

in a UniBasic program. 

Tip: Use OPENSEQ to open files that use CHAR(10) as a delimiter. You can then use 

READSEQ to read the next line delimited by CHAR(10), or WRITESEQ to write a 

line delimited by CHAR(10). You also can use OSBREAD to read a block of data from 

the file, or OSBWRITE to write a block of data to the file. 

Note: For UniData for Windows Platforms only: When you use OPENSEQ, UniData 

uses the fopen function to open files in Text mode and converts NEWLINE [CHAR 

(10)] line delimiters to CARRIAGE RETURN–NEWLINE pairs [CHAR(13) and 

CHAR(10)]. 


Parameters 



absolutepath The operating system path and sequential file name. 

seq.filename Specifies a UniData directory type file name. 

record.id Specifies a record in the sequential file at which to start 

accessing. 

READONLY Opens the file for reading only. If the program attempts to write 

to a file opened in READONLY mode, UniData displays a 

runtime error message and does not update the file. For 

information about security procedures, see Administering 

UniData on UNIX or Administering UniData on Windows 

Platforms. 

TO seq.file.var Specifies a file variable to contain a pointer to the opened file. 

ON ERROR statements Specifies statements to execute if the OPENSEQ statement fails 







until the lock on the record is released. You can place the 




the record. 





statements. 

OPENSEQ Parameters 

OPENSEQ 1-540


After you execute OPENSEQ, the STATUS function returns one of the values 


Example 

In the following example, the program statement opens the sequential file 

INV.SOURCES in the directory PRINTERS, and assigns the file variable PRNT: 


OPENSEQ 'PRINTERS','INV.SOURCES' TO PRNT ELSE GOSUB CLOSED: 



CLOSESEQ, OPEN, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, 

OSOPEN, OSREAD, OSWRITE, READSEQ, WEOFSEQ, WRITESEQ, 

WRITESEQF 

UniData 


0 The record does not exist. 

1 The file you specify is not a sequential-access file. 

2 The file does not exist. 

3 The READONLY clause was included in the command 

statement and the record does not exist. 

4 An unknown error occurred (such as having too many files open 

or permission problems). 


DEFAULT.LOCKED.ACTION – For information, see UniData Commands 


openSocket 

Syntax 

openSocket(name_or_IP, port, mode, timeout, socket_handle) 



Description 

Use the openSocket function to open a socket connection in a specified mode and 

return the status. 

Parameters 



name_or_IP DNS name (x.com) or IP address of a server. 



Mode Return Status 



0 - Non-blocking The function will return immediately regardless of whether or not the 

socket is successfully opened. The return code inidcates if the 

operation is successful. The timeout value is ignored. 

1 - Blocking If a positive timeout is specified, the function will either return with 

a valid socket handle or will time out after the specified timeout 

period. If the timeout value is 0, the function will block until either 

the socket is successfully opened, the underlying TCP/IP connection 

times out or some other error prevents the socket from opening. 



0 Success. 


openSocket Return Codes

OpenXMLData 

Syntax 

OpenXMLData(xml_handle,xml_data_extraction_rule, xml_data_handle) 



Description 

Use the OpenXMLData function to open an XML document after preparing it using 

the PrepareXML function. 

Parameters 



xml_handle The XML handle generated by the PrepareXML() function. 

xml_data_extraction_ 

rule 

The path to the XML extraction rule file. 

xml_data_handle The XML data file handle. The following are the possible return 

values: 

XML.SUCCESS Success. 

XML.ERROR Failed 

XML.INVALID.HANDLE Invalid XML handle 

OpenXMLData Parameters 

OpenXMLData 1-544

Example 

The following example illustrates use of the OpenXMLData function: 


status = OpenXMLData(“STUDENT_XML”, 

“_XML_/MYSTUDENT.ext”,STUDENT_XML_DATA) 

If status = XML.ERROR THEN 

STOP “Error when opening the XML document. “ 

END 

IF status = XML.INVALID.HANDLE THEN 

STOP “Error: Invalid parameter passed.” 

END

OR 

Syntax 

expr1 OR expr2 

Synonym 

! 

Description 

The OR Boolean operator combines a set of expressions. If expr1 or expr2 is true, the 

combined expression is true. Either expression must be true for a true condition. 

Example 

In the following example, the program segment combines expressions (X < Y) and 

(Y < Z). If either expression is true, the program calls subroutine RETRY. 

X = 1 ; Y = 2 ; z = 3 

IF (X < Y) OR (Y < Z) THEN GOSUB RETRY: 



AND, NOTS, OR 

OR 1-546

OSBREAD 

Syntax 

OSBREAD var FROM file.var [AT byte.expr] LENGTH length.expr [NODELAY] 


Description 

The UniBasic OSBREAD command reads data from a file starting at a specified byte 

location for a certain length of bytes, and assigns the data to a variable. OSBREAD 

performs an operating system block read on a UNIX, or Windows platform file. 

Note: Before you use OSBREAD, you must open the file by using the OSOPEN or 

OPENSEQ 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. OSBREAD converts 

CHAR(0) to CHAR(128) when reading a block of data. 

Reading from a Named Pipe 

Keep these points in mind when you write programs that read from named pipes: 


Unlike a typical read, reading a named pipe removes the data. 

Your application should check the length of var after reading a pipe. The 

value returned could be shorter than length.expr. 

UniData truncates the data if it is longer than length.expr. 

Reading Other Types of Files 

Processing of files that are not named pipes is determined by the presence or absence 

of the AT clause: 

If the AT clause is included, UniBasic begins reading from the file at the 

offset specified by byte.expr.

If the AT clause is not included, UniBasic begins reading from the current 

location of the file pointer. 

Because named pipes must be read from the beginning, the AT clause is not 

appropriate for accessing them. If the AT clause is specified, the ON 

ERROR executes, and the UniBasic STATUS function is set to 2. If the ON 

ERROR clause is not included, the program aborts. 

After successful execution of OSBREAD against a file that is not a named 

pipe, the file pointer remains at the next byte after the data read. 

Parameters 



var Specifies a variable to which to assign the data read. 

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

AT byte.expr Specifies a location in the file from which to begin reading data. 

If byte.expr is 0, the read begins at the beginning of the file. 

When reading a named pipe, do not specify an AT clause. Pipes 

are always read with no offset. 

LENGTH length.expr Specifies a length of data to read from the file, starting at 

byte.expr. 

length.expr cannot be longer than the maximum string length 

determined by your system configuration. 

NODELAY Forces an immediate read of a named pipe regardless of whether 

the pipe contains data. If you do not specify NODELAY, the 

process attempting to read waits until the pipe is opened for 

writing and data is written to it. 

If filename is not a named pipe, NODELAY has no effect. 

ON ERROR statements Specifies statements to execute if a fatal error 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 

OSBREAD 1-548


After you execute OSBREAD, the STATUS function returns one of the values 


Examples 

In the following example, the program statement reads 10,000 bytes of the file RFILE 

starting from the beginning of the file. The program assigns the data it reads to the 

variable TEST. 


OSBREAD TEST FROM 'RFILE' AT 0 LENGTH 10000 

In the next example, the program segment reads 15,000 bytes from an NTFS or 

UNIX 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 




0 The read was successful. 

1 The file name is invalid. 

2 Access is denied by the operating system. 


4 An unknown error occurred. 


CLOSESEQ, OPENSEQ, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, 

READSEQ, WRITESEQ, WRITESEQF

OSBWRITE 

Syntax 

OSBWRITE expr {ON | TO} file.var [AT byte.expr] [NODELAY] [ON ERROR 

statements] 

Description 

The UniBasic OSBWRITE command writes an expression to a sequential file 

starting at a specified byte location. OSBWRITE immediately writes a file segment 

out to the UNIX, or Windows platform file. 

You do not have to specify a length expression because the number of bytes in expr 

is written to the file. 

Note: Before you use OSBWRITE, you must open the file by using the OSOPEN or 


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 UniBasic reads a 

string that contains CHAR(0) characters by using OSBREAD, those characters are 

converted to CHAR(128). OSBWRITE converts CHAR(128) back to CHAR(0) when 

writing a block of characters. 

Writing to Named Pipes 

The combination of the following conditions and command options determine the 

action taken by UniBasic when OSBWRITE is executed against a named pipe: 

Presence and length of data in the pipe 

Open/closed status of the pipe 

Presence or absence of the AT and NODELAY command options 

For information about writing applications that access named pipes, see the Developing 

UniBasic Applications manual. 

OSBWRITE 1-550

Writing to Other Types of Files 

For files that are not named pipes, processing is determined by the presence or 

absence of the AT clause: 


AT clause specified – UniBasic begins writing to the file at the offset 

specified by byte.expr. 

AT clause not specified – UniBasic begins writing to the current location of 

the file pointer. 

After successful execution of OSBWRITE against a file that is not a named 

pipe, the file pointer remains at the next byte after the data is written. 

Parameters 



expr Specifies the expression to write to the file. 

ON | TO file.var Specifies the file on which to write the expression. 

AT byte.expr If byte.expr is 0, the write begins at the beginning of the file. 

NODELAY Forces an immediate write. 

Include NODELAY to write to a named pipe immediately 

regardless of whether the pipe contains data. If you do not 

specify NODELAY, the process attempting to write waits until 

the pipe is opened for reading. 

ON ERROR statements Specifies statements to execute if the OSBWRITE statement 





OSBWRITE Parameters


After you execute OSBWRITE, the STATUS function returns one of the values 


Examples 


0 The write was successful. 

1 The file name is invalid. 

2 You do not have permission to access the file. 



In the following example, the program statement writes the data in TEST to the 

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 CLIENT file, and appends the record onto a variable 

(BLOCK), terminating each record with an ASCII 10 (line feed). When it is 

complete, the code writes the block to the NTFS or UNIX file name opened to the 

variable CLIENT.SEQ. 

DONE = 0 

LOOP 

READNEXT REC.ID ELSE DONE = 1 

UNTIL DONE DO 

READ REC FROM CLIENT,REC.ID ELSE REC = ' ' 

IF REC THEN 

REC = REC.ID:@FM:REC 

BLOCK := REC:CHAR(10) 

END 

REPEAT 

OSBWRITE BLOCK ON CLIENT.SEQ AT 0 

OSBWRITE 1-552



CLOSESEQ, OPENSEQ, OSBREAD, OSCLOSE, OSDELETE, OSOPEN, 

READSEQ, WRITESEQ, WRITESEQF 


OSCLOSE 

Syntax 

OSCLOSE file.var [ON ERROR statements] 

Description 

The UniBasic OSCLOSE command closes a sequential file that you opened with the 

OSOPEN or OPENSEQ command. 

Parameters 



file.var Specifies the file to close. 

ON ERROR 

statements 

Specifies statements to execute if the OSCLOSE statement fails with a 

fatal error because the file is not open, an I/O error occurs, or UniData 


If you do not specify the ON ERROR clause and a fatal error occurs, the 

program terminates. 

OSCLOSE Parameters 


After you execute OSCLOSE, the STATUS function returns one of the values 



0 The file is closed successfully. 

5 The file did not close. 


OSCLOSE 1-554

Example 

In the following example, the program statement closes the file UNDEF: 

OSCLOSE UNDEF 



CLOSE, CLOSESEQ, OPENSEQ, OSOPEN 


OSDELETE 

Syntax 

OSDELETE filename [ON ERROR statements] 

Description 

The UniBasic OSDELETE command deletes an NTFS or UNIX sequential file. 

Warning: The UniBasic OSDELETE command is intended for use on OS-type files 

(not UniData hashed files). If you execute the command against a recoverable 

hashed file, UniData could crash immediately or at the next Recoverable File System 

(RFS) checkpoint. If you execute the command against a nonrecoverable hashed file, 

UniData will not crash, but other unpredictable problems could occur. 

Parameters 



filename Specifies the file to delete. filename must include the file path. If you do 

not specify a path, UniData searches the current directory. 

ON ERROR 

statements 

Specifies statements to execute if the OSDELETE statement fails with a 





OSDELETE Parameters 

OSDELETE 1-556


After you execute OSDELETE, the STATUS function returns one of the values 


Examples 

In the following example, the program statement deletes the file NAMES in the 

current directory: 

OSDELETE "NAMES" 

In the next example, the program statement deletes the file client.rec in the UNIX 

subdirectory /u/trans: 


OSDELETE '/u/trans/client.rec' 




0 The file was deleted. 

1 The directory name is invalid. 

2 UniData cannot access the file (such as user 

does not have permission). 



CLOSESEQ, DELETE, OPENSEQ, OSOPEN, OSCLOSE

OSOPEN 

Syntax 

OSOPEN filename [READONLY | WRITEONLY] TO file.var [NODELAY] 

[ON ERROR statements] {THEN | ELSE} statements [END] 

Description 

The UniBasic OSOPEN command opens a sequential file that does not use 

CHAR(10) as the line delimiter. 

Read/write access mode is the default. Specify this access mode by omitting 

READONLY and WRITEONLY. 

Tip: After opening a sequential file with OSOPEN, use OSBREAD to read a block of 

data from the file, or OSBWRITE to write a block of data to the file. You also can use 

READSEQ to read a record from the file, or WRITESEQ or WRITESEQF to write a 

record to the file, if the file is not a named pipe. (READSEQ, WRITESEQ, and 

WRITESEQF are line-oriented commands that use CHAR(10) as the line delimiter.) 

Note: On UniData for Windows Platforms only: When you use OSOPEN, UniData 

uses the open function to open files in binary mode, but does not convert NEWLINE 

[CHAR(10)] delimiters to CARRIAGE RETURN–NEWLINE pairs [CHAR(13) and 

CHAR(10)] as the OPENSEQ command does. 

OSOPEN 1-558

Parameters 




filename Specifies the file to open. filename must include the entire path 

name unless the file resides in the current directory. 

READONLY Directs UniData to open the file for reading only. If the program 

attempts to write to a file opened in READONLY mode, 

UniData displays a runtime error message and does not update 

the file. For information about security procedures, see 

Administering UniData on UNIX or Administering UniData on 

Windows Platforms. 

WRITEONLY Specifies that the pipe or file is open for write access only. 

TO file.var Specifies a variable to contain a pointer to the file. 

NODELAY Forces a pipe to be opened immediately. This enables a process 

to continue even when the pipe is not open in the opposite access 

mode. The application must then manage access to the pipe to 

ensure that it is opened for the opposite process before reading 

from or writing to it. 

If filename is not a named pipe, NODELAY has no effect. 

ON ERROR statements Specifies statements to execute if the OSOPEN statement fails 









statements. 

OSOPEN Parameters

Example 

In the following example, the program statement opens the file INVENTORY as 

INVENT unless UniData cannot access the file. 

OSOPEN 'INVENTORY' TO INVENT ELSE STOP "Can't open INVENTORY" 



CLOSESEQ, OPEN, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, 

OSDELETE, READSEQ, WRITESEQ, WRITESEQF 

OSOPEN 1-560

OSREAD 

Syntax 

OSREAD var FROM filename [ON ERROR statements] {THEN statements [END] 

| ELSE statements [END]} 

Description 

The UniBasic OSREAD command reads an entire sequential file and assigns the 

contents of the file to a variable. 

Warning: Do not use OSREAD on large files. If the file is too large for the program 

memory, the program aborts and a runtime error message is generated. On large 

files, use OSBREAD or READSEQ. 

Note: UniData uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. 

ASCII 0 cannot be used in any string variable within UniBasic. OSREAD converts 

CHAR(0) to CHAR(128) when reading a block of data. 

Parameters 




var Specifies the variable to which to assign the data from the file. 

FROM filename The filename must include the entire path to the file unless 

filename exists in the current directory. 

OSREAD Parameters


ON ERROR statements Specifies statements to execute if the OSREAD statement fails 

with a fatal error because the file is not open, an I/O error 








statements. 

Example 

In the following example, the program segment reads the data stored in the UNIX file 

‘BILLING’ in the subdirectory ‘disk1’ and assigns it to the variable BILL.REC: 

OSREAD BILL.REC FROM "disk1/BILLING" ELSE 

PRINT "NO BILLING RECORD FOUND" 

END 



OSWRITE 

OSREAD Parameters (continued) 

OSREAD 1-562

OSWRITE 

Syntax 

OSWRITE expr {ON | TO} filename [ON ERROR statements] 

Description 

The UniBasic OSWRITE command writes the contents of an expression to a 

sequential file. 

Note: UniData uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. For 

this reason, you cannot use ASCII 0 in any string variable in UniBasic. If UniBasic 

reads a string with a CHAR(0) character, and then the character is converted to 

CHAR(128), OSWRITE converts CHAR(128) to CHAR(0) when writing a block of 

characters. 

Parameters 




expr Specifies the expression to write to filename. 

ON | TO filename Specifies the name of a sequential file to which to write. 

ON ERROR statements Specifies statements to execute if the OSWRITE statement fails 





OSWRITE Parameters

Example 

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" 



OSREAD 

OSWRITE 1-564

PAGE 

Syntax 

PAGE [ON num.expr] [expr] 

Description 

The UniBasic PAGE command prints the current output page. UniData prints the 

page with any specified header or footer. 

If you do not specify any parameters, the result depends on the last PRINTER 

command executed: 


PRINTER OFF – The new page is generated on the user’s terminal. 

PRINTER ON – The new page is generated on the system printer. 

Parameters 



ON num.expr Specifies the page number of the next output page. Each subsequent 

page is incremented by one. 

expr Specifies a target print file for the completed page where num.expr is 

the number assigned to the file. When you specify a num.expr, the 

PRINTER command setting is disregarded. 

For assistance assigning print files, see your system administrator. 

PAGE Parameters

Examples 

In the following example, the program statement completes the current page with 

footings, then advances to a new page. The PRINTER command setting determines 

where the page is printed. 

PAGE 

In the next example, the program statement sends the completed page to the file 

assigned to print unit 5. If UniData cannot find the print unit specified, the program 

prints nothing. 

PAGE ON 5 



PRINTER 

UniData 


PAGE 1-564

PAUSE 

Syntax 

PAUSE [wait_time] 

Description 

The UniBasic PAUSE command suspends the UniData process that issues the 

command for the amount of time you specify with wait_time, or until a UniBasic 

WAKE command is executed for this process. Keep in mind the following points 

when executing PAUSE: 


PAUSE has no effect if wait_time is a negative number, or if another 

UniData process has previously issued a WAKE command for this process. 

To pause a process indefinitely, omit wait_time, or specify a wait_time of 2. 

PAUSE must be executed by the process to be paused. 

Examples 

The following sample program executes the UniBasic PAUSE command to pause the 

current session: 

PAUSE_WAKE 

PRINT "How long do you want to pause this session": 

INPUT pause_time 

PAUSE pause_time 

END 

The following example executes the preceding program. In this execution, the user 

does not enter an amount of time to pause the session, so it is paused indefinitely. 

(The cursor rests on the line following the prompt.) 

:RUN BP PAUSE_WAKE 

How long do you want to pause this session?

From another UniData session, the user executes the LIST.PAUSED command to 

obtain the process ID for the paused process, and then wakes it up by specifying 

WAKE 1052: 

:LIST.PAUSED 

Number of Paused Users 

~~~~~~~~~~~~~~~~~~~~~~ 

1 

UDTNO USRNBR UID USRNAME USRTYPE TTY 

LEFTTIME TOT_TIME 

1 1052 1283 carolw udt pts/0 - 

- 

:WAKE 1052 

: 



WAKE 

UniData 

LIST.PAUSED, PAUSE, SLEEP, WAKE – For information, see the UniData 


PAUSE 1-566

PCPERFORM 

Syntax 

PCPERFORM str.expr [CAPTURING, dyn.array.var] 

Description 

The UniBasic PCPERFORM command executes an operating system command 

from within a UniBasic program. 

PCPERFORM is similar to the EXECUTE and PERFORM commands except that 

PCPERFORM executes an operating system command. 

If PCPERFORM is successful, UniData sets @SYSTEM.RETURN.CODE to 0. If 

unsuccessful, UniData sets @SYSTEM.RETURN.CODE to -1. 

Note: The settings of UDT.OPTIONS affect the way ECL commands execute. For 

information about these options, see the UDT.OPTIONS Commands Reference. For 

information about UDT.OPTIONS that could affect that command, see the 

appropriate ECL command in UniData Commands Reference. 

Parameters 




str.expr Specifies a string to execute as a host operating system command. 

CAPTURING, 

dyn.array.var 

Specifies a target dynamic array to capture the output of the host 

operating system command. 

PCPERFORM Parameters

Example 

In the following example, the program statement executes the operating system date 

command: 

PCPERFORM "date" CAPTURING DATE.TIME 



EXECUTE, EXECUTESQL, MDPERFORM, UDTEXECUTE 

PCPERFORM 1-568

PERFORM 

PERFORM is a synonym for the EXECUTE command. For more information, see 

EXECUTE. 

Synonym 

EXECUTE 


PRECISION 

Syntax 

PRECISION num.expr 

Description 

The UniBasic PRECISION command rounds numbers to the number of decimal 

places indicated in num.expr. num.expr can be a number from 0 to 14. If the number 

is not within this range, UniData does not change the setting. The default is four 

decimal places. 

Tip: UniData converts the operands in numeric operations from string to numeric 

data type, performs the operations, and then converts the results back to string data 

type. When making calculations for which you require a high degree of precision, use 

the PRECISION command to force UniData to represent a particular level of decimal 

representation. 

Set the UniData FLOAT.PRECISION to 4 to truncate rather than round at the 

PRECISION setting. 

Examples 

In the following example, the program statement results in all numeric variables 

being truncated to eight decimal places: 

PRECISION 8 

In the next example, the program statement truncates all digits to the right of the 

decimal point: 

PRECISION 0 

In the next example, the program statement sets precision based on the variable DEC: 

PRECISION DEC 

PRECISION 1-570


UniData 

FLOAT.PRECISION – For information, see the UniData Commands Reference. 


PrepareXML 

Syntax 

PrepareXML(xml_file,xml_handle) 



Description 

Use the PrepareXML function to prepare the XML document in the UniBASIC 

program. This step allocates memory for the XML document, opens the document, 

determines the file structure of the document, and returns the file structure. 

Parameters 



xml_file The path to the file where the XML document resides. 

xml_handle The return value. The return value is the UniBASIC variable for 

xml_handle. Status is one of the following return values: 


XML.ERROR Error 

PrepareXML Parameters 

PrepareXML 1-572

Example 

The following example illustrates use of the PrepareXML function: 


STATUS = PrepareXML(“_XML_/MYSTUDENT.XML”,STUDENT_XML) 

IF STATUS=XML.ERROR THEN 

STATUS = XMLError(errmsg) 

PRINT “error message “:errmsg 

STOP “Error when preparing XML document “ 

END

PRINT 

Syntax 

PRINT [ON num.expr] [print.expr] 

Description 

The UniBasic PRINT command prints data on the display terminal or the system 

printer, or sends data to a print file. 

Separate multiple items in a single PRINT statement with commas or colons. A 

comma directs the printer to execute a tab. Tab stops are set to 10 spaces. If you use 

a colon to separate statements, UniData concatenates the items. 

Unless a PRINT expression ends with a colon, UniData executes a carriage return 

after printing the line. If the output from the PRINT statement exceeds the current 

page width, it wraps to the next line. 

Tip: You can use the UniBasic @ function with the PRINT command to place the 

cursor and/or direct the terminal to take some action. Execute the ECL REUSE.ROW 

command to determines whether a line feed is executed when the UniBasic PRINT @ 

function references column only. For example, PRINT @(10) rather than PRINT 

@(3,10). 

Note: The PRINT statement interprets two consecutive nonprinting ASCII characters 

(such as CHAR(192):CHAR(192)) as one character when displaying data. 

To suppress the line feed at the end of displayed text, place a colon at the end of the 

PRINT or DISPLAY statement. 

PRINT 1-574

Parameters 



Examples 

In the following example, the program segment prints HI THERE on the system 

printer: 

PRINTER ON 

PRINT "HI THERE" 

In the next example, the program statement sends the value of variable X concatenated 

to "X = " to the file specified by unit 10: 

PRINT ON 10 "X = ":X 

In the next example, the @ function is included with a terminal option. -1 clears the 

screen before printing. 


ON num.expr Specifies a target print file. If you do not use the ON clause, the data is 

printed based on the last PRINTER command executed: 

PRINTER OFF – The data prints on the display terminal. 

PRINTER ON – The data prints on the system printer. 

print.expr Specifies an expression to print. It can be any valid UniBasic 

expression. If you do not specify a print.expr, a PRINT statement sends 

a line feed character to the printer or file. 

PRINT Parameters 

PRINT @(-1):"Enter true or false: " 

INPUT answer,5_ 

In the next example, the comma separation character prints X, Y, a string separated 

by tabs, X+Y, tabs twice, then prints another string, and finally print the average 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 as the result of the comma separation character. A 

colon causes all data items to be concatenated. 

The following program demonstrates the use of the colon at the end of the PRINT 

statement to suppress the line feed issued by UniBasic at the end of displayed text. 

The first PRINT statement does not end in a colon. Therefore, UniBasic issues a 

carriage return and prints a question mark (the default prompt character). The second 

PRINT statement ends in a colon. In this case, UniBasic displays the default prompt 

character and waits on the same line with the PRINT statement. 

PRINT "Enter character to display" 

INPUT X 

PRINT "The character you entered was(1): ":X 

PRINT "Enter character to display": 

INPUT X 

PRINT "The character you entered was(2): ":X 

This program produces the following output (with input from the 

user): 

Enter character to display 

?* 

The character you entered was(1): * 

Enter character to display?# 

The character you entered was(2): # 



@, CRT, GETPTR, INPUTERR, PRINTER, PRINTER CLOSE 

UniData 


PRINT 1-576

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 executed without the ON 

clause). If you specify ON, UniData directs all output to the system printer. If you 

specify OFF, UniData directs all output to the terminal screen. 

PRINTER ON causes runtime error messages to print on the system printer. 

Note: If the printer and your computer are not communicating properly when you 

execute a print command (for example, a PRINT statement after a PRINTER ON 

command), UniData generates an error. 

Example 

In the following example, the program statement sends all future report output (data 

from PRINT, FOOTER, HEADER, and PAGE commands) to the printer: 

PRINTER ON 


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. The ON clause does not physically close the print 

file. Instead, it sends its contents to a print buffer, leaving the file empty. Then you 

can send additional data to the same print file to begin a new set of data to be printed. 

As many as 31 print files can be open at the same 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. 

Note: Data in a print file is automatically sent to the print queue if the program ends 

or issues a PRINTER CLOSE statement. 

Example 

In the following example, the program statement sends the current contents of print 

file 5 to the print queue: 

PRINTER CLOSE ON 5 


UniData 


PRINTER CLOSE 1-578

PRINTERR 

Syntax 

PRINTERR expr [FROM file.var] 

Description 

The UniBasic PRINTERR command prints error messages stored in the UniData 

system message file or in a user-defined file. 

To obtain a message from a user-defined error message file, you must open the file 

first. 

The UniBasic commands ABORT and PRINTERR return the system message you 

specify by ID in the command. You can also retrieve system messages using a 

UniBasic program by opening the system message file and reading a message record 

by ID. 

Note: ENGLISH.MSG is the default system message file that is activated when you 

install UniData. If you execute udtlang.config to select a language group, a different 

system message file could be activated. To find out which language is installed on 

your system, execute the ECL command SET.LANG CURRENT. For more 

information, see UniData International. 


Parameters 



expr Specifies a dynamic array that consists of two elements. The first 

element is the key for a record in the error message file. The second 

element is a parameter that some of the format codes use. For format 

codes, see the following table. Attribute marks (@AM or @FM) delimit 

elements. 

FROM file.var Specifies a file from which to extract a user-defined error message. The 

default is the UniData error message file. 

PRINTERR Parameters 

Creating a User-Defined Error Message 

Error messages in the UniData error message file consist of format codes and literal 

strings. The following table describes the codes you can include in error messages. 


A Extracts the next element in expr. 

A(n) Extracts the next element in expr, left-justified in a string of length n. 

C Clears the screen. 

D Enters the date in internal format. 

E literal Enters the message ID at the beginning of the message enclosed in brackets, 

followed by an optional literal string. 

H literal Prints literal. 

L Prints a carriage return/line feed. You must specify L (carriage return/line 

feed) explicitly. 

L(n) Prints n carriage returns/line feeds. 

R(n) Extracts the next element in expr, right-justified in an attribute of n blanks. 

S(n) Prints n spaces. 

PRINTERR Error Message Codes 

PRINTERR 1-580


Examples 

In the following example, the UniData udtlang.MSG file contains error message 

4432 and a user-defined file (S_ERR) contains error message E009. These messages 

contain the following: 


T Enters the time in internal format. 

W(n) Pauses for n seconds before continuing to display the message. 

X Skips the next parameter passed to the UniData message printing routine. 

PRINTERR Error Message Codes (continued) 

Message 4432 Message E009 

in udtlang.MSG 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 

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 cannot be found, the program segment 

produces the following error message: 

[4432] FILE test_file DOES NOT EXIST 

CAN'T PROCEED! 

19 Jan 1996 

10:34:19 

If you enter 12 for VAR1, the program segment produces the following error 

message: 

=>ERR [E009] 

VAR1 IS NOT PROPERLY SPECIFIED 

PRINTERR 1-582

PROCREAD 

Syntax 

PROCREAD var {THEN statements [END] | 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. 

Note: A proc is a PQ-type VOC record. 

Parameters 




var Specifies variable to which to assign the string value of the 

primary input buffer of the calling proc. 

THEN statements END THEN executes if this program was called by a proc. END is 

required to terminate multiline THEN statements. 

ELSE statements END ELSE executes if this program was not called by a proc. END is 

required to terminate multiline ELSE statements. 

PROCREAD Parameters

Examples 

In the following example, the program segment assigns the string value in the 

primary input buffer to ARGUMENTS. If the program had been called by something 

other than a proc, the program prints a two-line error message. 

PROCREAD ARGUMENTS ELSE 

PRINT "ERROR!" 

PRINT "DIALOUT MUST BE CALLED FROM A PROC" 

ABORT 

END 

The following sample Proc loads the UniBasic program name proc.test into the data 

stack (Hproc.test), turns on that stack (STON), and loads “ONE” into the primary 

output buffer (HONE). The next command (P) executes the data stack entry, which 

runs proc.basic. Finally, D0 displays the contents of the active input buffer. 

The program proc.test prints after the proc, and a sample execution of the proc 

follows the program: 

PQ 

C 

C name: proc.one 

C test the interface of basic and PROC. 

C 

Hproc.test 

STON 

HONE 

P 

D0 

PROCREAD 1-584

The following globally cataloged program, proc.test, is executed by the preceding 

proc. The INPUT statement reads from the currently active output buffer, which the 

proc loaded with “ONE”. 


*----------------------------------------------------------------- 

--------- 

* subdirectory: interface 

* program name: proc.test 

* version : 1.6 or later 

* compile mode: any 

* catalog : y 

* catalog flag: local 

* test for : accepting passed arguments from a proc and 

writing 

* data to PROC data buffer (PROCWRITE). 

* called by : any proc or executed at the ECL prompt 

*----------------------------------------------------------------- 

---------* 

* 

PROGRAM proc.basic 

$BASICTYPE 'R' 

PRINT '*******************' 

PRINT 'TEST --> PROCREAD ' 

PRINT '*******************' 

PROCREAD pname 

THEN 

len = LEN(pname) 

PRINT "The last command executed is stored in the primary input 

buffer." 

PRINT "The last 10 characters of the 1st buffer are 

:":pname[0,len] 

PRINT "The length of the primary input buffer is :":LEN(pname) 

END ELSE 

PRINT "Not run from PROC." 

END 

PRINT '*******************' 

PRINT 'TEST --> PROCWRITE' 

PRINT '*******************' 

INPUT procname 

IF procname = 'ONE' THEN 

letters = "abcdefg,1234567,ABCDEFG,tuvwxyz," 

string = '' 

limit = 512 

FOR I = 1 TO limit STEP 32 

string := letters 

NEXT I 

PRINT "String length = ":LEN(string)

END ELSE 

string = "ONE TWO THREE FOUR FIVE" 

END 

PROCWRITE string 

END 

The preceding proc and program produce the following output: 

:wproctest 

******************* 

TEST --> PROCREAD 

******************* 

The last command executed is stored in the primary input buffer. 

The last 10 characters of the 1st buffer are :wproctest 

The length of the primary input buffer is :9 

******************* 

TEST --> PROCWRITE 

******************* 

?ONE 

String length = 512 

abcdefg,1234567,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz,ab 

cdefg,1234567,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz,abcd 

efg,1234567,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz,abcdef 

g,1234567,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz,abcdefg, 

1234567,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz,abcdefg,12 



7,ABCDEFG,tuvwxyz,abcdefg,1234567,ABCDEFG,tuvwxyz, 



PROCWRITE 

PROCREAD 1-586

PROCWRITE 

Syntax 

PROCWRITE expr 

Description 

The UniBasic PROCWRITE command writes data to the primary input buffer of the 

calling Proc. PROCWRITE overlays any data in the primary input buffer with the 

new data in PROCWRITE. 

Example 

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 

Note: Another example is provided with PROCREAD. 



PROCREAD

PROGRAM 

Syntax 

PROGRAM prog.name 

Description 

The UniBasic PROGRAM command defines the name of the current main program. 

This statement is optional. It is used for documentation purposes only. The 

PROGRAM statement must be the first noncomment statement in the program. 

Example 

In the following example, the program segment declares the program name as 

BOOKS: 

REM This is a program to bill customers 

PROGRAM BILLS 



SUBROUTINE 

UniData 

BASIC, CATALOG – For information, see the UniData Commands Reference. 

PROGRAM 1-588

PROMPT 

Syntax 

PROMPT str.expr 

Description 

The UniBasic PROMPT command sets the prompt displayed by the INPUT 

command to a specified single-byte character. If str.expr is longer than one character, 

UniData uses the first character as the prompt. You cannot set the prompt to a 

multibyte character. 

Data received from a DATA statement displays after the prompt. 

If you want to suppress the default prompt character, set the prompt to an empty 

string. The default prompt character is the question mark. 

Tip: Setting the prompt to an empty string also suppresses display of input from a 

DATA statement on the terminal screen. For example: 

PROMPT "" 

DATA "mypassword" 

INPUT PASSWD 

will not echo “mypassword” to the terminal screen. The PROMPT statement must 

precede the DATA statement. 

Data input from the keyboard will still echo on the display terminal. 

When you want to display text on the screen and have the cursor remain at the end of 

the displayed text awaiting user input, place a colon at the end of the PRINT or 

DISPLAY statement. 


Example 

In the following example, the contents of variable PSTRING (in this case, an 

asterisk) become the new prompt. When an INPUT command is used in the program, 

an asterisk appears at the current cursor position on the display terminal. 

PSTRING = "*" 

PROMPT PSTRING 



IN, INPUT, INPUT @, INPUTIF, INPUTTRAP 

PROMPT 1-590

protocolLogging 

Syntax 

protocolLogging(log_file, log_action, log_level) 



Description 

This function will start or stop logging. 

Parameters 



The following table describes each log level and detail. 


log_file The name of the file to which the logs will be recorded. The default log file 

name is httplog which is created under the current directory. 

log_action Either “ON” or “OFF”. The default is “OFF”. 

log_level The detail level of logging from 0 - 10. See table below. 

protocolLogging Parameters 


0 No logging. 

1 Socket open/read/write/close action (no real data) HTTP request: host 

info(URL) 

log_level Details


2 Level 1 logging plus socket data statistics (size, and so forth). 

3 Level 2 logging plus all data actually transferred. 

4-10 More detailed status data to assist debugging. 

log_level Details (continued) 


Return 

Code Status 

0 Success. 

1 Failed to start logging. 


protocolLogging 1-592

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 ^. 

Example 

In the following example, the program segment raises variable X to the power of 3, 

first using exponentiation operator **, then using the PWR function, and finally 

using the exponentiation operator ^. The results are identical. 

X = 2 

PRINT X**3 

PRINT PWR(X,3) 

PRINT X^3 


^ 


QUOTE 

Syntax 

QUOTE(str.expr) 

Synonym 

DQUOTE 

Description 

The UniBasic QUOTE function encloses a string expression in double quotation 

marks. 

Examples 

In the following example, the program segment encloses the string stored in VAR2 

with double quotation marks, and then stores that string (“STRING2”) in VAR3: 

VAR2 = "STRING2" 

VAR3 = QUOTE(VAR2) 

In the following example, the program statement uses DQUOTE to print “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) 

QUOTE 1-593



SQUOTE 


RAISE 

Syntax 

RAISE(str.expr) 

Description 

The UniBasic RAISE function raises all UniData delimiters to the next level. 

UniData raises attribute marks to record marks, value marks to attribute marks, and 

subvalue marks to value marks. 

Example 

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' 



LOWER 

RAISE 1-595

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. UniData assigns the first attribute of the record to the first position 

of the array, the second attribute to the second position, and so on. If UniData cannot 

find the record you specify, it executes the ELSE clause and returns dyn.array.var 

empty. 


environment, you must use record locks to prevent more than one user from accessing 

the same record at the same time. For more information about UniBasic record 

locking, see Developing UniBasic Applications. 

Warning: Do not use UniBasic READ commands to open or modify binary data in 

DIR-type files (for example, BP). Doing so could corrupt data in the file. Instead, use 

OSREAD or OSBREAD after executing the UniBasic NOCONVERT command. 


Parameters 



dyn.array.var Specifies a target dynamic array for the data being read. 

FROM file.var, Specifies a file variable from which to read the record. 



The default file is one for which no file variable is assigned in 

the OPEN statement. 

record.ID.expr Specifies a record to read. 

ON ERROR statements Specifies statements to execute if the READ statement fails with 

a fatal error because the file is not open, an I/O error occurs, or 

UniData cannot find the file. 







statements. 

READ Parameters 


After you execute READ, the STATUS function returns one of the values described 



0 Successful read. 

2 A read error occurred. 

5 An encryption error occurred during the READ operation. 

STATUS Function Values 

READ 1-597

Example 

In the following example, the program segment reads a record from the CLIENTS 

file with ID CLIENT.ID. If the record ID is found, UniData executes the subroutine 

PROCESS.CLIENT. Otherwise, UniData prints a message and the program performs 

the subroutine REPROMPT. 


READ CLIENT.REC FROM CLIENT, CLIENT.ID THEN 

GOSUB PROCESS.CLIENT 

END ELSE 

PRINT 'NO CLIENT REC FOR 'CLIENT.ID 

END 



CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, 

WRITE

READBCK 

Syntax 

READBCK dyn.array.var [FROM file.var] [ON ERROR statements] {THEN 

statements [END] | ELSE statements [END]} 

Description 

The first READBCK command retrieves the alternate key set by SETINDEX, then 

each subsequent READBCK retrieves the previous alternate key value in the index. 

The corresponding record is read into a dynamic array, and the record ID is assigned 

to the @ID variable. 



the same record at the same time. For more information about UniBasic record 


Using this command in a loop, a UniBasic program retrieves records in descending 

order based on an indexed attribute. 

Before executing READBCK, you must set the alternate key value with the 

SETINDEX command. The SETINDEX parameters BUFFER.KEYS and 

VALIDATE.KEY determine, respectively, whether the buffering mechanism is used 

and whether keys are validated when READBCK executes. For details, see 

SETINDEX. 

READBCK sets the STATUS function return value to 10 if UniBasic detects a 

duplicate alternate index key value and you have executed the ECL command 

DUP.STATUS ON during the current session. 

READBCK 1-599

Parameters 




After you execute READBCK, the STATUS function returns one of the values 



dyn.array.var Specifies a dynamic array to which to assign the values read. 

FROM file.var Specifies a file variable from which to read the record. 





ON ERROR statements Specifies statements to execute if the READBCK statement fails 







ELSE statements END ELSE executes if the read is not successful or the record does not 

exist. END is required to terminate multiline ELSE statements. 

READBCK Parameters 

Paramete 

r Description 


10 UniBasic found and read a duplicate alternate index key value, and ECL 

DUP.STATUS is on. 


Example 

In the following example, the program segment sets the index to the first record that 

contains Smith, and then reads that record and the previous four: 

OPEN 'CLIENTS' TO tmp ELSE STOP 

SETINDEX 'LNAME', 'Smith' ON tmp 


READBCK rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

END 

The preceding program produces the following results: 

Marge, Smith Smith Widgets 

Pearl, Sloane Harvard Assoc. 

Reginald, Sklar Culver Excavating 

Alexandria, Singleton Vintech Inc. 

Larry, Singh Smith Widgets 

Note: This program reads the records even if the records are locked by another user. 



READBCKL, READBCKU, READFWD, READFWDL, READFWDU, 

READXBCK, READXFWD, SELECTINDEX, SETINDEX 

UniData 

BUILD.INDEX, CREATE.INDEX, DUP.STATUS – For information, see the 

UniData Commands Reference. 

READBCK 1-601

READBCKL 

Syntax 

READBCKL dyn.array.var [FROM file.var] [ON ERROR statements] 


READBCKL dyn.array.var [FROM file.var] [LOCKED statements] 


Description 

The first READBCKL command retrieves the alternate key set by SETINDEX, and 

then each subsequent READBCKL retrieves the previous alternate key in the index. 

The corresponding record is read into a dynamic array, and the record ID is assigned 

to the @ID variable. READBCKL checks for locks. If the record is available, it sets 

a shared (L) lock before reading the record. 





Before executing READBCKL, you must set the pointer in the alternate key file with 

the SETINDEX command. The SETINDEX parameters BUFFER.KEYS and 


and whether keys are validated when READBCKL executes. For details, see 

SETINDEX. 

READBCKL sets the STATUS function return value to 10 if UniBasic detects a 




Parameters 



dyn.array.var Specifies a target dynamic array to receive the data read. 






ON ERROR statements Specifies statements to execute if the READBCKL statement 





LOCKED statements Specifies statements to execute if the record is already locked. 

If you do not specify the LOCKED clause, and if the record is 

locked, UniData waits until the record is available. 


to make the terminal beep while you wait for UniData to 

unlock the record. 

THEN statements END THEN executes if the read is not successful. END is required 

to terminate multiline THEN statements. 

ELSE statements END ELSE executes if the read is not successful, the current 

alternate key value is not set by the SETINDEX command, or 

UniData cannot locate the current alternate key value (for 

example, when UniData reaches the end of the alternate 

index). END is required to terminate multiline ELSE 

statements. 

READBCKL Parameters 

READBCKL 1-603


After you execute READBCKL, the STATUS function returns one of the values 




Example 

This example uses the following program to lock the CLIENT file for two minutes: 





OPEN "CLIENTS" TO CLIENT.FILE ELSE STOP 

FILELOCK CLIENT.FILE LOCKED PRINT "CLIENTS FILE already locked." 

SLEEP 120 

FILEUNLOCK CLIENT.FILE 

If you execute the following program: 




READBCKL rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

END 

Notice that execution halts on the second program until the first program unlocks the 

CLIENTS file. This is because commands that set shared locks cannot access files 

locked with exclusive locks (FILELOCK sets an exclusive lock). 

Note: If the first program had set a shared lock, the second program would have been 

able to read the records.



READBCK, READBCKU, READFWD, READFWDL, READFWDU, 


UniData 

BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS 

– For information, see the UniData Commands Reference. 

READBCKL 1-605

READBCKU 

Syntax 

READBCKU dyn.array.var [FROM file.var] [ON ERROR statements] 


READBCKU dyn.array.var [FROM file.var] [LOCKED statements] 


Description 

The first READBCKU command retrieves the alternate key set by SETINDEX, and 

then each subsequent READBCKU retrieves the previous alternate key value in the 

index. The corresponding record is read into a dynamic array, and the record ID is 

assigned to the @ID variable. READBCKU checks for locks. If the record is 

available, it sets an exclusive (U) lock before reading the record. 





Before executing READBCKU, you must set the alternate key value with the 

SETINDEX command. The SETINDEX parameters BUFFER.KEYS and 


and whether keys are validated when READBCKU executes. For details, see 

SETINDEX. 

READBCKU sets the STATUS function return value to 10 if UniBasic detects a 




Parameters 



dyn.array.var Specifies a target dynamic array to receive the data read. 






ON ERROR 

statements 

Specifies statements to execute if the READBCKU statement 





LOCKED statements Specifies statements to execute if the record is already locked. If 

you do not specify the LOCKED clause, and if the record is 

locked, UniData waits until the record is available. 



the record. 

THEN statements END THEN executes if the read is not successful. END is required to 


ELSE statements END ELSE executes if the read is not successful, the current alternate 

key value is not set by the SETINDEX command, or UniData 

cannot locate the current alternate key value (for example, when 

UniData reaches the end of the alternate index). END is required 

to terminate multiline ELSE statements. 

READBCKU Parameters 

READBCKU 1-607


After you execute READBCKU, the STATUS function returns one of the values 




Example 








READBCKU rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

SLEEP 60 

END 





READBCKU rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

END 


record associated with “Smith.” This is because commands that set exclusive locks 

cannot access records lock with any kind of lock.



READBCK, READBCKL, READFWD, READFWDL, READFWDU, 


UniData 



READBCKU 1-609

READFWD 

Syntax 

READFWD dyn.array.var [FROM file.var] [ON ERROR statements] {THEN 


Description 

The first READFWD command retrieves the alternate key set by SETINDEX, and 

then each subsequent READFWD retrieves the next alternate key value in the index. 

UniData reads the corresponding record into a dynamic array, and then assigns the 

record ID to the @ID variable. 



the same record at the same time. For more information about the UniBasic record 


Using this command in a loop, a UniBasic program retrieves records in ascending 


Before executing READFWD, you must set a pointer to an alternate key value with 



and whether keys are validated when READFWD executes. For details, see 

SETINDEX. 

READFWD sets the STATUS function return value to 10 if UniBasic detects a 




Parameters 



dyn.array.var Specifies a dynamic array to contain the record. 

FROM file.var Specifies a file from which to read the record. 





ON ERROR statements Specifies statements to execute if the READFWD statement 









READFWD Parameters 


After you execute READFWD, the STATUS function returns one of the values 







READFWD 1-611

Example 

In the following example, the program segment sets the index to the first record that 

contains Smith, and then reads that record and the next four: 



SETINDEX 'LNAME', 'Singh' ON tmp 


READFWD rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

This program produces the following results: 

Charles, Singh Goddard Fabrics 

Larry, Singh Smith Widgets 

Alexandria, Singleton Vintech Inc. 

Reginald, Sklar Culver Excavating 

Pearl, Sloane Harvard Assoc. 

Note: This program reads the records even if the records are locked by other users. 



READBCK, READBCKL, READBCKU, READFWDL, READFWDU, 

READXFWD, READXBCK, SELECTINDEX, SETINDEX 

UniData 

BUILD.INDEX, CREATE.INDEX, DUP.STATUS – For information, see the 

UniData Commands Reference.

READFWDL 

Syntax 

READFWDL dyn.array.var [FROM file.var] [ON ERROR statements] 


READFWDL dyn.array.var [FROM file.var] [LOCKED statements] 


Description 

The first READFWDL command retrieves the alternate key set by SETINDEX, and 

then each subsequent READFWDL retrieves the next alternate key value in the 

index. UniData reads the corresponding record into a dynamic array, and then assigns 

the record ID to the @ID variable. READFWDL checks for locks. If the record is 

available, it sets a shared (L) lock. 





Before executing READFWDL, you must set a pointer to an alternate key value with 



and whether keys are validated when READFWDL executes. For details, see 

SETINDEX. 

READFWDL sets the STATUS function return value to 10 if UniBasic detects a 


DUP.STATUS ON during the current work session. 

READFWDL 1-613

Parameters 










ON ERROR statements Specifies statements to execute if the READFWDL statement 





LOCKED statements Specifies statements to execute if the record is locked by 

another user. If you do not specify a LOCKED clause, the 

program waits until the lock on the record is released. 



the record. 



ELSE statements END ELSE executes if the read is not successful or the record does 

not exist. END is required to terminate multiline ELSE 

statements. 

READFWDL Parameters


After you execute READFWDL, the STATUS function returns one of the values 







Example 



FILELOCK CLIENT.FILE LOCKED PRINT "CLIENTS FILE already locked." 

SLEEP 120 

FILEUNLOCK CLIENT.FILE 





READFWDL rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

END 


CLIENTS file. This is because commands that set shared locks cannot access files 

locked with exclusive locks (FILELOCK sets an exclusive lock). 

Note: If the first program had set a shared lock, the second program would have been 

able to read the records. 

READFWDL 1-615



READBCK, READBCKL, READBCKU, READFWD, READFWDU, 


UniData 




READFWDU 

Syntax 

READFWDU dyn.array.var [FROM file.var] [ON ERROR statements] 


READFWDU dyn.array.var [FROM file.var] [LOCKED statements] 


Description 

The first READFWDU command retrieves the alternate key set by SETINDEX, and 

then each subsequent READFWDU retrieves the next alternate key value in the 

index. UniData reads the corresponding record into a dynamic array, and then assigns 

the record ID to the @ID variable. READFWDU checks for locks. If the record is 

available, READFWDU sets an exclusive (U) lock before reading the record. 





Before executing READFWDU, you must set a pointer to the alternate key value 

with the SETINDEX command. 

READFWDU sets the STATUS function return value to 10 if UniBasic detects a 


DUP.STATUS ON during the current work session. 

READFWDU 1-617

Parameters 










ON ERROR statements Specifies statements to execute if the READFWDU statement 










the record. 





statements. 

READFWDU Parameters


After you execute READFWDU, the STATUS function returns one of the values 







Example 




READFWDU rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

SLEEP 120 

END 





READFWDU rec FROM tmp THEN PRINT rec:", ":rec:" ":rec 

ELSE STOP 

NEXT X 

END 


record associated with “Smith.” This is because commands that set exclusive locks 

cannot access records lock with any kind of lock. 

READFWDU 1-619



READBCK, READBCKL, READBCKU, READFWD, READFWDL, 


UniData 




READL 

Syntax 

READL dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] 


READL dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements] 


Description 

The UniBasic READL command reads the specified record from a file and assigns 

its contents to a dynamic array. UniData assigns the first attribute of the record to the 

first position of the array, the second attribute to the second position, and so on. 

READL checks for locks. If the record is available, it sets a read-only lock on the 

record, preventing other lock-checking commands from updating it. 




binary data in DIR-type files (for example, BP). Doing so could corrupt data in the 

file. Instead, use OSREAD or OSBREAD after executing the UniBasic NOCONVERT 

command. 

READL 1-621

Parameters 




dyn.array.var Specifies a dynamic array to receive the record. 






ON ERROR statements Specifies statements to execute if the READL statement fails 






user (with an exclusive lock). If you do not specify a LOCKED 

clause, the program waits until the lock on the record is released. 



the record. 





READL Parameters


After you execute READL, the STATUS function returns one of the values described 


Examples 

This example uses the following program to lock the ORDERS file for two minutes: 

OPEN "ORDERS" TO ORDER.FILE ELSE STOP 

FILELOCK ORDER.FILE LOCKED PRINT "ORDERS FILE already locked." 

SLEEP 120 

FILEUNLOCK ORDER.FILE 

If you immediately execute the following program: 

OPEN "ORDERS" TO tmp ELSE STOP 

READL rec FROM tmp,'941' THEN PRINT rec LOCKED PRINT "Record 

locked, try again later" 

END 

the second program prints “Record locked, try again later”. 





1 UniData was unable to read the record. 

n The record is locked. The user number of the user who locked 

the record. 


CLOSE, DELETE, OPEN, READ, READU, READV, READVL, READVU, 

WRITE 

READL 1-623

UniData 




READLIST 

Syntax 

READLIST dyn.array.var [FROM list.num] {THEN statements [END] | ELSE 


Synonym 

READSELECT (BASICTYPE P only) 

Description 

The UniBasic READLIST command assigns the values in an active select list to a 

dynamic array. Each select list element becomes an attribute in the dynamic array. 

Note: Use the following syntax in BASICTYPE M: 

READLIST dyn.array.var FROM list.num [, acct.name] [SETTING count.var] 


If you create a list under an account other than the current one, you can specify the 

account with acct.name. The SETTING clause sets the number of elements in the list 

to count.var. 

In BASICTYPE P, use the READSELECT command with the following syntax: 

READSELECT dyn.array.var [FROM list.name] {THEN statements [END] | ELSE 


READLIST 1-625

Parameters 



Example 

In the following example, the program segment selects the IDs in the INVENTORY 

file to select list 0, and then builds a dynamic array of the items for which quantity in 

stock is greater than 10. The last program statement prints the select list to show its 

contents. 


dyn.array.var Specifies a dynamic array to contain the values removed from 

the select list. 

FROM list.num Specifies which select list (0-9) you want to use. If you do not 

specify a list.num, UniData reads the default list (0). If no items 

are available in the list, UniData executes the ELSE clause. 



ELSE statements END ELSE executes if the read is not successful or the list does not 


READLIST Parameters 

OPEN 'INVENTORY' TO INV.FILE ELSE STOP 

SELECT INV.FILE 

DONE = 0 

LOOP 

READNEXT INV.ID ELSE DONE = 1 

WHILE NOT(DONE) DO 

READ INV.REC FROM INV.FILE,INV.ID ELSE 

PRINT "No INVENTORY RECORD: ":INV.ID 

END 

IF INV.REC > 9 THEN 

READLIST LIST.ITEM ELSE LIST.ITEM = " " 

END 

REPEAT 

PRINT LIST.ITEM



DELETELIST, FORMLIST, GETLIST, READNEXT, SELECT, 

SELECTINDEX, SELECTINFO, WRITELIST 

UniQuery 

DELETE.LIST, GET.LIST, SELECT, SAVE.LIST, SSELECT – For information, see 


UniData SQL 


READLIST 1-627

READNEXT 

Syntax 

READNEXT id.var [, val.var[, subval.var]] [FROM list.num.expr] 


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, but assigns it to a variable. 

After the variable is assigned, you can use it within a READ statement to access it. 

As an example, a customer transaction might require that data be read in a particular 

sequence. The sequence is determined by using a sorted SELECT statement to select 

IDs in the appropriate order and then using the READNEXT statement to assign an 

ID to a variable. 

Note: READNEXT performs differently with BASICTYPEs M and P as shown in the 

following syntax: 

READNEXT var FROM list.name {, acct.name} 

[SETTING count.var] {THEN statements [END] | ELSE statements [END]} 

The SETTING clause assigns the number of elements in the list to the variable 

count.var. 

READNEXT and Multivalued Attributes 

Select lists used by READNEXT can contain an optional value and subvalue 

positions (if you create the list using the BY.EXP keyword). The select list created by 

using this keyword is sorted based on a multivalued or subvalued attribute. The select 

list contains, in each of two attributes, the record ID and position of the sorted value 

or subvalue. The READNEXT command passes the value or subvalue positions to 

val.var and subval.var. A subsequent READ statement might access the appropriate 

value using val.var (and subval.var). 


Note: When you create a select list using the BY.EXP keyword against a multivalued 

or multi-subvalued attribute, the resulting select list contains the multivalue position 

in the second value of the attribute and the multi-subvalue position in the third value 

of the attribute. If a BY.EXP select statement is executed against an attribute with a 

value code specifier of MV, the third value in each attribute in the resulting select list 

is -5 as the following shows: 

001: 785}1}-5 

002: 796}1}-5 

003: 812}1}-5 

... 

READNEXT assigns the values and subvalues of each record ID to val.var and 

subval.var. The val.var and subval.var each can contain more than one data value 

(separated by value or 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 in 

subval.var corresponds to the value and subvalue position of the attribute in the first 

BY.EXP expression. The second subvalue in val.var and in subval.var corresponds 

to the value and subvalue position of the attribute in the second BY.EXP clause, and 

so forth for each successive BY.EXP clause. 

Parameters 



id.var Specifies a variable to contain the value of the next record ID. 

,val.var,subval.var Specifies a value and subvalue to read. 

FROM list.num.expr Specifies which select list (0-9) you want to use. If you do not 

specify list.num, the default (0) list is used. If no items are 

available in the list, UniData executes the ELSE clause. 

READNEXT Parameters 

READNEXT 1-629


Examples 

In the following example, the program segment reads 10 IDs from select list 1, and 

then reads the records associated with those IDs. If a record ID is not found in the 

default system file, the program displays the message NOT FOUND. 


ON ERROR statements Specifies statements to execute if the READNEXT statement 




occurs, the user enters the debugger. 





statements. 

READNEXT Parameters (continued) 

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 selects all Canadian clients, and then executes 

READNEXT to read and display the records for the first 22: 




GETLIST 'canadians' SETTING LIST.CNT 

ELSE PRINT CLIENT:" SAVELISTS ID ‘canadians’ CANNOT BE 

FOUND";STOP 

PRINT @(-1) 

FOR I = 1 TO 22 




END ELSE 


END 

NEXT I 

CLEARSELECT 

END 



DELETELIST, FORMLIST, GETLIST, READLIST, SELECT, SELECTINDEX, 

SELECTINFO, WRITELIST 

UniQuery 



UniData SQL 


READNEXT 1-631

READNEXTTUPLE 

Syntax 

READNEXTTUPLE dyn.array.var FROM file.name.expr {THEN 


Description 

The UniBasic READNEXTTUPLE command assigns the next entire record to a 

variable. The record ID is obtained from an active select list that was created by a 

UniData SQL SELECT statement during the current work session. 

READNEXTTUPLE creates a dynamic array delimited by attribute marks (@AM). 

The attribute marks are entered by the UniData SQL SELECT statement. 

Tip: Do not use the UniData SQL UNNEST command in the SQL statement that 

creates the ID list. UniData might 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 contain the record. 

FROM file.name.expr Specifies the file from which to read the next record ID. 

file.name.expr must have been created during the current session 

by: 

An EXECUTESQL statement with a TO clause in the UniBasic 

program. 

A UniData SQL statement executed at the ECL prompt before 

the program was run. 



ELSE statements END ELSE executes if the read is not successful, the record does not 

exist, or the last record has been read. END is required to 

terminate multiline ELSE statements. 

READNEXTTUPLE Parameters 

READNEXTTUPLE 1-633

Example 

In the following example, the program segment executes a UniData SQL statement 

and stores the output in an internal result file called SQL_INPUT. The 

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 = "SELECT NAME, ADDRESS, CITY" 

OUT.COMMAND := " FROM CLIENTS TO SQL_INPUT; " 


DONE = 0 

BPIOCP 

LOOP 

READNEXTTUPLE CLIENT.REC FROM "SQL_INPUT" ELSE 

DONE = 1 

END 

UNTIL DONE DO 

CONVERT @AM TO " " IN CLIENT.REC 

CONVERT @VM TO","IN CLIENT.REC 

PRINT CLIENT.REC 

REPEAT 

END 



EXECUTE, EXECUTESQL 

UniData SQL 

SELECT – For information, see Using UniData SQL.

READSELECT 

READSELECT is a synonym for the READLIST command. For more information, 

see READLIST. 

Synonym 

READLIST 

READSELECT 1-635

READSEQ 

Syntax 

READSEQ var FROM seq.file.var {THEN statements [END] | 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: Before you use READSEQ, you must open the file by using the OSOPEN or 


If the file is a named pipe, you cannot use READSEQ to read it. You must use the 

OSBREAD command. 

Each read from the sequential file searches for a line feed character [CHAR(10)] to 

determine the end of the record. READSEQ maintains a pointer to the current 

position in the file (where the last record terminated). 

Parameters 




var Specifies a variable to which to assign the record. 

READSEQ Parameters


FROM seq.file.var Specifies a sequential file from which to read the record. 

seq.file.var must be a sequential file opened by using an 

OPENSEQ or OSOPEN statement. 





Example 

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" 



READSEQ Parameters (continued) 

CLOSESEQ, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, 

OSOPEN, WRITESEQ, WRITESEQF 

READSEQ 1-637

eadSocket 

Syntax 

readSocket(socket_handle, socket_data, max_read_size, time_out, blocking_mode, 

actual_read_size) 



Description 

Use the readSocket function to read data in the socket buffer up to max_read_size 

characters. 

Parameters 





socket_data The data to be read from the socket. 

max_read_size The maximum mumber of characters to return. If this is 0, then 

the entire buffer should be returned. 

time_out The time (in milliseconds) before a return in blocking mode. 

This is ignored for non-blocking read. 

blocking_mode 0:using current mode 

1:blocking 

2:non-blocking 

actual_read_size The number of characters actually read. -1 if error. 

readSocket Parameters



0 - Non-Blocking The function will return immediately if there is no data in the 

socket. If the max_read_size parameter is greater than the socket 

buffer then just the socket buffer will be returned. 

1 - Blocking If there is no data in the socket, the function will block until data 

is put into the socket on the other end. It will return up to the 

max_read_size character setting. 




0 Success. 


readSocket Return Codes 

readSocket 1-639

READT 

Syntax 

READT [UNIT (mu.expr)] var {THEN statements [END] | ELSE statements 

[END]} 

Description 

The UniBasic READT command reads the next record from a tape and assigns it to 

a variable. 

Note: Before you use the READT command, you must attach a tape drive with the 

T.ATT command. For information about tape commands, see the UniData 

Commands Reference. You must use the TAPELEN option for the T.ATT command 

and specify the length of the tape in megabytes. This command is intended for use 

with UniData tapes only. 

UniData uses the ASCII 0 character (CHAR(0)) as an end-of-record mark. Therefore, 

you cannot use ASCII 0 in any string variable in UniBasic. READT converts 

(CHAR(0)) to CHAR(128). 


Parameters 



UNIT (mu.expr) Specifies the conversion code (first digit), and the unit number 

(second digit). UniData allows unit numbers from 0 through 9. 

mu.expr is optional. The default value is 00, indicating tape unit 

0 and no conversion: 

0 – No conversion (ASCII assumed) 

1 – EBCDIC conversion 

2 – Invert high bit 

3 – Swap bytes 

var Specifies a variable to contain the record. 





READT Parameters 


After you execute READT, the STATUS function returns one of the values described 




1 End of file encountered. 

2 End of tape encountered. 

3 Tape not assigned. 


READT 1-641

Example 

In the following example, the program segment first uses the ECL T.ATT command 

to reserve tape unit 0 and perform no conversion. Then the program segment reads 

all the records on the tape (until the end of the file or 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 



RESIZET, REWIND, WEOF, WRITET 

UniData 


4 Parity error. 

5 Unknown hardware error. 

6 Other unspecified error. 

STATUS Function Return Values (continued) 

SETTAPE, T.ATT, T.DET – For information, see the UniData Commands Reference.

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. READU checks for locks. If the record is available, it sets an 

exclusive lock and reads the record. 




binary data in DIR-type files (for example, BP). Doing so could corrupt data in the 

file. Instead, use OSREAD or OSBREAD after executing the UniBasic NOCONVERT 

command. 

READU 1-643

Parameters 





FROM file.var, Specifies the file variable from which to read the record. 





record.ID.expr Specifies the record ID to use to retrieve the record. 

ON ERROR statements Specifies statements to execute if the READU statement fails 







until the lock on the record is released. 



the record. 





statements. 

READU Parameters


After you execute READU, the STATUS function returns one of the values described 


Examples 



1 UniData was unable to read the record. 

n The record is locked. The user number of the user who locked 

the file is returned in n. 



“Sample Programs,” in Developing UniBasic Applications. READU checks for 

locks. If the record is available, it sets an exclusive lock and reads the record into 

ORDER.REC. 

DISPLAY_DATA: 



READU ORDER.REC FROM ORDERS_FILE,ORDER_NUMBER THEN 

* Read with a lock so that no one else can modify it at the same 

time. 

RECORD_FOUND = 1 

The record remains locked until the following program executes, which releases 

locks: 

WRITE ORDER.REC ON ORDERS_FILE,ORDER_NUMBER 

In the following example, the program segment assigns the record, read from the 

default file, to the variable INFO, and sets an exclusive lock on that record. UniData 

prints “Record locked” if the record is locked by another program, or prints “File not 

found” if the record does not exist. If the default file is not found, the program ends. 

READU INFO FROM "IDENT" LOCKED PRINT "Record locked" 

ELSE PRINT "Record not found" 

READU 1-645



CLOSE, DELETE, OPEN, READ, READL, READV, READVL, READVU, 

WRITE 

UniData 




READV 

Syntax 

READV var FROM [file.var,] record.ID.expr, attribute.expr 


Description 

The UniBasic READV command assigns the data from an attribute of a record to a 

variable. 

Note: READV ignores locks. To update a record, you should use the READVU 

command, which checks for locks. For an explanation of UniData locks, see 

Developing UniBasic Applications.. 

Tip: To improve efficiency, use READV when only one or two attributes are needed 

from a record. If access to more attributes is needed, READ or MATREAD is more 

efficient. 

Parameters 



var Specifies a dynamic array to contain the attribute. 

FROM file.var, Specifies the file from which to read the record. 





record.ID.expr Specifies the record to read. 

attribute.expr Specifies the attribute to read. 

READV Parameters 

READV 1-647


Examples 

In the following example, the program segment reads CLIENT.NAME from the 

CLIENTS file, record ID 10034, attribute 2. If the record exists, UniData appends the 

attribute to string NAME.ARRAY1 using the short form of the replace command. 

Otherwise, UniData executes the ELSE clause. 


ON ERROR statements Specifies statements to execute if the READV statement fails 









READV Parameters (continued) 

NAME.ARRAY1 = "Smith Jones Brown" 


READV CLIENT.NAME FROM CLIENT.FILE,"10034",2 THEN 

NAME.ARRAY1 = CLIENT.NAME 

PRINT NAME.ARRAY1 

END ELSE 

PRINT 'NO FILE FOR CLIENT ':CLIENT.ID 

END 

In the next example, you can use the READV command with an attribute.expr of 0 

to verify that a record exists (for example, if you are assigning IDs sequentially in the 

CLIENTS file). Each time you need to create a new ID, you need to verify that the 

ID you selected is not in use. The following code accomplishes this task, incrementing 

the ID until an ID is available. 

LOOP 

READV CHECK FROM CLIENT,NEXT.ID,0 ELSE CHECK = 0 

UNTIL CHECK NE 0 DO 

NEXT.ID += 1 

REPEAT CLIENT.ID = NEXT.ID



CLOSE, DELETE, OPEN, READ, READL, READU, READVL, READVU, 

WRITE 

READV 1-649

READVL 

Syntax 

READVL var FROM [file.var,] record.ID.expr, attribute.expr 



READVL var FROM [file.var,] record.ID.expr, attribute.expr 



Description 

The UniBasic READVL command assigns the data from an attribute of a record to 

a variable. READVL checks for locks. If the record is available, it sets a shared lock 

before it reads the record. 



You generally use the READVL command when only one or two attributes are needed 

from a record. If access to more attributes is needed, READ or MATREAD is more 

efficient. 


Parameters 



var Specifies the variable to contain the attribute. 

FROM file.var, Specifies the file from which to read the attribute. 

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. 





attribute.expr Specifies an attribute from which to read. 

ON ERROR statements Specifies statements to execute if the READVL statement fails 










the record. 





statements. 

READVL Parameters 

READVL 1-651

Example 

In the following example, READVL checks for locks on the record CARS in the 

default file. If the record is available, it sets a shared lock and reads the third attribute 

of the record. If the data is not found, UniData displays the message “NOT FOUND”. 


READVL MODEL FROM "CARS",3 ELSE PRINT "NOT FOUND" 



CLOSE, DELETE, OPEN, READ, READL, READU, READV, READVU, WRITE 

UniData 



READVU 

Syntax 

READVU var FROM [file.var,] record.ID.expr, attribute.expr 



READVU var FROM [file.var,] record.ID.expr, attribute.expr 



Description 

The UniBasic READVU command assigns the data from an attribute of a record to 

a variable. READVU checks for locks. If the record is available, it sets an exclusive 

lock before it reads the record. 

Tip: You can improve efficiency by using the READVU command when you need only 

one or two attributes from a record. If more attributes are necessary, or if you need 

to update more attributes, use the READU or MATREADU commands. 

UniBasic locks are advisory only. For more information, see Developing UniBasic 

Applications. 

READVU 1-653

Parameters 




var Specifies a variable to contain the data read from the attribute. 

FROM file.var, Specifies the file from which to read the attribute. 





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. 

ON ERROR statements Specifies statements to execute if the READVU statement fails 










the record. 





statements. 

READVU Parameters

Examples 

The following program segment is taken from Appendix A, “Sample Programs,” in 

Developing UniBasic Applications. READVU checks for locks. If the record is 

available, it sets an exclusive lock and reads the multivalued attribute containing the 

order number the user wants to delete. 






END 


END 

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, UniData 

displays a read-error message. 

READVU SUPPL FROM INV,ID,7 LOCKED PRINT "Locked" 

ELSE GOTO 2010: 



CLOSE, DELETE, OPEN, READ, READL, READU, READV, READVL, WRITE 

UniData 



READVU 1-655

READXBCK 

Syntax 

READXBCK dyn.array.var [FROM file.var] [ON ERROR statements] {THEN 


Description 

The UniBasic READXBCK command reads the previous key in an alternate key 

index in much the same manner as the READBCK command, but does not read the 

associated record. READXBCK enables a program to read alternate keys without 

incurring the overhead of retrieving a record every time. 

Parameters 





FROM file.var Specifies the file from which to read the record. 





READXBCK Parameters


ON ERROR statements Specifies statements to execute if the READXBCK statement 












READFWDU, READXFWD, SELECTINDEX, SETINDEX 

UniData 

READXBCK Parameters (continued) 



READXBCK 1-657

READXFWD 

Syntax 

READXFWD dyn.array.var [FROM file.var] [ON ERROR statements] 


Description 

The UniBasic READXFWD command reads the next value in an alternate key index 

in much the same manner as the READFWD command, but does not read the 

associated record. READXFWD enables a program to read alternate keys without 

incurring the overhead of retrieving a record every time. 

Parameters 





FROM file.var Specifies the file from which to read the record. 





READXFWD Parameters


ON ERROR statements Specifies statements to execute if the READXFWD statement 












READFWDU, READXBCK, SELECTINDEX, SETINDEX 

UniData 

READXFWD Parameters (continued) 



READXFWD 1-659

ReadXMLData 

Syntax 

ReadXMLData(xml_data_handle, rec) 



Description 

After opening the XML document with the OpenXMLData function, read the 

document using the ReadXMLData function. UniBASIC returns the XML data as a 


Syntax 



After you read the XML document, you can execute any UniBASIC statement or 

function against the data. 


xml_data_handle A variable that holds the XML data handle created by the 

OpenXMLData function. 

rec A mark-delimited dynamic array containing the extracted data. 

ReadXMLData Parameters

Status Codes 

The status code can be one of the following: 

Status Code Description 


XML.ERROR Failure 

XML.INVALID.HANDLE Invalid xml_data_handle 

XML.EOF End of data 

ReadXMLData Status Codes 

Example 

The following example illustrates use of the ReadXMLData function: 

MOREDATA=1 

LOOP WHILE (MOREDATA=1) 

status = ReadXMLData(STUDENT_XML,rec) 

IF status = XML.ERROR THEN 

STOP “Error when preparing the XML document. “ 

END ELSE IF status = XML.EOF THEN 

PRINT “No more data” 

MOREDATA = 0 

END ELSE 

PRINT “rec = “:rec 

END 

REPEAT 

ReadXMLData 1-661

RECORDLOCKED 

Syntax 

RECORDLOCKED (file.var, rec.id.expr) 

Description 

The UniBasic RECORDLOCKED function returns the lock status of the specified 

record or file. For an explanation of UniData locks, and for a sample program you 

can use to test this command, see Developing UniBasic Applications. 


With null value handling on, the null value in file.var results in a RECORDLOCKED 

return value of -2 and a STATUS function return value of -12. The null value is a valid 

record ID and can be passed to the function in rec.id.expr. 

Parameters 




file.var Specifies the file on which to check lock status. The null value in file.var 

results in a RECORDLOCKED return value of -2. 

rec.id.expr Specifies the record on which to check lock status. 

RECORDLOCKED Parameters

RECORDLOCKED Function Return Values 

The RECORDLOCKED function returns one of the values described in the following 

table. 

Value Lock Type Lock Owner Locking Command 

4 exclusive you FILELOCK, SQL LOCK TABLE, 

implicit SQL TP lock escalation. 

3 shared you FILELOCK, SQL LOCK TABLE, 


2 exclusive you READU, RECORDLOCKU, SQL 

TP implicit record locking. 

1 shared you READL, RECORDLOCKL, SQL 


0 The record is not locked. 

-1 shared another user READL, RECORDLOCKL, SQL 


-2 exclusive another user READU, RECORDLOCKU, SQL 


-3 shared another user FILELOCK, SQL LOCK TABLE, 


-4 exclusive another user FILELOCK, SQL LOCK TABLE, 


RECORDLOCKED Return Values 

Note: When UDT.OPTIONS 35 is on, this function returns a value of -2 when another 

user has a READU lock on the record or file. 

RECORDLOCKED 1-663


After you execute RECORDLOCKED, the STATUS function returns one of the 

values described in the following table. 

Value 



FILELOCK, FILEUNLOCK, RECORDLOCKL, RECORDLOCKU, RELEASE 


RECORDLOCKED 

Return Value Meaning 

n A number between -1 

and -4. 

The record is locked. The user number of the user 

who owns the lock is returned in n. 

0 0 The record is not locked. 

-1 -11 The file is NFA. Currently, RECORDLOCKED 

does not support NFA files. 

-2 -12 Invalid file type. file.var can contain the null value. 

-3 -13 System error: unknown user. 


RECORDLOCKL 

Syntax 

RECORDLOCKL [file.var,] record.ID.expr [ON ERROR statements] 

[LOCKED statements] 

Description 

The UniBasic RECORDLOCKL command checks for record locks. If the record is 

available, it sets a shared lock on the record. For an explanation of UniData locks, 

and for a sample program that you can use to test this command, see Developing 


Parameters 



file.var, Specifies the file from which to read the record. 





RECORDLOCKL Parameters 

RECORDLOCKL 1-665


Examples 

In the following example, the program statement sets a shared lock on the record 

HOLLY in the default file. If the record is already locked by another user, the 

program waits until the record is released. 

RECORDLOCKL "HOLLY" 

In the next example, the program segment sets a lock on the record with the ID Smith 

from file CLIENT.FILE. If the record is locked, UniData displays the message “THE 

RECORD IS ALREADY LOCKED”. 


record.ID.expr Specifies a record to lock. 

ON ERROR 

statements 

RECORDLOCKL CLIENT.FILE,"Smith" 

LOCKED PRINT "THE RECORD IS ALREADY LOCKED" 



Specifies statements to execute if the RECORDLOCKL 

statement fails with a fatal error because the file is not open, an 

I/O error occurs, or UniData cannot find the file. 



LOCKED statements Specifies statements to execute if another user has an exclusive 

lock on the record. If you do not specify a LOCKED clause, the 




the record. 

RECORDLOCKL Parameters (continued) 

FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKU, RELEASE

UniData 



RECORDLOCKL 1-667

RECORDLOCKU 

Syntax 

RECORDLOCKU [file.var,] record.ID.expr [ON ERROR statements] 

[LOCKED statements] 

Description 

The UniBasic RECORDLOCKU command checks for record locks. If the record is 

available, it sets an exclusive lock on the record. For an explanation of UniData locks, 

and for a sample program that you can use to test this command, see Developing 


Parameters 




file.var, Specifies the file from which to read the record. 





RECORDLOCKU Parameters


record.ID.expr Specifies a record to lock. 

ON ERROR 

statements 



FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKL, RELEASE 

UniData 

Specifies statements to execute if the RECORDLOCKU 

statement fails with a fatal error because the file is not open, an 

I/O error occurs, or UniData cannot find the file. 








the record. 

RECORDLOCKU Parameters (continued) 

DEFAULT.LOCKED.ACTION – For information, see UniData Commands 


RECORDLOCKU 1-669

RELEASE 

Syntax 

RELEASE [file.var [, record.ID.expr]] [ON ERROR statements] 

Description 

The UniBasic RELEASE command unlocks records and files locked by the same 

user process. If no files or records are locked, RELEASE has no effect. 

Tip: UniBasic locks are advisory only. For more information, see Developing 


Parameters 




file.var Specifies a file to unlock. If you do not specify a file or a record, 

UniData releases all locks set by the same user process. 

,record.ID.expr Specifies a record ID to unlock. If you do not specify a record 

with record.ID.expr, UniData releases all locked records within 

the file. 

ON ERROR statements Specifies statements to execute if the RELEASE statement fails 

with a fatal error because the file is not open, an I/O error 




RELEASE Parameters

Examples 


“Sample Program,” of Developing UniBasic Applications. In this program, the 

WRITE statement unlocks records so that locks are retained only as long as required. 

However, some error conditions could result in processing returning to the main 

routine with a record still locked. For this reason, the program segment includes a 

RELEASE statement. 

*-------------- Main Logic ----------------------------- 

GOSUB INITIALIZE 

LOOP 

GOSUB DISPLAY_SCREEN 

GOSUB GET_ORDER_NUMBER 

UNTIL ORDER_NUMBER[1,1] = 'Q' 

GOSUB DISPLAY_DATA 

IF RECORD_FOUND THEN GOSUB GET_RECORD_COMMAND 

RELEASE 

REPEAT 

GOSUB EXIT 

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" 



FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKL, 

RECORDLOCKU 

RELEASE 1-671

ReleaseXML 

Syntax 

ReleaseXML(XMLhandle) 



Description 

Release the dynamic array variable using the ReleaseXML function. 

ReleaseXML destroys the internal DOM tree and releases the associated memory. 

Parameter 

The following table describes the parameter of the syntax. 



XMLhandle The XML handle created by the PrepareXML function. 

ReleaseXML Parameter

REM 

Syntax 

REM [comment text] 

Synonyms 

!, * 

Note: REM is also a synonym for the MOD function. For more information, see 

MOD. 

Description 

The UniBasic REM command enables you to enter remarks in a program. You can 

enter the comment on a line by itself by entering the comment command followed by 

text. You also can enter a comment on a line that contains another UniBasic command 

by preceding the comment command with a semicolon. 

Tip: In structured programming, a single command is entered on each line. This 

makes programs easier to read and maintain. 

REM 1-673

Example 

In the following example, comments describe the subroutine’s functionality. The 

program uses !, *, and REM. 


! 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.

REMOVE 

Syntax 

REMOVE var FROM dyn.var [AT col.pos] SETTING delim.var 

Description 

The UniBasic REMOVE command extracts an element from a dynamic array and 

assigns the removed element to a variable. REMOVE does not change the value of 

the dynamic array. REMOVE supports multibyte languages. 

REMOVE searches a dynamic array for system delimiters. When UniData finds a 

delimiter, it assigns the contents of the array element and the delimiter to the variable. 

UniData maintains a pointer to the last substring you remove so that successive 

REMOVE statements move progressively through a dynamic array. 

Tip: Use REMOVE to sequentially process the elements of a dynamic array. 

Parameters 



var Specifies the element to contain the extracted array element. 

REMOVE Parameters 

REMOVE 1-675


The SETTING clause assigns the variable delim.var a value based on the type of 

delimiter encountered. The following table describes the values of the delimiter 

codes. 

*ASCII value is language-dependent and can be reassigned. 


FROM dyn.var Specifies a dynamic array from which to remove elements. 

AT col.pos Specifies the position in the array at which to start removing 

elements. 

This position is the number of characters, including system 

delimiters, from the beginning of the array. To process the entire 

array, set col.pos to 1 (0 defaults to 1). The value of col.pos 

changes as the array is processed, indicating the current position 

of the pointer. 

SETTING delim.var Specifies the delimiter code. When the end of the array is 

encountered, delim.var is set to 0. 

REMOVE Parameters (continued) 

Delimiete 

r Code Description ASCII Value* 

0 array end 

1 record mark 255 

2 attribute mark 254 

3 value mark 253 

4 subvalue mark 252 

5 text mark 251 

6 not used; nonprinting 250 

7 not used; nonprinting 249 

REMOVE Delimiter Codes

Examples 

In the following example, the program segment processes the dynamic array 

CLIENT: 

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, VAR contains the following: 

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) = 0 

Notice that each element in the array VAR contains the extracted array element and 

the associated delimiter. 

In the next example, the program segment starts at the beginning of the array 

AMOUNTS, successively removes each element from the array, calculates a 3.5 

percent tax amount, and adds it into the variable TAX.AMT. When MARK = 0 

(delim.var is 0), processing terminates. 

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 

UniBasic 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 

In UniBasic, the result is the following: 

AB 4 2 

CD 7 2 

EF 9 0 

REMOVE 1-677

In some implementations, the values are different: 

AB 3 2 

CD 6 2 

EF 8 2 

In the next example, the program segment compares processing time for the 

REMOVE statement versus the EXTRACT statement: 


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 += 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 


Bigtest in file VOC: 6000 lines, 59999 bytes. 

Processing time: 

EXTRACT: 00:07:26 

REMOVE: 00:00:03



DEL, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS 

REMOVE 1-679

REMOVE 

Syntax 

REMOVE(dyn.array.var, delim.var) 

Description 

The UniBasic REMOVE function extracts an element from a dynamic array and 

assigns the removed element to a variable. REMOVE does not change the value of 

the dynamic array. 

REMOVE searches a dynamic array for system delimiters. When UniData finds a 

delimiter, it assigns the contents of the array element and the delimiter to the variable. 

UniData maintains a pointer to the last substring you remove so that successive 

REMOVE statements move progressively through a dynamic array. 

The REMOVE function performs the same action as the REMOVE command, but 

you cannot use it to specify a starting position. 

Tip: Use REMOVE to sequentially process the elements of a dynamic array. 

Parameters 




dyn.array.var Specifies a dynamic array from which to remove elements. 

delim.var Specifies the delimiter code. When the end of the array is encountered, 

delim.var is set to 0. 

REMOVE Parameters

The variable delim.var is assigned a value based on the type of delimiter encountered. 

The following table describes the values of the delimiter codes. 

*ASCII value is language-dependent and can be reassigned. 



Delimiter 

Code Description ASCII Value* 

0 array end 

1 record mark 255 

2 attribute mark 254 

3 value mark 253 

4 subvalue mark 252 

5 text mark 251 

6 nonprinting; not used 250 

7 nonprinting; not used 249 

REMOVE Delimiter Codes 

DEL, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS 

REMOVE 1-681

REPLACE 

Syntax 

REPLACE(dyn.array.expr, attrib.expr, val.expr, subval.expr, replace.expr) 

dyn.array.expr = replace.expr 

Description 

The UniBasic REPLACE function replaces data in a dynamic array with an 

expression. 

If an attribute, value, or subvalue is less than 0, the replacement string is placed after 

the last attribute, value, or subvalue as appropriate. If the position given does not exist 

(for example, attribute 6 specified in an array with two attributes), the necessary 

number of attribute, value, and subvalue marks are added to create the specified 

position. 


With null value handling on, when UniBasic encounters the null value in a command 

parameter when a number is expected (attrib.expr, val.expr, subval.expr,), it displays 

a warning message and uses 0. 


Parameters 



dyn.array.expr Specifies the dynamic array to modify. 

attrib.expr Specifies the attribute to replace. The following rules also apply: 

If attrib.expr is a negative number, replace.expr is appended to the 

existing value instead of replacing it. 

If attrib.expr is 0, the preceding level (attribute, value, subvalue) is 

replaced by replace.expr. 

val.expr Specifies the value of the attribute to replace. The following rules also 

apply: 





subval.expr Specifies the subvalue of the value of the attribute to replace. The 

following rules also apply: 





replace.expr Specifies the replacement value. 

REPLACE Parameters 

Examples 

In this example, the program statement replaces the first value of attribute 2 with the 

value ‘220 W. 44TH’: 

CLIENT.REC = REPLACE(CLIENT.REC,4,1,0,'220 W. 44TH') 

REPLACE 1-683

In the next example, the program segment replaces “Blue” with the null value in STG, 

prints STG, then replaces the null value with “Blue” in STG, and prints STG again. 

The subroutine PRINT.SETUP converts attribute marks, value marks, and the null 

value to characters that can be displayed and printed. 


STG = "Movies":@AM:"The Sacrifice":@VM:"Blue":@AM:"Rocky IV" 

STG = REPLACE(STG,2,2,0,@NULL) 


PRINT "STG = ":PRT.STG 

STG = REPLACE(STG,2,2,0,"Blue") 


PRINT "STG = ":PRT.STG 

PRINT.SETUP: 




RETURN 


STG = Movies@AMThe Sacrifice@VM@NULL@AMRocky IV 

STG = Movies@AMThe Sacrifice@VMBlue@AMRocky IV 

In the next example, the first REPLACE places Harry Smith in the first attribute 

position. 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") 


CUST.REC = "Harry 

Smith":@AM::@AM::@AM::@AM:"V220":@VM:"V230" 

In the following example, the program uses the short form of the REPLACE 

command to append CLIENT.NAME to NAME.ARRAY1: 

NAME.ARRAY1 = "Smith Jones Brown" 


READV CLIENT.NAME FROM CLIENT.FILE,"10034",2 THEN 

NAME.ARRAY1 = CLIENT.NAME 

PRINT NAME.ARRAY1 

END ELSE 

PRINT 'NO RECORD FOR CLIENT ':CLIENT.ID 

END



DEL, DELETE, EXTRACT, INSERT, REMOVE, REPLACE 

REPLACE 1-685

RESIZET 

Syntax 

RESIZET [UNIT(mu.expr)] expr {THEN statements [END] | ELSE statements 

[END]} 

Description 

The UniBasic RESIZET command changes the block size the WRITET command 

uses. When UniData processes a variable length record, the record length is less than 

the block length and UniData fills the remaining portion of the block with blanks. 

Tip: Use this command when the block size in a file is not the same as the block size 

in T.ATT. 

Parameters 



Paragraph Description 

UNIT(mu.expr) Specifies the conversion code and unit number. The mu.expr is 

optional. The default value is UNIT (00) for tape unit 0 with no 

conversion (ASCII assumed). 

0 – No conversion (ASCII assumed). 

1 – EBCDIC conversion. 

2 – Invert high bit. 

3 – Swap bytes. 

expr Specifies the block size to which to resize. 

THEN statements END THEN executes if the resize is successful. END is required to 


ELSE statements END ELSE executes if the resize is not successful. END is required to 

terminate multiline ELSE statements. 

RESIZET Parameters

Example 

In the following example, the program segment changes the block size the WRITET 

statement uses for the length of REC: 

RESIZET LEN(REC) ELSE PRINT 'RESIZET ERROR' 

WRITET REC ELSE PRINT 'WRITET ERROR' 



READT, REWIND, WRITET 

UniData 

SETTAPE, T.ATT, T.DET – For information, see the UniData Commands Reference. 

RESIZET 1-687

RETURN 

Syntax 

RETURN [TO label[:]] 

Description 

The UniBasic RETURN command transfers program control from a subroutine back 

to the calling program or subroutine. 

The optional TO clause returns to a statement label. This clause is valid only for 

internal subroutine returns. If you do not specify a TO clause, control passes to the 

statement immediately following the GOSUB or CALL statement in the calling 

program or subroutine. 

Example 

The following externally cataloged subroutine is called by the sample program in 

Appendix A, “Sample Program,” of Developing UniBasic Applications. The 

RETURN statement returns control to UPDATE_ORDERS. 


SUBROUTINE DISPLAY_MESSAGE(MESSAGE) 

DISPLAY @(5,20):MESSAGE 

DISPLAY @(5,21):"Press the (Return) key.": 

INPUT PAUSE,1_ 

RETURN 



CALL, GOSUB, ON/GOSUB

REUSE 

Syntax 

REUSE(dyn.array.expr) 

Description 

The UniBasic REUSE function affects the application of arithmetic operations on 

dynamic arrays. 

When REUSE Is Not Used 

When you execute an arithmetic operation on an array and you do not include the 

REUSE function, one of the following happens: 

Array and constant – When you apply an arithmetic operation to an array 

and a constant, the operation is executed against only the first element of the 

array. If you want the operation to execute on every element in the array, 

apply REUSE to the constant. 

Two arrays – When you execute an arithmetic operation on arrays of 

different lengths, the operation is performed on the number of elements in 

the shortest array only. The remaining elements are each filled with 1 or 0, 

depending on the operation performed: 

Division – 1. 

Addition, subtraction, and multiplication – 0. 

If you apply REUSE to the shorter array, the last element in this array is used 

to perform the operation on the remaining elements in the longer array. 

REUSE 1-689

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 


VCOST = 4000:@VM:200:@VM:0 

VCOST takes its length from VIEWERS, the longest of the two arrays, but multiplication 

is performed on only the first two elements of each array because the other 

array, COST, has only two elements. The final element in the result array (VCOST) 

is filled with 0. 0 is used to fill because the arithmetic operation is multiplication. 

However, if you apply the REUSE function to the shorter array: 

VCOST = VIEWERS*REUSE(COST) 


VCOST = 4000:@VM:200:@VM:300 

The final element in COST (1) is used to multiply with the final element of 

VIEWERS and fill the final element of the result array, VCOST.

REWIND 

Syntax 

REWIND [UNIT(mu.expr)] {THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic REWIND command rewinds a tape. 

Note: Before you can use the REWIND command, you must reserve a tape drive for 

use with the T.ATT command. For information about ECL T.ATT, see the UniData 


Parameters 



UNIT(mu.expr) Specifies the conversion code (first digit), and the unit number 


The mu.expr is optional and the default value is UNIT (00) for 

tape unit 0 with no conversion (ASCII assumed). 





THEN statements END THEN executes if the rewind is successful. END is required to 


ELSE statements END ELSE executes if the rewind is not successful. END is required 

to terminate multiline ELSE statements. 

REWIND Parameters 

REWIND 1-691

Example 

In the following example, the program segment first uses the ECL T.ATT command 

to reserve tape unit 0 and specifies no conversion code. Then a routine reads all the 

records on the tape (until the end of the file or 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' 



READT, RESIZET, WRITET 

UniData 


RND 

Syntax 

RND(num.expr) 

Description 

The UniBasic RND function returns a random integer from 0 through 

num.expr minus 1. 

Example 

In the following example, the program statement prints a random number from 0 

through 9: 

PRINT RND(10) 



RNDSEED 

RND 1-693

RNDSEED 

Syntax 

RNDSEED expr 

Description 

The UniBasic RNDSEED command enables 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 program with the same seed. 

expr is a numeric seed point. Each time you use the same expr, RND generates the 

same sequence of random numbers. 

Example 

In the following program segment, RND produces an array of random numbers to 

replace the values in VCOST. Because RNDSEEN is a constant, this program always 

produces the same series of random numbers. Without this statement, the program 

produces a different set of random numbers each time it is run. 


RNDSEED 234 

VCOST = 100:@VM:200:@VM:0@VM:100:@VM:200:@VM:300 

VCOST = RND(VCOST) 

PRINT VCOST 



RND

RQM 

RQM is a synonym for the SLEEP function. For more information, see SLEEP. 

Synonym 

SLEEP 

RQM 1-695

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 can be any valid 

numbers or string numbers of any magnitude or precision. 

Tip: Processing string data type numbers rather than numeric data type numbers 

degrades processing speed. Numbers specified in quotation marks are string data 

type. Numbers specified without quotation marks are numeric data type. The data 

type in a variable is determined by the data first loaded into it. 

If x or y contains nonnumeric data, UniData 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. Because string numbers can exceed the 

range of numbers that standard arithmetic operators can accommodate, you might not 

want to use the SADD function in any expression in which a standard number is 

valid. 

Note: The result of the SADD function cannot exceed the maximum allowable 

number determined by your hardware. 

Example 

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) 


saveSecurityContext 

Syntax 

saveSecurityContext(context, name, passPhrase) 



Description 

The saveSecurityContext() function encrypts and saves a security context to a 

system security file. UniData maintains this file on a per account basis for. and uses 

the name as the record ID to access the saved security information. Since the information 

is encrypted, you should not attempt to directly manipulate the information. 

You may want your application to a security context to be used later. You can create 

multiple contexts to suit different needs. For example, you may want to use different 

protocols to talk to different servers. These contexts can be saved and reused. 

When creating a saved context, you must provide both a name and a passPhrase to 

use to encrypt the contents of the context. You must provide the name and passPhrase 

to load the saved context back. To ensure a high level of security, we recommend that 

the passPhrase be relatively long, yet easy to remember. 

Parameters 



context The Security context handle. 

name String containing the file name of the saved context. 

passPhrase String containing the password to encrypt the context contents. 

saveSecurityContext Parameters 

saveSecurityContext 1-697


Return 

Code Status 

0 Success. 



2 Invalid parameters (empty name or passPhrase). 

3 Context could not be saved. 

Return Code Status

SCMP 

Syntax 

SCMP(x, y) 

Description 

The UniBasic SCMP function compares two string numbers and returns a value 

depending on the result of the comparison. Arguments can be any valid numbers or 

string numbers of any magnitude or precision. If x or y contains nonnumeric data, 

UniData displays an error message, and the comparison returns 0. 

SCMP Function Return Values 

The SCMP function returns one of the values described in the following table. 

Comparison 

x < y -1 

x = y 0 

x > y 1 

Returning 

Value 

SCMP Function Return Values 

Tip: Processing string data-type numbers rather than numeric data-type numbers 



type in a variable is determined by the data first loaded into it. 

SCMP 1-699

Example 

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), UniData executes the PRINT 

statement. 


IF SCMP(FA,FB) GT 0 THEN 

PRINT FA:" IS GREATER THAN ":FB

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 can be any valid numbers or string 

numbers of any magnitude or precision. However, result precision is limited to 14 

significant digits. 




type of a variable is determined by the data first loaded into it. 

If x or y contains nonnumeric data, UniData displays an error message, and the 

operation results in 0. If y is 0, UniData displays an error message that indicates you 

cannot divide by 0 and returns a result of 0. 

The SDIV function results in a string number, so you can use the function in any 

expression in which a string is required. Because the resulting string numbers can be 

longer than the arithmetic operator can accommodate, you might not want to use the 

SDIV function in expressions requiring numeric data type. 

Example 

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) 

SDIV 1-701

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 an active select list of all record IDs in a 

file. Records appear in the list in the order in which they are stored in the file. 

You can access the select list with a READNEXT statement. 

The UniBasic SELECT command differs from EXECUTE "SELECT ...", which 

executes the UniQuery SELECT command. The UniBasic SELECT command 

immediately makes available to READNEXT one group of IDs at a time. The 

program does not have to wait for the entire ID list to be constructed. 

If changes occur in a group that has not been selected yet, those changes are reflected 

in the select list that is being read by the program. If an ID is deleted before the group 

is selected by the UniBasic program, that ID does not appear in the list. 

Record IDs are truncated at 96 characters when they are copied into the select list. 

When using the UniQuery 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. 

Note: You can specify named or numbered lists (using list.num.expr or list.var.expr) 

in BASICTYPEs R and U. Only named lists (list.var.expr) are supported in 

BASICTYPEs M and P. 


Parameters 



file.var Specifies a file variable from which to read record IDs. 

If you do not specify a file.var, UniData reads from the default file. If 

no default file is open, a fatal error occurs. 

The default file is one for which no file variable is assigned in the 


dyn.array Specifies a dynamic array from which to select a list of attributes. 

TO list.num.expr Supported in BASICTYPEs R and U only. Specifies a numbered 

select list, 0–9, to contain record IDs. If you do not specify a list, 

SELECT creates list 0. 

TO list.var.expr Supported in all BASICTYPEs. Specifies a named select list to 

contain record IDs. 

Initialize list.var.expr with a statement like 

list.name = '' 

before using it in the SELECT statement to avoid a compiler warning 

for an uninitialized variable. 

ON ERROR 

statements 

Specifies statements to execute if the SELECT statement fails with a 





SELECT Parameters 

SELECT 1-703

Examples 

The following program segment places in select list 1 all record IDs in the CLIENTS 

file, and then prints the ID of the first record: 


OPEN 'CLIENTS' TO CLIENT ON ERROR PRINT "File open error." THEN 

PRINT "OPEN" 

SELECT CLIENT TO 1 

READNEXT var FROM 1 ON ERROR PRINT "Error in READNEXT." THEN 

PRINT var 

END ELSE 

PRINT "Record not found." 

END 

The following sample program creates a select list that is named rather than 

numbered. This program is compiled in BASICTYPE P, but compiles and runs in all 

BASICTYPEs. 


list = '' 

OPEN 'INVENTORY' TO INV_FILE ELSE PRINT "OPEN error" 

SELECT INV_FILE TO list 

FOR X = 1 TO 10 

READNEXT ID FROM list ELSE 

PRINT "No more IDs in list" 

END 

READU REC FROM INV_FILE,ID THEN 

PRINT "Record ":X:" is ":REC:" ":REC 

END ELSE 

PRINT "Record not found." 

END 

NEXT X 

END 

Here is the output for this program: 

Record 1 is 10105 Memory 

Record 2 is 10076 Telephone 

Record 3 is 10020 Adapter 

Record 4 is 10086 Modem 

Record 5 is 10092 Adapter 

Record 6 is 10073 Monitor 

Record 7 is 10041 Computer 


Record 9 is 10103 Telephone 


In the following example, the program statement creates a list of all record IDs in the 

INVENTORY file in active select list 0: 

SELECT INVENTORY

In the next example, the program segment first creates a list of all IDs in the 

ORDERS file and assigns the ID list to list 1. It then uses the READNEXT command 

to read the IDs from the list sequentially, executing a subroutine, 

PROCESS.ORDERS, each time. 

SELECT ORDERS TO 1 

LOOP 

READNEXT ORDER.ID FROM 1 ELSE TAPE.ID = " " 

WHILE ORDER.ID 

GOSUB PROCESS.ORDERS 

REPEAT 



DELETELIST, FORMLIST, READLIST, SELECTINDEX, SELECTINFO, 

WRITELIST 

UniQuery 



UniData SQL 


SELECT 1-705

SELECTINDEX 

Syntax 

SELECTINDEX index.name.expr[, key.val.expr] FROM file.var [TO list.num.expr] 

Description 

The UniBasic SELECTINDEX command creates a select list based on an alternate 

key index. 

Note: SELECTINDEX is not supported with EDA files. 

Parameters 




index.name.expr Specifies an alternate key index from which to select all key 

values 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


After you execute SELECTINDEX, the STATUS function returns one of the values 



0 The select list is loaded with alternate key values or record IDs for the specified 

file. 

1 No alternate index key exists for this attribute using the name specified. The select 

list is empty. 


Examples 

The following program creates a select list based on alternate index LNAME, and 

then reads the record using the first ID retrieved from that list: 


SELECTINDEX 'LNAME' FROM CLIENT.FILE TO 2 

PRINT @(-1) 

READNEXT ID FROM 2 THEN 



END ELSE 


END 

CLEARSELECT 

END 

In the following example, SELECTINDEX uses the alternate key index LNAME and 

creates a list of all the last names contained in the CLIENTS file: 

SELECTINDEX "LNAME" FROM CLIENTS 

In the next example, SELECTINDEX uses the alternate key value “Smith” and 

creates a list of all occurrences of Smith contained in the CLIENTS file: 

SELECTINDEX "LNAME","Smith" FROM CLIENTS 

SELECTINDEX 1-707



DELETELIST, FORMLIST, INDICES, READLIST, SELECT, SELECTINFO, 

SETINDEX, WRITELIST 

UniQuery 



UniData SQL 



SELECTINFO 

Syntax 

SELECTINFO([list.num.expr,] 1) 

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). 

Parameters 



list.num.expr The select list number (0-9). 

1 The only code.expr currently implemented is 1, which returns the values 


SELECTINFO Parameters 

SELECTINFO Function Return Values 

The SELECTINFO function returns one of the values described in the following 

table. 


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 Function Return Values 

SELECTINFO 1-709



DELETELIST, FORMLIST, READLIST, SELECT, SELECTINDEX, WRITELIST 

UniQuery 



UniData SQL 



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. 

Parameters 



X Directs UniData to convert expr from an exploded ASCII hexadecimal 

representation string to its binary equivalent, and then transmit it on the 

specified line. The conversion process ends when UniData reads the first 

nonhexadecimal character. 

expr:expr2... A string that contains data formatting expressions. You can specify more 

than one string to send. 

: Suppresses the sending of a terminating carriage return and line feed. 

TO line.expr Specifies a line number. line.expr must be valid or an error message 

displays and the user enters the UniBasic debugger. 

If the line is attached, the process has exclusive use of it. If the line is not 

attached, UniData performs the ELSE clause. 

THEN 

statements 

END 

ELSE 

statements 

END 

THEN executes if the SEND is successful. END is required to terminate 

multiline statements. 

ELSE executes if the SEND is not successful. END is required to 

terminate multiline statements. 

SEND Parameters 

SEND 1-711

Note: SEND with the X option suppresses the output of return/line feed. However, you 

cannot include both quotation marks and the colon (‘:’) in the same statement. 

Examples 

In the following example, the program statement sends the string to line 0 unless line 

0 is not attached. If line 0 is not attached, UniData 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 0: 

TESTVAR = "48454C404F WORLD" 

SENDX TESTVAR TO 0 ELSE PRINT "Line not attached" 



GET 

UniData 

PROTOCOL – For information, see the UniData Commands Reference.

SEQ 

Syntax 

SEQ("char.expr") 

Description 

The UniBasic SEQ function converts a single character to its ASCII code value. The 

SEQ function is the complement of the CHAR function. SEQ supports multibyte 

languages. 

Tip: Use SEQ(@NULL) to determine the ASCII code that represents the null value 

on your system. 

Example 

In the following example, the program statement prints the ASCII code 

corresponding to the character “#” (in this case, 35): 

PRINT SEQ("#") 



ASCII, CHAR, CHARS, EBCDIC 

SEQ 1-713

SEQS 

Syntax 

SEQS("char.expr") 

Description 

The UniBasic SEQS function converts the first character in each element of a 

dynamic array to its ASCII code value. SEQS supports multibyte languages. 

Example 

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) 



ASCII, CHAR, CHARS, EBCDIC, SEQ

setAuthenticationDepth 

Syntax 

setAuthenticationDepth(context, depth, serverOrClient) 



Description 

The setAuthenticationDepth() function sets how deeply UniData should verify 

before deciding that a certificate is not valid. 

You can use this function to set both server authentication and client certification, 

determined by the value in serverOrClient parameter. The default depth for both is 1. 

The depth is the maximum number of intermediate issuer certificate, or CA certificates 

which must be examined while verifying an incoming certificate. Specifically, 

a depth of 0 means that the certificate must be self-signed. A default depth of 1 means 

that the incoming certificate can be either self-signed, or signed by a CA which is 

known to the context. 

Parameters 




depth Numeric value for verification depth. 

serverOrClient 1 - Server 

2 - Client 

setAuthenticationDepth Parameters 

setAuthenticationDepth 1-715


Return 

Code Status 

0 Success. 



2 Invalid depth (must be greater than or equal to 0). 

3 Invalid value for serverOrClient (must be 1 or 2) 

Return Code Status

setCipherSuite 

Syntax 

setCipherSuite(context,cipherSpecs) 



Description 

The setCipherSuite() function enables you to identify which cipher suites to support 

for the specified context. It affects the cipher suites and public key algorithms 

supported during the SSL/TLS handshake and subsequent data exchanges. 

When a context is created, its cipher suites will all be set to SSLv3 suites by default. 

The CipherSpecs parameter is a string containing cipher-spec separated by colons. 

An SSL cipher specification in cipher-spec is composed of 4 major attributes as well 

as several, less significant attributes. These are defined below. 

Some of this information on ciphers is excerpted from the mod_ssl open source 

package of the Apache web server. 

Key Exchange Algorithm - RSA or Diffie-Hellman variants. 

Authentication Algorithm - RSA, Diffie-Hellman, DSS or none. 

Cipher/Encryption Algorithm - DES, Triple-DES, RC4, RC2, or none. 

MAC Digest Algorithm - MD5, SHA or SHA1. 

An SSL cipher can also be an export cipher and is either an SSLv2 or SSLv3/TLSv1 

cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, one can 

either specify all the ciphers, one at a time, or use aliases to specify the preference 

and order for the ciphers. 

For detailed information about cipher algorithms, see UniBasic Extensions. 

setCipherSuite 1-717

Parameters 






CipherSpecs String containing cipher suite specification described above. 

setCipherSuite Parameters 

Return 

Code Status 

0 Success. 


2 Invalid cipher suite specification. 

setCipherSuite Return Codes

setClientAuthentication 

Syntax 

setClientAuthentication(context,option) 



Description 

The setClientAuthentication() function turns client authentication for a server 

socket on or off. 

When option is set to on, during the initial SSL handshake, the server sends a client 

authentication request to the client. It will also receive the client certificate and 

perform authentication according to the issuer’s certificate (or certificate chain) set 

in the security context. 

Parameters 




option 1 - ON 

2 - OFF 

setClientAuthentication Parameters 

setClientAuthentication 1-719



Return 

Code Status 

0 Success. 


Return Code Status

SETENV 

Syntax 

SETENV(var_name, value) 

Description 

Use the SETENV function to set an environment variable from UniBasic. 

Parameters 



var_name The name of the environment variable. 

value The value of the environment variable. 

SETENV Parameters 

Return Codes 

The following table describes the SETENV return codes. 

Return Code Description 

0 Setting the environment variable was successful. 

-1 Setting the environment variable was not successful. 

SETENV Return Codes 

SETENV 1-721

setHTTPDefault 

Syntax 

setHTTPDefault(option, value) 



Description 

The setHTTPDefault function configures the default HTTP settings, including 

proxy server and port, buffer size, authentication credential, HTTP version, and 

request header values. UniBasic uses these settings with every HTTP request that 

follows. 

If you require all outgoing network traffic to go through a proxy server, you should 

call setHTTPDefault() with value containing the proxy server name or IP address as 

well as the port (if other than the default of 80). 

Parameters 




option A string containing an option name. See the table below for the options 

currently defined. 

value A string containing the appropriate option value. 

setHTTPDefault Parameters

The following table describes the available options for setHTTPDefault. 


PROXY_NAME Name or IP address of the proxy server. 

PROXY_PORT The port number to be used on the proxy server. This only needs 

to be specified if the port is other than the default of 80. 

VERSION The version of HTTP to be used. The default version is 1.0, but 

it can be set to 1.1 for web servers that understand the newer 

protocol. The string should be ”1.0” or “1.1”. 

BUFSIZE The size of the buffer for HTTP data transfer between UniData 

and the web server. The default is 4096 however, the buffer size 

can be increased to improve performance. It should be entered 

as an integer greater than or equal to 4096. 

AUTHENTICATE The user name and password to gain access. The string should 

be “user-name:password”. Default Basic authentication can 

also be set. If a request is denied (HTTP staus 401/407), 

UniBasic will search for the default credential to automatically 

re-submit the request. 

HEADERS The header to be sent with the HTTP request. If default_headers 

contains an empty string, then any current user-specified default 

header will be cleared. Currently, the only default header 

UniBasic sets automatically is “User-Agent” UniData 6.0.” If 

you do not want to send out this header you should overwrite it 

with setHTTPDefault(). Per RFC 2616, for “net politeness,”an 

HTTP client should always send out this header. UniBasic will 

also send a date/time stamp with every HTTP request. 

According to RFC 2616, the stamp will represent time in 

Universal Time (UT) format. A header should be entered as a 

dynamic array in the form of 

@VM@Fm@VM. 

setHTTPDefault Options 

setHTTPDefault 1-723


Note: All defaults set by setHTTPDefault() will be in effect until the end of the 

current UniData session. If you do not want the setting to affect subsequent 

programs, you will need to clear it before exiting the current program. If the user 

wishes to set the “Authorization” or “Proxy-Authorization” header as defualts, see 

the description under setRequestHeader(). To clear the default settings, pass an 

empty string with PROXY_NAME, AUTHENTICATE and HEADERS, and 0 for 

PROXY_PORT and BUFSIZE. 



0 Success. 

1 Invalid option. 

2 Invalid Value. 

setHTTPDefault Return Codes

SETINDEX 

Syntax 

SETINDEX index.name.expr [, [rop] key.val.expr [, id.expr]] [ON file.var] 

[BUFFER.KEYS {ON | OFF}] [VALIDATE.KEY {ON | OFF}] 

Description 

The UniBasic SETINDEX command sets a pointer to a key in an alternate key index. 

Note: The FILEINFO function, specifically FILEINFO(file.var,21), returns the 

current alternate key value. 

UniBasic maintains index.name.expr for READBCK or READFWD, and related 

statements. Normally, you should use the following relational (rop) operators: 

Before READBCK statements: LT, LE, LAST_ALT_KEY 

Before READFWD statements: GT, GE, EQ, FIRST_ALT_KEY, 

NULLVAL_ALT_KEY 

Note: You can point to only one alternate index at a time. Each time you use 

SETINDEX, the current value is reset and the subsequent READFWD/READBCK 

statement reads the record associated with the newly selected index. 

SETINDEX 1-725

Parameters 




index.name.expr Specifies the alternate key index to use in subsequent 

READFWD/READBCK statements. 

rop One of several valid operators (see the following table). The default 

rop operator is EQ. 

, key.val.expr Specifies the key value to initialize. If you do not specify this value, 

UniData sets the internal pointer to the first key value in the index. 

If you specify FIRST_ALT_KEY, LAST_ALT_KEY, or 

NULLVAL_ALT_KEY as rop, you cannot specify key.val.expr. 

, id.expr Specifies the @ID associated with the key value to position the 

pointer in the index. 

When the id.expr entered does not exist, SETINDEX sets the 

position to the key value following the expected location of id.expr. 

ON file.var Specifies the file to act on. 

BUFFER.KEYS 

ON | OFF 

VALIDATE.KEY 

ON | OFF 

Directs READFWD/READBCK to use or not use a buffering 

mechanism. 

ON improves performance, but you could miss some newly added 

key values. 

OFF (the default) slows performance, but you will not miss any key 

values added after the one you just read. 

Directs READFWD/READBCK to validate or not validate the key 

value just read against what is in the tuple. Because reading a key 

value and its tuple is not an atomic action, a tuple could be deleted 

after it is read. ON prevents this, but could degrade performance. 

SETINDEX Parameters

op Operators 

The following table describes the valid rop operators. 

Operator Resulting Current Alternate Key Value 

EQ First value equal to the specified value (default). 

GT First value greater than that specified. 

GE First value greater than or equal to that specified. 

LT Last value less than that specified. 

LE Last value less than or equal to that specified. 

FIRST_ALT_KEY First non-null alternate key value. Keys that are an empty string 

are sorted before keys containing values. If you specify 

FIRST_ALT_KEY as rop, you cannot specify key.val.expr. 

LAST_ALT_KEY Last alternate key value. If you specify LAST_ALT_KEY as 

rop, you cannot specify key.val.expr. 

NULLVAL_ALT_KEY First null alternate key value. Keys that are empty strings are 

sorted after null value keys, followed by keys containing 

values. If you specify NULLVAL_ALT_KEY as rop, you 

cannot specify key.val.expr. 

rop Operators 


After you execute SETINDEX, the STATUS function returns one of the values 


Status 


0 The alternate key specified exists. 

1 Error. 

2 The alternate key specified does not exist. 


SETINDEX 1-727

Examples 

In the following example, the program segment sets the pointer at the first occurrence 

of the data element containing Miller in the alternate index LNAME: 


OPEN 'CLIENTS' TO tmp 

ELSE STOP 

SETINDEX 'LNAME', 'SMITH' ON tmp 

The following series of examples demonstrates the use of SETINDEX to set the 

record pointer to the first null key in the PROD_NAME alternate key index: 

OPEN 'INVENTORY' TO inventory ELSE PRINT "Open error" 

SETINDEX 'PROD_NAME', NULLVAL_ALT_KEY inventory 


READFWD rec FROM inventory THEN 

PRINT rec:", ":rec:", ":rec 

END ELSE NULL 

NEXT X 

STOP 

This program produces the following result when no null values exist in the 

PROD_NAME index: 

:RUN BP set.idx 

10020, Adapter, A/C Adapter for notebook computers 

10086, Adapter, Ethernet LC Card 

10092, Adapter, Workgroup Hub 

10082, CD Player, Portable Model 

10104, CD Player, Personal Model, Bass Boost 

After the null value is inserted into the PROD_NAME attribute for records 10008 and 

56060, this same program produces the following results: 


10015, , Portable, B/W, 6 ppm 

10238, , Super Deluxe Model 



10092, Adapter, Workgroup Hub

The following program demonstrates the use of SETINDEX to set the record pointer 

to the first non-null key in the PROD_NAME alternate key index by specifying rop 

operator FIRST_ALT_KEY: 

OPEN 'INVENTORY' TO inventory ELSE PRINT "Open error" 

SETINDEX 'PROD_NAME', FIRST_ALT_KEY inventory 


READFWD rec FROM inventory THEN 

PRINT rec:", ":rec:", ":rec 

END ELSE NULL 

NEXT X 

STOP 

Next, run this program using the INVENTORY file that you modified to contain null 

values in the PROD_NAME attribute for records 10015 and 10238. The following 

output results. 




10092, Adapter, Workgroup Hub 

10082, CD Player, Portable Model 

10104, CD Player, Personal Model, Bass Boost 

Tip: You would obtain this same output if the INVENTORY file contained no null 

values in PROD_NAME and you specified rop NULLVAL_ALT_KEY. 




READFWDU, READXBCK, READXFWD, SELECTINDEX 

UniData 



SETINDEX 1-729

setPrivateKey 

Syntax 

setPrivateKey(key, format, keyLoc, passPhrase, validate, context) 



Description 

The setPrivateKey() function loads the private key into a security context so that it 

can be used by SSL functions. If the context already had a set private key, it will be 

replaced. 

SSL depends on public key crypto algorithms to perform its functions. A pair of keys 

is needed for each communicating party to transfer data over SSL The public key is 

usually contained in a certificate, signed by a CA, while the private key is kept 

secretly by the user. 

Private key is used to digitally sign a message or encrypt a symmetric secret key to 

be used for data encryption. 

For detailed information about the setPrivateKey function, see UniBasic Extensions. 

Parameters 




Key A string containing either the key or path for a key file. 

Format 1 - PEM (Base64 encoded) format 

2 - DER (ASN.1 binary) format 

KeyLoc 1 - key contained in key string 

2 - key is in a file specified by key 

setPrivateKey Parameters


passPhrase String containing the path phrase required for gaining access to the key. 

It can be empty if the key is not pass phrase protected. THIS IS NOT 

RECOMMENDED! 

Validate 1 - Validate against matching public key 

0 - Will not bother to validate 

Context The security context handle. 


Return 

Code Status 

0 Success 

1 Invalid Security handle 

2 Invalid format 

setPrivateKey Parameters (continued) 

3 Invalid key type 

4 Key file cannot be accessed (non-existent or wrong pass phrase) 

5 Certificate cannot be accessed 

6 Private key does not match public key in certificate 

7 Private key cannot be interpreted 

99 Other errors that prevent private key from being accepted by 

UniData or UniVerse. 

setPrivateKey Return Codes 

setPrivateKey 1-731

setRandomSeed 

Syntax 

setRandomSeed(inFiles, outFile, length, context) 



Description 

The setRandomSeed() function generates a random seed file from a series of source 

files and sets that file as the default seed file for the supplied security context. 

The strength of cryptographic functions depends on the true randomness of the keys. 

This function generates and sets the random seed file used by many of the UniData 

cryptographic functions. By default, UniData uses the .rnd file in your current 

account. You can override the default by calling this function. 

The random seed file is specified by outFile, which is generated based on source files 

specified in inFiles. For Windows platforms, multiple files must be separated by “;” 

(a semi-colon). For Unix platforms, multiple files must be separated by “:” (a colon). 

The length parameter specifies how many bytes of seed data UniData should 

generate. 

If you do not specify a source in the inFiles parameter, the outFile parameter must 

already exist. 

If you do not specify context, the seed file will be used as a global seed file that 

applies to all cryptographic functions. However, a seed file setting in a particular 

security context will always override the global setting. 


Parameters 



inFiles A string containing source file names. 

outFiles A string containing the generated seed file. 

length The number of bytes that should be generated (the default is 1024 if less 

that 1024 is specified). 


setRandomSeed Parameters 


Return 

Code Status 

0 Success. 

1 Invalid parameter(s). 

2 Random file generation error. 

3 Random file set error. 

setRandomSeed Return Codes 

setRandomSeed 1-733

setRequestHeader 

Syntax 

setRequestHeader(request_handle, header_name, header_value) 



Description 

The setRequestHeader function allows the user to set additional headers for a 

request. 

Parameters 





request_handle The handle to the request returned by createRequest(). 

header_name The name of the header. 

header_value The value of the header. 

setRequestHeader Parameters 


0 Success. 


2 Invalid header (Incompatible with method). 

3 Invalid header value. 

setRequetHeader Return Codes

Note: Since a user-defined header or header value can be transferred, it is difficult 

to check the validity of parameters passed to the function. UniBasic currently will 

not perform syntax checking on the parameters, although it will reject setting a 

response header to a request. Refer to RFC 2616 for valid request headers. 

The header set by this function overwrites settings by setHTTPDefault(). 

This function supports Base64 encoding for Basic authentication. If header_name 

contains either “Authorization” or “Proxy-Authorization”, the header_value should 

then contain ASCII text user credential information in the format of 

“userid:password”, as specified by RFC 2617. This function will then encode the 

text based on Base64 encoding. 

Only Basic authentication is supported. Digest authentication may be supported in 

the future. Basic authentication is not safe and is not recommended for use with 

transferring secured data. 

setRequestHeader 1-735

setSocketOptions 

Syntax 

setSocketOptions(socket_handle, options) 



Description 

The setSocketOptions function sets the current value for a socket option associated 

with a socket of any type. 

Parameters 




socket_handle The socket handle from openSocket(), acceptSocket(), or 

initServerSocket(). 

options Dynamic Array containing information about the socket options and 

their current settings. The dynamic array is configured as: 



optName3... 

Where optName is specified by the caller and must be an option name 

string listed below. The first optValue specifies if the option is ON or 

OFF and must be one of two possible values: “1” for ON or “2” for OFF. 

The second optValue is optional and may hold additional data for a 

specific option. Currently, for the “LINGER” option it contains the 

delayed time (in milliseconds)before closing the socket. For all other 

options, it should not be specified as it will be ignored. 

setSocketOptions Parameters

The following table describes the available options (case-sensitive) for 

setSocketOptions. 


DEBUG Enable/disable recording of debug information. 

REUSEADDR Enable/disable the reuse of a location address (default) 

KEEPALIVE Enable/disable keeping connections alive. 

DONTROUTE Enable/disable routing bypass for outgoing messages. 

LINGER Linger on close if data is present. 

BROADCAST Enable/disable permission to transmit broadcast messages. 

OOBINLINE Enable/disable reception of out-of-band data in band. 

SNDBUF Set buffer size for output (default 4KB). 

RCVBUF Set buffer size for input (default 4KB). 

setSocketOptions Options 



0 Success. 


setSocketOptions Return Codes 

setSocketOptions 1-737

showSecurityContext 

Syntax 

showSecurityContext(context,config) 



Description 

The showSecurityContext() function dumps the SSL configuration parameters of a 

security context into a readable format. 

The security context handle must have been returned by a successful execution of 

createSecurityContext() or loadSecurityContext(). 

The configuration information includes: protocol, version, certificate, cipher suite 

used by this connection and start time, and so forth. 

Warning: For security reasons, UniData does not display the privateKey installed 

into the context. Once installed, there is no way for you to extract it. 

Parameters 





config A dynamic array containing the configuration data. 

saveSecurityContext Parameters


Return 

Code Status 

0 Success. 


2 Configuration data could not be obtained. 


showSecurityContext 1-739

SIGNATURE 

Syntax 

SIGNATURE(algorithm, action, data, dataLoc, key, keyLoc, keyFmt, pass, sigIn, 

result) 

Description 

The SIGNATURE() function generates a digital signature or verifies a signature 

using the supplied key. 

The algorithm parameter specifies the digest algorithm used to construct the 

signature. UniData supports the MD5 and SHA1 algorithms. There are four actions 

you can be specify: RSA-Sign, RSA-Verify, DSA-Sign, and DSA-Verify. If you 

choose DSA, you can only specify SHA1 in algorithm. 

The data to be signed or verified against a signature can be supplied either directly in 

data, or read from a file whose names is in data. 

For signing action, you should specify a private key. For verification, a public key is 

usually expected. However, UniData also accepts a private key for verification 

purposes. Key can be either in PEM or DER format. If a private key is password 

protected, the password must be supplied with pass. 

For verification, key can also contain a certificate or name of a certificate file. A 

signature is expected in sigIn. 

For signing action, the generated signature is put into result. 


Parameters 



algorithm The digest algorithm used for signing or verification (must be either 

“MD5” or “SHA1”). 

action 1 - RSA-Sign 

2 - RSA-Verify 

3 - DSA-Sign 

4 - DSA-Verify 

data Data or the name of the file containing the data to be signed or verified. 



key The key or the name of the file containing the key to be used to sign or 

verify. In the case of verification, key can be a certificate string or a file. 

keyLoc 1 - Key is in a string 

2 - Key is in a file 

3 - Key is in a certificate for verification 

keyFmt 1 - PEM 

2 - DER 

pass A string containing the pass phrase for the private key. 

sigIn A string containing a digital signature. 

result A generated signature or a file to store the signature. 

SIGNATURE Parameters 


Return 

Code Status 

0 Success. 

1 Unsupported digest algorithm. 



SIGNATURE 1-741

Return 

Code Status 


3 Message digest cannot be obtained. 

4 Invalid parameters. 

5 Key cannot be read or is in the wrong format / algorithm. 

6 Incorrect Password. 

7 Signature cannot be generated. 

8 Signature cannot be verified. 

Return Code Status (continued)

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. The result is 0.4226. 

X = 25 

SIN.X=SIN(X) 

In the next example, the program statement prints 1.0000, the sine of 90: 

PRINT SIN(90) 


ACOS, ASIN, ATAN, COS, TAN 

SIN 1-743

SLEEP 

Syntax 

SLEEP [hh:mm[:ss]] [seconds] 

Synonym 

RQM 

Description 

The UniBasic SLEEP and RQM commands halt program execution for the time 

specified in seconds, or until the time specified. 

Tip: You can use SLEEP or RQM if you want a processing or reporting program to 

wait until midnight before running to better use system resources. SLEEP is also 

useful when waiting for the release of locked system resources. 

Note: The original purpose of RQM was to release remaining execution time 

reserved for a program, allowing other programs to use the time. If a particular 

program is very computation-intensive, RQM could improve overall system 

performance. 

Parameters 




hh:mm:ss Specifies the time to end sleep in hours, minutes, and (optional) seconds. 

You must surround the time in quotation marks. 

seconds Specifies the number of seconds to sleep. 

SLEEP Parameters

Examples 

In the following example, the program statement halts program execution for 10 

seconds: 

SLEEP 10 

In the next example, the program statement suspends program execution until 11:45 

PM: 

SLEEP “23:45” 

In the next example, the program statement halts program execution for one second: 

SLEEP 

SLEEP 1-745

SMUL 

Syntax 

SMUL(x, y) 

Description 

The UniBasic SMUL function multiplies two string numbers and returns the result 

as a string number. Arguments can be any valid numbers or string numbers of any 

magnitude or precision. Using string numbers rather than standard numbers degrades 

processing speed. 


result of 0. 





The SMUL function results in a string number, so you can use the function in any 



want to use the SMUL function in any expression in which a standard number is 

valid. 

Example 

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) 


SOAPCreateRequest 

Syntax 

SOAPCreateRequest(URL, soapAction, Request) 



Description 

Creates a SOAP request and returns a handle to the request. 

Parameters 



URL A string containing the URL where the web service is located. UniData 

sends the SOAP request to this URL. [IN] 

soapAction A string UniData uses as the SOAPAction HTTP header for this SOAP 

request. [IN] 

Request The returned handle to the SOAP request. This handle can be used in 

subsequent calls to the SOAP API for UniBasic. [OUT] 

SOAPCreateRequest Parameters 

SOAPCreateRequest 1-747

Return Codes 

The return code indicating success or failure. The following table describes the value 

of each return code. 


You can also use the UniBasic STATUS() function to obtain the return status from the 

function. 


0 Function complete successfully. 

1 Invalid URL syntax. 

2 Invalid HTTP method (indicates the POST method is not 

supported by the HTTP server). 

SOAPCreateRequest Return Codes

SOAPCreateSecureRequest 

Syntax 

SOAPCreateSecureRequest(URL, soapAction, Request, security_context) 

Description 

The SOAPCreateSecureRequest function creates a secure SOAP request and 

returns a handle to the request. 

Parameters 



URL A string containing the URL where the web service is located. 

UniVerse sends the SOAP request to this URL. For information 

about the format of the URL, see URL Format. [IN] 

soapAction A string UniVerse uses as the SOAPAction HTTP header for this 

SOAP request. [IN] 

Request The returned handle to the SOAP request. You can use this 

handle can be used in subsequent calls to the SOAP API for 

UniVerse BASIC. [OUT] 

security_context A handle to the security context. 

SOAPCreateSecureRequest Parameters 

URL Format 

The URL you specify must follow the syntax defined in RFS 1738. The general 

format is: 

http://:/path>? 

SOAPCreateSecureRequest 1-749



Note: If the URL you define contains a searchpart, you must define it in its encoded 

format. For example, a space is converted to +, and other nonalphanumeric 

characters are converted to %HH format. 

You do not need to specify the host and path parameters in their encoded formats. 

UniVerse BASIC encodes these parameters prior to communicating with the web 

server. 

Return Code 



You can also use the UniVerse BASIC STATUS() function to obtain the return status 

from the function. 


host Either a name string or an IP address of the host system. 

port The port number to which you want to connect. If you do not specify 

port, UniVerse defaults to 80. Omit the preceding colon if you do not 

specify this parameter. 

path Defines the file you want to retrieve on the web server. If you do not 

specify path, UniVerse defaults to the home page. 

searchpart Use searchpart to send additional information to a web server. 

URL Parameters 


0 Function complete successfully. 

1 Invalid URL syntax. 

2 Invalid HTTP method (indicates the POST method is not supported by the 

HTTP server). 


SOAPCreateSecureRequest Return Codes

Example 

The following code segment illustrates the SOAPCreateSecureRequest function: 

* Create the Request 

Ret = SoapCreateSecureRequest(URL, SoapAction, SoapReq, 

SecurityContext) 

IF Ret 0 THEN 

STOP "Error in SoapCreateSecureRequest: " : Ret 

END 

. 

. 

SOAPCreateSecureRequest 1-751

SOAPGetDefault 

Syntax 

SOAPGetDefault(option, value) 



Description 

Gets default SOAP settings, such as the SOAP version. 

Parameters 




option A string containing an option name. UniData currently only supports the 

VERSION option. [IN] 

value A string returning the option value. [OUT] 

SOAPGetDefault Parameters

Return Codes 



Return 


0 Function completed successfully. 

1 Invalid option (currently, UniData only supports the VERSION 

option). 

SOAPGetDefault Return Codes 


function. 

SOAPGetDefault 1-753

SOAPGetFault 

Syntax 

SOAPGetFault(respData, soapFault) 



Description 

Parses the response data from SOAPSubmitRequest after receiving a SOAP Fault, 

into a dynamic array of SOAP Fault components. 

Parameters 




respData Response data from SOAPSubmitRequest after receiving a SOAP fault. 

[IN] 

soapFault Dynamic array consisting of Fault Code, Fault String, and optional Fault 

Detail, for example: 

@AM@AM@AM 

Fault code values are XML-qualified names, consisting of: 

? VersionMismatch 

? MustUnderstand 

? DTDNotSupported 

? DataEncoding Unknown 

? Sender 

? Receiver 

SOAPGetFault Parameters

Return Codes 





1 Invalid response data, possibly not a valid XML document. 

2 SOAP Fault not found in response data. 

SOAPGetFault Return Codes 


function. 

SOAPGetFault 1-755

SOAPGetResponseHeader 

Syntax 

SOAPGetResponseHeader(Request, headerName, headerValue) 



Description 

Gets a specific response header after issuing a SOAP request. 

Parameters 




Request Handle to the request created with SOAPCreateRequest. [IN] 

headerName The header name whose value is being queried. [IN] 

headerValue The header value, if present in the response, or empty string if not (in 

which case the return status of the function is 2). [OUT] 

SOAPGetResponseHeader Parameters

Return Codes 






2 Header not found in set of response headers. 

SOAPGetResponseHeader Return Codes 


function. 

SOAPGetResponseHeader 1-757

SOAPRequestWrite 

Syntax 

SOAPRequestWrite(Request, reqDoc, docTypeFlag) 



Description 

Outputs the SOAP request in XML format to a string or to a file. 

Parameters 





reqDoc Depending on docTypeFlag, either an output string containing 

the SOAP request content, or a path to a file where the SOAP 

request content will be written. [OUT] 

docTypeFlag A flag indicating whether reqDoc is an output string that is to 

hold the request content, or a path to a file where the SOAP 

request content will be written. 

? 0 – reqDoc is a file where the request content will be written 

upon successul completion. 

? 1 – reqDoc is a string that will hold the request upon 

successful completion. [IN] 

SOAPRequestWrite Parameters

Return Codes 



Return 




2 Unable to open the file named by reqDoc. 

3 Unable to write to the file named by reqDoc. 

SOAPRequestWrite Return Codes 


function. 

SOAPRequestWrite 1-759

SOAPSetDefault 

Syntax 

SOAPSetDefault(option, value) 



Description 

Setup default SOAP settings, such as SOAP version. 

Parameters 




option A string containing an option name. UniData currently only supports the 

“VERSION” option. [IN] 

value A string containing the appropriate option value. For the VERSION 

option, the string should be 1.0, 1.1, or 1.2. [IN] 

SOAPSetDefault Paramreters

Return Codes 



Return 



1 Invalid option (currently, UniData only supports VERSION). 

2 Invalid value. 1.1 assumed. 

SOAPSetDefault Return Codes 


function. 

USAGE NOTES 

The default SOAP version is 1.1. The namespace prefixes "env" and "enc" are 

associated with the SOAP namespace names 

http://schemas.xmlsoap.org/soap/envelope/ and 

http://schemas.xmlsoap.org/soap/encoding/ respectively. The namespace prefixed 

"xsi" and "xsd" are associated with the namespace names 

http://www.w3.org/1999/XMLSchema-instance and 

http://www.w3.org/1999/XMLSchema respectively. 

The SOAP version can be set to 1.2 to support the newer SOAP 1.2 protocol. The 

namespace prefixes "env" and "enc" will be associated with the SOAP namespace 

names "http://www.w3.org/2001/12/soap-envelope" and 

"http://www.w3.org/2001/12/soap-encoding" respectively. The namespace prefixes 

"xsd" and "xsi" will be associated with the namespace names 

"http://www.w3.org/2001/XMLSchema" and 

"http://www.w3.org/2001/XMLSchema-instance" respectively. 

All defaults set by SOAPSetDefault will be in effect until the end of the current 

UniData session. If you do not want the setting to affect subsequent programs, you 

need to clear it before exiting the current program. 

SOAPRequestWrite 1-761

Along with SOAPSetDefault, the CallHTTP function setHTTPDefault may be called 

to set HTTP-specific settings or headers, if the HTTP default settings are not 

sufficient. 


SOAPSetParameters 

Syntax 

SOAPSetParameters(Request, URI, serviceName, value) 



Descripton 

Sets up the SOAP request body, specifying a remote method to call along with the 

method's parameter list. 

Parameters 




namespace A string that is used as the namespace URI for the SOAP call. [IN] 

method The name of the method to be called. [IN] 

paramArray A dynamic array containing the method parameters for the SOAP call. 

Each method parameter consists of the following values: 

? A parameter name 

? A parameter value 

? A parameter type (if type is omitted, xsd:string will be used. 

name, value, and type are separated by @VM. Additional parameters are 

separated by @AM, as shown in the following example: 

@VM@VM@AM@VM@VM...[IN] 

SOAPSetParameters Parameters 

SOAPSetParameters 1-763

Return Codes 




function. 

Usage Notes 

As an example, the following inputs: 

will set the SOAP body as follows: 


Return 


0 Funtion completed successfully. 

1 Invalid request handle was passed to the function. 

SOAPSetParameters Return Codes 

Input Description 

Method “getStockQuote” 

namespace “http://host/#StockQuoteService” 

paramArray “symbol”:@VM:”IBM”:@VM:”xsd:string” 

SOAPSet Parameters Usage Notes 

 

 

IBM 

 

SOAPSetRequestBody 

Syntax 

SOAPSetRequestBody(Request, value) 



Description 

Sets up a SOAP request body directly, as opposed to having it be constructed through 

the SOAPSetParameters function. With this function it also possible to attach 

multiple body blocks to the SOAP request. 

Parameters 




value A dynamic array containing SOAP body blocks, for example: 

@AM... [IN] 

SOAPSetRequestBody Parameters 

SOAPSetRequestBody 1-765

Return Codes 




function. 


Return 




SOAPSetRequestBody Return Codes

SOAPSetRequestContent 

Syntax 

SOAPSetRequestContent(Request, reqDoc, docTypeFlag) 



Description 

Sets the entire SOAP request's content from an input string or from a file. 

Parameters 




reqDoc The input document to be used as the SOAP request content. [IN] 

docTypeFlag A flag indicating whether reqDoc is a string holding the actual content, 

or the path to a file holding the content. 

? 0 – reqDoc is a file holding the request content. 

? 1 – reqDoc is a string holding the request content. 

[IN] 

SOAPSetRequestContent Parameters 

SOAPSetRequestContent 1-767

Return Codes 

The return code indicating success or failure. The following table describes the status 



function. 


Return 




2 Unable to open the file named by reqDoc. 

3 Unable to read the file named by reqDoc. 

SOAPSetRequestContent Return Codes

SOAPSetRequestHeader 

Syntax 

SOAPSetRequestHeader(Request, value) 



Description 

Sets up a SOAP request header. By default, there is no SOAP header. 

Parameters 




value A dynamic array containing SOAP header blocks, for example: 

@AM...[IN] 

SOAPSetRequestHeader Parameters 

Return Codes 



Return 




SOAPSetRequestHeader Return Codes 

SOAPSetRequestHeader 1-769


function. 


SOAPSubmitRequest 

Syntax 

SOAPSubmitRequest(Request, timeout, respHeaders, respData, soapStatus) 



Description 

Submits a request and gets the response. 

Parameters 




timeout Timeout, in milliseconds, to wait for a response. [IN] 

respHeaders Dynamic array of HTTP response headers and their associated values. 

[OUT] 

respData The SOAP response message. [OUT] 

soapStatus Dynamic array containing status code and explanatory text. [OUT] 

SOAPSubmitRequest Parameters 

SOAPSubmitRequest 1-771

Return Codes 




function. 

Usage Notes 

Internally, SOAPSubmitRequest utilizes CallHTTP's submitRequest() to send out the 

SOAP message. The soapStatus variable holds the status from the underlying 

CallHTTP function. If an error occurs on the SOAP server while processing the 

request, soapStatus will indicate an HTTP 500 "Internal Server Error", and respData 

will be a SOAP Fault message indicating the server-side processing error. 





2 Request timed out. 

3 Network error occurred. 

4 Other error occurred. 

SOAPSubmitRequest Return Codes

SORT 

Syntax 

SORT(var) 

Description 

The SORT function enables you to sort a dynamic array. 

The elements in the dynamic array are sorted in ascending order, left-justified. 

UniBasic sorts the dynamic array by the highest system delimiter in the array. 

If the dynamic array contains any attribute marks, the sort is by attribute. 

Values and subvalues remain with the original attribute. 

If the dynamic array contains value marks and no attribute marks, the sort is 

by value. Subvalues are unaffected and remain with the original value. 

If the dynamic array contains subvalue marks and neither attribute marks 

nor value marks, the sort is by subvalue. 

Parameter 



var The name of the dynamic array to sort. 

SORT Parameter 

SORT 1-773

SOUNDEX 

Syntax 

SOUNDEX(expr) 

Description 

The UniBasic SOUNDEX function converts an expression into a phonetic code. This 

function can return unpredictable results with multibyte characters. 

Tip: Use SOUNDEX to compare alphabetic strings, such as names, when an 

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 nonalphabetic 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 with zeros any expression less than 

four characters.

SOUNDEX Phonetic Codes 

The following table displays the phonetic code for each letter that UniData evaluates. 

Examples 

The following table shows SOUNDEX sample output values. 



Code Letters 

1 B F P V 

2 C G J K Q S X Z 

3 D T 

4 L 

5 M N 

6 R 

UniBasic SOUNDEX Phonetic Codes 

Expression SOUNDEX 

STEPHEN S315 

STEVEN S315 

TERMINATE T655 

RRR R600 

SOUNDEX Sample Output Values 

ICONV SOUNDEX (S), OCONV SOUNDEX (S) 

SOUNDEX 1-775

SPACE 

Syntax 

SPACE(expr) 

Description 

The UniBasic SPACE function returns a string containing the specified number of 

spaces. 

Note: Functions can be concatenated within a PRINT statement. 

Example 

In the following example, the program statement prints HI and THERE separated by 

15 spaces: 


PRINT "HI":SPACE(15):"THERE" 


HI THERE 



SPACES

SPACES 

Syntax 

SPACES(dyn.array.expr) 

Description 

The UniBasic SPACES function returns the number of spaces specified in each 

element of the dynamic array dyn.array.expr. 

Example 

In the following example, the program segment prints the number of spaces specified 

in each element of the dynamic array ARR1: 

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 

second element, and so forth. 



SPACE 

SPACES 1-777

SPLICE 

Syntax 

SPLICE(expr1,"expr", expr2) 

Description 

The UniBasic SPLICE function concatenates two strings or arrays and inserts an 

expression between them. 

Parameters 

The following table describes each parameter of the syntax: 


Examples 

In the following example, the program segment concatenates PHONE to NUMBER 

and inserts a dash (-) between the two strings: 


expr1 Specifies the first string or array to concatenate. 

expr Specifies the expression to insert between expr1 and expr2 when concatenating 

them. 

expr2 Specifies the second string or array to concatenate. 

SPLICE s arameter 

PHONE = "555" 

NUMBER = "1234" 

PRINT SPLICE (PHONE,"-",NUMBER) 


555-1234

The following program inserts the null value between PHONE and NUMBER. The 

CALLED subroutine, PRINT.SETUP, converts UniData delimiters and the null value 

to printable characters (this subroutine is printed in the entry for CHANGE in this 

manual). 

PRT.STG='' 

PHONE = "555" 

NUMBER = "1234" 

STG = SPLICE (PHONE,@NULL,NUMBER) 

CALL PRINT.SETUP(STG,PRT.STG) 

PRINT PRT.STG 

END 


555@NULL1234 

In the following example, the program segment concatenates each element of array 

ARR1 to array ARR2 and inserts a plus sign (+) between the two elements: 

ARR1 = 1:@AM:2:@AM:3 

ARR2 = 4:@AM:5:@AM:6 

PRINT SPLICE (ARR1,"+",ARR2) 


1+4}2+5}3+6 



CAT, CATS 

SPLICE 1-779

SQLAllocConnect 

Syntax 

status = SQLAllocConnect (bci.env, connect.env) 



Description 

SQLAllocConnect allocates and initializes a connection environment in a UniData 

BCI environment. 

Use this function to create a connection environment to connect to a particular data 

source. One UniData BCI environment can have several connection environments, 

one for each data source. The function stores the internal representation of the 

connection environment in the connect.env variable. 

Note: Use the connection environment variable only in UniData BCI calls that 

require it. Using it improperly can cause a runtime error and break communication 

with the data source. 

Parameters 




bci.env UniData BCI environment variable returned in an SQLAllocEnv call. 

connect.env Variable that represents the allocated connection environment. 

SQLAllocConnect Parameters

Return Values 

The following table describes return values from the SQLAllocConnect function. 

Return Value Description 

0 SQL.SUCCESS 

−1 SQL.ERROR 

−2 SQL.INVALID.HANDLE 

SQLAllocConnect Return Values 

SQLAllocConnect 1-781

SQLAllocEnv 

Syntax 

status = SQLAllocEnv (bci.env) 



Description 

SQLAllocEnv creates an environment in which to execute UniData BCI calls. 

Use this function to allocate memory for a UniData BCI environment. The function 

stores the address in the bci.env variable. SQLAllocEnv must be the first UniData 

BCI call issued in any application. 

You can allocate more than one UniData BCI environment. 

Note: Use the environment variable only in UniData BCI calls that require it. Using 

it in any other context causes a runtime error or breaks communication with the data 

source. 

Parameters 




bci.env Variable that represents the allocated UniData BCI environment. 

SQLAllocEnv Parameters

Return Values 

The following table describes return values from the SQLAllocEnv function. 


0 SQL.SUCCESS 


SQLAllocEnv Return Values 

SQLAllocEnv 1-783

SQLAllocStmt 

Syntax 

status = SQLAllocStmt (connect.env, statement.env) 



Description 

SQLAllocStmt creates an SQL statement environment in which to execute SQL 

statements. 

Use this function to allocate memory for an SQL statement environment. 

Note: Use the SQL statement environment variable only in UniData BCI calls that 

require it. Using it in any other context causes a runtime error or breaks 

communication with the data source. 

Parameters 




connect.env Connection environment used in SQLAllocConnect and 

SQLConnect calls. If you have not established a connection to the 

data source using connect.env, an error is returned to the application. 

statement.env Variable that represents an SQL statement environment. 

SQLAllocStmt Parameters

Return Values 

The following table describes return values from the SQLAllocStmt function. 


0 SQL.SUCCESS 



SQLAllocStmt Return Values 

SQLAllocStmt 1-785

SQLBindCol 

Syntax 

status = SQLBindCol (statement.env, col#, data.type, column) 



Description 

Use this function to tell UniData BCI where to return the results of an SQLFetch call. 

SQLBindCol defines the name of the variable (column) to contain column results 

retrieved by SQLFetch, and specifies the data conversion (data.type) on the fetched 

data. SQLBindCol has no effect until SQLFetch is used. 

Normally you call SQLBindCol once for each column of data in the result set. When 

SQLFetch is issued, data is moved from the result set at the data source and put into 

the variables specified in the SQLBindCol call, overwriting existing variable 

contents. 

Data is converted from the SQL data type at the data source to the UniBasic data type 

requested by the SQLBindCol call, if possible. If data cannot be converted to 

data.type, an error occurs. 

Values are returned only for bound columns. Unbound columns are ignored and are 

not accessible. For example, if a SELECT command returns three columns, but 

SQLBindCol was called for only two columns, data from the third column is not 

accessible to your program. If you bind more variables than there are columns in the 

result set, an error is returned. If you bind no columns and an SQLFetch is issued, 

the cursor advances to the next row of results. 

You need not use SQLBindCol with SQL statements that do not produce result sets. 


Parameters 



statement.env SQL statement environment of the executed SQL statement. 

col# Column number of result data, starting at 1. This value must be from 1 

to the number of columns returned in an operation. 

data.type BASIC data type into which to convert the incoming data. Possible 

values are the following: 

SQL.B.CHAR – Character string data. 

SQL.B.BINARY – Bit string (raw) data. 

SQL.B.NUMBER – Numeric data (integer or double). 

SQL.B.DEFAULT – SQL data type determines the BASIC data type. 

SQL.B.INTDATE – UniData date in internal format. 

SQL.B.INTTIME – UniData time in internal format. 

column Variable that will contain column results obtained with SQLFetch. 

SQLBindCol Parameters 

Return Values 

The following table describes the return values of the SQLBindCol function. 


0 SQL.SUCCESS 



SQLBindCol Return Values 

SQLBindCol 1-787

SQLBindParameter 

Syntax 

status = SQLBindParameter ( statement.env, mrk#, data.type, sql.type, prec, scale, 

param [ , param.type ] ) 



Description 

SQLBindParameter specifies where to find values for input parameter markers 

when you issue an SQLExecute or SQLExecDirect call. For output parameter 

markers, SQLBindParameter specifies where to find the return value of a called 

procedure. 

Parameter markers are placeholders in SQL statements. Input parameter markers let 

a program send user-defined values with the SQL statement when an SQLExecute 

or SQLExecDirect call is executed repeatedly. Output parameter markers receive 

values returned from a called procedure. The placeholder character is ? (question 

mark). 

SQLBindParameter tells the system where to find the variables to substitute for 

parameter markers in the SQL statement and how to convert the data before sending 

it to the data source. You need to do only one SQLBindParameter for each 

parameter marker in the SQL statement, no matter how many times the statement is 

to be executed. 

For example, consider the following SQL statement: 


INSERT INTO T1 VALUES (?,?,?); 

If you want to load 1000 rows, you need issue only three SQLBindParameter calls, 

one for each question mark.

Normally you specify data.type as SQL.B.BASIC. If you specify sql.type as 

SQL.DATE, however, you can specify data.type as SQL.B.INTDATE; if you specify 

sql.type as SQL.TIME, you can specify data.type as SQL.B.INTTIME. If you specify 

sql.type as SQL.BINARY, SQL.VARBINARY, or SQL.LONGVARBINARY, you 

can specify data.type as SQL.B.BINARY. 

If you use SQL.B.INTDATE, the UniData BCI assumes the program variable holds 

a date in UniData internal date format and uses the DATEFORM conversion string 

to convert the internal date to an external format as required by the data source. To 

set or change the DATEFORM conversion string, see the SQLSetConnectOption 

function. 

If you specify sql.type as SQL.TIME and data.type as SQL.B.INTTIME, UniData 

BCI assumes the program variable holds a time in UniData internal time format and 

does not convert the data. 

SQLBindParameter uses the value of prec only for the following SQL data types: 

SQL.CHAR 

SQL.VARCHAR 

SQL.LONGVARCHAR 

SQL.WCHAR 

SQL.WVARCHAR 

SQL.WLONGVARCHAR 

SQL.BINARY 

SQL.VARBINARY 

SQL.LONGVARBINARY 

SQL.NUMERIC 

SQL.DECIMAL 

For all other data types, the extended parameters DBLPREC, FLOATPREC, and 

INTPREC determine the maximum length for strings representing double-precision 

numbers, floating-point numbers, and integers. 

SQLBindParameter 1-789

Parameters 


Input Variable Description 


statement.env SQL statement environment associated with an SQL statement. 

mrk# Number of the parameter marker in the SQL statement to which this 

call refers. Parameter markers in the SQL statement are numbered left 

to right, starting at 1. 

data.type UniBasic data type to bind to the parameter. data.type must be one of 

the following: 

SQL.B.BASI – Use with any sql.type. 

SQL.B.BINARY – Use only when sql.type is SQL.BINARY, 

SQL.VARBINARY, or SQL.LONGVARBINARY. 

SQL.B.INTDATE – Use only when sql.type is SQL.DATE. 

SQL.B.INTTIME – Use only when sql.type is SQL.TIME. 

sql.type SQL data type to which the UniBasic variable is converted. 

prec Precision of the parameter, representing the width of the parameter. If 

prec is 0, default values are used. 

scale Scale of the parameter, used only when sql.type is SQL.DECIMAL or 

SQL.NUMERIC. 

param Variable that contains the data to use when SQLExecute or 

SQLExecDirect is called. 

param.type Type of parameter. param.type can be one of the following: 

SQL.PARAM.INPUT – Use for parameters in an SQL statement that 

does not call a procedure, or for input parameters in a procedure call. 

SQL.PARAM.OUTPUT – Use for parameters that mark the output 

parameter in a procedure. 

SQL.PARAM.INPUT.OUTPUT – Use for an input/output parameter 

in a procedure. 

If you do not specify param.type, SQL.PARAM.INPUT is used. 

SQLBindParameter Input Variables

Return Values 

The following table describes the return values of the SQLBindParameter function. 

Return 


0 SQL.SUCCESS 



SQLBindParameter Return Values 

SQLBindParameter 1-791

SQLCancel 

Syntax 

status = SQLCancel (statement.env) 



Description 

This function is equivalent to the SQLFreeStmt call with the SQL.CLOSE option. It 

closes any open cursor associated with the SQL statement environment and discards 

pending results at the data source. 

It is good practice to issue SQLCancel when all results have been read from the data 

source, even if the SQL statement environment will not be reused immediately for 

another SQL statement. Issuing SQLCancel frees any locks that may be held at the 

data source. 

Parameters 




statement.env SQL statement environment. 

SQLCancel Parameters

Return Values 

The following table describes the return values of the SQLCancel function. 


0 SQL.SUCCESS 



SQLCancel Return Values 

SQLCancel 1-793

SQLColAttributes 

Syntax 

status = SQLColAttributes (statement.env, col#, col.attribute, text.var, num.var) 



Description 

Use this function to get information about a column. SQLColAttributes returns the 

specific information requested by the value of col.attribute. 

Some DBMSs (such as SYBASE) do not make column information available until 

after the SQL statement is executed. In such cases, issuing an SQLColAttributes 

call before executing the statement produces an error. 

The SQL.SUCCESS.WITH.INFO return occurs when you issue the call for a column 

that contains an unsupported data type or when text.var is truncated. The SQL data 

type returned is SQL.BINARY (−2). 

If you are connected to an ODBC database, SQL.COLUMN.NULLABLE always 

returns SQL.NULLABLE.UNKNOWN. 

When you are connected to an ODBC data source, calling SQLColAttributes with 

one of the column attributes returns a status of SQL.ERROR with SQLSTATE set to 

S1091. 


Parameters 




col# Column number to describe, starting with 1. 

col.attribute Attribute of the column that needs information. col.attribute values 

are listed under “Description” in this section. These values are 

defined in the ODBC.H file. 

text.var Contains column information for attributes returning text data. If the 

return value is numeric, text.var contains invalid information. 

num.var Contains column information for attributes returning numeric data. If 

the return value is text, num.var contains invalid information. 

SQLColAttributes Parameters 

The following table lists the column attributes you can use with ODBC databases. 

Column Attribute Output Description 

SQL.COLUMN.AUTO.INCREMENT num.var 1 – TRUE if the column values 

are incremented automatically. 

0 – FALSE if the column values 

are not incremented 

automatically. 

SQL.COLUMN.CASE.SENSITIVE num.var 1 – TRUE for character data. 

0 – FALSE for all other data. 

SQL.COLUMN.COUNT num.var Number of columns in result set. 

The col# argument must be a 

valid column number in the result 

set. 

SQL.COLUMN.DISPLAY.SIZE num.var Maximum number of characters 

required to display data from the 

column. 

SQL.COLUMN.LABEL text.var 

Column Attributes 

Column heading. 

SQLColAttributes 1-795



SQL.COLUMN.LENGTH num.var Number of bytes transferred by an 

SQLFetch call. 

SQL.COLUMN.NAME text.var Name of specified column. 

SQL.COLUMN.NULLABLE num.var Column can contain null values. 

Can return one of the following: 

0 – SQL.NO.NULLS 

1 – SQL.NULLABLE 

2 – 

SQL.NULLABLE.UNKNOWN 

SQL.COLUMN.PRECISION num.var Column precision. 

SQL.COLUMN.SCALE num.var Column scale. 

SQL.COLUMN.SEARCHABLE num.var Always returns 3, 

SQL.SEARCHABLE. 

SQL.COLUMN.TABLE.NAME text.var Name of the table to which the 

column belongs. If the column is 

an expression, an empty string is 

returned. 

SQL.COLUMN.TYPE num.var Number representing the SQL 

type of this column. 

SQL.COLUMN.TYPE.NAME text.var Data type name for column, 

specific to the data source. 

SQL.COLUMN.UNSIGNED num.var 1 – TRUE for nonnumeric data 

types. 

0 – FALSE for all other data 

types. 

SQL.COLUMN.UPDATABLE num.var Any expressions or computed 

columns return 

SQL.ATTR.READONLY, and 

stored data columns return 

SQL.ATTR.WRITE. 

Column Attributes (continued)

Return Values 

The following table describes the return values of the SQLColAttributes function. 


0 SQL.SUCCESS 

ODBC Data Sources 

1 SQL.SUCCESS.WITH.INFO 



SQLColAttributes Return Values 

The following table lists the column attributes you can use only with ODBC 

databases. 


SQL.COLUMN.MONEY num.var 1 – TRUE if column is money 

data type. 

0 – FALSE if column is not 

money data type. 

SQL.COLUMN.OWNER.NAME text.var Owner of the table containing 

the column. 

SQL.COLUMN.QUALIFIER.NAME text.var Qualifier of the table 

containing the column. 

ODBC Column Attributes 

SQLColAttributes 1-797

SQLColumns 

Syntax 

status = SQLColumns (statement.env, schema, owner, tablename, columnname ) 



Description 

This function returns a result set in statement.env as a cursor of 12 columns 

describing those columns found by the search pattern (see SQLTables). As with 

SQLTables, the search is done on the SQL catalog. This is a standard result set that 

can be accessed with SQLFetch. The ability to obtain descriptions of columns does 

not imply that a user has any privileges on those columns. 

Parameters 





schema Schema name search pattern. 

owner Table owner number search pattern. 

tablename Table name search pattern. 

columnname Column name search pattern. 

SQLColumns Input Variables

Result Set 

The result set contains 12 columns: 

Column Name Data Type 

TABLE.SCHEMA VARCHAR(128) 

OWNER INTEGER 

TABLE.NAME VARCHAR(128) 

COLUMN.NAME VARCHAR(128) 

DATA.TYPE SMALLINT 

TYPE.NAME VARCHAR(128) 

NUMERIC.PRECISION INTEGER 

CHAR.MAX.LENGTH INTEGER 

NUMERIC.SCALE SMALLINT 

NUMERIC.PREC.RADIX SMALLINT 

NULLABLE SMALLINT 

REMARKS VARCHAR(254) 

SQLColumns Result Set 

The application is responsible for binding variables for the output columns and 

fetching the results using SQLFetch. 

SQLColumns 1-799

Return Values 

The following table describes the returns values of the SQLColumns function. 

SQLSTATE Values 

The following table shows all possible SQLSTATE values returned by 

SQLColumns. 

SQLSTAT 

E Description 



0 SQL.SUCCESS 


–1 SQL.ERROR 

–2 SQL.INVALID.HANDLE 

SQLColumns Return Values 

S1000 General error for which no specific SQLSTATE code has been defined. 

S1001 Memory allocation failure. 

S1008 Cancelled. Execution of the statement was stopped by an SQLCancel call. 

S1010 Function sequence error. The statement.env specified is currently executing 

an SQL statement. 

S1C00 The table owner field was not numeric. 

24000 Invalid cursor state. Results are still pending from the previous SQL 

statement. Use SQLCancel to clear the results. 

42000 Syntax error or access violation. This can be caused by a variety of reasons. 

The native error code returned by the SQLError call indicates the specific 

UniData error that occurred. 

SQLSTATE Values

SQLConnect 

Syntax 

status = SQLConnect (connect.env, data.source, login1, login2) 



Description 

Use this function to connect to the ODBC data source specified by data.source. Use 

the login1 and login2 parameters to log in to the DBMS specified by the ODBC 

data.source. 

You cannot use SQLConnect within a transaction. An SQLConnect call issued 

within a transaction returns SQL.ERROR, and sets SQLSTATE to 25000, indicating 

that the SQLConnect function is illegal within a transaction. 

A connection is established when the data source validates the user name and 

authorization. 

Parameters 



connect.env Connection environment assigned in a previous SQLAllocConnect. 

SQLConnect Input Variables 

SQLConnect 1-801


Return Values 

The following table describes the return values of the SQLConnect function. 


data.source Data source name. For ODBC data sources, this is the name of a data 

source specified by the data source management program you are using. 

login1 For ODBC data sources, this is typically the password for the remote 

database or operating system. 

For the specific information required for login1 when connecting to ODBC 

data sources, see the configuration for the specific driver used. 

login2 For ODBC data sources, this is typically the password for the remote 

database or operating system. 

For the specific information required for login2 when connecting to ODBC 

data sources, see the configuration for the specific driver used. 

SQLConnect Input Variables (continued) 


0 SQL.SUCCESS 




SQLConnect Return Values

SQLDescribeCol 

Syntax 

status = SQLDescribeCol (statement.env, col#, col.name, sql.type, prec, scale, null) 



Description 

Use this function to get information about the column described by col#. 

The SQL.SUCCESS.WITH.INFO return occurs when you issue the call for a column 

that contains an unsupported data type, or if col.name is truncated. The SQL data type 

returned is SQL.BINARY (−2). 

Parameters 




col# Column number to describe, starting with 1. 

col.name Column name. 

sql.type SQL data type of the column, a numeric code defined in the ODBC.H 

file. 

SQLDescribeCol Input Variables 

SQLDescribeCol 1-803


Return Values 

The following table describes the return values of the SQLDescribeCol function. 


prec Precision of the column, or –1 if precision is unknown. 

scale Scale of the column, or –1 if scale is unknown. 

null One of the following: 

0 – SQL.NO.NULLS: field cannot contain NULL. 

1 – SQL.NULLABLE: field can contain NULL. 

2 – SQL.NULLABLE.UNKNOWN: not known whether field can 

contain NULL. 

SQLDescribeCol Input Variables (continued) 


0 SQL.SUCCESS 




SQLDescribeCol Return Values

SQLDisconnect 

Syntax 

status = SQLDisconnect (connect.env) 



Description 

SQLDisconnect disconnects a connection environment from a data source. 

You cannot use SQLDisconnect within a transaction. An SQLDisconnect call 

issued within a transaction returns SQL.ERROR, and sets SQLSTATE to 25000. You 

must commit or abort active transactions before disconnecting, and you must be in 

autocommit mode. If there is no active transaction, SQLDisconnect frees all SQL 

statement environments owned by this connection before disconnecting. 

SQLDisconnect returns SQL.SUCCESS.WITH.INFO if an error occurs but the 

disconnect succeeds. 

Parameters 



connect.env Connection environment. 

SQLDisconnect Input Variable 

SQLDisconnect 1-805

Return Values 

The following table describes the return values of the SQLDisconnect function. 



0 SQL.SUCCESS 




SQLDisconnect Return Values

SQLError 

Syntax 

status = SQLError (bci.env, connect.env, statement.env, sqlstate, dbms.code, error) 



Description 

SQLError returns error status information about one of the three environments you 

use. 

Use SQLError when a function returns a status value other than SQL.SUCCESS or 

SQL.INVALID.HANDLE. SQLError returns a value in sqlstate when UniData BCI 

detects an error condition. The dbms.code field contains information from the data 

source that identifies the error. 

Each environment type maintains its own error status. SQLError returns errors for 

the rightmost nonnull environment. For example, to get errors associated with a 

connection environment, specify input variables and constants in the following order: 

bci.env, connect.env, SQL.NULL.HSTMT 

To get errors associated with a particular SQL statement environment, specify the 

following: 

bci.env, connect.env, statement.env 

If all arguments are null, SQLError returns a status of SQL.NO.DATA.FOUND and 

sets SQLSTATE to 00000. 

Since multiple errors can be returned for a variable, you should call SQLError until 

it returns a status of SQL.NO.DATA.FOUND. This ensures that all errors are 

reported. 

SQLError 1-807


When a program is connected to an ODBC server, errors can be detected by UniData 

BCI, by the ODBC driver, or by the data source. When the error is returned, the 

source of the error is indicated by bracketed items in the error output variable, as 

shown in the following examples. 

Errors detected by Unidata BCI: 


[IBM][SQL Client] An illegal configuration option was found 

Errors detected by the ODBC driver: 

SQLConnect error: Status = -1 SQLState = S1000 Natcode = 

9352 

[ODBC] [INTERSOLV][ODBC Oracle driver][Oracle]ORA-09352: Windows 

32-bit 

Two-Task driver unable to spawn new ORACLE task 

For information about errors detected by the ODBC driver manager, see the 

Microsoft ODBC 2.0 Programmer’s Reference and SDK Guide. 

Errors detected by the data source: 

[IBM][SQL Client][IBM] Database not found or no system 

permissions. 

For information about errors detected by the data source, see the documentation 

provided for the DBMS running on the data source. 

Parameters 



bci.env UniData BCI environment or the constant SQL.NULL.HENV. 

connect.env Connection environment or the constant SQL.NULL.HDBC. 

statement.env SQL statement environment or the constant SQL.NULL.HSTMT. 

SQLError Input Variables


sqlstate SQLSTATE code. This code describes the UniData BCI Client error 

associated with the environment passed. sqlstate is always a fivecharacter 

string. 

dbms.code Error code specific to the data source. dbms.code contains an integer 

error code from the data source. If dbms.code is 0, the error was detected 

by UniData BCI. For the meanings of specific error codes, see the 

documentation provided for the data source. 

error Text describing the error in more detail. 

Return Values 

SQLError Input Variables (continued) 

The following table describes the return values of the SQLError function. 


0 SQL.SUCCESS 




100 SQL.NO.DATA.FOUND 

SQLError Return Values 

SQLError 1-809

SQLExecDirect 

Syntax 

status = SQLExecDirect (statement.env, statement) 



Description 

SQLExecDirect accepts an SQL statement or procedure call and delivers it to the 

data source for execution. It uses the current values of any SQL statement parameter 

markers. 

SQLExecDirect differs from SQLExecute in that it does not require a call to 

SQLPrepare. SQLExecDirect prepares the SQL statement or procedure call 

implicitly. Use SQLExecDirect when you do not need to execute the same SQL 

statement or procedure repeatedly. 

You can use parameter markers in the SQL statement or procedure call as long as you 

have resolved each marker with an SQLBindParameter call. 

After an SQLExecDirect call you can use SQLNumResultCols, SQLDescribeCol, 

SQLRowCount, or SQLColAttributes to get information about the resulting 

columns. You can use SQLNumResultCols to determine if the SQL statement or 

procedure call created a result set. 

If the executed SQL statement or procedure produces a set of results, you must use 

an SQLFreeStmt call with the SQL.CLOSE option before you execute another SQL 

statement or procedure call using the same SQL statement environment. The 

SQL.CLOSE option cancels any pending results still waiting at the data source. 


Your application programs should not try to issue transaction control statements 

directly to the data source (for instance, by issuing a COMMIT statement with 

SQLExecDirect or SQLPrepare). Programs should use only UniBasic transaction 

control statements. UniData BCI issues the correct combination of transaction 

control statements and middleware transaction control function calls that are appropriate 

for the DBMS you are using. Trying to use SQLExecDirect to execute explicit 

transaction control statements on ODBC data sources can cause unexpected results 

and errors. 

When SQLExecDirect calls a procedure, it does not begin a transaction. If a transaction 

is active when a procedure is called, the current transaction nesting level is 

maintained. 

Note: If you execute a stored procedure or enter a command batch with multiple 

SELECT statements, the results of only the first SELECT statement are returned. 

Parameters 



statement.env SQL statement environment from a previous SQLAllocStmt. 

SQLExecDirect Input Variables 

SQLExecDirect 1-811


Return Values 

The following table describes the return values of the SQLExecDirect function. 


statement Either an SQL statement or a call to an SQL procedure, to be executed at 

the data source. If you are connected to an ODBC data source, it may 

treat identifiers and keywords in the SQL statement case-sensitively. 

To call an SQL procedure, use one of the following syntaxes: 

[ { ] CALL procedure [ ( [ parameter [ , parameter ] … ] ) ] [ } ] 

If you are connected to an ODBC data source, use the first syntax and 

enclose the entire call statement in braces. 

procedure Name of the procedure. If the procedure name contains characters other 

than alphabetic or numeric, enclose the name in double quotation marks. 

To embed a single double quotation mark in the procedure name, use two 

consecutive double quotation marks. 

parameter Either a literal value or a parameter marker that marks where to insert 

values to send to or receive from the data source. Programmatic SQL 

uses a ? (question mark) as a parameter marker. 

Use parameters only if the procedure is a subroutine. The number and 

order of parameters must correspond to the number and order of the 

subroutine arguments. For an ODBC data source, parameters should be 

of the same data type as the procedure requires. 

SQLExecDirect Input Variables (continued) 


0 SQL.SUCCESS 




SQLExecDirect Return Values

SQLExecute 

Syntax 

status = SQLExecute (statement.env) 



Description 

Use this function to repeatedly execute an SQL statement, using different values for 

parameter markers. You must use an SQLPrepare call to prepare the SQL statement 

before you can use SQLExecute. If the SQL statement specified in the SQLPrepare 

call contains parameter markers, you must also issue an SQLBindParameter call for 

each marker in the SQL statement before you use SQLExecute. After you load the 

parameter marker variables with data to send to the data source, you can issue the 

SQLExecute call. By setting new values in the parameter marker variables and 

calling SQLExecute, new data values are sent to the data source and the SQL 

statement is executed using those values. 

If the SQL statement uses parameter markers, SQLExecute performs any data 

conversions required by the SQLBindParameter call for the parameter markers. If 

the SQL statement executed produces a set of results, you must use an SQLFreeStmt 

call with the SQL.CLOSE option before you execute another SQL statement using 

the same SQL statement environment. The SQL.CLOSE option cancels any pending 

results still waiting at the data source. 

Your application programs should not try to issue transaction control statements 

directly to the data source (for instance, by issuing a TRANSACTION COMMIT 

statement with SQLExecDirect or SQLPrepare). Programs should use only 

UniBasic transaction control statements. UniData BCI issues the correct combination 

of transaction control statements and middleware transaction control function calls 

that are appropriate for the DBMS you are using. Trying to use SQLExecute to 

execute explicit transaction control statements on ODBC data sources can cause 

unexpected results and errors. 

SQLExecute 1-813

SQLExecute tells the data source to execute a prepared SQL statement or a called 

procedure, using the current values of any parameter markers used in the statement. 

Using SQLExecute with an SQLBindParameter call is the most efficient way to 

execute a statement repeatedly, since the statement does not have to be parsed by the 

data source each time it is issued. 

Parameters 



Return Values 

The following table describes the return values of the SQLExecute function. 


statement.env SQL statement environment associated with a prepared SQL statement. 

SQLExecute Parameter 


0 SQL.SUCCESS 




SQLExecute Return Values

SQLFetch 

Syntax 

status = SQLFetch (statement.env) 



Description 

Use this function to retrieve the next row’s column values from the result set at the 

data source and put them into the variables specified with SQLBindCol. SQLFetch 

performs any required data conversions. 

SQLFetch returns SQL.SUCCESS.WITH.INFO if numeric data is truncated or 

rounded when converting SQL values to UniData values. 

SQLFetch logically advances the cursor to the next row in the result set. Unbound 

columns are ignored and are not available to the application. When no more rows are 

available, SQLFetch returns a status of 100 (SQL.NO.DATA.FOUND). 

Your application must issue an SQLFetch call at the same transaction nesting level 

(or deeper) as the corresponding SQLExecDirect or SQLExecute call. Also, an 

SQLFetch call must be executed at the same transaction isolation level as the 

SELECT statement that generates the data. If it does not, SQLFetch returns 

SQL.ERROR and sets SQLSTATE to S1000. 

Use SQLFetch only when a result set is pending at the data source. 

Parameters 




SQLFetch Parameters 

SQLFetch 1-815

Return Values 

The following table describes the return values of the SQLFetch function. 



0 SQL.SUCCESS 




100 SQL.NO.DATA.FOUND 

SQLFetch Return Values

SQLFreeConnect 

Syntax 

status = SQLFreeConnect (connect.env) 



Description 

SQLFreeConnect releases a connection environment and its resources. 

You must use SQLDisconnect to disconnect the connection environment from the 

data source before you release the connection environment with SQLFreeConnect, 

otherwise an error is returned. 

Parameters 




SQLFreeConnect Parameters 

SQLFreeConnect 1-817

Return Values 

The following table describes the return values of the SQLFreeConnect function. 



0 SQL.SUCCESS 



SQLFreeConnect Return Values

SQLFreeEnv 

Syntax 

status = SQLFreeEnv (bci.env) 



Description 

SQLFreeEnv releases an SQL Client Interface environment and its resources. 

You must use SQLFreeConnect to release all connection environments attached to 

the UniData BCI environment before you release the UniData BCI environment with 

SQLFreeEnv, otherwise an error is returned. 

Parameters 



bci.env UniData BCI environment. 

SQLFreeEnv Parameters 

SQLFreeEnv 1-819

Return Values 

The following table describes the return values of the SQLFreeEnv function. 



0 SQL.SUCCESS 



SQLFreeEnv Return Values

SQLFreeStmt 

Syntax 

status = SQLFreeStmt (statement.env, option) 



Description 

SQLFreeStmt frees some or all resources associated with an SQL statement 

environment. 

If your program uses the same SQL statement environment to execute different SQL 

statements, use SQLFreeStmt with the SQL.DROP option, then use SQLAllocStmt 

to reallocate a new SQL statement environment. This unbinds all bound columns and 

resets all parameter marker variables. 

It is good practice to issue SQLFreeStmt with the SQL.CLOSE option when all 

results have been read from the data source, even if the SQL statement environment 

will not be reused immediately for another SQL statement. Issuing SQLFreeStmt 

with the SQL.CLOSE option frees any locks that may be held at the data source. 

SQLFreeStmt 1-821

Parameters 





option option is one of the following: 

SQL.CLOSE – Closes any open cursor associated with 

the SQL statement environment and discards pending 

results at the data source. Using the SQL.CLOSE 

option cancels the current query. All parameter 

markers and columns remain bound to the variables 

specified in the SQLBindCol and 

SQLBindParameter calls. 

SQL.UNBIND – Releases all bound column variables 

defined in SQLBindCol for this SQL statement 

environment. 

SQL.RESET.PARAMS – Releases all parameter 

marker variables set by SQLBindParameter for this 

SQL statement environment. 

SQL.DROP – Releases the SQL statement 

environment. This option terminates all access to the 

SQL statement environment. SQL.DROP also closes 

cursors, discards pending results, unbinds columns, 

and resets parameter marker variables. 

Options are defined in the ODBC.H file. 

SQLFreeStmt Input Variables

Return Values 

The following table describes the return values of the SQLFreeStmt function. 


0 SQL.SUCCESS 



SQLFreeStmt Return Values 

SQLFreeStmt 1-823

SQLGetInfo 

Syntax 

status = SQLGetInfo (connect.env, info.type, info.value) 



Description 

SQLGetInfo returns general information about the ODBC driver and the data 

source. 

This function supports all of the possible requests for information defined in the 

ODBC 2.0 specification. The #defines for info.type are contained in the ODBC.H 

include file. 

Parameters 





info.type The specific information requested. For a list of values, see the info.type 

tables under “Description.” 

info.value The information returned by SQLGetInfo. 

SQLGetInfo Parameters

ODBC info.type Values 

The following table lists the valid ODBC values for info.type. For more detailed 

information about information types, see Microsoft ODBC 2.0 Programmer’s 

Reference and SDK Guide. 

Driver Information 

SQL.ACTIVE.CONNECTIONS SQL.DRIVER.VER 

SQL.ACTIVE.STATEMENTS SQL.FETCH.DIRECTION 

SQL.DATA.SOURCE.NAME SQL.FILE.USAGE 

SQL.DRIVER.HDBC SQL.GETDATA.EXTENSIONS 

SQL.DRIVER.HENV SQL.LOCK.TYPES 

SQL.DRIVER.HLIB SQL.ODBC.API.CONFORMANCE 

SQL.DRIVER.HSTMT SQL.ODBC.SAG.CLI.CONFORMANCE 

SQL.DRIVER.NAME SQL.ODBC.VER 

SQL.DRIVER.ODBC.VER SQL.POS.OPERATIONS 

SQL.ROW.UPDATES SQL.SERVER.NAME 

SQL.SEARCH.PATTERN.ESCAPE 

DBMS Product Information 

SQL.DATABASE.NAME SQL.DBMS.VER 

SQL.DBMS.NAME 

Data Source Information 

SQL.ACCESSIBLE.PROCEDURES SQL.OWNER.TERM 

SQL.ACCESSIBLE.TABLES SQL.PROCEDURE.TERM 

SQL.BOOKMARK.PERSISTENCE SQL.QUALIFIER.TERM 

ODBC info.type Values 

SQLGetInfo 1-825


SQL.CONCAT.NULL.BEHAVIOR SQL.SCROLL.CONCURRENCY 

SQL.CURSOR.COMMIT.BEHAVIOR SQL.SCROLL.OPTIONS 

SQL.DATA.SOURCE.READ.ONLY SQL.STATIC.SENSITIVITY 

SQL.DEFAULT.TXN.ISOLATION SQL.TABLE.TERM 

SQL.MULT.RESULT.SETS SQL.TXN.CAPABLE 

SQL.MULTIPLE.ACTIVE.TXN SQL.TXN.ISOLATION.OPTION 

SQL.NEED.LONG.DATA.LEN SQL.USER.NAME 

SQL.NULL.COLLATION 

Supported SQL 

SQL.ALTER.TABLE SQL.ODBC.SQL.OPT.IEF 

SQL.COLUMN.ALIAS SQL.ORDER.BY.COLUMNS.IN.SELECT 

SQL.CORRELATION.NAME SQL.OUTER.JOINS 

SQL.EXPRESSIONS.IN.ORDER.BY SQL.OWNER.USAGE 

SQL.GROUP.BY SQL.POSITIONED.STATEMENTS 

SQL.IDENTIFIER.CASE SQL.PROCEDURES 

SQL.IDENTIFIER.QUOTE.CHAR SQL.QUALIFIER.LOCATION 

SQL.KEYWORDS SQL.QUALIFIER.NAME.SEPARATOR 

SQL.LIKE.ESCAPE.CLAUSE SQL.QUALIFIER.USAGE 

SQL.NON.NULLABLE.COLUMNS SQL.QUOTED.IDENTIFIER.CASE 

SQL.ODBC.SQL.CONFORMANCE SQL.SPECIAL.CHARACTERS 

SQL.SUBQUERIES SQL.UNION 

SQL Limits 

ODBC info.type Values (continued)

SQL.MAX.BINARY.LITERAL.LEN SQL.MAX.OWNER.NAME.LEN 

SQL.MAX.CHAR.LITERAL.LEN SQL.MAX.PROCEDURE.NAME.LEN 

SQL.MAX.COLUMN.NAME.LEN SQL.MAX.QUALIFIER.NAME.LEN 

SQL.MAX.COLUMNS.IN.GROUP.BY SQL.MAX.ROW.SIZE 

SQL.MAX.COLUMNS.IN.ORDER.BY SQL.MAX.ROW.SIZE.INCLUDES.LONG 

SQL.MAX.COLUMNS.IN.INDEX SQL.MAX.STATEMENT.LEN 

SQL.MAX.COLUMNS.IN.SELECT SQL.MAX.TABLE.NAME.LEN 

SQL.MAX.COLUMNS.IN.TABLE SQL.MAX.TABLES.IN.SELECT 

SQL.MAX.CURSOR.NAME.LEN SQL.MAX.USER.NAME.LEN 

SQL.MAX.INDEX.SIZE 

Scalar Function Information 

SQL.CONVERT.FUNCTIONS SQL.TIMEDATE.ADD.INTERVALS 

SQL.NUMERIC.FUNCTIONS SQL.TIMEDATE.DIFF.INTERVALS 

SQL.STRING.FUNCTIONS SQL.TIMEDATE.FUNCTIONS 

SQL.SYSTEM.FUNCTIONS 

Conversion Information 

SQL.CONVERT.BIGINT SQL.CONVERT.LONGVARCHAR 

SQL.CONVERT.BINARY SQL.CONVERT.NUMERIC 

SQL.CONVERT.BIT SQL.CONVERT.REAL 

SQL.CONVERT.CHAR SQL.CONVERT.SMALLINT 

SQL.CONVERT.DATE SQL.CONVERT.TIME 

SQL.CONVERT.DECIMAL SQL.CONVERT.TIMESTAMP 

ODBC info.type Values (continued) 

SQLGetInfo 1-827

Return Values 

The following table lists the return values of the SQLGetInfo function. 


SQL.CONVERT.DOUBLE SQL.CONVERT.TINYINT 

SQL.CONVERT.FLOAT SQL.CONVERT.VARBINARY 

SQL.CONVERT.INTEGER SQL.CONVERT.VARCHAR 

SQL.CONVERT.LONGVARBINARY 

ODBC info.type Values (continued) 


0 SQL.SUCCESS 




SQLGetInfo Return Values

SQLGetTypeInfo 

Syntax 

status = SQLGetTypeInfo (statement.env, sql.type) 



Description 

SQLGetTypeInfo returns information about an SQL on the data source. You can use 

SQLGetTypeInfo only against ODBC data sources. 

SQLGetTypeInfo returns a standard result set ordered by DATA.TYPE and 

TYPE.NAME. 

SQLGetTypeInfo 1-829

Parameters 





sql.type A driver-specific SQL data type, or one of the following: 

SQL.B.BINARY 

SQL.BIGINT 

SQL.BINARY 

SQL.BIT 

SQL.C.BINARY 

SQL.CHAR 

SQL.DATE 

SQL.DECIMAL 

SQL.DOUBLE 

SQL.FLOAT 

SQL.INTEGER 

SQL.LONGVARBINARY 

SQL.LONGVARCHAR 

SQL.NUMERIC 

SQL.REAL 

SQL.SMALLINT 

SQL.TIME 

SQL.TIMESTAMP 

SQL TINYINT 

SQL.VARBINARY 

SQL.VARCHAR 

SQL.WCHAR 

SQL.WLONGVARCHAR 

SQL.WVARCHAR 

SQLGetTypeInfo Input Variables

Result Set 

The following table lists the columns in the result set. For more detailed information 

about data type information, see the Microsoft ODBC 2.0 Programmer’s Reference 

and SDK Guide. 

Column Name Data Type Description 

TYPE.NAME Varchar Data-source-dependent data type name. 

DATA.TYPE Smallint Driver-dependent or SQL data type. 

PRECISION Integer Maximum precision of the data type on 

the data source. 

LITERAL.PREFIX Varchar(128) Characters used to prefix a literal. 

LITERAL.SUFFIX Varchar(128) Characters used to terminate a literal. 

CREATE.PARAMS Varchar(128) Parameters for a data type definition. 

NULLABLE Smallint Data type accepts null values. Returns 

one of the following: 

SQL.NO.NULLS 

SQL.NULLABLE 

SQL.NULLABLE.UNKNOWN 

CASE.SENSITIVE Smallint Character data type is case-sensitive. 

Returns one of the following: 

TRUE if data type is a character data 

type and is case-sensitive 

FALSE if data type is not a character 

data type and is not case-sensitive 

SQLGetTypeInfo Results 




SEARCHABLE Smallint How the WHERE clause uses the data 

type. Returns one of the following: 

SQL.UNSEARCHABLE if data type 

cannot be used 

SQL.LIKE.ONLY if data type can be 

used only with the LIKE predicate 

SQL.ALL.EXCEPT.LIKE if data type 

can be used with all comparison 

operators except LIKE 

SQL.SEARCHABLE if data type can be 

used with any comparison operator 

UNSIGNED.ATTRIBUTE Smallint Data type is unsigned. Returns one of the 

following: 

TRUE if data type is unsigned 

FALSE if data type is signed 

NULL if attribute is not applicable to the 

data type or the data type is not numeric 

MONEY Smallint Data type is a money data type. Returns 


TRUE if data type is a money data type 

FALSE if it is not 

AUTO.INCREMENT Smallint Data type is autoincrementing. Returns 


TRUE if data type is autoincrementing 

FALSE if it is not 

NULL if attribute is not applicable to the 

data type or the data type is not numeric 

LOCAL.TYPE.NAME Varchar(128) Localized version of TYPE.NAME. 

MINIMUM.SCALE Smallint Minimum scale of the data type on the 

data source. 

MAXIMUM.SCALE Smallint Maximum scale of the data type on the 

data source. 

SQLGetTypeInfo Results

Return Values 

The following table describes the return values of the SQLGetTypeInfo function. 


0 SQL.SUCCESS 




SQLGetTypeInfo Return Values 


SQLNumParams 

Syntax 

status = SQLNumParams (statement.env, parameters) 



Description 

SQLNumParams returns the number of parameters in an SQL statement. 

Use this function after preparing or executing an SQL statement or procedure call to 

find the number of parameters in an SQL statement. If the statement associated with 

statement.env contains no parameters, parameters is set to 0. 

Parameters 




statement.env SQL statement environment containing the prepared or executed 

SQL statement. 

parameters Number of parameters in the statement. 

SQLNumParams Parameters

Return Values 

The following table describes the return values of the SQLNumParams function. 

Return 


0 SQL.SUCCESS 



SQLNumParams Return Values 

SQLNumParams 1-835

SQLNumResultCols 

Syntax 

status = SQLNumResultCols (statement.env, cols) 



Description 

SQLNumResultCols returns the number of columns in a result set. 

Use this function after executing an SQL statement to find the number of columns in 

the result set. If the executed statement was not a SELECT statement or a called 

procedure that produced a result set, the number of result columns returned is 0. 

Use this function when the number of columns to be bound to application variables 

is unknown, for example, when your program is processing SQL statements entered 

by users. 

Parameters 




statement.env SQL statement environment containing the executed SQL statement. 

cols Number of report columns generated. 

SQLNumResultCols Parameters

Return Values 

The following table describes the return values of the SQLNumResultCols function. 


0 SQL.SUCCESS 



SQLNumResultCols Return Values 

SQLNumResultCols 1-837

SQLParamOptions 

Syntax 

status = SQLParamOptions (statement.env, option, value) 



Description 

SQLParamOptions lets applications load an array of parameter markers in a single 

SQLExecDirect or SQLExecute function call. Use this function only when you are 

connected to an ODBC data source. 

SQLParamOptions works for all parameter types—output and input/output parameters 

as well as the more usual input parameters. 

Be careful when you use matrices instead of arrays. For example, in the matrix: 

dim matrix(10,10) 

the elements 1,1, 1,2, ..., 1,10, 2,1, 2,2, ... occupy consecutive memory locations. 

Since SQLParamOptions requires each location specified in SQLBind Parameter to 

point to a consecutive series of values in memory, an application using a matrix must 

load the values of the matrix in the correct order. 

When the SQL statement is executed, all variables are checked, data is converted 

when necessary, and all values in the set are verified to be appropriate and within the 

bounds of the marker definition. Values are then copied to low-level structures 

associated with each parameter marker. If a failure occurs while the values are being 

checked, SQLExecDirect or SQLExecute returns SQL.ERROR, and value contains 

the number of the row where the failure occurred. 


Parameters 




option One of the following, followed by a value: 

SQL.PARAMOPTIONS.SET – value is an input variable containing the 

number of rows to process. It can be an integer from 1 through 1024. 

SQL.PARAMOPTIONS.READ – value is an output variable containing 

the number of parameter rows processed by SQLExecDirect or SQLExecute. 

As each set of parameters is processed, value is updated to the 

current row number. If SQLExecDirect or SQLExecute encounters 

an error, value contains the number of the row that failed. 

value If option is SQL.PARAMOPTIONS.SET, value is the number of rows to 

process. It can be an integer from 1 through 1024. 1 is the default. 

If option is SQL.PARAMOPTIONS.READ, value contains the number of 

parameter rows processed by SQLExecDirect or SQLExecute. As each 

set of parameters is processed, value is updated to the current row number. 

SQLParamOptions Parameters 

Return Values 

The following table describes the return values of the SQLParamOptions function. 


0 SQL.SUCCESS 




SQLParamOptions Return Values 

SQLParamOptions 1-839

Example 

This example shows how you might use SQLParamOptions to load a simple table. 

Table TAB1 has two columns: an integer column and a CHAR(30) column. 


$include INCLUDE ODBC.H 

arrsize = 20 

dim p1(arrsize) 

dim p2(arrsize) 

SQLINS1 = "INSERT INTO TAB1 VALUES(?,?)" 

rowindex = 0 

status = SQLAllocEnv(henv) 

status = SQLAllocConnect(henv, hdbc) 

status = SQLConnect(hdbc, "odbcds", "dbuid", "dbpwd") 

status = SQLAllocStmt(hdbc, hstmt) 

status = SQLPrepare(hstmt, SQLINS1) 

status = SQLBindParameter(hstmt, 1, SQL.B.BASIC, SQL.INTEGER, 0, 

0, p1(1), 

SQL.PARAM.INPUT) 

status = SQLBindParameter(hstmt, 2, SQL.B.BASIC, SQL.CHAR, 30, 0, 

p2(1), 

SQL.PARAM.INPUT) 

status = SQLParamOptions(hstmt, SQL.PARAMOPTIONS.SET, arrsize) 

for index = 1 to arrsize 

p1(index) = index 

p2(index) = "This is row ":index 

next index 

* now execute, delivering 20 sets of parameters in one network 

operation 

stexec = SQLExecute(hstmt) 

status = SQLParamOptions(hstmt, SQL.PARAMOPTIONS.READ, rowindex) 

if stexec = SQL.ERROR then 

print "Error in parameter row number ":rowindex 

end else 

print rowindex:" parameter marker sets were processed" 

end

SQLPrepare 

Syntax 

status = SQLPrepare (statement.env, statement) 



Description 

SQLPrepare passes an SQL statement or procedure call to the data source in order 

to prepare it for execution by SQLExecute. 

Use this function to deliver either an SQL statement or a call to an SQL procedure to 

the data source where it can prepare to execute the passed SQL statement or the 

procedure. The application subsequently uses SQLExecute to tell the data source to 

execute the prepared SQL statement or procedure. 

What happens when the data source executes the SQLPrepare call depends on the 

data source. In many cases the data source parses the SQL statement and generates 

an execution plan that allows rapid, efficient execution of the SQL statement. 

Use SQLPrepare and SQLExecute functions when you are issuing SQL statements 

or calling a procedure repeatedly. You can supply values to a prepared INSERT or 

UPDATE statement and issue an SQLExecute call each time you change the values 

of parameter markers. SQLExecute sends the current values of the parameter 

markers to the data source and executes the prepared SQL statement or procedure 

with the current values. 

Note: Before you issue an SQLExecute call, all parameter markers in the SQL 

statement or procedure call must be defined using an SQLBindParameter call, 

otherwise SQLExecute returns an error. 

If the parameter type of an SQLBindParameter procedure is 

SQL.PARAM.OUTPUT or SQL.PARAM.INPUT.OUTPUT, values are returned to 

the specified program variables. 

SQLPrepare 1-841


If you execute a stored procedure or enter a command batch with multiple SELECT 

statements, the results of only the first SELECT statement are returned. 

Parameters 




statement.env SQL statement environment from a previous SQLAllocStmt. 

statement Either an SQL statement or a call to an SQL procedure, to be executed at 

the data source. 

To call an SQL procedure, use the following syntax: 

[ { ] CALL procedure [ ( [ parameter [ , parameter ] … ] ) ] [ } ] 

procedure Name of the procedure. If the procedure name contains characters other 

than alphabetic or numeric, enclose the name in double quotation marks. 

To embed a single double quotation mark in the procedure name, use two 

consecutive double quotation marks. 

parameter Either a literal value or a parameter marker that marks where to insert 

values to send to or receive from the data source. Programmatic SQL 

uses a ? (question mark) as a parameter marker. 

Use parameters only if the procedure is a subroutine. The number and 

order of parameters must correspond to the subroutine arguments. For an 

ODBC data source, parameters should be of the same data type as the 

procedure requires. 

SQLPrepare Parameters

Return Values 

The following table describes the returns values of the SQLPrepare function. 

Return 


0 SQL.SUCCESS 




SQLPrepare Return Values 

SQLPrepare 1-843

SQLRowCount 

Syntax 

status = SQLRowCount (statement.env, rows) 



Description 

SQLRowCount returns the number of rows changed by UPDATE, INSERT, or 

DELETE statements, or by a called procedure that executes one of these statements. 

Statements such as GRANT and CREATE TABLE, which do not update rows in the 

database, return 0 in rows. 

For a SELECT statement, a 0 row count is always returned, unless the SELECT 

statement includes the TO SLIST clause. In that case, SQLRowCount returns the 

number of rows in the select list. 

The value of rows returned after executing a stored procedure at the data source may 

not be accurate. It is accurate for a single UPDATE, INSERT, or DELETE statement. 

Parameters 




statement.env SQL statement environment containing the executed SQL statement. 

rows Number of rows affected by the operation. 

SQLRowCount Parameters

Return Values 

The following table describes the return values of the SQLRowCount function. 


0 SQL.SUCCESS 



SQLRowCount Return Values 

SQLRowCount 1-845

SQLSetConnectOption 

Syntax 

status = SQLSetConnectOption (connect.env, option, value) 



Description 

SQLSetConnectOption controls some aspects of the connection to a data source. 

Parameters 

The following table describes each paramenter of the syntax. 



connect.env Connection environment returned from a previous SQLAllocConnect. 

SQLSetConnectOption Parameters

Options 

The following table describes the options available with SQLSetConnectOption. 


SQL.AUTO.COMMIT Determines the commit mode for transactions. When you use 

this option, the connection must already be established, and the 

SQL.PRIVATE.TX option must be set to 

SQL.PRIVATE.TX.ON. Valid settings are: 

SQL.AUTO.COMMIT.ON – Puts a private connection into 

autocommit mode. 

SQL.AUTO.COMMIT.OFF – Puts a private connection into 

manual commit mode. 

SQL.PRIVATE.TX Determines if a transaction is controlled by UniBasic or the data 

source. Valid settings are: 

SQL.PRIVATE.TX.ON – Transaction processing is controlled 

directly by the DBMS on the server. 

SQL.PRIVATE.TX.OFF – Transaction processing is fully 

managed by UniBasic. 

SQL.TXN.ISOLATION Determines the isolation level on the server. When you use this 

option, the connection must already be established, the 

SQL.PRIVATE.TX option must be set to 

SQL.PRIVATE.TX.ON, and no transactions may be active.Valid 

settings are: 

SQL.TXN.READ.UNCOMMITTED – Sets the isolation level 

on the server to 1. 

SQL.TXN.READ.COMMITTED – Sets the isolation level on 

the server to 2. 

SQL.TXN.REPEATABLE.READ – Sets the isolation level on 

the server to 3. 

SQL.TXN.SERIALIZABLE – Sets the isolation level on the 

server to 4. 

SQLSetConnectOption Options 

SQLSetConnectOption 1-847

Return Values 

The following table describes the return values for the 

SQLSetConnectOption. 

Private Transactions 

SQL.PRIVATE.TX.ON frees the connection from being managed by the UniData 

transaction manager. When you make a connection private, the application can use 

the SQL.AUTOCOMMIT option to put the connection into either autocommit mode 

or manual commit mode. By default, private connections are in autocommit mode, in 

which each SQL statement is treated as a separate transaction, committed after the 

statement is executed. 

In manual commit mode the application can do either of the following: 



0 SQL.SUCCESS 



SQLSetConnectOption Return Values 

Use the SQLTransact function to commit or roll back changes to the 

database. 

Set the SQL.AUTOCOMMIT option of SQLSetConnectOption to 

SQL.AUTOCOMMIT.ON. This commits any outstanding transactions and 

returns the connection to autocommit mode. 

You must return the connection to autocommit mode before using SQLDisconnect 

to close the connection. You can do this in two ways: 

Set the SQL.AUTOCOMMIT option of SQLSetConnectOption to 

SQL.AUTOCOMMIT.ON 

Set the SQL.PRIVATE.TX option of SQLSetConnectOption to 

SQL.PRIVATE.TX.OFF

When a connection is private, SQL.TXN.ISOLATION lets the application define the 

default transaction isolation level at which to execute server operations. To determine 

what isolation levels the data source supports, use the 

SQL.TXN.ISOLATION.OPTION option of the SQLGetInfo function. This returns 

a bitmap of the options the data source supports. The application can then use the 

UniBasic BIT functions to determine whether a particular bit is set in the bitmap. 

Use SQLSetConnectOption with the SQL.TXN.ISOLATION option only in the 

following two places: 

Immediately following an SQLConnect function call 

Immediately following an SQLTransact call to commit or roll back an 

operation 

Whenever you execute an SQL statement, a new transaction exists, which makes 

setting the SQL.TXN.ISOLATION option illegal. If a transaction is active when the 

SQL.TXN.ISOLATION.OPTION is set, UniData BCI returns SQL.ERROR and sets 

SQLSTATE to S1C00. 

SQLSetConnectOption 1-849

SQLSetParam 

SQLSetParam is a synonym for SQLBindParameter. 




SQLSpecialColumns 

Syntax 

status = SQLSpecialColumns (statement.env, col.type, schema, owner, tablename, 

IDscope, null) 



Description 

SQLSpecialColumns gets information about columns in a table. 

SQLSpecialColumns lets applications scroll forward and backward in a result set to 

get the most recent data from a set of rows. Columns returned for column type 

SQL.BEST.ROWID are guaranteed not to change while positioned on that row. 

Columns of the row ID can remain valid even when the cursor is not positioned on 

the row. The application can determine this by checking the SCOPE column in the 

result set. 

Once the application gets values for SQL.BEST.ROWID, it can use these values to 

reselect that row within the defined scope. The SELECT statement is guaranteed to 

return either no rows or one row. 

Columns returned for SQL.BEST.ROWID can always be used in an SQL select 

expression or WHERE clause. However, SQLColumns does not necessarily return 

these columns. If no columns uniquely identify each row in the table, SQLSpecial- 

Columns returns a row set with no rows; a subsequent call to SQLFetch returns 

SQL.NO.DATA.FOUND. 

Columns returned for column type SQL.ROWVER let applications check if any 

columns in a given row have been updated while the row was reselected using the 

row ID. 

If col.type, IDscope, or null specifies characteristics not supported by the data source, 

SQLSpecialColumns returns a result set with no rows, and a subsequent call to 

SQLFetch returns SQL.NO.DATA.FOUND. 

SQLSpecialColumns 1-851

For complete details about the SQLSpecialColumns function, see the Microsoft 

ODBC 2.0 Programmer’s Reference and SDK Guide. 

Parameters 





col.type Type of column to return. col.type is one of the following: 

SQL.BEST.ROWID – Returns the best column or set of columns that 

uniquely identifies a row in a table. 

SQL.ROWVER – Returns the column or columns that are automatically 

updated when any value in the row is updated by a transaction. 

schema Qualifier name for tablename. If a driver supports qualifiers for some 

tables but not others, use an empty string for tables that do not have 

qualifiers. 

owner Name of the owner of the table. If a driver supports owners for some 

table but not others, use an empty string for tables that do not have 

owners. 

tablename Name of the table. 

IDscope Minimum required scope of the row ID. IDscope is one of the 

following: 

SQL.SCOPE.CURROW – Row ID is guaranteed to be valid only while 

positioned on that row. 

SQL.SCOPE.TRANSACTION – Row ID is guaranteed to be valid for 

the duration of the current transaction. 

SQL.SCOPE.SESSION – Row ID is guaranteed to be valid for the 

duration of the session. 

null Can be one of the following: 

SQL.NO.NULLS – Excludes special columns that can have null values. 

SQL.NULLABLE – Returns special columns even if they can have null 

values. 

SQLSpecialColumns Input Variables

Return Values 

The following table describes the return values of the SQLSpecialColumns 

function. 


0 SQL.SUCCESS 




SQLSpecialColumns Return Values 

Results are returned as a standard result set ordered by SCOPE. The following table 

lists the columns in the result set. The lengths of VARCHAR columns are maximums; 

the actual lengths depend on the data source. To get the length of the 

COLUMN.NAME column, use the SQL.MAX.COLUMN.NAME.LEN option of 

the SQLGetInfo function. 


SCOPE Smallint Actual scope of the row ID. It contains 


SQL.SCOPE.CURROW 

SQL.SCOPE.TRANSACTION 

SQL.SCOPE.SESSION 

The null value is returned when col.type 

is SQL.ROWVER. 

COLUMN.NAME Varchar(128) 

Not null 

DATA.TYPE Smallint 

Not null 

TYPE.NAME Varchar(128) 

Not null 

Column identifier. 

SQLSpecialColumns Results 

Either an ODBC SQL data type or a 

driver-specific SQL data type. 

Data-source-dependent data type name. 

SQLSpecialColumns 1-853



PRECISION Integer Precision of the column on the data 

source. The null value is returned for 

data types where precision does not 

apply. 

LENGTH Integer The length in bytes of data transferred 

on an SQLGetData or SQLFetch if 

SQL.C.DEFAULT is specified. For 

numeric data, this size can differ from 

the size of the data stored on the data 

source. This value is the same as the 

PRECISION column for character or 

binary data. 

SCALE Smallint The scale of the column on the data 

source. The null value is returned for 

data types where scale does not apply. 

PSEUDO.COLUMN Smallint Indicates whether the column is a 

pseudo-column: 

SQL.PC.UNKNOWN 

SQL.PC.PSEUDO 

SQL.PC.NOT.PSEUDO 

Pseudo-columns should not be quoted 

with the identifier quote character 

returned by SQLGetInfo. 

SQLSpecialColumns Results (continued)

SQLStatistics 

Syntax 

status = SQLStatistics (statement.env, schema, owner, tablename, index.type, 

accuracy) 



Description 

SQLStatistics gets a list of statistics about a single table and its indexes. Use this 

function only when you are connected to an ODBC data source. 

SQLStatistics returns information as a standard result set ordered by 

NON.UNIQUE, TYPE, INDEX.QUALIFIER, INDEX.NAME, and 

SEQ.IN.INDEX. The result set combines statistics for the table with statistics for 

each index. 

Note: SQLStatistics might not return all indexes. For example, a driver might return 

only the indexes in files in the current directory. Applications can use any valid index 

regardless of whether it is returned by SQLStatistics. 

Parameters 




schema Qualifier name for tablename. If a driver supports qualifiers for some 

tables but not others, use an empty string for tables that do not have 

qualifiers. 

owner Name of the owner of the table. If a driver supports owners for some table 

but not others, use an empty string for tables that do not have owners. 

SQLStatistics Parameters 

SQLStatistics 1-855


tablename Name of the table. 

index.type One of the following: 

SQL.INDEX.UNIQUE 

SQL.INDEX.ALL 

Return Values 

The following table describes the return values of the SQLStatistics function. 


accuracy The importance of the CARDINALITY and PAGES columns in the result 

set: 

SQL.ENSURE – The driver unconditionally gets the statistics. 

SQL.QUICK – The driver gets results only if they are readily available 

from the server. The driver does not ensure that the values are current. 

SQLStatistics Parameters 


0 SQL.SUCCESS 




SQLStatistics Return Values

The lengths of VARCHAR columns are maximums; the actual lengths depend on the 

data source. Use SQLGetInfo to determine the actual lengths of the 

TABLE.QUALIFIER, TABLE.OWNER, TABLE.NAME, and COLUMN.NAME 

columns. 


TABLE.QUALIFIER Varchar(128) Table qualifier identifier (schema) of the 

table. The null value is returned if it is not 

applicable to the data source. If a driver 

supports qualifiers for some tables but not 

others, it returns an empty string for tables 

without qualifiers. 

TABLE.OWNER Varchar(128) Name of the owner of the table. The null 

value is returned if it is not applicable to the 

data source. If a driver supports owners for 

some tables but not others, it returns an empty 

string for tables without owners. 

TABLE.NAME Varchar(128) 

Not null 

Name of the table. 

NON.UNIQUE Smallint The index prohibits duplicate values: 

TRUE if the index values can be nonunique. 

FALSE if the index values must be unique. 

NULL if TYPE is SQL.TABLE.STAT. 

INDEX.QUALIFIER Varchar(128) Index qualifier identifier used by the DROP 

INDEX statement. The null value is returned 

if the data source does not support index 

qualifiers or if TYPE is SQL.TABLE.STAT. 

If a nonnull value is returned, it must be used 

to qualify the index name in a DROP INDEX 

statement, otherwise the TABLE.OWNER 

name should be used to qualify the index 

name. 

INDEX.NAME Varchar(128) Name of the index. The null value is returned 

if TYPE is SQL.TABLE.STAT. 

SQLStatistics Results 

SQLStatistics 1-857

TYPE Smallint 

Not null 



Type of information returned: 

SQL.TABLE.STAT indicates a statistic for 

the table. 

SQL.INDEX.CLUSTERED indicates a 

clustered index. 

SQL.INDEX.HASHED indicates a hashed 

index. 

SQL.INDEX.OTHER indicates another type 

of index. 

SEQ.IN.INDEX Smallint Column sequence number in index, starting 

with 1. The null value is returned if TYPE is 

SQL.TABLE.STAT. 

COLUMN.NAME Varchar(128) Name of a column. If the column is based on 

an expression, the expression is returned. If 

the expression cannot be determined, an 

empty string is returned. If the index is 

filtered, each column in the filter condition is 

returned (this may require more than one 

row). The null value is returned if TYPE is 


COLLATION Char(1) Sort sequence for the column: 

A indicates ascending. 

B indicates descending. 

The null value is returned if the data source 

does not support column sort sequence. 

SQLStatistics Results (continued)


CARDINALITY Integer Number of rows in the table if TYPE is 

SQL.TABLE.STAT. Number of unique 

values in the index if TYPE is not 

SQL.TABLE.STAT. The null value is 

returned if the value is not available from the 

data source or if it is not applicable to the data 

source. 

PAGES Integer Number of pages for the table if TYPE is 

SQL.TABLE.STAT. Number of pages for the 

index if TYPE is not SQL.TABLE.STAT. The 

null value is returned if the value is not 

available from the data source or if it is not 

applicable to the data source. 

FILTER.CONDITION Varchar(128) If the index is filtered, the filter condition, or 

an empty string if the filter condition cannot 

be determined. 

The null value is returned if the index is not 

filtered, or if it cannot be determined that the 

index is filtered, or TYPE is 


If the row in the result set corresponds to a table, the driver sets TYPE to 

SQL.TABLE.STAT and sets the following columns to NULL: 

NON.UNIQUE 

INDEX.QUALIFIER 

INDEX.NAME 

SEQ.IN.INDEX 

COLUMN.NAME 

COLLATION 

SQLStatistics Results (continued) 

If CARDINALITY or PAGES are not available from the data source, the driver sets 

them to NULL. 

For complete details about the SQLStatistics function, see the Microsoft ODBC 2.0 

Programmer’s Reference and SDK Guide. 

SQLStatistics 1-859

SQLTables 

Syntax 

status = SQLTables (statement.env, schema, owner, tablename, type) 



Description 

SQLTables returns a result set listing the tables matching the search patterns. Use this 

function only when you are connected to an ODBC data source. 

This function returns statement.env as a standard result set of five columns containing 

the schemas, owners, names, types, and remarks for all tables found by the search. 

The search criteria arguments can contain a literal, an SQL LIKE pattern, or be 

empty. If a literal or LIKE pattern is specified, only values matching the pattern are 

returned. If a criterion is empty, tables with any value for that attribute are returned. 

owner cannot specify a LIKE pattern. 

Parameters 





schema Schema name search pattern. 

owner Table owner number search pattern. 

tablename Table name search pattern. 

type Table type (one of the following: BASE TABLE, VIEW, 

ASSOCIATION, or TABLE) search pattern. 

SQLTables Parameters

You can access the result set with SQLFetch. These five columns have the following 

descriptors: 

Special Search Criteria 

Three special search criteria combinations enable an application to enumerate the set 

of schemas, owners, and tables: 

Table 

Qualifier 

Column Name Data Type 

TABLE.SCHEMA VARCHAR(128) 

TABLE.OWNER VARCHAR(128) 

TABLE.NAME VARCHAR(128) 

TABLE.TYPE VARCHAR(128) 

REMARKS VARCHAR(254) 

SQL Tables Results 

Table 

Owner Table Name Table Type Return Is ... 

% empty string empty string ignored Set of distinct 

schema names 

empty string empty string ignored Set of distinct table 

owners 

empty string empty string empty string % Set of distinct table 

types 

Special Search Criteria for Enumerating the Set of Schemas, Owners, and 

Tables 

The ability to obtain information about tables does not imply that you have any privileges 

on those tables. 

SQLTables 1-861

Return Values 

The following table describes the return values of the SQLTables function. 


The following table describes the SQLSTATE values. 

SQLSTAT 

E Description 



0 SQL.SUCCESS 




SQLTables Return Values 



S1008 Cancelled. Execution of the statement was stopped by an SQLCancel call. 

S1010 Function sequence error. The statement.env specified is currently executing 

an SQL statement. 

S1C00 The table owner field was not numeric. 

24000 Invalid cursor state. Results are still pending from the previous SQL 

statement. Use SQLCancel to clear the results. 

42000 Syntax error or access violation. This can be caused by a variety of reasons. 

The native error code returned by the SQLError call indicates the specific 

error that occurred. 

SQLSTATE Values

SQLTransact 

Syntax 

status = SQLTransact (bci.env, connect.env, type) 



Description 

SQLTransact requests a COMMIT or ROLLBACK for all SQL statements 

associated with a connection or all connections associated with an environment. Use 

this function only when you are connected to an ODBC data source. 

This function provides the same transaction functions as the UniBasic statement 

TRANSACTION COMMIT. When connect.env is a valid connection environment 

with SQL.AUTOCOMMIT set to OFF, SQLTransact commits the connection. 

To use SQLTransact, all of the following conditions must be met: 

The SQL.PRIVATE.TX option of SQLSetConnectOption is set to 

SQL.PRIVATE.TX.ON. 

The SQL.AUTOCOMMIT option is set to SQL.AUTOCOMMIT.OFF. 

The connection is active. 

Setting bci.env to a valid environment handle and connect.env to SQL.NULL.HDBC 

requests the server to try to execute the requested action on all hdbcs that are in a 

connected state. 

If any action fails, SQL.ERROR is returned, and the user can determine which 

connections failed by calling SQLError for each connection environment in turn. 

If you call SQLTransact with a type of SQL.COMMIT or SQL.ROLLBACK when 

no transaction is active, SQL.SUCCESS is returned. 

SQLTransact 1-863

Parameters 



Return Values 

The following table describes the return values of the SQLTransact function. 


bci.env UniData BCI environment. 

connect.env Connection environment or SQL.NULL.HDBC. 

type One of the following: 

SQL.COMMIT – Writes all modified data to the data source, releases all 

lock acquired by the current transaction, and terminates the transaction. 

SQL.ROLLBACK – Discards any changes written during the transaction 

and terminates it. 

SQLTransact Input Variables 

Return 


0 SQL.SUCCESS 



SQLTransact Return Values


The following table describes the SQLSTATE values for the SQLTransact function. 

SQLSTAT 

E Description 



S1012 type did not contain SQL.COMMIT or SQL.ROLLBACK. 

08003 No connection is active on connect.env. 

08007 The connection associated with the transaction failed during the execution of 

the function. It cannot be determined if the requested operation completed 

before the failure. 


SQLTransact 1-865

SQRT 

Syntax 

SQRT(num.expr) 

Description 

The UniBasic SQRT function returns the square root of a positive numeric argument. 

Example 

In the following example, the program statement prints SQUARE ROOT OF 16 IS 4: 


PRINT "SQUARE ROOT OF 16 IS ":SQRT(16)

SQUOTE 

Syntax 

SQUOTE(str.expr) 

Description 

The UniBasic SQUOTE function encloses a string with single quotation marks. 

Examples 

In the following example, the program statement prints ‘This is ‘a’ test’ on the screen: 

PRINT SQUOTE("This is 'a' test") 

In the next example, the program segment prints ‘This is another test’ on the screen: 

X = "This is another test" 

PRINT SQUOTE(X) 



QUOTE 

SQUOTE 1-867

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. Arguments can be any valid 

numbers or string numbers of any magnitude or precision. 






result of 0. 

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. 

Example 

In the following example, the program statement assigns to B the result of subtracting 

1.4149 from A, and then prints the answer 98.5851: 

A = 100 

B = SSUB(A, "1.4149") 

PRINT B 


STATUS 

Syntax 

STATUS( ) 

Description 

The UniBasic STATUS function returns a code indicating the condition of the 

command or function just executed. 

Several UniBasic commands and functions set STATUS function return values. For 

information about the return values set by a particular command or function, see 

Appendix F, “Commands That Set STATUS() Return Values.” 

Example 

In the following example, the STATUS function returns a value of 0, indicating a 

successful conversion of a valid date by OCONV. STATUS would return 1 if 7334 

were an invalid input date or 2 if D were an invalid conversion specification. 

PRINT OCONV(7334,"D") 

PRINT STATUS() 



SYSTEM 

@variables – For information, see Appendix B, “UniBasic@variables.” 

STATUS 1-869

STOP 

Syntax 

STOP [expr] 

Description 

The UniBasic STOP command halts execution of the current program. If you specify 

an expression, UniData prints the expression on the display terminal before halting 

the program. expr can contain variables, functions, and arithmetic or string operators. 

STOP returns the cursor to the UniData prompt, a calling menu, or a calling 

paragraph, depending on how the program was executed. 

Tip: The ABORT command returns the cursor to UniData level regardless of what 

process initiated the program. 

Note: The STOP command performs differently with BASICTYPE P. The following 

syntax is valid in BASICTYPE P: 

STOP [message-id] 

STOP [expr,...] 

message-id must evaluate to a key contained in UniData error message file ERRMSG. 

expr can contain variables, functions, 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 'CLIENTS' READONLY TO CLIENT.FILE ELSE STOP "Cannot Open" 

READ REC FROM CLIENTR, CLIENT.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. 

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 



ABORT 

STOP 1-871

STR 

Syntax 

STR(str.expr, num.expr) 

Description 

The UniBasic STR function returns a string composed of a number of repetitions of 

a string. 


If a function encounters the null value in a parameter when a number is expected 

(num.expr), a warning message displays, and UniBasic uses 0. 

Parameters 



Example 

In the following example, the program statement prints a string of 25 hyphens on the 

terminal screen: 

PRINT STR("-",25) 


str.expr Specifies a string expression to concatenate num.expr times. 

num.expr Specifies the number of repetitions of the string expression to concatenate. 

STR Parameters



STRS 

STR 1-873

STRS 

Syntax 

STRS(dyn.array, expr) 

Description 

The UniBasic STRS function returns each element of dyn.array the number of times 

specified in expr. 


If a function encounters the null value in a parameter when a number is expected 

(expr), a warning message displays, and UniBasic uses 0. 

Example 

In the following example, the program segment prints the each element of the ARR1 

dynamic array 10 times: 


ARR1 = 1:@AM:2:@AM:3:@AM:4:@AM:5 

ARR2 = STRS(ARR1,10) 

PRINT ARR2 


1111111111}2222222222}3333333333}4444444444}5555555555 



STR

submitRequest 

Syntax 

submitRequest(request_handle, time_out, post_data, response_headers, 

response_data, http_status) 



Description 

The submitRequest function submits a request and gets a response. 

The request is formed on the basis of default HTTP settings and previous setRequestHeader() 

and addRequestParameter() values. Specifically, for a GET 

method with parameters added, UniBasic creates a parameter string (properly 

encoded) and attaches to the URL string after the ‘?’ character. 

For a POST request with non-empty post_data, the data is attached to the request 

message as is. No encoding is performed, and any parameters added through addRequestParameter() 

will be totally ignored. Otherwise the following processing will 

be performed. 

For a POST request with default content type, the parameter string will be assembled, 

a Content-Length header created, and then the string is attached as the last part of the 

request message. 

For a POST request with multipart/* content type, a unique boundary string is created 

and then multiple parts will be generated in the sequence they were added through 

calling addRequestParameter(). Each will have a unique boundary, followed by 

optional Content-* headers, and data part. The total length is calculated and a 

Content-Length header is added to the message header. 

The request is then sent to the Web server identified by the URL supplied with the 

request and created through createRequest() (maybe through a proxy server). 

UniBasic is then waiting for the web server to respond. Once the response message 

is received, the status contained in the response is analyzed. 

submitRequest 1-875

If the response status indicates that redirection is needed (status 301, 302, 305 or 

307), it will be performed automatically, up to five consecutive redirections (the limit 

is set to prevent looping, suggested by RFC 2616). 

If the response status is 401 or 407 (access denied), the response headers will be 

examined to see if the server requires (or accepts) Basic authentication. If no Basic 

authentication request is found, the function will return with an error. Otherwise 

default Authentication (set by setHTTPDefault) will be used to resend the request. 

If no default authentication is set, and no other cached user authentication is found, 

the function will return with an error. 

If the user provides authentication information through “Authorization” or “Proxy- 

Authorization” header, the encoded information is cached. If later, a Basic authentication 

request is raised, no default authentication is found, and only one 

user/password encoding is cached, then it will be used to resend the request. 

The response from the HTTP server is disposed into response_header and 

response_data. It is the user’s responsibility to parse the headers and data. UniBasic 

only performs transfer encoding (chunked encoding), and nothing else is done on the 

data. In other words, content-encoding (gzip, compress, deflate, and so forth) are 

supposed to be handled by the user, as with all MIME types. 

Also, if a response contains header “Content-type: multipart/*”, all the data (multiple 

bodies enclosed in “boundary delimiters”, see RFC 2046) will be stored in 

response_data. It is the user’s responsibility to parse it according to “boundary” 

parameter. 

Parameters 





time_out The timeout value (in milliseconds) before the wait response is 

abandoned. 

post_data The data sent with the POST request. 

submitRequest Parameters


response_headers A dynamic array to stre header/value pairs. 

response_data The resultant data (may be in binary format). 

http_status A dynamic array containing the status code and explanatory text. 

submitRequest Parameters 



0 Success. 


2 Timed out. 

3 Network Error. 

4 Other Errors. 


submitRequest 1-877

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 noncomment 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 SUBROUTINE statement must match, although variable names do not need 

to be the same. Changes made to arguments in the subroutine retain their new values 

when UniData exits the subroutine and control reverts to the calling program. 

When calling a subroutine from UniData ODBC, the subroutine name cannot contain 

any special characters. 

Note: All subroutines must be cataloged using the ECL CATALOG command before 

being called. For more information about the CATALOG command, see the UniData 


Parameters 




sub.name Specifies the subroutine name. 

(argument1 ,argument2 ...) Specifies arguments to pass to the subroutine. The 

arguments can be simple variables, dynamic arrays, or 

dimensioned arrays. 

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. The subroutine, 

COMP, renames the passed arguments, calculates their average, and returns the result 

in the third variable. 

This is the main program: 

REM Main program 

PRINT "Enter A,B:":; INPUT A; INPUT B 

CALL COMP(A,B,C) 

PRINT "Average = ":C 

STOP 

This is the subroutine: 

REM Calculates average of two numbers 

SUBROUTINE COMP(X,Y,Z) 

Z = (X+Y)/2 

RETURN 

END 

The sample program in Appendix A, “Sample Program,” in Developing UniBasic 

Applications includes the following subroutine, which is called by the main program 

to display messages on the screen: 

SUBROUTINE DISPLAY_MESSAGE(MESSAGE) 

DISPLAY @(5,20):MESSAGE 

DISPLAY @(5,21):"Press the (Return) key.": 


RETURN 



CALL, PROGRAM, SUBROUTINE (Update Trigger), SUBROUTINE (Delete 

Trigger) 

UniData 

BASIC, CATALOG – For information, see the UniData Commands Reference. 

SUBROUTINE 1-879

SUBROUTINE (Update Trigger) 

Syntax 

SUBROUTINE trigname(execstat, dictflag, filename, record.ID.expr, recordval) 

FUNCTION trigname(dictflag, filename, record.ID.expr, recordval) 

Description 

Triggers enforce user-defined constraints that must be met before data can be 

updated. The trigger is associated with the data file, so it verifies any access to the 

data. A UniBasic trigger subroutine or function serves as an UPDATE trigger. The 

SUBROUTINE or FUNCTION definition must be the first line in the UniBasic 

trigger. 

You must include a RETURN statement in the function: 

RETURN [execstat] 

Points to Remember 


When you attempt to update a record, UniData calls the trigger, passing the 

file name, DICT if dictionary file, record ID, and the input value before 

updating the record. The subroutine returns the execution status and the new 

record value. 

If the update request fails, the subroutine must return an execstat value of 0. 

If the request passes, the return value must be 1. 

Tip: You can call a C routine from the UniBasic subroutine or function that is called 

from a trigger.

Parameters 


Paragraph Description 

trigname Name of the globally cataloged subroutine. 

execstat Execution status returned by the trigger subroutine: 

0 – No updates allowed. 

1 – Update is allowed. 

2 – Update is allowed; uses the return recordval. 

dictflag “DICT” – Indicates that the trigger is operating on the dictionary file. 

“” – Indicates that the trigger is operating on the data file. 

The quotation marks are required. 

filename The name of the file on which the trigger is operating. 

record.ID.expr The record to be updated. 

recordval The input record value submitted to the UPDATE trigger. recordval is 

both an input and output parameter. The trigger can change this value 

(for example, by performing a conversion). Then, if the trigger sets 

execstat to 2, this value is passed back in recordval and updates the data 

record. Only strings and numbers are valid. 

If the value returned in recordval is invalid, the record is not updated, 

even if the trigger subroutine sets execstat to 2. In this case, the 

UniBasic STATUS function returns 3 when executed immediately after 

the command that calls the trigger. Only strings and numbers are valid. 

SUBROUTINE Update Trigger Parameters 


After you execute a trigger subroutine, the STATUS function returns one of the 


SUBROUTINE (Update Trigger) 1-881

Tip: The UniBasic STATUS function returns the status of the preceding command. 

You can place it within the trigger subroutine to learn about the status of individual 

commands executed within the trigger. If you place it immediately after the statement 

that calls the trigger, it returns the status of the UniBasic command as determined by 

the trigger. The trigger subroutine also returns a value indicating its status in the 

parameter execstat. These values returned in execstat are listed in the Parameters 

section. 

Return 


0 No error. 

Examples 

The following example begins with an UPDATE trigger subroutine called TRIG1. 

Because the return status is always 0, no record in the file can be updated. 


1 System error, such as a damaged file. 

2 Constraint violation. In this case, the UniBasic trigger subroutine returns a 

value of 0 in the parameter execstat, indicating that the update or delete is not 

allowed. 

3 Trigger execution error or unexpected return from trigger routine (for 

example, the trigger subroutine is not cataloged). 


SUBROUTINE 

TRIG1(exec.stat,dict.flag,trig.name,rec.id.expr,rec.val) 

exec.stat=0 

RETURN 

Next, we create the trigger, associate it with the ORDERS file, and list the triggers 

associated with the ORDERS file: 

:CREATE.TRIGGER ORDERS TRIG1 UPDATE 

:LIST.TRIGGER ORDERS 

BEFORE UPDATE TRIGGER: TRIG1 

BEFORE DELETE TRIGGER: not defined

Finally, we attempt to copy record 969 into record 970 in the ORDERS file, and the 

trigger prevents the copy: 

:COPY FROM ORDERS TO ORDERS 969,970 

Cannot update 970, due to trigger constraint. 

0 records copied 

SUBROUTINE (Update Trigger) 1-883

SUBROUTINE (Delete Trigger) 

Syntax 

SUBROUTINE trigname(execstat, dictflag, filename, record.ID.expr) 

FUNCTION trigname(dictflag, filename, record.ID.expr) 

Description 

A UniBasic subroutine or function serves as the DELETE trigger that is executed 

when you attempt to delete a record in the subject file. The SUBROUTINE or 

FUNCTION definition must be the first line in the UniBasic trigger subroutine. 

You must include a RETURN statement in the function: 

RETURN [execstat] 

Points to Remember 

Remember the following items when writing a subroutine that is triggered by a user 

attempting to delete a record: 


When you attempt to delete a record, UniData calls the trigger, passing the 

file name, DICT if dictionary file, record ID, and the input value before 

deleting the record. The subroutine returns the execution status. 

If the delete request fails the constraint, the subroutine must return a status 

of 0. If the request passes, the return must be 1. 

Tip: You can call a C routine from the UniBasic subroutine or function that is called 

from a trigger.

Parameters 



trigname Name of the globally cataloged subroutine. 

execstat Execution status returned by the trigger subroutine. Valid values for this 

include: 

0 – Delete is not allowed. 

1 – Delete is allowed. 

dictflag “DICT” – Indicates that the trigger is operating on the dictionary file. 

“” – Indicates that the trigger is operating on the data file. 

The quotation marks are required. 

filename Name of the file the trigger is operating on. 

record.ID.expr Record to be deleted. 

SUBROUTINE Delete Trigger Parameters 


After you execute a trigger subroutine, the STATUS function returns one of the 


SUBROUTINE (Delete Trigger) 1-885

Tip: The UniBasic STATUS function returns the status of the preceding command. 

You can place it within the trigger subroutine to learn about the status of individual 

commands executed within the trigger. If you place it immediately after the statement 

that calls the trigger, it returns the status of the UniBasic command as determined by 

the trigger. The trigger subroutine also returns a value indicating its status in the 

parameter execstat. These values returned in execstat are listed in the “Parameters” 

section. 


0 No error. 

Example 

The following example begins with a DELETE trigger subroutine called DEL_TRIG. 

This subroutine always returns 1 and always allows records to be deleted: 



2 Constraint violation. In this case, the UniBasic trigger subroutine 

returns a value of 0 in the parameter execstat, indicating that the update 

or delete is not allowed. 




SUBROUTINE 

DEL_TRIG(exec.stat,dict.flag,trig.name,rec.id.expr,rec.val) 

exec.stat=1 

RETURN 

Note: After creating and compiling the subroutine, you must catalog it globally. 

Next, we create the trigger and associate it with the ORDERS file: 

:CREATE.TRIGGER ORDERS DEL_TRIG DELETE 

Finally, we delete records in the ORDERS file. The trigger always allows the deletion 

because the subroutine sets the execution status to 1. 

:DELETE ORDERS 912 

'912' deleted. 

:

SUBSTRINGS 

Syntax 

SUBSTRINGS(dyn.array, num.expr1, num.expr2) 

Description 

The UniBasic SUBSTRINGS function extracts strings from elements within a 

dynamic array. SUBSTRINGS supports multibyte languages. 

Parameters 



dyn.array Specifies the dynamic array from which to extract the substring. 

num.expr1 Specifies a starting position for the extraction operation. 

num.expr2 Specifies the number of characters to return. 

SUBSTRINGS Parameters 

Example 

In the following example, the program segment extracts the first character of each 

element of the dynamic array LASTNAMES. This results in S}J}J}H. 

LASTNAMES = "Smith":@AM:"Jones":@AM:"Johnson":@AM:"Howard" 

LINITIAL = SUBSTRINGS(LASTNAMES,1,1) 

PRINT LINITIAL 

SUBSTRINGS 1-887



DEL, INSERT, REMOVE, REPLACE 


SUM 

Syntax 

SUM(dyn.array [, ] [, 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. You can input a range, starting position, and 

level at which to perform the sum. 

Note: The SUM function can contain a maximum of 1621 characters. 

Parameters 



dyn.array Specifies a dynamic array of numeric values to sum. 

, , start.expr 

, stop.expr 

Specifies a range within the dynamic array to sum. The range is 

specified as an attribute, a value, a starting point, and a stopping 

point. 

SUM Parameters 

Tip: To sum all elements in an array, execute SUM twice. The first execution sums 

each group of subvalues and returns a string of numeric values; the second SUM 

returns a single value. 

SUM 1-889

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) 


VAL1 = 22:@VM:30 

In the next example, the program statement sums VAL1 and returns the numeric 

value 52 with no dynamic array delimiters: 

VAL1 = SUM(VAL1)

SWAP 

Syntax 

SWAP str.expr1 WITH str.expr2 IN var 

Description 

The UniBasic SWAP command replaces all occurrences of one substring with a 

second substring. The search string does not have to be the same length as the 

replacement string. SWAP supports mulitbyte languages. 

Tip: CONVERT compares and replaces substrings on a character-by-character 

basis. CONVERT cannot exchange strings of different lengths. 

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 

SWAP 1-891

In the next example, SWAP does not replace a character with a character, but it 

replaces a string with a string. The program segment prints HARRY BELAFONTE. 


STRING = 'MARION BELAFONTE' 

SWAP 'MARION' WITH 'HARRY' IN STRING 

PRINT STRING 

The following program first creates a string that contains the null value, then calls a 

subroutine that converts UniData delimiters and the null value to characters that can 

be displayed or printed. Next, the program swaps the null value for another string 

(“def”), calls the conversion subroutine again, and prints the string again. 

A = @AM:"abc":@VM:@NULL:@VM:"ghi":@AM:"jkl" 

B = A 

CALL null.swap(B) 

PRINT B 

SWAP @NULL WITH "def" IN A 

B = A 

CALL null.swap(B) 

PRINT B 

The called subroutine is: 

SUBROUTINE null.swap(B) 

SWAP @NULL WITH "null" IN B 

SWAP @AM WITH " " IN B 

SWAP @VM WITH " " IN B 

SWAP @SM WITH " " IN B 

RETURN 

This program prints: 

:RUN BP null.swap.test 

abc null ghi jkl 

abc def ghi jkl 



CONVERT

SYSTEM 

Syntax 

SYSTEM(expr) 

Description 

The UniBasic SYSTEM function retrieves certain system-level parameters set by 

UniBasic statements or by ECL commands such as SETPTR, TERM, and query 

statements. 

Note: The SYSTEM function is similar to the STATUS function and several of the 

@variables featured in Appendix B, “UniBasic@variables.” The SYSTEM and 

STATUS functions return the same values after execution of UniBasic commands and 

functions. 

Parameters 

expr must be a number from 0 through 16. If you specify 0, the value of SYSTEM is 

determined by a previously executed UniBasic command. If you specify a number 

from 1 through 16, UniData returns predefined system parameters as described in the 

following table. UniBasic returns the original value when expr is invalid. 


1 1 – PRINTER ON or (P) option is specified. Output is printed on the system 

printer. 

0 – Output is printed to the 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. 

SYSTEM Parameters 

SYSTEM 1-893



6 Current number of lines printed on the terminal or printer page. 

7 Terminal type. 

8 Current tape block size. 

9 Current CPU millisecond count from the start of the program. 

10 1 – The current stack (STON) condition is enabled. 

0 – Current stack is inactive. 

11 n – A SELECT list is active. n = # of items selected. 

0 – No SELECT list is active. 

12 Current time in milliseconds (local time). 

13 Sleeps one second. 

14 Number of characters in the type-ahead buffer. If the number of characters 

in the internal buffer exceeds 511 bytes, this parameter returns 511. 

15 Returns command options as a character string. 

16 Run level, same as @LEVEL. 

17 Indicates where UniData transfers control of a UniBasic program when the 

next RETURN statement executes. 

0 – Program 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 interrupt key is set. If the value is 0, the 

interrupt key is enabled. For all other values, the interrupt key is disabled. 

To enable the interrupt key, you must match the number of BREAK OFF 

statements in a program with an equal number of BREAK ON statements 

to bring the value of SYSTEM(30) to 0. 

31 Returns the value of $UDTHOME. 

32 Returns current BASICTYPE. 

SYSTEM Parameters (continued)


33 Returns the implementation of UniData that is currently running, such as 

UNIX or a Windows platform. 

34 Not currently used. 

35 The language. 

36 Shows the current setting for DATE.FORMAT: 

0 – Date format is MM/DD/YY. 

1 – Date format is DD/MM/YY. 

37 The character used to separate thousands. 

38 The character used as the decimal point. 

39 The character used for the dollar sign. 

40 Returns the name of the program being run. 

41 Returns the UniData product serial number. 

42 Returns the ASCII value of @RM. 

43 Returns the ASCII value of the print control character. (Default print 

control character is 192.) 

44 Returns the ASCII value of @NULL. 

45 Returns the version, including patch number, of UniData currently running. 

If it is different from the version number stored in the VOC file, an asterisk 

is appended to the version number. 

The operating system-level updatevoc command updates the VOC file from 

the latest installation or patch. 

48 Returns the name of the COMO file automatically created by a PHANTOM 

process. This function is available to the process the PHANTOM process 

spawned, not to the parent process. 

49 Returns the calling stack for the UniBasic program at runtime. The calling 

stack is stored in a dynamic array with each line represented as a separate 

field. Each field is separated into three values (the sequence number, the 

object name, and the line number), and the values are separated by value 

marks. 

SYSTEM Parameters (continued) 

SYSTEM 1-895



50 The UniBasic SYSTEM(50) function returns a list of files open in UniBasic 

as a dynamic array. The first field is multivalued, and contains the following 

information: 

Value 1 – The maximum number of files that can be opened system-wide. 

Value 2 – The current number of hashed files open in UniBasic. 

Value 3 – The current number of dynamic hashed files open in UniBasic. 

Value 4 – The current number of recoverable hashed files open in UniBasic. 

Value 5 – The current number of sequential and OS-level files open in 

UniBasic. 

Value 6 – The current number of index files open in UniBasic. 

Value 7 – The current number of temporarily closed files in UniBasic. 

51 Returns information about device licensing. If you are not using device 

licensing, SYSTEM(51) returns a null string. 

52 Returns the entire command stack for the UniBasic program at runtime. The 

command stack is stored in a dynamic array. Commands are separated by 

attribute marks (@FM). 

512 

(Windows 

platforms 

only) 

In a UDTelnet session, returns the IP address. In a console session, returns 

the word “Console”. 

513 Returns the current UniData version and build number. 

514 Returns the number of UniData users currently logged in. SYSTEM(514) 

does not include phantoms. 

515 

(Windows 

NT or 

Windows 

2000 only) 

516 

(Windows 

only) 

Returns the localized name of the Administrators group. The group name 

differs based on the localized version of Windows. 

Note - SYSTEM(515) lets UniData SQL create privilege table records for 

items owned by the Administrators group, even if the Windows version is 

not an English-language version. 

Returns 1 if the user is a member of the local Administrators group. 

Otherwise, returns 0. 

9010 Returns the type of database. This function returns UD if the database is 

UniData, or UV if the database is UniVerse. If the database is the UniData 

Personal Edition, the function returns UD.PE. 

SYSTEM Parameters (continued)

Example 

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 

SYSTEM 1-897

TAN 

Syntax 

TAN(num.expr) 

Description 

The UniBasic TAN function returns the trigonometric tangent of a numeric 

expression, num.expr. 

Example 

In the following example, the program statement prints 0.2679, the tangent of the 

argument 15: 

PRINT TAN(15) 


ACOS, ASIN, ATAN, COS, SIN 


TIME 

Syntax 

TIME( ) 

Description 

The UniBasic TIME function returns the time of day in internal format, expressed as 

the number of seconds elapsed since midnight. 

Note: The TIME function has no arguments. 

Examples 

In the following example, the program statement prints the time of day in internal 

format. If the time is 1:01 A.M., UniData prints the value 3660, the number of 

seconds since midnight in internal format. 

PRINT TIME() 

In the next example, the TIME function is used in conjunction with the OCONV 

function for conversion to external format: 

PRINT OCONV(TIME(),"MT") 



DATE, ICONV Date (D), OCONV Date (D), TIMEDATE 

TIME 1-872

TIMEDATE 

Syntax 

TIMEDATE( ) 

Description 

The UniBasic TIMEDATE function returns a string representation of the current 

time and date in the following external format: 

hh:mm:ss dd mmm yyyy 

Example 

In the following example, the program statement assigns the string representation of 

the current time and date to the variable TSTRING. If the current time and date were 

November 1, 1999, at 11:45 A.M., TSTRING would be “11:45:00 01 NOV 1999”. 

TSTRING = TIMEDATE() 



DATE, ICONV Date (D), OCONV Date (D), TIME 


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 the 

transaction was in progress, and none of the updates associated with the transaction 

take place. 

A transaction can abort due to any of the following conditions, in addition to the 

execution of a TRANSACTION ABORT statement: 

A program finishes before a transaction commit is issued (STOP or END). 

A program chains to another program. 

An error 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 interrupt key during a 

transaction. 

The user is forced to log out or the user process is killed, which terminates 

a program before a transaction commit is issued. 

UniData handles the above abort conditions in the same way it does the TRANS- 

ACTION ABORT statement, by canceling the transaction. 

Tip: You should be aware of these various abort conditions and control the resulting 

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. 

TRANSACTION ABORT 1-874

Example 

In the following example, the transaction process aborts if var is 0: 


TRANSACTION START 

THEN PRINT "Transaction started." 

ELSE PRINT "Transaction start failed, STATUS = ":STATUS(): STOP 

READU var FROM file.var, record1 

var += 2 

IF var = 0 THEN TRANSACTION ABORT; GOTO ERR: 

WRITE var TO file.var, record1 

TRANSACTION COMMIT 

THEN PRINT "Transaction committed." 

ELSE PRINT "Transaction Aborted, STATUS = ":STATUS(); STOP 



TRANSACTION COMMIT, TRANSACTION START


Syntax 

TRANSACTION COMMIT {THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic TRANSACTION COMMIT command concludes the active transaction. 

UniData writes all pending writes to the appropriate files. You must specify a 

THEN clause or an ELSE clause. You can specify both clauses. 

UniData performs the following steps during a transaction commit: 

Disables the interrupt key. 

Writes all updates. 

Releases all record locks locked inside the transaction. 

Executes the THEN clause if it exists. 

Enables the interrupt key. 

Warning: When including WRITE statements within a transaction, you must code an 

ON ERROR clause that takes appropriate action to notify the user and stop the transaction. 

If the transaction is not aborted by the ON ERROR clause, processing 

continues, and the transaction will commit inappropriately. 

TRANSACTION COMMIT 1-876

Parameters 




After you execute TRANSACTION COMMIT, the STATUS function returns one of 

the values described in the following table. 


THEN statements END THEN executes if the commit is successful. END is required to 


ELSE statements END ELSE executes if the commit is not successful because no transaction 

is active or the record (or ID) does not exist. END is 

required to terminate multiline ELSE statements. 

UniData performs the following steps when a commit fails: 

Aborts the transaction. 

Executes the ELSE clause if it exists. 

Releases all record locks inside the transaction. 

TRANSACTION COMMIT Parameters 


0 The commit completed successfully. 

1 Transaction not started. 

3 Transaction cannot commit. 


Examples 

The program segment below is taken from the sample program in Appendix A, 

“Sample Program, in Developing UniBasic Applications. The segment executes the 

UniBasic function STATUS if the commit is not successful, but does not abort the 

transaction. However, when an error occurs, the transaction will never be committed 

and will automatically abort when the program terminates. 

TRANSACTION COMMIT ELSE 

IF STATUS() = 1 THEN 

DISPLAY "The TRANSACTION was not started" 

END ELSE 

DISPLAY "The TRANSACTION could not be committed." 

END 

END 

In the following example, the TRANSACTION COMMIT command ends the transaction 

process and writes the new record to the database. Otherwise, it prints the 

return value of the UniBasic STATUS function. 


THEN PRINT "Transaction committed." 

ELSE PRINT "Transaction aborted, STATUS = ":STATUS(); STOP 



TRANSACTION ABORT, TRANSACTION START 

TRANSACTION COMMIT 1-878

TRANSACTION START 

Syntax 

TRANSACTION START {THEN statements [END] | ELSE statements [END]} 

Description 

The UniBasic TRANSACTION START command initiates a new transaction, 

storing all updates until a TRANSACTION COMMIT or TRANSACTION ABORT 

statement executes. 

Warning: When you include WRITE statements within a transaction, you must code 

an ON ERROR clause that takes action to notify the user and take appropriate action, 

such as stopping the transaction. If the transaction is not aborted by the ON ERROR 

clause, processing continues, and the transaction could commit inappropriately. 

Parameters 




THEN statements END THEN executes if the TRANSACTION START is successful. 

END is required to terminate multiline THEN statements. 

ELSE statements END ELSE executes if the TRANSACTION START is not 

successful, the record or ID does not exist, or a transaction is 

already active. END is required to terminate multiline ELSE 

statements. 

TRANSACTION START Parameters


After you execute TRANSACTION START, the STATUS function returns one of the 


Example 

The following program segment displays a message if a transaction is already started 

when TRANSACTION START is executed: 

TRANSACTION START ELSE 

IF STATUS() = 1 THEN 

DISPLAY "A Transaction had already been started, NESTED 

Transactions" 

DISPLAY "are NOT Allowed. (Contact System Administrator)" 


END 

END 




0 The transaction was started. 

1 The transaction was not started. 


TRANSACTION COMMIT, TRANSACTION COMMIT 

TRANSACTION START 1-880

TRIM 

Syntax 

TRIM(str.expr[,char[,type]]) 

Description 

The UniBasic TRIM function removes all spaces or every occurrence of a specified 

character from a string expression. If UniData does not find an occurrence of the 

specified character, the string remains unchanged. TRIM removes leading or trailing 

occurrences of the specified character from a string, and converts embedded spaces 

or occurrences of the specified characters in a string to one space or a specified 

character. UniData does not remove single spaces or occurrences of the specified 

character embedded in the string. 

Parameters 




str.expr Specifies a string from which to remove spaces or the specified character. 

,char Specifies a character to remove from str.expr. The default is a space. 

,type Specifies the type of removal to perform. If char is an empty string, UniData 

does not perform the operation. 

L – Removes all leading occurrences of char. 

T – Removes all trailing occurrences of char. 

B – Removes leading and trailing occurrences of char. 

A – Removes all occurrences of char. 

R – (Default) Removes all leading, trailing, and contiguous occurrences of 

char. 

TRIM Parameters

Note: IBM recommends that you do not use the TRIM function on dynamic arrays. 

For BASICTYPEs M and P, some leading and trailing spaces or occurrences of a 

specified character are not removed from elements in a dynamic array. For example, 

for BASICTYPE M or P, the following program segment: 

P = “**Fred**Smith**”:@VM:”**Jim**Olsen**” 

Q = TRIM(P,”*”) 

produces the following result (notice the asterisks surrounding the delimiter 

character): 

Q = Fred*Smith*}*Jim*Olsen 

For BASICTYPE R or U, the program segment produces the following result: 

Q = Fred*Smith}Jim Olsen 

To get this latter result regardless of BASICTYPE, use the TRIMS function. 

Examples 

In the following example, the program segment removes the leading, trailing, and 

extraneous blanks from the variable NAME: 

NAME = " Zenith, R. " 

NAME = TRIM(NAME) 


NAME = "Zenith, R." 

In the next example, the program segment removes the asterisks from the variables 

X and Y: 

X = TRIM("***NOT***ICE***","*") 

Y = TRIM("***NOT***ICE***","*","A") 


X = "NOT*ICE" 

Y = "NOTICE" 

TRIM 1-882



TRIMB, TRIMF, TRIMS 


TRIMB 

Syntax 

TRIMB(str.expr) 

Description 

The UniBasic TRIMB function removes any trailing spaces from a string expression. 

If UniData does not find any trailing spaces, the string remains unchanged. 

Example 

In the following example, the program statement removes the trailing spaces from the 

variable NAME. This results in NAME = " Zenith, R.". 

NAME = " Zenith, R. " 

NAME = TRIMB(NAME) 



TRIM, TRIMF, TRIMS 

TRIMB 1-884

TRIMF 

Syntax 

TRIMF(str.expr) 

Description 

The UniBasic TRIMF function removes any leading spaces from the string 

expression. If UniData does not find any leading spaces, the string remains 

unchanged. 

Example 

In the following example, the program segment removes the leading spaces from the 

variable NAME, storing the resulting string. This results in "Zenith, R. ". 

NAME= " Zenith, R. " 

NAME = TRIMF(NAME) 



TRIM, TRIMB, TRIMS 


TRIMS 

Syntax 

TRIMS(dyn.array[,char[,type]]) 

Description 

The UniBasic TRIMS function removes any spaces from each element of a dynamic 

array. If UniData does not find any spaces, the element remains unchanged. 

TRIMS removes any leading or trailing spaces from a string and converts any 

contiguous spaces in a string to one space. Single blanks between text are not 

removed. 

Parameters 



dyn.array Specifies a dynamic array from which to remove spaces or the specified 

character. 

,char Specifies a character to remove from elements in dyn.array. The default is a 

space. 

,type Specifies the type of removal to perform. If char is an empty string, UniData 

does not perform the operation. 

L – Removes all leading occurrences of char. 

T – Removes all trailing occurrences of char. 

B – Removes leading and trailing occurrences of char. 

A – Removes all occurrences of char. 

R – (Default) Removes all leading, trailing, and contiguous occurrences of 

char. 

TRIMS Parameters 

TRIMS 1-886

Example 

In the following example, the program segment removes any spaces from each 

element of the dynamic array ARR1: 


ARR1 = " Jones ":@AM:" Smith ":@AM:" Johnson " 

ARR1 = TRIMS(ARR1) 


ARR1 = Jones}Smith}Johnson 



TRIM, TRIMB, TRIMF

UDTEXECUTE 

Syntax 

UDTEXECUTE str.expr [{ASYNC | SYNC} ON connection] 

[CAPTURING dyn.array.var] [RETURNING dyn.array.var] [PASSCOM] 

Description 

The UniBasic UDTEXECUTE command executes a command in ECLTYPE U, 

regardless of the BASICTYPE used when the program was compiled. 

When you compile a program in BASICTYPE P, EXECUTE or PERFORM passes 

the string to execute to a nonstandard UniData parser. This parser looks for a specific 

sentence structure common to BASICTYPE P systems. Standard UniQuery 

sentences might not be handled correctly in this circumstance. Therefore, when you 

want to execute a standard UniQuery statement from within a UniBasic program that 

has been compiled in BASICTYPE P, use the UDTEXECUTE command instead of 

EXECUTE or PERFORM. 

STACKCOMMON 





contents of unnamed common areas are passed to the executed program and 

back to the executing program. 


the contents of unnamed common areas are not passed to the program you 

execute. Instead, they are saved, and the unnamed common areas of the 

called program are initialized to 0. When control is passed back to the 

calling program, it is restored to its value before the program call. Unnamed 

common areas are never passed to a phantom program. 

Note: STACKCOMMON defaults to OFF in BASICTYPEs R and U, but is always on 

in BASICTYPEs M and P. 

UDTEXECUTE 1-889

Parameters 





COMMON, EXECUTE, EXECUTESQL, MDPERFORM, PCPERFORM 

UniData 

STACKCOMMON – For information, see the UniData Commands Reference. 


str.expr Specifies a command to execute. 

ASYNC | SYNC UniData no longer supports this parameter, but it remains for syntax 

compatibility. 

ON connection UniData no longer supports this parameter, but it remains for syntax 

compatibility. 

CAPTURING, 

dyn.array.var 

RETURNING, 

dyn.array.var 

The CAPTURING clause stores the output in a dynamic array 

instead of on the display terminal. Each line of the text becomes an 

attribute in the array. Output sent to the printer is not affected by this 

clause. 

The order of CAPTURING and RETURNING is interchangeable. 

The RETURNING clause captures error messages resulting from the 

command executed with UDTEXECUTE. This variable contains a 

string of error message numbers separated by spaces. If the executed 

command creates a spooler hold file, UniData also returns the hold 

file number in the same variable. 

PASSCOM This parameter is provided for backward compatibility for releases 

before 3.1. 

UDTEXECUTE Parameters

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. 

Example 

In the following example, the program statement returns 0 if FILENAME1 is 

currently assigned a value. It returns 1 if no value is currently assigned. 

X = UNASSIGNED(FILENAME1) 

UNASSIGNED 1-891

UNLOCK 

Syntax 

UNLOCK [num.expr] 

Description 

The UniBasic UNLOCK command unlocks predefined computer resources reserved 

by the LOCK command. Resource numbers range from 0 through 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. 

The lock is associated with num.expr, not the resource. Therefore, a command that 

does not check for locks against the resource number will access the resource even if 

it is locked. For example, an installation might assign locks 1 through 4 to four 

system printers. When an application needs to reserve printer 1, the application 

executes LOCK 1. All other programs must check for locks before accessing the 

resource for the lock to be effective. 

Resources are not automatically unlocked by the termination of the locking program. 

You must use the UniBasic UNLOCK or ECL QUIT commands to release them. You 

also can release resources by executing the ECL CLEAR.LOCKS command at the 

UniData level. 

Example 

In the following example, the program statement unlocks all computer resources 

reserved by the current user: 

UNLOCK 




LOCK 

UniData 

CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS – For information, see the 


UNLOCK 1-893

UPCASE 

Syntax 

UPCASE(string.expr) 

Description 

The UniBasic UPCASE function converts lowercase characters to uppercase. 

Nonalphabetic values are not changed. Special characters, including the null value, 

are not converted by this function. UPCASE does not support multibyte languages. 

Example 

In the following example, the program segment converts “be bold!!” to “BE 

BOLD!!”: 

STRING = 'be bold!!' 

PRINT UPCASE(STRING) 



DOWNCASE, ICONV Masked Character (MC), OCONV Masked Character (MC) 


WAKE 

Syntax 

WAKE pid 

Description 

The UniBasic WAKE command activates a UniData process (pid) that has been 

paused with either the ECL PAUSE command or the UniBasic PAUSE command. If 

the specified process has not already been paused, UniData disregards the next 

PAUSE issued for the process indicated by pid. 

Example 

The following program, WAKEUP, lists paused processes, then prompts for the ID of 

a process to wake up. Next, the program executes the UniBasic WAKE command 

against that process, and then executes LIST.PAUSED again to verify that the process 

was reactivated. 

WAKEUP 

EXECUTE "LIST.PAUSED" 

PRINT "Enter ID for process to wake ": 

INPUT pid 

WAKE pid 

EXECUTE "LIST.PAUSED" 

The following example shows the results of executing the preceding program, 

waking up process 10811: 

1 :RUN BP WAKEUP 

2 Number of Paused Users 

3 ~~~~~~~~~~~~~~~~~~~~~~ 

4 1 

5 

6 UDTNO USRNBR UID USRNAME USRTYPE TTY LEFTTIME 

TOT_TIME 

7 1 10811 1283 carolw udt pts/0 - - 

8 

9 Enter ID for process to wake ?10811 

10 Number of Paused Users 

11 ~~~~~~~~~~~~~~~~~~~~~~ 

12 0 

WAKE 1-896



PAUSE 

UniData 

LIST.PAUSED, PAUSE, WAKE – For information, see the UniData Commands 


UniData Paragraph Command 

SLEEP – For information, see Using UniData. 


WEOF 

Syntax 

WEOF [UNIT(mu.expr)] {THEN statements [END] | 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 the unit number 


The mu.expr is optional, and the default value for UNIT is (00) 

for tape unit 0 with no conversion performed (ASCII assumed). 

Valid options include the following: 





THEN statements END THEN executes if command execution is successful. END is 


ELSE statements END ELSE executes if command execution is not successful or the 

record (or ID) does not exist. END is required to terminate 

multiline ELSE statements. 

WEOF Parameters 

WEOF 1-898


After you execute WEOF, the STATUS function returns one of the values described 


Example 

In the following example, the program statement writes an end-of-file mark to tape 

0. If unable to write the end-of-file mark, UniData executes the ELSE clause. 


WEOF UNIT(00) ELSE "Unable to write an end-of-file" 



READT, RESIZET, REWIND, WRITET 

UniData 











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, which results in the file being truncated at the current 

position. 

Tip: Use WEOFSEQ after a series of WRITESEQ operations. 

Parameters 



seq.file.var Specifies a sequential file variable to which to write the end-of-file mark. 

ON ERROR 

statements 

Example 

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 

Specifies statements to execute if the WEOFSEQ statement fails with a 





WEOFSEQ Parameters 

WEOFSEQ 1-900



CLOSESEQ, OPENSEQ, OSCLOSE, OSOPEN, READSEQ, WRITESEQ, 

WRITESEQF 


WRITE 

Syntax 

WRITE expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements] 

Description 

The UniBasic WRITE command writes an expression to an opened file and releases 

locks set by the same process. 

Note: WRITE updates the record and releases UniData locks regardless of lock 

status. To check for and retain record locks, use the WRITEU command. For more 

information, see Developing UniBasic Applications. 

To maintain file integrity, UniData locks records with a nonprogrammable lock 

during a write. UniData releases this lock immediately after the WRITE command 

executes. 




command. 

Updating Alternate Key Indexes 

Remember the following points about alternate key indexes when you code WRITE 

statements: 

Alternate key indexes that are currently enabled are automatically updated 

when you write a record. 

If you execute the ECL command DUP.STATUS ON, and then write a 

record that creates a duplicate alternate key, WRITE sets the STATUS return 

value to 10. 

WRITE 1-902


If the NO.DUPS keyword was specified when the alternate key index was 

created, UniBasic will not write a record that would create a duplicate index 

key. Instead, the ON ERROR clause executes (or the program aborts if ON 

ERROR is not coded) and the STATUS function returns a value of 10. RFS 

does not support NO.DUPS. 

Parameters 



expr Specifies an expression to write to the record. 

ON | TO file.var Specifies a file to which to write the expression. 

If you do not specify a file.var, UniData writes to the default file. If 

no default file is open, a fatal error occurs. 

A default file is one for which no file variable is assigned in the OPEN 

statement. 

record.ID.expr Specifies a record to receive the expression. If the record already 

exists, the new expression you specify with expr replaces the existing 

information. If the record you specify does not exist, UniData creates 

the record. 

ON ERROR 

statements 

Specifies statements to execute in the event of a fatal error condition 

(such as the file is not open, an I/O error occurs in the write process, 

or the record contains a duplicate alternate index key). If you do not 

specify the ON ERROR clause, the program terminates under fatal 

error conditions. 

When including WRITE statements within a transaction, you must 

code an ON ERROR clause that notifies the user and takes appropriate 

action, such as stopping the transaction. If the transaction is not 

aborted by the ON ERROR clause, processing continues, and the 

transaction could commit inappropriately. 

WRITE Parameters


After you execute WRITE, the STATUS function returns one of the values described 


Return 

Value Meaning 

0 Successful write. 



value of 0 in the parameter execstat, indicating that the WRITE is not 

allowed. 



10 Non-RFS files – WRITE created a duplicate alternate index key and ECL 

DUP.STATUS is on; or WRITE failed because a duplicate value exists in the 

index, and NO.DUPS was specified when the index was created. 

RFS files – WRITE created a duplicate value in the index, and ECL 



Examples 


“Sample Program, in Developing UniBasic Applications. The statements update 

records that were previously locked with READU and release locks on the records. 

WRITE CLIENT.REC ON CLIENT_FILE,CLIENT_NUMBER 

WRITE ORDER.REC ON ORDERS_FILE,ORDER_NUMBER 

In the next example, the program statement writes the contents of the variable 

OVERSTOCK to the file named in variable FNAME as a record with ID OS: 

WRITE OVERSTOCK TO FNAME,"OS" 

WRITE 1-904




WRITEU, WRITEV, WRITEVU 

UniData 

DUP.STATUS – For information, see the UniData Commands Reference. 


WRITELIST 

Syntax 

WRITELIST var ON list.name 

Description 

The UniBasic WRITELIST command writes the contents of a variable to a saved 

list. The values saved can then be used as item IDs to retrieve the data record. 

WRITELIST saves only the first value of the attribute. UniData saves only the first 

value in a multivalued or multi-subvalued attribute. 

Parameters 




DELETELIST, FORMLIST, READLIST, SELECT, SELECTINDEX, 

SELECTINFO 

UniQuery 


var Specifies a variable to place in a saved list. 

ON list.name Specifies a saved list to contain the retrieved list. 

WRITELIST Parameters 



WRITELIST 1-906

UniData SQL 



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 at the current record pointer position. 

Note: Before you use WRITESEQ, you must open the file by using the OSOPEN or 


Tip: Use the READSEQ command to position the record pointer before using 

WRITESEQ. 

If the file is a named pipe, you cannot use WRITESEQ to write to it. You must use the 

OSBWRITE command. 

WRITESEQ cannot immediately write a record to disk. UniData stores records in a 

buffer until the buffer is full. 

Parameters 



expr Specifies an expression to write as a record. 

APPEND Use the APPEND option to start the WRITESEQ process at 

the end-of-file mark. When APPEND is included, and no file 

exists, UniData creates a new file. 

ON | TO seq.file.var Specifies a sequential file to receive the expression. 

WRITESEQ Parameters 

WRITESEQ 1-908


Example 

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 the file. 


ON ERROR statements Specifies statements to execute if the WRITESEQ statement 





THEN statements END THEN executes if the WRITESEQ is successful. END is 


ELSE statements END ELSE executes if the WRITESEQ is not successful or the 



WRITESEQ BAD.ACCOUNTS TO ACCOUNTS 

ELSE PRINT "NOT AT END-OF-FILE" 



WRITESEQ Parameters (continued) 


OSOPEN, READSEQ, WEOFSEQ, 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 

sequential file from a current record pointer position and forces UniData to immediately 

write the data to the disk. 

Note: Before you use WRITESEQF, you must open the file by using the OSOPEN or 


Tip: Use the READSEQ command to position the record pointer before using 

WRITESEQF. 

If the file is a named pipe, you cannot use WRITESEQF to write to it. You must use 

the OSBWRITE command. 

Use the READSEQ command to position the record pointer before using 

WRITESEQF. 

Parameters 



expr Specifies an expression to write as a record. 

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, UniData creates a new file. 

ON | TO seq.file.var Specifies a sequential file variable to receive the expression. 

WRITESEQF Parameters 

WRITESEQF 1-910


Example 

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. 


ON ERROR statements Specifies statements to execute if the WRITESEQF statement 





If you specify the ON ERROR clause and UniData cannot find 

the end-of-file mark, the ELSE clause executes. 

THEN statements END THEN executes if the WRITESEQF is successful. END is 


ELSE statements END ELSE executes if the WRITESEQF is not successful or the 



WRITESEQF CHK.WRITE ON PAYROLL ELSE GOTO 100: 



WRITESEQF Parameters (continued) 


OSOPEN, READSEQ, WEOFSEQ, WRITESEQ

writeSocket 

Syntax 

writeSocket(socket_handle, socket_data, time_out, blocking_mode, 

actual_write_size) 



Description 

Use the writeSocket function to write data to a socket connection. 

Parameters 




socket_data The data to be written to the socket. 

time_out The allowable time (in milliseconds) for blocking. This is 

ignored for a non-blocking write. 

blocking_mode 0:using current mode 

1:blocking 

2:non-blocking 

actual_write_size The number of characters actually written. 

writeSocket Parameters 

writeSocket 1-912





0 - Blocking The function will return only after all characters in socket_data 

are written to the socket. 

1 - Non-Blocking The function may return with fewer character written than the 

actual length (in the case that the socket is full). 



0 Success. 


writeSocket Return Codes

WRITET 

Syntax 

WRITET [UNIT(mu.expr)] expr {THEN statements [END] | ELSE statements 

[END]} 

Description 

The UniBasic WRITET command writes the value of an expression as a record onto 

tape. 

Note: Before you can use the WRITET command, you must reserve a tape drive with 

the ECL T.ATT command. For detailed information about tape commands, see the 


UniData uses the ASCII 0 character (CHAR(0)) as a string-end delimiter. Therefore, 

you cannot use ASCII 0 in any string variable in UniBasic. When a string is read in 

a UniBasic program, CHAR(0) characters are converted to CHAR(128), and 

WRITET converts CHAR(128) back to CHAR(0). 

WRITET 1-914

Parameters 



Multireel Tape Processing 

You must use the TAPELEN option for the T.ATT command and specify the tape 

length. This command is intended for use with UniData tapes only. For information 

about the ECL T.ATT command, see the UniData Commands Reference. 


UNIT(mu.expr) Specifies the conversion code (first digit) and the unit number 

(second digit). Unit numbers range from 0 through 9. 

The mu.expr is optional and the default value for UNIT is (00) 

for tape unit 0 with no conversion performed (ASCII assumed). 

Valid options include the following: 





expr Specifies an expression to write. 

THEN statements END THEN executes if command execution is successful. END is 


ELSE statements END ELSE executes if command execution is not successful or the 



WRITET Parameters


After you execute WRITET, the STATUS function returns one of the values 


Example 

In the following example, the T.ATT command is executed, and then UniData writes 

the variable TAX.RECORD to tape: 

PERFORM "T.ATT" 

WRITET UNIT (00) TAX.RECORD ELSE PRINT 'TAPE PROBLEM' 



READT, RESIZET, REWIND, WEOF 

UniData 










SETTAPE, T.ATT, T.DET – For information, see the UniData Commands Reference. 

WRITET 1-916

WRITEU 

Syntax 

WRITEU expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements] 

Description 

The UniBasic WRITEU command writes a record to a file without releasing locks. 

WRITEU writes regardless of lock status. 






command. 


Remember the following points about alternate key indexes when you code WRITEU 

statements: 





record that creates a duplicate alternate key, WRITEU sets the STATUS 

return value to 10. 





does not support NO.DUPS.

Parameters 



expr Specifies an expression to write to the file. 

ON | TO file.var, Specifies a file to receive the expression. 

If you do not specify a file.var, UniData writes to the default file. 

If no default file is open, a fatal WRITEU error occurs. 



record.ID.expr Specifies a record to receive the expression. 

ON ERROR 

statements 

Specifies statements to execute if the WRITEU statement fails 

with a fatal error (such as the file is not open, an I/O error occurs 

in the write process, or the record contains a duplicate alternate 

index key). If the transaction is not aborted by the ON ERROR 

clause, processing continues, and the transaction could commit 

inappropriately. 

WRITEU Parameters 


After you execute WRITEU, the STATUS function returns one of the values 






WRITEU 1-918


Example 

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 before executing WRITEU. 


2 Constraint violation. In this case, the UniBasic trigger subroutine returns 

a value of 0 in the parameter execstat, indicating that the WRITEU is not 

allowed. 


example, trigger subroutine is not cataloged). 

10 Non-RFS files – WRITEU created a duplicate alternate index key and 

ECL DUP.STATUS is ON; or WRITEU failed because a duplicate value 

exists in the index, and NO.DUPS was specified when the index was 

created. 

RFS files – WRITEU created a duplicate value in the index, and ECL 

DUP.STATUS is ON. 

WRITEU IDEA.57 ON IDEAS,'LAST' 




WRITE, WRITEV, WRITEVU 

UniData 


DUP.STATUS – For information, see the UniData Commands Reference.

WRITEV 

Syntax 

WRITEV expr {ON | TO} [file.var,] record.ID.expr, attrib.expr 


Description 

The UniBasic WRITEV command updates a specified attribute in a file regardless 

of lock status. 

Note: The WRITEV command releases locks set by the same process. UniBasic locks 

are advisory only. For more information, see Developing UniBasic Applications.. 


Remember the following points about alternate key indexes when you code WRITEV 

statements: 




record that creates a duplicate alternate key, WRITEV sets the STATUS 

return value to 10. 






WRITEV 1-920

Parameters 




expr Specifies an expression to write to an attribute of a record. 



If no default file is open, a fatal WRITEV error occurs. 




attrib.expr Specifies an attribute to receive the expression. 

ON ERROR 

statements 

Specifies statements to execute if the WRITEV statement fails 



index key). 



When including WRITEV statements within a transaction, you 

must code an ON ERROR clause that notifies the user and takes 

appropriate action, such as stopping the transaction. If the transaction 

is not aborted by the ON ERROR clause, processing 

continues, and the transaction could commit inappropriately. 

WRITEV Parameters


After you execute WRITEV, the STATUS function returns one of the values 






value of 0 in the parameter execstat, indicating that the WRITEV is not 

allowed. 



10 Non-RFS files – WRITEV created a duplicate alternate index key and ECL 

DUP.STATUS is on; or WRITEV failed because a duplicate value exists in 

the index and NO.DUPS was specified when the index was created. 

RFS files – WRITEV created a duplicate value in the index, and ECL 



Examples 

In the following example, the program statement writes the variable NAME to the 

first attribute in the customer record with CLIENT.ID in the file CLIENTS: 

WRITEV NAME ON CLIENT,CLIENT.ID,1 

WRITEV 1-922


Program,” in Developing UniBasic Applications. It demonstrates using WRITEV to 

write an attribute. Notice that the attribute is read and the record locked. Then 

LOCATE is used to determine the position (within the attribute) of the value to be 

deleted. After that value is deleted, the attribute is written back to the record. 







END 


END 

* 

DELETE ORDERS_FILE, ORDER_NUMBER 

RELEASE CLIENT_FILE,CLIENT_NUMBER 

RETURN 




WRITE, WRITEU, WRITEVU 

UniData 

DUP.STATUS – For information, see the UniData Commands Reference.

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 record 

regardless of lock status. This command retains locks. As with the WRITEV 

statement, the record ID and attribute number are mandatory. 


UniBasic Applications.. 


Remember the following points about alternate key indexes when you code 

WRITEVU statements: 



If you execute the ECL command DUP.STATUS ON, then write a record 

that creates a duplicate alternate key, WRITEVU sets the STATUS return 

value to 10. 






WRITEVU 1-924

Parameters 




expr Specifies an expression to write to an attribute of a record. 



If no default file is open, a fatal error occurs. 




attrib.expr Specifies an attribute to receive the expression. 

ON ERROR 

statements 

Specifies statements to execute if the WRITEVU statement fails 



index key). 



When including WRITEVU statements within a transaction, you 

must code an ON ERROR clause that notifies the user and takes 

appropriate action, such as stopping the transaction. If the 

transaction is not aborted by the ON ERROR clause, processing 

continues, and the transaction could commit inappropriately. 

WRITEVU Parameters

STATUS Function Return Value 

After you execute WRITEVU, the STATUS function returns one of the values in the 






value of 0 in the parameter execstat, indicating that the WRITEVU is not 

allowed. 



10 Non-RFS files – WRITEVU created a duplicate alternate index key and 

ECL DUP.STATUS is ON; or WRITEVU failed because a duplicate value 

exists in the index, and NO.DUPS was specified when the index was 

created. 

RFS files – WRITEVU created a duplicate value in the index, and ECL 

DUP.STATUS is ON. 





WRITE, WRITEU, WRITEV 

UniData 

DUP.STATUS – For information, see the UniData Commands Reference. 

WRITEVU 1-926

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\BASICREF\BASRX.fm 

3/5/10 

XDOMAddChild 

Syntax 

XDOMAddChild(xmlHandle, xpathString, nsMap, nodeHandle, 

dupFlag,nodeType) 



Description 

Finds the xpathString in the context xmlHandle in the DOM structure, and inserts a 

node as the last child of the found node. If the inserted node type is 

XDOM.ATTR.NODE, this node is inserted as an attribute. 


C:\Program 

Files\Adobe\FrameMaker8\UniData 

Parameters 



xmlHandle The handle to the context. [IN] 

xpathString Relative or absolute xpath string. [IN] 

The xpathString parameter uses the in-encoding parameter set in the 

system-level or account-level xmlconfig file, the XMLSETOPTIONS 

command, or the XMLSetOptions() API. 

nsMap The map of namespaces which resolve the prefixes in the xpath string. 

Format is “xmlns=default_url xmlns:prefix1=prefix1_url 

xmlns:prefix2=prefix2_url” 

For example: 

“xmlns=http://myproject.mycompany.com 

xmlns:a_prefix=a.mycompany.com” [IN] 

The nsMap parameter uses the in-encoding parameter set in the systemlevel 

or account-level xmlconfig file, the XMLSETOPTIONS 


nodeHandle Handle to a DOM subtree. If nodeHandle points to a DOM document, 

all of its children are inserted, in the same order. [IN] 

dupFlag XDOM.DUP: Clones nodeHandle, and inserts the duplicate node. 

XDOM.NODUP: Inserts the original node. The subtree is also removed 

from its original location. [IN] 

XDOMAddChild Parameters 

XDOMAddChild 1-929


3/5/10 

Return Codes 





XML.SUCCESS The function completed successfully. 

XML.ERROR An error occurrred. 

XML.INVALID.HANDLE An invalid DOM handle was returned to the function. 

XDOMAddChild Return Codes

C:\Program 


XDOMAppend 

Syntax 

XDOMAppend(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag) 



Description 

Finds the xpathString in the context xmlHandle in the DOM structure, and inserts 

nodeHandle into the DOM structure as next sibling of the found node. If the inserted 

node type is XDOM.ATTR.NODE, this node is inserted as an attribute. 

Parameters 




xpathString Relative or absolute XPath string. [IN] 




XDOMAppend Parameters 

XDOMAppend 1-931


3/5/10 


Return Codes 




nsMap The map of namespaces which resolve the prefixes in the xpathString. 



For example: 


xmlns:a_prefix=a.mycompany.com” 

[IN] 





all of its children are inserted, in the same order. [IN] 

dupFlag XDOM.DUP: Clones nodeHandle, and insert the duplicate node. 

XDOM.NODUP: Inserts the original node. The subtree is also removed 

from its original location. 

[IN] 

XDOMAppend Parameters (continued) 





XDOMAppend Return Codes

C:\Program 


XDOMClone 

Syntax 

XDOMClone(xmlHandle, newXmlHandle, depth) 



Description 

Duplicates the DOM subtree specified by xmlHandle to a new subtree specified by 

newXmlHandle. The duplicate node has no parent (parentNode returns null.). 

Cloning an element copies all attributes and their values, including those generated 

by the XML processor, to represent defaulted attributes, but this method does not 

copy any text it contains unless it is a deep clone, since the text is contained in a child 

Text node. Cloning any other type of node simply returns a copy of this node. 

Parameters 



xmlHandle Handle to the DOM subtree. [IN] 

newXmlHandle Handle to the new DOM subtree. [IN] 

depth XDOM.FALSE: Clone only the node itself. 

XDOM.TRUE: Recursively clone the subtree under the specified node. 

[IN] 

XDOMClone Parameters 

XDOMClone 1-933


3/5/10 

Return Codes 








XDOMClone Return Codes

C:\Program 


XDOMClose 

Syntax 

XDOMClose(domHandle) 



Description 

XDOMClose frees the DOM structure. 

Parameters 



domHandle Handle to the DOM structure. [IN] 

XDOMClose Parameter 

Return Codes 




XML.SUCCESS Function completed successfully. 

XML.ERROR An error occurred. 

XML.INVALID.HANDLE Invalid DOM handle passed to the function. 

XDOMClose Return Codes 

XDOMClose 1-935


3/5/10 

XDOMCreateNode 

Syntax 

XDOMCreateNode(xmlHandle, nodeName, nodeValue, nodeType, nodeHandle) 

Note: This function is case-sensitive. If you want it to be case-insensitive, you must 

compile your programs using the BASIC command with the -i option. 

Description 

XDOMCreateNode creates a new node in the DOM structure. 

Parameters 




xmlHandle A handle to the DOM structure. This handle acts as the context 

when resolving the namespace_uri from the prefix or resolving 

the prefix from the namespace_uri. 

[IN] 

nodeName The name of the node to be created. [IN] 

The name can be in any of the following formats: 

Local_name 

prefix: local_name:namespace_uri 

prefix:local_name 

:local_name:namespace_uri 

The nodeName parameter uses the in-encoding parameter set in 

the system-level or account-level xmlconfig file, the XMLSE- 

TOPTIONS command, or the XMLSetOptions() API. 

XDOMCreateNode Parameters

C:\Program 



nodeValue The string to hold the node value. [IN] 

The nodeValue parameter uses the in-encoding parameter set in 



nodeType The type of the node to be created. Valid values are: 

XDOM.ELEMENT.NODE 

XDOM.ATTR.NODE 

XDOM.TEXT.NODE 

XDOM.CDATA.NODE 

XDOM.ENTITY.REF.NODE 

XDOM.ENTITY.NODE 

XDOM.PROC.INST.NODE 

XDOM.COMMENT.NODE 

XDOM.DOC.NODE 

XDOM.DOC.TYPE.NODE 

XDOM.DOC.FRAG.NODE 

XDEOM.NOTATION.NODE 

XDOM.XML.DECL.NODE 

UniData uses this argument, along with direction and childIndex, 

to get the right type node. For example, if direction is 

XDOM.PREV.SIBLING, and nodeType is 

XDOM.ELEMENT.NODE, UniData finds the element node that 

is the first previous sibling of nodeHandle. If direction is 

XDOM.CHILD, childIndex is XDOM.FIRST.CHILD, and 

nodeType is XDOM.ELEMENT.NODE, UniData finds the 

element node that is the first element child of nodeHandle. If the 

direction is XDOM.CHILD, childIndex is 2, and nodeType is 

XDOM.ELEMENT.NODE, UniData finds the element node that 

is the second element child of nodeHandle. 

When the direction is 

XDOM.NEXT.SIBLING.WITH.SAME.NAME, 

XDOM.PREV.SIBLING.WITH.SAME.NAME, or 

XDOM.PARENT, this argument is not used. [IN] 

nodeHandle A handle to the node to be created in the DOM structure. 

[IN] 

XDOMCreateNode Parameters (continued) 

XDOMCreateNode 1-937


3/5/10 

Return Codes 

The return code indicates success or failure. The following table describes each 

return code. 





XDOMCreateNode Return Codes

C:\Program 


XDOMCreateRoot 

Syntax 

XDOMCreateRoot(domHandle[,xmlOptions]) 



Description 

XDOMCreateRoot creates a new DOM structure with root only. You can use the 

result handle in other functions where a DOM handle or node handle is needed. The 

default declaration for the XML document created by this function is as follows: 

 

XDOMCreateRoot 1-939


3/5/10 

Parameters 




domHandle Handle to the opened DOM structure. [OUT] 

xmlOptions A string specifying the key/value pairs for the encoding, standalone, 

and version options to be declared in the XML document 

created by this function. [IN] 

The string can be entered in either of the following formats: 

"version=1.0 encoding=ISO-8859-1 

standalone=yes" 

or 

’version="1.0" encoding="iso-8859-1" 

standalone="no"’ 

The encoding, standalone, and version options are the same as 

those in the xmlconfig file and accept the same values. Keys and 

values are case-insensitive. 

Valid encoding settings can be found at 

http://www.iana.org/assignments/character-sets 

XDOMCreateRoot Parameter

C:\Program 


Return Codes 






If an error is encountered in xmlOptions, XMLGetError() 

returns one of the following error codes: 

38 Invalid XML config key: ‘key_name’ 

39 Invalid XML config value: ‘value_string’ 

40 Invalid XML config format: ‘name_value_string’ 

XDOMCreateRoot Return Codes 

XDOMCreateRoot 1-941


3/5/10 

XDOMEvaluate 

Syntax 

XDOMEvaluate(xmlHandle, xpathString, nsMap, aValue) 



Description 

XDOMEvaluate returns the value of the XPathString in the context xmlHandle in the 

DOM structure. 


C:\Program 


Parameters 



xmlHandle Handle to the context. [IN] 





nsMap The map of namespaces which resolves the prefixes in the xpathString. 



For example: 



[IN] 




aValue The value of xpathString. [OUT] 

The aValue parameter uses the out-encoding parameter set in the systemlevel 



XDOMEvaluate Parameters 

XDOMEvaluate 1-943


3/5/10 

Return Codes 








XDOMEvaluate Return Codes

C:\Program 


XDOMGetAttribute 

Syntax 

XDOMGetAttribute(nodeHandle, attrName, nodeHandle) 



Description 

XDOMGetAttribute gets the node's attribute node, whose attribute name is attrName. 

Parameters 



nodeHandle Handle to the DOM node. [IN] 

attrName Attribute name. [IN] 

The attrName parameter uses the in-encoding parameter set in 



nodeHandle Handle to the found attribute node. [OUT] 

XDOMGetAttribute Parameters 

XDOMGetAttribute 1-945


3/5/10 

Return Codes 








XDOMGetAttribute Return Codes

C:\Program 


XDOMGetNodeName 

Syntax 

XDOMGetNodeName(nodeHandle, nodeName) 



Description 

XDOMGetNodeName gets the node name. 

Parameters 




nodeName String to store the node name. [OUT] 

The nodeName parameter uses the out-encoding parameter set in the 



XDOMGetNodeName Parameters 

XDOMGetNodeName 1-947


3/5/10 

Return Codes 








XDOMGetNodeName Return Codes

C:\Program 


XDOMGetNodeType 

Syntax 

XDOMGetNodeType(nodeHandle, nodeType) 



Description 

XDOMGetNodeType gets the node type. 

Parameters 


Return Codes 


nodeHandle The handle to the DOM node. [IN] 

nodeType An integer to store the node type. [OUT] 

XDOMGetNodeType Parameters 







XDOMGetNodeType Return Codes 

XDOMGetNodeType 1-949


3/5/10 

XDOMGetNodeValue 

Syntax 

XDOMGetNodeValue(nodeHandle, nodeValue) 



Description 

XDOMGetNodeValue gets the node value. 

Parameters 





nodeValue The string to hold the node value. [OUT] 

The nodeValue parameter uses the out-encoding parameter set in 



XDOMGetNodeValue Parameters

C:\Program 


Return Codes 







XDOMGetNodeValue Return Codes 

XDOMGetNodeValue 1-951


3/5/10 

XDOMGetOwnerDocument 

Syntax 

XDOMGetOwnerDocument(nodeHandle, domHandle) 



Description 

XDOMGetOwnerDocument gets the DOM handle to which the nodeHandle belongs. 

Parameters 



Return Codes 





domHandle Handle to the DOM structure. [OUT] 





XDOMGetOwnerDocument Return Codes

C:\Program 


XDOMGetUserData 

Syntax 

XDOMGetUserData(nodeHandle, userData) 



Description 

XDOMGetUserData gets the user data associated with the node. 

Parameters 




userData String to hold the user data. [OUT] 

XDOMGetUserData Parameters 

Return Codes 







XDOMGetUserData Return Codes 

XDOMGetUserData 1-953


3/5/10 

XDOMImportNode 

Syntax 

XDOMImportNode(xmlHandle, depth, importedNodeHandle, outNodeHandle) 

Description 

The XDOMImportNode function imports a node from another document into the 

current document. The returned node has no parent. The source node is not altered or 

removed from the original document. 

For all nodes, importing a node creates a node object owned by the document from 

which you are importing. The attribute values are identical to the source node's 

nodeName and nodeType, as well as attributes related to namespaces (prefix, 

localName, and namespaceURI). 

UniData attempts to mirror the behavior expected if a fragment of the XML source 

was copied from one document to another by copying additional information, as 

appropriate, to the nodeType. UniData recognizes that the two documents may have 

different DTDs. The following describes the specifics for each type of node: 

ATTRIBUTE_NODE 

UniData sets the ownerElement attribute to null and the specified flag to true on the 

generated DOMAttr. UniData recursively imports the descendants of the source 

DOMAttr and reassembles the resulting nodes to form a corresponding subtree. 

Note: The depth parameter has no effect on DOMAttr nodes. These nodes always 

carry their children with them when imported. 

DOCUMENT_FRAGMENT_NODE 

If the value of the depth option is true, UniData recursively imports the descendants 

of the source element and reassembles the resulting nodes to form the corresponding 

subtree. If the value of the depth option is false, UniData generates an empty 

DOMDocumentFragment. 


C:\Program 


DOCUMENT_NODE 

You cannot import DOMDocument nodes. 

DOCUMENT_TYPE_NODE 

You cannot import DOMDocumentType nodes. 

ELEMENT_NODE 

UniData imports specified attribute nodes of the source document, and attaches the 

generated DOMAttr nodes to the generated DOMElement. UniData does not copy 

default attributes, although they are assigned if the document to which you are 

importing defines default attributes for this element name. If the value of the 

importNode depth parameter is true, UniData recursively imports the descendants of 

the source element and reassembles the resulting nodes to form the corresponding 

subtree. 

ENTITY_NODE 

You can import DOMEntity nodes, but in the current release of the DOM, the 

DOMDocumentType is read only. When you import and ENTITY_NODE, UniData 

copies the publicId, systemId, and notationName attributes. If the value of the depth 

parameter is true, UniData recursively imports the descendants of the source 

DOMEntity and reassembles the resulting node to form the corresponding subtree. 

ENTITY_REFERENCE_NODE 

If you import this type of node, UniData only copies the DOMEntityReference itself, 

even if the value of the depth parameter is true. This is because the source and destination 

documents may have defined the entity differently. If the document you are 

importing provides a definition for this entity name, UniData assigns that value. 

NOTATION_NODE 

You can import DOMNotation nodes, but in the current release of the DOM, the 

DOMDocumentType is read only. When you import a NOTATION_NODE, UniData 

copies the publicId and systemId attributes. The depth parament has no effect on 

DOMNotation nodes, since they do not have children. 



3/5/10 

PROCESSING_INSTRUCTION_NODE 

UniData copies the target and data values from the source node to the current 

document. 

TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE 

With these types of nodes, inheriting from DOMCharacterData, UniData copies the 

data and length attributes from the source node to the current document. 

Parameters 




xmlHandle The target XML document to which you are importing. [IN] 

depth XDOM.FALSE - import only the node itself. 

XDOM.TRUE - recursively import the subtree under the node 

specified by importedNodeHandle. 

This parameter has no effect on DOMAttr, 

DOMEntityReference, and DOMNotation nodes. [IN] 

importedNodeHandle The handle to the node you are importing. [IN] 

newXMLHandle The handle to the new node. [IN] 

XDOMImportNode Parameters

C:\Program 


Return Status 

The following table describes the return status for XDOMImportNode: 

Status Description 

XML.SUCCESS The import was successful. 

XML.ERROR An error occurred during import. 

XML.INVALID.HANDLE The xmlHandle or importedNodeHandle is not a valid XML 

handle. 

XDOMImportNode Return Status 



3/5/10 

XDOMInsert 

Syntax 

XDOMInsert (xmlHandle, xpathString, nsMap, nodeHandle, dupFlag) 



Description 

XDOMInsert finds the xpathString in the context xmlHandle in the DOM structure, 

and inserts nodeHandle into the DOM structure as the previous sibling of the found 

node. If the inserted node type is XDOM.ATTR.NODE, this node is inserted as an 

attribute. 


C:\Program 


Parameters 








nsMap The map of namespaces which resolves the prefixes in the 

xpathString. 



For example: 



[IN] 

The nsMap parameter uses the in-encoding parameter set in the 



nodeHandle The handle to a DOM subtree. If nodeHandle points to a DOM 

document, all of its children are inserted, in the same order. [IN] 

dupFlag XDOM.DUP: Clones nodeHandle, and inserts the duplicate node. 

XDOM.NODUP: Inserts the original node. The subtree is also 

removed from its original location. 

XDOMInsert Parameters 

XDOMInsert 1-959


3/5/10 

Return Codes 








XDOMInsert Return Codes

C:\Program 


XDOMLocate 

Syntax 

XDOMLocate(xmlHandle, xpathString, nsMap, nodeHandle) 



Description 

XDOMLocate finds a starting point for relative XPath searching in context 

xmlHandle in the DOM structure. The xpathString should specify only one node; 

otherwise, this function will return an error. 

XDOMLocate 1-961


3/5/10 

Parameters 



Return Codes 




xmlHandle A handle to the DOM structure. [IN] 

xpathString A string to specify the starting point. [IN] 

The xpathString parameter uses the in-encoding parameter set in 



nsMAP The map of namespaces which resolve the prefixes in the xpath- 

String. The format is: 

“xmlns=default_url xmlns:prefix1=prefix1_url 

xmlns:prefix2=prefix2_url 

For example: 

“xmlns=”http://myproject.mycompany.com 

xmlns:a_prefix=a.mycompany.com 

[IN] 


system-level or account-level xmlconfig file, the XMLSETOP- 

TIONS command, or the XMLSetOptions() API. 

nodeHandle Handle to the found node. [OUT] 

XDOMLocate Parameters 




XML.INVALID.HANDLE An invalid handle was returned to the function. 

XDOMLocate Return Codes

C:\Program 


Note: In this document, xmlHandle is a generic type, it can be domHandle or 

nodeHandle. DomHandle stands for a whole document, while nodeHandle stands for 

a subtree. DomHandle is also a nodeHandle. 

XDOMLocate 1-963


3/5/10 

XDOMLocateNode 

Syntax 

XDOMLocateNode(nodeHandle, direction, childIndex, nodeType, 

newNodeHandle) 



Description 

XDOMLocateNode traverses from nodeHandle and gets the next node according to 

direction and childIndex. 

Parameters 




nodeHandle The handle to the starting node. [IN] 

direction Direction to traverse. Valid values are: 

XDOM.PREV.SIBLING 

XDOM.NEXT.SIBLING 

XDOM.NEXT.SIBLING.WITH.SAME.NAME 

XDOM.PREV.SIBLING.WITH.SAME.NAME 

XDOM.PARENT 

XDOM.CHILD 

[IN] 

XDOMLocateNode Parameters

C:\Program 



childIndex The index in the child array. Valid values are: 

XDOM.FIRST.CHILD 

XDOM.LAST.CHILD 

Positive Integer 

[IN] 

nodeType The typeof node to be located. Valid values are: 

XDOM.NONE 

XDOM.ELEMENT.NODE 

XDOM.ATTR.NODE 

XDOM.TEXT.NODE 

XDOM.CDATA.NODE 

XDOM.ENTITY.REF.NODE 

XDOM.ENTITY.NODE 

XDOM.PROC.INST.NODE 

XDOM.COMMENT.NODE 

XDOM.DOC.NODE 

XDOM.DOC.TYPE.NODE 

XDOM.DOC.FRAG.NODE 

XDEOM.NOTATION.NODE 

XDOM.XML.DECL.NODE 

If nodeType is not XDOM.NONE, UniData uses this argument, 

along with direction and childIndex, to get the right typed node. 

For example, if direction is XDOM.PREV.SIBLING, and 

nodeType is XDOM.ELEMENT.NODE, UniData finds the 

element node which is the first previous sibling of nodeHandle. 

If direction is XDOM.CHILD, childIndex is 

XDOM.FIRST.CHILD, and nodeType is 

XDOM.ELEMENT.NODE, UniData finds the element node 

which is the first element child of nodeHandle. If the direction is 

XDOM.CHILD, childIndex is 2, and nodeType is 

XDOM.ELEMENT.NODE, UniData finds the element node 

which is the second element child of nodeHandle. 

When the direction is 

XDOM.NEXT.SIBLING.WITH.SAME.NAME, 

XDOM.PREV.SIBLING.WITH.SAME.NAME, or 

XDOM.PARENT, this argument is not used. [IN] 

newNodeHandle Handle to the found node. [OUT] 

XDOMLocateNode Parameters (continued) 

XDOMLocateNode 1-965


3/5/10 

Return Codes 







XM.INVALID.HANDLE An invalid handle was returned to the function. 

XDOMLocateNode Return Codes

C:\Program 


XDOMOpen 

Syntax 

XDOMOpen(xmlDocument, docLocation, domHandle) 



Description 

XDOMOpen reads an XML document and creates a DOM structure. If the DTD is 

included in the document, UniData validates the document. The XML document can 

be from a string, or from a file, depending on the docLocation flag. 

Parameters 



xmlDocument The XML document. [IN] 

docLocation A flag to specify whether xmlDocument is a string holding the XML 

document, or it is a file containing the XML document. Valid values are: 

XML.FROM.FILE 

XML.FROM.STRING 

[IN] 

domHandle Handle to the opened DOM structure. [OUT] 

XDOMOpen Parameters 

XDOMOpen 1-967


3/5/10 

Return Codes 








XDOMOpen Return Codes

C:\Program 


XDOMRemove 

Syntax 

XDOMRemove(xmlHandle, xpathString, nsMap, attrName, nodeHandle) 



Description 

XDOMRemove finds the xpathString in the context xmlHandle in the DOM 

structure, then removes the found node or its attribute with name attrName. 

XDOMRemove 1-969


3/5/10 

Parameters 




xmlHandle Handle to the context. [IN] 

xpathString Relative or absolute xpath string. [IN] 




nsMap The map of namespaces which resolve the prefixes in the xpathString. 

Format is “xmlns=default_url xmlns:prefix1_url 


For example: 



[IN] 




attrName The attribute name. [IN] 

The attrName parameter uses the in-encoding parameter set in the 



nodeHandle The removed node, if nodeHandle is not NULL. [OUT] 

XDOMRemove Parameters

C:\Program 


Return Codes 







XDOMRemove Return Codes 

XDOMRemove 1-971


3/5/10 

XDOMReplace 

Syntax 

XDOMReplace(xmlHandle, xpathString, nsMap, nodeHandle, dupFlag) 



Description 

XDOMReplace finds the xpathString in the context xmlHandle in the DOM structure, 

and replaces the found node with nodeHandle. 

Parameters 







system-level or account-level xmlconfig file, the 

XMLSETOPTIONS command, or the XMLSetOptions() API. 

XDOMReplace Parameters

C:\Program 



nsMap The map of namespaces which resolve the prefixes in the 

xpathString. 



For example: 


xmlns:a_prefix=a.mycompany.com” [IN] 


system-level or account-level xmlconfig file, the 

XMLSETOPTIONS command, or the XMLSetOptions() API. 


the found node is replaced by all of nodeHandle children, which are 

inserted in the same order. [IN] 

dupFlag XDOM.DUP: Clones nodeHandle, and replaces it with the duplicate 

node. 

XDOM.NODUP: Replaces with the original node. The subtree is also 

removed from its original location. [IN] 

Return Codes 

XDOMReplace Parameters (continued) 







XDOMReplace Return Codes 

XDOMReplace 1-973


3/5/10 

XDOMSetNodeValue 

Syntax 

XDOMSetNodeValue(nodeHandle, nodeValue) 



Description 

XDOMSetNodeValue sets the node value. 

Parameters 





nodeValue String to hold the node value. [IN] 

The nodeValue parameter uses the in-encoding parameter set in 



XDOMSetNodeValue Parameters

C:\Program 


Return Codes 







XDOMSetNodeValue Return Codes 

XDOMSetNodeValue 1-975


3/5/10 

XDOMSetUserData 

Syntax 

XDOMSetUserData(nodeHandle, userData) 



Description 

XDOMSetUserData sets the user data associated with the node. 

Parameters 


Return Codes 






userData String to hold the user data. [IN] 

XDOMSetUserData Parameters 





XDOMSetUserData Return Codes

C:\Program 


XDOMTransform 

Syntax 

XDOMTransform(domHandle, styleSheet, ssLocation, outHandle[, outFormat]) 



Description 

XDOMTransform transforms the input DOM structure using the style sheet specified 

by styleSheetFile to output the DOM structure, file, or string. 

Parameters 




styleSheet Handle to the context [IN] 

XDOMTransform Parameters 

XDOMTransform 1-977


3/5/10 


Return Codes 




ssLocation A flag to specify whether styleSheet contains style sheet itself, or is just 

the style sheet file name. Value values are: 

XML.FROM.FILE (default) 


[IN] 

outHandle Handle to the resulting DOM structure, file, or string. [OUT] 

outFormat Specifies one of the following values as the output format for the DOM 

structure: 

XML.TO.DOM – Transforms the input DOM structure using the 

style sheet specified by styleSheet, and outputs the resulting 

document into a DOM structure. 

XML.TO.FILE – Transforms the input DOM structure using the style 

sheet specified by styleSheet, and outputs the resulting document into 

a file. 

XML.TO.STRING – Transforms the input DOM structure using the 

style sheet specified by styleSheet, and outputs the resulting 

document into a string. 

XDOMTransform Parameters (continued) 





XDOMTransform Return Codes

C:\Program 


XDOMValidate 

Syntax 

XDOMValidate(xmlDocument, docLocation,, noNsSchema, noNsSchemaLocation[, 

NsSchemas]) 



Description 

XDOMValidata validates the DOM document using an external nonamespace 

schema specified by noNsSchema and, optionally, external namespace schemas 

specified by NsSchemas. 

Parameters 



xmlDocument The name of the XML document. [IN] 

docLocation A flag to specify whether xmlDocument is the document itself, 

or the document file name. Valid values are: 



XML.FROM.DOM 

[IN] 

XDOMValidate Parameters 

XDOMValidate 1-979


3/5/10 


Return Codes 




noNsSchema The external no-namespace schema file. [IN] 

noNsSchemaLocation A flag to specify whether noNsSchema is the schema itself, or 

the schema file name. Valid values are: 



[IN] 

NsSchemas The external namespace schema files. [IN] 

XDOMValidate Parameters (continued) 




XML.INVALID.HANDLE An invalid DOM handle was passed to the function. 

XDOMValidate Return Codes

C:\Program 


XDOMValidateDom 

Syntax 

XDOMValidateDom(domHandle, noNsSchema, noNsSchemaLocation[, 

NsSchemas]) 

Note: This function is case-sensitive. If you want it to be case-insensitive, you must 

compile your programs using the BASIC command with the -i option. 

Description 

XDOMValidateDom validates the DOM document using an external no-namespace 

schema specified by noNsSchema and, optionally, external namespace schemas 

specified by NsSchemas. 

Parameters 




noNsSchema The external no-namespace schema file. [IN] 

noNsSchemaLocation A flag to specify whether noNsSchema is the schema itself, or 

the schema file name. Valid values are: 



[IN] 

NsSchemas The external namespace schema files. [IN] 

XDOMValidateDom Parameters 

XDOMValidateDom 1-981


3/5/10 

Return Codes 


return code. 





XML.INVALID.HANDLE An invalid DOM handle was passed to the function. 

XDOMValidateDom Return Codes

C:\Program 


XDOMWrite 

Syntax 

XDOMWrite(domHandle, xmlDocument, docLocation[, xmlOptions]) 



Description 

XDOMWrite writes the DOM structure to xmlDocument. xmlDocument can be a 

string or a file, depending on the value of the docLocation flag. 

Parameters 



domHandle Handle to the opened DOM structure. [IN] 

XDOMWrite Parameters 

XDOMWrite 1-983


3/5/10 



xmlDocument The XML document [OUT] 

docLocation A flag to specify whether xmlDocument is an output string which 

shoujld hold the XML document, or it is a file where the XML 

document should be written. Valid values are: 

XML.TO.FILE 

XML.TO.STRING 

[IN] 

xmlOptions A string specifying the key/value pairs of the XML options to be used 

in the XML document written by this function. [IN] 


"encoding=ISO-8859-1 standalone=yes newline=CR-LF" 

or 

‘encoding="iso-8859-1" standalone="no"’ 

The XML options are the same as those in the xmlconfig file and accept 

the same values. Keys and values are case-insensitive. 

Valid encoding settings can be found at http://www.iana.org/assignments/character-sets 

XDOMWrite Parameters (continued)

C:\Program 


Return Codes 






If an error is encountered in xmlOptions, 

XMLGetError() returns one of the following 

error codes: 

38 Invalid XML config key: ’key_name’ 

39 Invalid XML config value: ’value_string’ 

40 Invalid XML config format: 

’name_value_string’ 


XDOMWrite Return Codes 

XDOMWrite 1-985


3/5/10 

XLATE 

Syntax 

XLATE(filename, rec.id.expr, attrib.expr, "code") 

Description 

The UniBasic XLATE function returns the contents of an attribute, and takes 

additional action if the record does not exist or the attribute is empty. 

This function performs the same action as the TRANS virtual attribute function. 

Parameters 




filename 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 a record ID in file.expr. 

attrib.expr Specifies a valid attribute in file.expr. 

"code" Enter a code specifying action to be taken if the record does not exist or 

the attribute is empty: 

C – Substitutes the id.expr for the value of the function. 

V – Returns an empty string and prints an error message. 

X – Returns an empty string. 

XLATE Parameters

C:\Program 



UniData 

TRANS – For information, see Using UniData. 

XLATE 1-987


3/5/10 

XMAPAppendRec 

Syntax 

XMAPAppendRec(XMAPhandle, file_name, record) 



Description 

The XMAPAppendRec function formats the specified record from the UniData file 

as a U2XMAP dataset record and appends it to the U2XMAP dataset. 

Parameters 




XMAPhandle The handle to the U2XMAP dataset. 

The XMAPhandle parameter uses the in-encoding parameter set 

in the system-level or account-level xmlconfig file, the XMLSE- 

TOPTIONS command, or the XMLSetOptions() API for the 

input record value. 

file_name The name of the UniData file that is being mapped in the 

U2 XMAP dataset 

record The data record formatted according to the dictionary 

record of the UniData file. 

XMAPAppendRec Parameters

C:\Program 


Return Values 

The following table describes the return values of the XMAPAppendRec function. 


XML_SUCCESS The XML document was opened successfully. 

XML_ERROR An error occurred opening the XML document. 

XML_INVALID_HANDLE The XMAP dataset was invalid. 

XMAPAppendRec Return Values 

XLATE 1-989


3/5/10 

XMAPClose 

Syntax 

XMAPClose(XMAPhandle) 



Description 

The XMAPClose function closes the U2XMAP dataset handle and frees all related 

structures and memory. 

Parameter 



Return Values 

The following table describes the return values from the XMAPClose function. 



XMAPClose Parameter 


XML_SUCCESS The XML document was closed successfully. 

XML_ERROR An error occurred closing the XML document. 


XMAPClose Return Values

C:\Program 


XMAPCreate 

Syntax 

XMAPCreate(u2xmapping_rules, mapping_flag, XMAPhandle) 



Description 

The XMAPCreate function creates an empty XML document for transferring data 

from the UniData database to XML according the mapping rules you define. 

Parameters 



u2xmapping_rules The name of the U2XMAP file, or the UniBasic variable 

containing the XML to Database mapping rules. 

mapping_flag A flag indicating if the mapping file is the U2XMAP file itself 

or a string located within the UniBasic program. Valid values 

are: 

XMAP.FROM.FILE - the mapping rules are contained in a 

U2XMAP file. 

XMAP.FROM.STRING - u2xmapping_rules is the name of 

the variable containing the mapping rules. 

XMAPhandle The handle to the XMAP dataset. 

XMAPCreate Parameters 

XMAPCreate 1-991


3/5/10 

The following table describes the return values for the XMAPCreate function. 






XMAPCreate Return Values

C:\Program 


XMAPOpen 

Syntax 

XMAPOpen(xml_document, doc_flag, u2xmapping_rules, u2xmap_flag, 

XMAPhandle) 



Description 

The XMAPOpen function opens an XML document as a U2XMAP data set. 

Parameters 



xml_document The name of the XML document. 


XML.FROM.DOM - xml_document is a DOM handle. 

XML.FROM.FILE - xml_document is a file name. 

XML.FROM.STRING -xml_document is the name of 

variable containing the XML document. 

XMAPOpen Parameters 

XMAPOpen 1-993


3/5/10 


Return Values 

The following table describes the return values for the XMAPOpen function. 


u2xmapping_rules The name of the U2XMAP file, or the UniBasic variable 

containing the XML to Database mapping rules. 

u2xmap_flag A flag indicating if the mapping file is the U2XMAP file itself 


are: 


U2XMAP file. 

XMAP.FROM.STRING - u2xmap_flag is the name of the 

variable containing the mapping rules. 

XMAPhandle The handle to the XMAP dataset. 

This API registers the current in-encoding and out-encoding 

parameters in the XMAPhandle. These parameters are used 

throughout the life of the XMAPhandle. 

XMAPOpen Parameters (continued) 




XMAPOpen Return Values

C:\Program 


XMAPReadNext 

Syntax 

XMAPReadNext(XMAPhandle, file_name, record) 



Description 

The XMAPReadNext function retrieves the next record from the U2XMAP dataset 

and formats it as a record of the UniData file that is being mapped. 

Parameters 



XMAPhandle The U2XMAP dataset handle. 

The XMAPhandle parameter uses the out-encoding parameter set in the 


command, or the XMLSetOptions() API for the record value. 

file_name The name of the UniData file that is being mapped in the U2XMAP 

dataset. 

record The data record formatted according to the dictionary record of the file. 

XMAPReadNext Parameters 

XMAPReadNext 1-995


3/5/10 

Return Values 

The following table describes the return values for the XMAPReadNext function. 



XML_SUCCESS The XMAPReadNext was executed successfully. 

XML_ERROR Error in executing XMAPReadNext. 

XML_INVALID_HANDLE U2 XMAP dataset handle was invalid. 

XML_EOF The end of the U2XMAP dataset has been reached. 

XMAPReadNext Return Values

C:\Program 


XMAPToXMLDoc 

Syntax 

XMAPToXMLDoc(XMAPhandle, xmlfile, doc_flag[, xmlOptions]) 



Description 

The XMAPToXMLDoc function generates an XML document from the data in the 

U2XMAP dataset using the mapping rules you define. The XML document can be 

either an XML DOM handle or an XML document. UniData writes the data to a file 

or a UniBasic variable. 

Parameters 




XMAPToXMLDoc Parameters 

XMAPToXMLDoc 1-997


3/5/10 



xmlfile The name of the XML file, or the name of a UniBasic variable to hold the 

XML document. 

doc_flag Indicates where to write the XML document. Valid values are: 

XML.TO.DOM - Writes the XML document to an XML DOM handle. 

XML.TO.FILE - Writes the XML document to a file. 

XML.TO.STRING - Writes the XML document to a UniBasic variable. 

xmlOptions A string specifying the key/value pairs of the XML options to be used in the 

XML document generated by this function. [IN] 


"encoding=ISO-8859-1 standalone=yes newline=CR-LF" 

or 

‘encoding="iso-8859-1" standalone="no"’ 

The XML options are the same as those in the xmlconfig file and accept the 

same values. Keys and values are case-insensitive. 

Valid encoding settings can be found at http://www.iana.org/assignments/character-sets 

XMAPToXMLDoc Parameters (continued)

C:\Program 


Return Values 

The following table describes the return values of the XMAPToXMLDoc function. 




If an error is encountered in xmlOptions, XMLGetError() 

returns one of the following error codes: 





XMAPToXMLDoc Return Values 

XMAPToXMLDoc 1-999


3/5/10 

XMLError 

Syntax 

XMLError(errmsg) 



Description 

Use the XMLError function to get the last error message. 

Errmsg is the error message string, or one of the following return values: 



XML.ERROR Failure

C:\Program 


XMLExecute 

Syntax 

XMLExecute(cmd, options, xmlvar, xsdvar) 



Description 

The XMLExecute function enables you to create an XML document using the 

UniQuery LIST statement or the UniData SQL SELECT statement from a UniBasic 

program. 

Parameters 



cmd Holds the text string of the UniQuery LIST statement or the UniData SQL 

SELECT statement. [IN] 

options Each XML-related option is separated by a field mark (@FM). If the 

option requires a value, the values are contained in the same field, 

separated by value marks (@VM). 

WITHDTD Creates a DTD and binds it with the XML 

document. By default, UniData creates an XML 

schema. However, if you include WITHDTD in 

your UniQuery or UniData SQL statement, 

UniData does not create an XML schema, but 

only produces the DTD. 

ELEMENTS The XML output is in element-centric format. 

XMLExecute Parameters 

XMLExecute 1-1001


3/5/10 



‘XMLMAPPING’: 

@VM:’mapping_file_ 

name’ 

‘SCHEMA’:@VM: 

’type’ 

Specifies the mapping file containing transformation 

rules for display. This file must exist in 

the _XML_ directory. 

The default schema format is ref type schema. 

You can use the SCHEMA attribute to define a 

different schema format. 

HIDEMV, HIDEMS Normally, when UniData processes multivalued 

or multi-subvalued fields, UniData adds another 

level of elements to produce multiple levels of 

nesting. You have the option of disabling this 

additional level by adding the HIDEMV and 

HIDEMS attributes. When these options are on, 

the generated XML document and the 

associated DTD or XML schema have fewer 

levels of nesting. 

HIDEROOT Allows you to specify to only create a segment 

of an XML document, for example, using the 

SAMPLE keyword and other conditional 

clauses. If you specify HIDEROOT, UniData 

only creates the record portion of the XML 

document, it does not create a DTD or XML 

schema. 

‘RECORD’:@VM: 

’newrecords’ 

‘ROOT’:@VM: 

’newroot’ 

The default record name is FILENAME_record. 

The record attribute in the ROOT element 

changes the record name. 

The default root element name in an XML 

document is ROOT. You can change the name of 

the root element as shown in the following 

example: 

root=”root_element_name” 

XMLExecute Parameters (continued)

C:\Program 



Example 

TARGETNAM- 

ESPACE:@FM:’name 

spaceURL’ 

COLLAPSEMV, 

COLLAPSEMS 

The following example illustrates the XMLExecute function: 

UniData displays the targetnamespace attribute 

in the XMLSchema as 

targetNamespace, and uses the URL you specify 

to define schemaLocation. If you define the 

targetnamespace and other explicit namespace 

definitions, UniData checks if the explicitly 

defined namespace has the same URL and the 

targetnamespace. If it does, UniData uses the 

namespace name to qualify the schema element, 

and the XML document element name. 

Normally, when UniData processes multivalued 

or multi-subvalued fields, UniData adds another 

level of elements to produce multiple levels of 

nesting. You have the option of disabling this 

additional level by adding the COLLAPSEMV 

and COLLAPSE MS attributes. When these 

options are on, the generated XML document 

and the associated DTD or XML Schema have 

fewer levels of nesting. 

XmlVar The name of the variable to which to write the generated XML document 

[OUT] 

XsdVar The name of the variable in which to store the XML Schema if one is 

generated along with the XML document. [OUT] 

XMLExecute Parameters (continued) 

CMD="SELECT SEMESTER,COURSE_NBR FROM STUDENT;" 

OPTIONS := "COLLAPSEMS" 

OPTIONS := @FM:"HIDEROOT" 

OPTIONS := @FM:"root":@VM:"mystudent" 

OPTIONS :=@FM:"record":@VM:"myrecord" 

OPTIONS :=@FM:"targetnamespace":@VM:"http://www.ibm.com" 

OPTIONS := @FM:"elementformdefault" 

STATUS = XMLEXECUTE(CMD,OPTIONS,XMLVAR,XSDVAR) 

PRINT XSDVAR 

PRINT XMLVAR 

XMLExecute 1-1003


3/5/10 

XMLGetError 

Syntax 

XMLGetError(errorCode, errorMessage) 



Description 

XMLGetError gets the error code and error message after the previous XML API 

failed. 

Parameters 


Return Codes 





errorCode The error code. [OUT] 

errorMessage The error message. [OUT] 

XMLGetError Parameters 




XDOMGetError Return Codes

C:\Program 


XMLGetOptions 

Syntax 

XMLGetOptions(outOptions[, delimiterString]) 

Description 

Use this function in UniBasic programs to return the values for encoding and other 

XML options in effect in the current UniData session. 

Parameters 



outOptions A variable used to retrieve the XML options key/value pairs in 

effect in the current UniData session. [OUT] 

delimiterString Optional. Specifies the string to be used to separate the key/value 

pairs returned by the command. By default, delimiterString is a 

space. [IN] 

XMLGetOptions Parameters 

Examples 

The following example shows the format for entering delimiterString as the string 

used to separate the key/value pairs returned by the function. Key/value pairs can be 

separated by a space or by any string, such as , as shown in this example: 

(xmlOptions, "") 

encoding=defaultin-encoding=UTF-8version=1.1standalone=no 

out-xml-declaration=trueout-format-pretty-print=falseoutnormalize-characters=trueout-split-cdata-sections=trueoutvalidation=falseout-expand-entity-references=falseoutwhitespace-in-element-content=trueout-discard-defaultcontent=trueout-format-canonical=trueout-write-bom=false 

XMLGetOptions 1-1005


3/5/10 

If you enter the XMLGetOptions function with no delimiterString, the key/value 

pairs are separated by a space, as shown in the next example: 

XMLGetOptions(xmlOptions) 


encoding=default in-encoding=UTF-8 version=1.1 standalone=no outxml-declaration=true 

out-format-pretty-print=false out-normalizecharacters=true 

out-split-cdata-sections=true out-validation=false 

out-expand-entity-references=false out-whitespace-in-elementcontent=true 

out-discard-default-content=true out-formatcanonical=true 

out-write-bom=false 

Return Codes 

The return code indicates the status on completion of this function. The following 

table describes each return code. 



XMLGetOptions Return Codes

C:\Program 


XMLGetOptionValue 

Syntax 

XMLGetOptionValue(optionName, outOptionValue) 

Description 

Use this function in UniBasic programs to return the value of encoding or any other 

XML option in effect in the current UniData session. 

Parameters 



optionName The name of the XML option for which you want to retrieve the 

current value. [IN] 

The XML options are the same as those in the xmlconfig file. 

outOptionValue A variable used to retrieve the value of the specified XML option 

in the current UniData session. [OUT] 

XMLGetOptionValue Parameters 

Example 

The following example shows the format for entering the optionName and outOptionValue 

variables: 

XMLGetOptionValue("encoding", xmlOptionValue) 

This function returns the value of the encoding option in the second argument, 

xmlOptionValue. 

XMLGetOptionValue 1-1007


3/5/10 

Return Codes 


return code. 




XML.ERROR When the return status is XML.ERROR, XMLGetError() returns 

the following error code: 


XMLGETOPTIONVALUE Return Codes

C:\Program 


XMLSetOptions 

Syntax 

XMLSetOptions("options") 

Description 

Use this function in UniBasic programs to set the encoding parameter and other XML 

options in the current UniData session. The settings specified in this API override the 

settings in the system-level and account-level xmlconfig files and in ECL commands 

during the current session. 

Parameters 



options A string in the format of space-delimited key/value pairs. [IN] 

The XML options are the same as those in the xmlconfig file and 

accept the same values. Keys and values are case-insensitive. 

The XMLSetOptions function also accepts three special strings as 

the options parameter. 

defaults – Sets all XML options to their default settings in 

the current session. 

reload – Reloads the current system-level and account-level 

xmlconfig files, since they may have changed after you started 

your UniData session. 

reset – Resets XML options to the original settings that were 

loaded when you started the UniData session. 

A special string must be entered as the only option. 

XMLSetOptions Parameters 

XMLSetOptions 1-1009


3/5/10 

Examples 

The following example shows the format for entering the XML options in this API. 


XMLSetOptions("encoding=iso-8859-1 newline=CR-LF") 

The next example shows the format for entering a special string as the options 

parameter: 

XMLSetOptions("defaults") 

Return Codes 


return code. 



XML.ERROR When the return status is XML.ERROR, XMLGetError() returns 

one of the following error codes: 




Note: When the return code is XML.ERROR, none of the 

XML parameters are changed. 

XMLSetOptions Return Codes

C:\Program 


XMLTODB 

Syntax 

XMLTODB(xml_document, doc_flag, u2xmapping_rules, u2xmap_ flag, status) 

Description 

The XMLTODB function populates the UniData database from UniBasic. If you 

want to transform specific data, use the XMAP API. 

Parameters 



xml_document The name of the XML document. 


XML.FROM.DOM - xml_document is a DOM handle. 

XML.FROM.FILE - xml_document is a file name. 

XML.FROM.STRING - xml_document is the name of 

variable containing the XML document 

u2xmapping_rules The mapping rules for the XML document. 

u2xmap_flag A flag indicating if the mapping file is the U2XMAP file itself 


are: 


U2XMAP file. 

XMAP.FROM.STRING - u2xmap_flag is the name of the 

variable containing the mapping rules. 

Status The return status. 

XMAPOpen Parameters 

XMLTODB 1-1011

ASCII Character 

Codes 

This appendix describes each ASCII (American Standard Code for 

Information Interchange) code. 

ASCII Value 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 

011 VT B 

012 FF C 

013 CR D 

014 SO E 

ASCII Character Codes 

Hex 

Character 

Appendix 

A


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 

036 $ 24 

037 % 25 

ASCII Character Codes (continued) 

Hex 

Character 

A-2

A-3 UniBasic Commands Reference 


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 


Hex 

Character


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 


Hex 

Character 

A-4



084 T 54 

085 U 55 

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 


Hex 

Character


107 k 6B 

108 l 6C 

109 m 6D 

110 n 6E 

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 


Hex 

Character 

A-6



130 é 82 

131 â 83 

132 ä 84 

133 à 85 

134 å 86 

135 ç 87 

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 


Hex 

Character


153 Ö 99 

154 Ü 9A 

155 ¢ 9B 

156 £ 9C 

157 ¥ 9D 

158 ¤ 9E 

159 ƒ 9F 

160 á A0 

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 


Hex 

Character 

A-8



176 ã B0 

177 õ B1 

178 Ø B2 

179 ø B3 

180 œ B4 

181 Œ B5 

182 À B6 

183 Ã B7 

184 Õ B8 

185 § B9 

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 


Hex 

Character


199 Á C7 

200 Â C8 

201 È C9 

202 Ê CA 

203 Ë CB 

204 Ì CC 

205 Í CD 

206 Î CE 

207 Ï CF 

208 Ò D0 

209 Ó D1 

210 Ô D2 

211 nonprinting D3 

212 nonprinting D4 

213 Ù D5 

214 Ú D6 

215 Û D7 

216 Ÿ D8 

217 ß D9 

218 nonprinting DA 

219 nonprinting DB 

220 nonprinting DC 

221 nonprinting DD 


Hex 

Character 

A-10



222 nonprinting DE 

223 nonprinting DF 

224 nonprinting E0 










234 nonprinting EA 

235 nonprinting EB 

236 nonprinting EC 

237 nonprinting ED 

238 nonprinting EE 

239 nonprinting EF 

240 nonprinting F0 






Hex 

Character







250 nonprinting FA 

251 text mark FB 

252 subvalue 

mark 

FC 

253 value mark FD 

254 attribute mark FE 

255 record mark FF 


Hex 

Character 

A-12

UniBasic@variables 

This appendix lists the @variables available in UniBasic, the delimiter 

@variables, and the codes returned by @SYSTEM.RETURN.CODE. 

Appendix 

B

@variables 

The following table describes the valid @variables. 

@variable Description 

@ACCOUNT Returns the operating system 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 about other system delimiter @ variables, see 

“Delimiter @variables” in this appendix. 

@COMMAND Last UniData command executed. Changes the value for each 

statement executed 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 data stack or input queue. 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, in internal format, when the program began 

executing. 

@DAY Two-digit day of the month. 

@DICT Current dictionary (must perform an assignment). 

@FORMAT Used with CALCULATE and the braces {} function. Returns 

the format code from a dictionary item. 

@GID For UNIX, returns the group ID assigned to a user. For 

Windows NT or Windows 2000, returns a string that contains 

all the group names (separated by value marks) to which the 

user belongs. 

@variables 

B-2

B-3 UniBasic Commands Reference 


@HEADER Used with CALCULATE and the braces {} function. Returns 

the column heading from a dictionary item. 

@ID Current record ID. 

@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 no paragraph 

is being executed, an empty string is returned. If another 

paragraph is called within the first paragraph executed, the 

returned value is of the called paragraph until control is 

returned to the calling paragraph. 

@PATH Current operating system path for the directory where the user 

resides. The value of @PATH changes with the LOGTO 

command. 

@RECORD Current record (must be assigned). 

@RECUR0 

@RECUR1 

@RECUR2 

@RECUR3 

@RECUR4 

Recursive user defined. @RECUR# variables are reset at the 

ECL prompt. 

@RM Inserts a record mark at compile time. 



@variables (continued)


@SENTENCE The statement that invoked the current UniBasic program in 

progress. Reflects the last command entered at the ECL prompt 

or in a paragraph or sentence executed by a UniBasic program. 

Each UniBasic EXECUTE and CHAIN statement also resets 

@SENTENCE. 

@SM Inserts a subvalue mark (same as @SVM) at compile time. 

For information about other delimiter variables, see “Delimiter 

@variables” in this appendix. 

@SVM Inserts a subvalue mark (same as @SM) at compile time. 



@SYS.BELL Enables or disables a user’s terminal bell. 

@SYSTEM.RETURN. 

CODE 

Returns a value indicating a condition or error after the 

execution of an ECL command. For most commands, 0 

indicates the command was completed correctly, and -1 

indicates that the command was not completed correctly. 

For more information, see “@SYSTEM.RETURN.CODE 

Values” in this appendix. 

@TIME The time (in internal format) when the first program in the call 

string program. 

@TM Inserts a text mark at compile time. The text mark has no direct 

effect, but can be used by UniBasic programs. 



@TRANSACTION Returns 1 if there is a transaction occurring, and returns 0 if 

there is no transaction occurring. 

@TTY Returns the terminal port name, such as tty01, tty1a, or console. 

@UDTNO Returns an integer between 1 and the maximum number of 

users allowed on the system. Numbers are assigned sequentially 

based on the sequence of entry into UniData. Phantom 

processes are counted. 

@UID The operating system user ID number for the user. 

@variables (continued) 

B-4

@USER0 

@USER1 

@USER2 

@USER3 

@USER4 



User-defined. @USER# variables retain their value throughout 

a user session unless the values are explicitly changed. 

@USERNO Current udt process ID number. 

@USER.RETURN.CO 

DE 

User-defined. 

@USER.TYPE Returns the type of process currently running. UniBasic has 

three types of processes: 

0 – Normal terminal processes. 

1 – Background (phantom) processes. 

2 – Redirected standard input. 

@VM Inserts a value mark at compile time. 

For information about other delimiter @variables, see 


@WHO Retrieves your current directory. For example, if you are in 

UNIX directory /u/ud/AP, the value of @WHO is AP. 

@YEAR Two-digit representation of the year. 

@variables (continued)

Delimiter @variables 

The following @variables are replaced by the compiler with dynamic arrays delimiters. 

Use the same @variables to place delimiters in UniData hashed files. 


@AM Attribute mark 

@VM Value mark 

@SM Subvalue mark 

@RM Record mark 

@TM Text mark 

@SVM Subvalue mark (same as @SM) 

Delimiter @variables 

B-6


@SYSTEM.RETURN.CODE Values 

@SYSTEM.RETURN.CODE returns various values based on the last command 

executed. @SYSTEM.RETURN.CODE is available in UniBasic, and is set by many 

commands, both UniBasic and ECL. 

ECL @SYSTEM.RETURN.CODE Values 

The following table describes the possible @SYSTEM.RETURN.CODE values for 

various ECL commands. 

Command Success Return Value Error Return Value 

BSELECT The number of items in the 

select list. 

BUILD.INDEX The number of indexes built. -1 

COMPILE.DICT 0 -1 

CREATE.INDEX The number of indexes created. -1 

DELETE.INDEX The number of indexes deleted. -1 

ESEARCH The number of items in the 

select list. 

FORM.LIST The number of items in the 

select list. 

GET.LIST The number of items in the 

select list. 

LIST The number of items listed. -1 

LIST.INDEX The number of indexes listed. -1 

LIST.ITEM The number of items listed. -1 

LIST.LABEL The number of items listed. -1 


-1 

-1 

-1 

-1


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 the 

select list. 

MODIFY The number of records 

modified. 

NSELECT The number of items in the 

select list. 

QSELECT The number of items in the 

select list. 

SAVE.LIST The number of items saved. -1 

SELECT The number of items in the 

select list. 

SORT The number of items listed. -1 

SORT.ITEM The number of items listed. -1 

SORT.LABEL The number of items listed. -1 

SSELECT The number of items in the 

select list. 

STACKCOMMON 1 – On 

0 – Off 

-1 

-1 

0 

-1 

-1 

-1 

N/A 

ECL @SYSTEM.RETURN.CODE Values (continued) 

B-8


UniBasic @SYSTEM.RETURN.CODE Values 

The following table describes the possible @SYSTEM.RETURN.CODE values for 

UniBasic commands.. 


GETQUEUE The number of locks waiting to 

be released. 

GETREADU The number of locks set. -1 

INPUT (with FOR or 

WAITING clause 

included) 

INPUT @ (with FOR or 

WAITING clause 

included) 

0 -1 (used if timeout 

option is set; INPUT 

timed out) 

0 -1 (used if timeout 

option is set; INPUT 

timed out) 

PCPERFORM 0 -1 


-1

Operators in UniBasic 

This appendix describes the arithmetic, Boolean, and relational 

operators available you can use in UniBasic. 

Appendix 

C

C-2 UniBasic Commands Reference 

Arithmetic Operators 

The following table describes the arithmetic operators for UniBasic. 

Operator Action Example Related Function 

+ Unary plus (same as 

multiplying by +1). 

- Unary minus 

(changes to the 

opposite sign, same as 

multiplying by 

-1). 

VAR = +VAR ABS 

VAR = -VAR NEG 

+ Addition. X = VAR1 + VAR2 

VAR = VAR + 1 

- Subtraction. X = VAR1 - VAR2 

VAR = VAR - 1 

SADD, SUM 

SSUB 

* Multiplication. X = VAR1 * VAR2 SMUL 

/ Division. QUANTITY = 

PRICE/COST 

SDIV 

** or ^ Exponentiation. X = VAR^2 PWR 

:, CAT Concatenation. X = VAR1:VAR2 

+= Increments the value 

of a variable. 

-= Decrements the value 

of a variable. 

LINES += 1 

LINES -= 1 

Arithmetic Operators

Operator Action Example Related Function 

*= Multiplies the value 

to the left of the 

operator by the value 

to the right of the 

operator. 

/= Divides the value to 

the left of the operator 

by the value to the 

right of the operator. 

:= Concatenates the 

value to the left of the 

operator by the value 

to the right of the 

operator. 

VAR1 *= VAR2 

VAR1 /= VAR2 

VAR1 := VAR2 

Arithmetic Operators (continued) 



C-3

C-4 UniBasic Commands Reference 

Boolean Operators 

The following table describes the Boolean operators for UniBasic. 

Operator Action Example 

AND, & When both expressions 

are true, the 

result is true. 

OR, ! When either 

expression is true, the 

result is true. 

NOT Inverts the result of 

conditional 

statements. 

NOTS Inverts the logical 

result of each element 

of a dynamic array. 

IF (X < Y) AND (Y < Z) THEN GOSUB 

1000 

IF (X < Y) OR (Y < Z) THEN GOSUB 

1000 

IF (X < Y) AND NOT (Y < z) GOSUB 

1000 

A = 1:@FM:0:@FM:1:@FM:30 

B = NOTS(A) 

B contains 0}1}0}0. 

Boolean Operators

Relational Operators 

The following table describes the relational operators for UniBasic. 

Operator 

Multivalued 

Equivalent Description Example 

=, EQ EQS Equal to. IF VAR1 = VAR2 

THEN GOSUB SUB1 

DO UNTIL VAR1 = 

VAR2 

#, , > Y THEN 

GOSUB 1000 

>, GT GTS Greater than. IF VAR1 > VAR2 


DO UNTIL VAR1 > 

VAR2 

=, =>, #= VAR2 


DO UNTIL VAR1 

=> VAR2 

Reserved Words 

This appendix lists the reserved keywords, commands, functions, and 

@variables. Do not use any of them for subroutine names or for 

UniBasic variable names. 


$BASICTYPE $DEFINE 

$F $FALSE 

$IFDEF $IFNDEF 

$INCLUDE $INSERT 

$T $TRUE 

$UNDEFINE @ 

@ACCOUNT @COMMAND 

@CONV @CRTHIGH 

@CRTWIDE @DATA 

@DATE @DAY 

@DICT @FALSE 

@FORMAT @GID 

@HEADER @ID 

@LASTVERB @LEVEL 

@LOGNAME @LPTRHIGH 


Appendix 

D


@LPTRWIDE @MONTH 

@NULL @PARASENTENCE 

@PATH @PROCTYPE 

@RECORD @RECUR0 

@RECUR1 @RECUR2 

@RECUR3 @RECUR4 

@SENTENCE @SYS.BELL 

@SYSTEM.RETURN.CO 

DE 

@TIME 

@TRANSACTION @TRUE 

@TTY @TUPLE 

@UDTNO @UID 

@USER.RETURN.CODE @USER.TYPE 

@USER0 @USER1 

@USER2 @USER3 

@USER4 @USERNO 

@WHO @YEAR 

ABORT ABS 

ABSOLUTE ACOS 

ALPHA AND 

APPEND AS 

ASCII ASIN 

ASSIGN ASYNC 

AT ATAN 

Reserved Words (continued) 

D-2

D-3 UniBasic Commands Reference 


BEFORE BEGIN 

BITAND BITNOT 

BITOR BITXOR 

BPIOCP BPIOCPN 

BREAK BUFFER.KEYS 

BY BYTELEN 

CALCULATE CALL 

CALLC CALLING 

CAPTURING CASE 

CAT CATS 

CHAIN CHANGE 

CHAR CHARLEN 

CHARS CHECKSUM 

CLEAR CLEARCOM 

CLEARCOMMON CLEARDATA 

CLEARFILE CLEARINPUT 

CLEARSELECT CLEARSQL 

CLOSE CLOSESEQ 

COL1 COL2 

COM COMMIT 

COMMON COMPILE.DICT.ITEM 

CONNECT CONTINUE 

CONVERT COS 

COUNT COUNTS 

Reserved Words (continued)


CRT CURRENT 

DATA DATE 

DCOUNT DEBUG 

DECLARE DEFFUN 

DEL DELETE 

DELETELIST DELETEU 

DIM DIMENSION 

DIR DISCONNECT 

DISPLAY DISPLAYWIDTH 

DO DOWNCASE 

DQUOTE DROUND 

DTX EBCDIC 

ECHO ELSE 

END ENTER 

EQ EQS 

EQU EQUATE 

EXECUTE EXECUTESQL 

EXIT EXP 

EXTRACT FIELD 

FIELDS FIELDSTORE 

FILEINFO FILELOCK 

FILEUNLOCK FIND 

FINDSTR FIRST_ALT_KEY 

FLUSH FMT 


D-4



FMTS FOOTING 

FOR FORMLIST 

FROM FUNCTION 

GARBAGECOLLECT GE 

GES GET 

GETCOLUMNDATA GETCOLUMNNAME 

GETENV GETERRMSG 

GETLIST GETMSG 

GETNEXTTUPLE GETPTR 

GETPU GETQUEUE 

GETREADU GETUSERGROUP 

GETUSERID GETUSERNAME 

GETX GO 

GOSUB GOTO 

GROUP GROUPSTORE 

GT GTS 

HASH HEADING 

HELP HUSH 

ICONV ICONVS 

IF IN 

INCLUDE INDEX 

INDEXS INDICES 

INMAT INPUT 

INPUTCLEAR INPUTERR 



INPUTIF INPUTNULL 

INPUTTRAP INS 

INSERT INT 

ISMB ISNV 

ISNVS ISOLATION 

ITYPE JRNL_STATUS 

LAST_ALT_KEY LE 

LEN LENGTH 

LENS LES 

LINEMARK LN 

LOCATE LOCK 

LOCKED LOOP 

LOWER LT 

LTS MAT 

MATBUILD MATCH 

MATCHES MATCHFIELD 

MATPARSE MATREAD 

MATREADL MATREADU 

MATWRITE MATWRITEU 

MAXIMUM MBLEN 

MDPERFORM MINIMUM 

MOD NE 

NEG NES 

NEXT NOCONVERT 


D-6



NODELAY NOT 

NOTS NULL 

NULLVAL_ALT_KEY NUM 

NUMS OCONV 

OCONVS OFF 

ON OPEN 

OPENSEQ OR 

OSBREAD OSBWRITE 

OSCLOSE OSDELETE 

OSOPEN OSREAD 

OSWRITE PAGE 

PASSCOM PASSCOMMON 

PASSLIST PAUSE 

PCPERFORM PERFORM 

PRECISION PREVIOUS 

PRINT PRINTER 

PRINTERR PRIOR 

PROCREAD PROCWRITE 

PROGRAM PROMPT 

PWR QUOTE 

RAISE READ 

READBCK READBCKL 

READBCKU READFWD 

READFWDL READFWDU 



READL READLIST 

READNEXT READNEXTTUPLE 

READONLY READSEQ 

READT READU 

READV READVL 

READVU READWRITE 

READXBCK READXFWD 

RECORDLOCKED RECORDLOCKL 

RECORDLOCKU RELATIVE 

RELEASE REM 

REMOVE REPEAT 

REPLACE RESIZET 

RETURN RETURNING 

REUSE REWIND 

RND RNDSEED 

RQM RTNLIST 

SADD SCMP 

SDIV SELECT 

SELECTINDEX SELECTINFO 

SEND SENDX 

SEQ SEQS 

SETINDEX SETMARK 

SETROW SETTABLE 

SETTING SIN 


D-8



SLEEP SMUL 

SOUNDEX SPACE 

SPACES SPLICE 

SQRT SQUOTE 

SSUB STATUS 

STEP STOP 

STR STRS 

SUBROUTINE SUBSTRINGS 

SUM SWAP 

SYNC SYSTEM 

TAN THEN 

TIME TIMEDATE 

TIMEOUT TO 

TRANSACTION TRIM 

TRIMB TRIMF 

TRIMS UDTEXECUTE 

UNASSIGNED UNFILTERED 

UNLOCK UNTIL 

UPCASE USE 

USING VALIDATE.KEY 

VERB WAIT 

WAITING WAKE 

WEOF WEOFSEQ 

WHILE WITH 



WRITE WRITELIST 

WRITEONLY WRITESEQ 

WRITESEQF WRITET 

WRITEU WRITEV 

WRITEVU XLATE 

XTD 


D-10

Commands Affected 

by BASICTYPEs and 

UDT.OPTIONS 

This appendix lists the UniBasic commands and functions that behave 

differently or have different syntax depending on the BASICTYPE or 

UDT.OPTIONS you have set at the time you compile the program. For 

detailed information about how BASICTYPEs or UDT.OPTIONS 

affect a particular command or function, see the documentation for that 

command or function in this manual. For descriptions of BASIC- 

TYPEs, see the UniBasic $BASICTYPE command in this manual. For 

more detailed information about UDT.OPTIONS, see the 

UDT.OPTIONS Commands Reference. 

Appendix 

E

Command or 

Function 

The BASICTYPE Setting 

Determines... UDT.OPTIONS 

$INCLUDE Whether you can use INCLUDE for 

the $INCLUDE command. 

[] Whether the [] (square brackets) 

function can entirely remove parts or 

all of a substring. 

ABORT Whether you can specify multiple 

messages to display when the 

program aborts. The BASICTYPE 

setting also determines whether you 

can specify a message ID that 

evaluates to a key in the UniData 

error message file. 

CALLC N/A 88 

N/A 

N/A 

CHAIN N/A 6, 11, 27, 40, 54 

CLEAR Whether the CLEAR command can 

set all variables in unnamed common 

areas to 0. 

COMMON Whether zero elements are 

maintained in arrays. The 

BASICTYPE setting also determines 

whether you can use the PASSCOM 

option. 

COUNT Whether the COUNT function can 

find overlapping character substrings 

in a string. 

COUNTS Whether the COUNTS function can 

find overlapping character substrings 

in an array of strings. 

8 

N/A 

N/A 

N/A 

N/A 

CRT N/A 5, 46 

DATA N/A 11, 27 

DEBUG N/A 14 

Commands and Functions Affected by BASICTYPEs and UDT.OPTIONS 

E-2

Command or 

Function 

E-3 UniBasic Commands Reference 



DISPLAY N/A 5, 46 

DIM Whether excess data (including 

delimiters) resulting from redimensioning 

an array can be placed in 

position 0,0 of the dimensioned 

array. 

EBCDIC Whether ASCII data is converted to 

EBCDIC before it is written to tape. 

ECHO N/A 99 

ENTER N/A 78 

EXECUTE Whether commands are parsed by 

using the standard UniData parser or 

the P-type parser. 

EXECUTESQL N/A 35 

FLUSH N/A 46 

FMT How the data is formatted (in cases 

for which the BASICTYPE setting 

can produce different results). 

N/A 

N/A 

11, 27, 35, 46, 93, 105 

N/A 

FOOTING N/A 34, 64 

HEADING N/A 32, 34 

ICONV Whether the ICONV function returns 

an empty string if UDT.OPTIONS 56 

is on and the input value or 

conversion code is invalid. 

ICONVS Whether the ICONVS function 

returns an empty string if 

UDT.OPTIONS 56 is on and the 

input value or conversion code is 

invalid. 

IN N/A 46 

56 (for ICONV D, 

also 60 and 82; for 

ICONV MC, also 62) 


56

Command or 

Function 



INPUT N/A 12, 18, 46, 65, 83 

INPUT @ N/A 101 

LOCATE The number of array elements you 

can include in a search and the search 

driven by those elements. 

MATPARSE Whether excess data (including 

delimiters) resulting from executing 

the MATPARSE command can be 

placed in position 0,0 of the dimensioned 

array. 

MATREAD Whether excess data (including 


the MATREAD command can be 


array. 

MATREADL Whether excess data (including 


the MATREADL command can be 


array. 

MATREADU Whether excess data (including 


the MATREADU command can be 


array. 

MDPERFORM N/A 35 

OCONV Whether the OCONV function 




invalid. 

85 

N/A 

N/A 

N/A 

N/A 

56 (for OCONV D, 

also 4 and 29; for 

OCONV MD, also 13 

and 63) 


E-4

Command or 

Function 




OCONVS Whether the OCONVS function 




invalid. 

ON/GOSUB Whether UniData bypasses the 

GOSUB clause and executes the next 

program statement (contingent on 

whether the expression in the 

ON/GOSUB command is nonnumeric 

or less than 1). 

ON/GOTO Whether UniData bypasses the 

GOTO clause and executes the next 

program statement (contingent on 

whether the expression in the 

ON/GOTO command is nonnumeric 

or less than 1). 

PCPERFORM N/A 35 

PERFORM Whether commands are parsed by 

using the standard UniData parser or 

the P-type parser. 

56 

N/A 

N/A 

PRINT N/A 5, 46 

PROCREAD N/A 75, 102 

PROCWRITE N/A 75 

11, 27, 35, 46, 93, 105 

Commands and Functions Affected by BASICTYPEs and UDT.OPTIONS

Command or 

Function 



READLIST Whether you should use the 

READLIST or READSELECT 

command to assign values in an 

active select list to a dynamic array. 

The BASICTYPE setting also determines 

whether you can assign values 

in a select list, based on an account 

other than the current one, to a 

dynamic array. It also determines 

whether you can use the SETTING 

clause to set the number of elements 

in the select list to a variable. 

READNEXT Whether you can assign the next 

record ID from an active select list, 

based on an account other than the 

current one, to a variable. It also 

determines whether you can use the 

SETTING clause to set the number of 

elements in the select list to a 

variable. 

RECORDLOCKED N/A 35 

RELEASE N/A 78 

SELECT Whether you can specify a numbered 

select list (0–9) in the SELECT 

command. 

SELECTINFO What the -1 SELECTINFO function 

return value means. 

SLEEP N/A 46 

STOP Whether you can specify multiple 

messages to display when the 

program stops. The BASICTYPE 

setting also determines whether you 

can specify a message ID that 

evaluates to a key in the UniData 

error message file. 

N/A 

23, 71 

N/A 

N/A 

8, 46 


E-6

Command or 

Function 




SYSTEM N/A 100 

TRIM Whether all leading and trailing 

spaces or occurrences of a specified 

character are removed from each 

element in a dynamic array. For a 

simple string expression, any 

BASICTYPE setting produces the 

same result. 

UDTEXECUTE N/A 35 

N/A 

Commands and Functions Affected by BASICTYPEs and UDT.OPTIONS

Commands That Set 

STATUS() Return 

Values 

This appendix lists the UniBasic commands and functions that set 

STATUS function return values and describes each value. 

Appendix 

F

F-2 UniBasic Commands Reference 

Command or 

Function STATUS() Return Values 

FILELOCK 0 – File locked successfully. 

usernum – If the file was already locked, and if the LOCKED 

clause was included in the FILELOCK statement, STATUS() 

returns the user number of the process that locked the file. 

FMT 0 – Successful completion. 

1 – String expression is invalid or exceeds the allowable string 

size. 

2 – Conversion code is invalid. 

GETPTR 0 – Successful completion. 

1 – No more rows exist. 

2 – Other error. 

ICONV 0 – Successful conversion. 

1 – Invalid input data. 

2 – Invalid conversion specification. 

3 – Invalid date for “D” conversion code only. 

5 – Null value if null value handling is turned on. 

ICONV D 0 – Successful conversion of a valid date. 

1 – Invalid input date. 


3 – Date was converted correctly, but month and day were 

inverted in input value. 

ICONVS 0 – Successful conversion. 

1 – Invalid input data. 


3 – Invalid date for “D” conversion code only. 

5 – Null value if null value handling is turned on. 

Commands and Functions That Set STATUS() Return Values

Command or 


MATWRITE 0 – The record was locked before MATWRITE executed. You 

are in danger of simultaneously updating a record being updated 

by another user. 

-2 – The record was not locked before MATWRITE executed. 

MATWRITEU 0 – The record was locked before MATWRITEU executed. You 

are in danger of simultaneously updating a record being updated 

by another user. 

-2 – The record was not locked before MATWRITEU executed. 

OCONV D 0 – Successful conversion of a valid date. 

1 – The input date was invalid. 

2 – The conversion code was invalid. 

OPENSEQ 0 – The record does not exist. 

1 – The file you specify is not a sequential-access file. 

2 – The file does not exist. 

3 – The READONLY clause was included in the command 

statement and the record does not exist. 

4 – An unknown error occurred (such as having too many files 

open or permission problems). 

OSBREAD 0 – The read was successful. 

1 – The file name is invalid. 

2 – Access is denied by the operating system. 


4 – An unknown error occurred. 

OSBWRITE 0 – The write was successful. 

1 – The file name is invalid. 

2 – You do not have permission to access the file. 


OSCLOSE 0 – The file has closed successfully. 

5 – The file did not close. 

Commands and Functions That Set STATUS() Return Values (continued) 

F-3


Command or 


OSDELETE 0 – The file was deleted. 

1 – The directory name is invalid. 

2 – UniData cannot access the file (such as user does not have 

permission). 


READ 0 – Successful read. 

2 – A read error occurred. 

READBCK 0 – Successful read. 

10 – UniBasic found and read a duplicate alternate index key 

value, and ECL DUP.STATUS is on. 

READBCKL 0 – Successful read. 



READBCKU 0 – Successful read. 



READFWD 0 – Successful read. 



READFWDL 0 – Successful read. 



READFWDU 0 – Successful read. 



READL 0 – Successful read. 

1 – UniData was unable to read the record. 

n – The record is locked. The user number of the user who 

locked the record. 

Commands and Functions That Set STATUS() Return Values (continued)

Command or 


READT 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. 

READU 0 – Successful read. 

1 – UniData was unable to read the record. 

n – The record is locked. The user number of the user who 

locked the file is returned in n. 

RECORDLOCKED n – The record is locked. The user number of the user who owns 

the lock is returned in n. 

0 – The record is not locked. 

-1 – The file is NFA. Currently, RECORDLOCKED does not 

support NFA files. 

-2 – Invalid file type. file.var can contain the null value. 

-3 – System error: unknown user. 

SELECTINDEX 0 – The select list is loaded with alternate key values or record 

IDs for the specified file. 

1 – No alternate index key exists for this attribute using the name 

specified. The select list is empty. 

SETINDEX 0 – The alternate key specified exists. 

1 – Error. 

2 – The alternate key specified does not exist. 


F-5

SUBROUTINE (Update 

Trigger) 

SUBROUTINE (Delete 

Trigger) 

TRANSACTION 

COMMIT 

TRANSACTION 

START 


Command or 


0 – No error. 

1 – System error, such as a damaged file. 

2 – Constraint violation. In this case, the UniBasic trigger 

subroutine returns a value of 0 in the parameter execstat, 

indicating that the update or delete is not allowed. 

3 – Trigger execution error or unexpected return from trigger 

routine (for example, the trigger subroutine is not cataloged). 

0 – No error. 




indicating that the update or delete is not allowed. 



0 – The commit completed successfully. 

1 – Transaction not started. 

3 – Transaction cannot commit. 

0 – The transaction was started. 

1 – The transaction was not started. 

WEOF 0 – Successful read. 








Command or 


WRITE 0 – Successful write. 




indicating that the WRITE is not allowed. 



10 – Non-RFS files: WRITE created a duplicate alternate index 

key and ECL DUP.STATUS is on; or WRITE failed because a 

duplicate value exists in the index, and NO.DUPS was specified 

when the index was created. RFS files: WRITE created a 

duplicate value in the index, and ECL DUP.STATUS is on. 

WRITET 0 – Successful read. 








F-7


Command or 


WRITEU 0 – Successful write. 




indicating that the WRITEU is not allowed. 


routine (for example, trigger subroutine is not cataloged). 

10 – Non-RFS files: WRITEU created a duplicate alternate 

index key and ECL DUP.STATUS is ON; or WRITEU failed 

because a duplicate value exists in the index, and NO.DUPS was 

specified when the index was created. RFS files: WRITEU 

created a duplicate value in the index, and ECL DUP.STATUS is 

ON. 

WRITEV 0 – Successful write. 




indicating that the WRITEV is not allowed. 



10 – Non-RFS files: WRITEV created a duplicate alternate 

index key and ECL DUP.STATUS is on; or WRITEV failed 

because a duplicate value exists in the index and NO.DUPS was 

specified when the index was created. RFS files: WRITEV 


on. 


Command or 


WRITEVU 0 – Successful write. 




indicating that the WRITE VU is not allowed. 



10 – Non-RFS files: WRITEVU created a duplicate alternate 

index key and ECL DUP.STATUS is ON; or WRITEVU failed 

because a duplicate value exists in the index, and NO.DUPS was 

specified when the index was created. RFS files: WRITEVU 


ON. 


F-9

UniBasic Commands Reference - Rocket Software

Create successful ePaper yourself

Delete template?

Save as template?