Unify VISION: 4GL Reference - Support

R

Unify VISION: 4GL Reference

E

1996, 1999, 2000, 2002 Unify Corporation. All rights reserved. Sacramento, California, USA.

No part of this document may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise without the prior written consent of Unify Corporation. Unify Corporation makes no representations or warranties with respect to the contents of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Unify Corporation reserves the right to revise this document and to make changes from time to time in its content without being obligated to notify any person of such revisions or changes. The Software described in this document is furnished under a Software License Agreement. The Software may be used or copied only in accordance with the terms of the license agreement. It is against the law to copy the Software on tape, disk, or any other medium for any purpose other than that described in the license agreement. The Unify Corporation Publications Department values and appreciates any comments you may have concerning our products or this document. Please address comments to: Unify VISION Product Manager Unify Corporation 2101 Arena Blvd. Suite 100 Sacramento, CA 95834–1922 (800) 468–6439 (916) 928–6400 FAX (916) 928–6406 UNIFY, ACCELL, VISION, and the Unify Logo are registered trademarks of Unify Corporation. DataServer is a trademark of Unify Corporation. UNIX is a registered trademark of The Open Group in the United States and other countries. The X Window System is a product of the Massachusetts Institute of Technology. Motif, OSF, and OSF/Motif are trademarks of Open Software Foundation, Inc. SYBASE is a registered trademark, and SQL Server, DB_Library, and Open Server are trademarks of Sybase, Inc. INFORMIX is a registered trademark of a subsidiary of IBM. INGRES is a trademark of Computer Associates INternational, Inc. ORACLE is a registered trademark of Oracle Corporation. Sun is a registered trademark, and SunView, Sun_3, Sun_4, X11/NeWS, SunOS, PC_NFS, and Open Windows are trademarks of Sun Microsystems. All SPARC trademarks are trademarks or registered trademarks of SPARC International, Inc. SPARCstation is licensed exclusively to Sun Microsystems, Inc. Novell is a registered trademark of Novell, Inc. Macintosh is a trademark of Apple Computer, Inc. Microsoft, MS, and Windows are registered trademarksoff Microsoft. All other products or services mentioned herein may be registered trademarks, trademarks, or service marks of their respective manufacturers, companies, or organizations. Part Number: 7366-05 2

Contents About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15

Part I Language fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17

1

19 20 20 21 24 26 27 27 27 28 30 30 33 36 37

Writing scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VISION Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Help with VISION Script Editor . . . . . . . . . . . . . . . . . . . . . . Connecting to a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database connection statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database-dependent system functions . . . . . . . . . . . . . . . . . . . . . . . DBMS-specific statements and clauses . . . . . . . . . . . . . . . . . . . . . . Referring to database objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Qualifying table or column names . . . . . . . . . . . . . . . . . . . . . . . . . . Database object name case sensitivity . . . . . . . . . . . . . . . . . . . . . . . Using table name synonyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating SYBASE SQL Server temporary tables from scripts . . . . . . . Processing queries and using the browse feature with SYBASE SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing database queries for SYBASE SQL Server . . . . . . . . . . . . . Using the browse feature with SYBASE SQL Server . . . . . . . . . . . Embedded SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The EXECUTING clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The locking clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing parameters to SQL statements . . . . . . . . . . . . . . . . . . . . . . . Writing a dynamic SQL section in a script . . . . . . . . . . . . . . . . . . . . Describing the SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using an SQL handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling stored procedures from form scripts . . . . . . . . . . . . . . . . . . . . . Calling INFORMIX stored procedures . . . . . . . . . . . . . . . . . . . . . .

39 39 40 41 42 43 43 44 45 45 46 47 48 51 54 54 3

Calling INGRES database procedures . . . . . . . . . . . . . . . . . . . . . . . Calling ODBC stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling ORACLE stored procedures . . . . . . . . . . . . . . . . . . . . . . . . Calling SYBASE SQL Server stored procedures . . . . . . . . . . . . . . . Using Unify DataServer stored procedures . . . . . . . . . . . . . . . . . . . 2

4

56 58 58 62 70

Script functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Types of functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Global functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Local functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Defining a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 The function header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Defining a global or local function . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Defining return values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Defining function names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Defining function parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Writing the function body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Using a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Calling the function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Declaring the function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Using ORACLE system functions in scripts . . . . . . . . . . . . . . . . . . . . . 90 Executing functions with timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Timer event example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Declaring a timer event handler function . . . . . . . . . . . . . . . . . . . . . 91 Creating a timer event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Deleting a timer event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Error-handler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Elements used by an error-handler function . . . . . . . . . . . . . . . . . . . 93 Defining an error handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Declaring a DBMS error handler . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Declaring a script error handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Installing an error handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Returning information about ORACLE version 7 or SYBASE SQL error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Handling SYBASE SQL Server errors . . . . . . . . . . . . . . . . . . . . . . . . . 99 Handling SYBASE SQL Server transaction abort errors . . . . . . . . . 99 Handling SYBASE SQL Server trigger errors . . . . . . . . . . . . . . . . . 100 Building links for data transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Building a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Building a cold link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Building a hot link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Writing DDE event handler functions . . . . . . . . . . . . . . . . . . . . . . . 110 Unify VISION: 4GL Reference

3

4

Contents

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

117

Using the preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

123

Using a preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

124

Defining preprocessor variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the #define statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the #define variable statement . . . . . . . . . . . . . . . . . . . . . . . .

125 125 126

Including external files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

130

Tokens and operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

133

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence of operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

134 136 136

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

138

Tokens and symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form script tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metacharacters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

140 140 141

Member operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

142

Dereference operator (–>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

143

Assignment operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SET statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clear-to-find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

146 146 146

Arithmetic operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Addition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subtraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiplication and division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modulus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unary positive and negative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

148 148 149 149 151 152 152

Relational operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Equality and inequality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

153 154 156 158

Logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical OR and logical AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical NOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

161 162 163

Bitwise operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bitwise OR and bitwise AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bitwise negation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

165 166 166 5

6

Null value operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Undefined value operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

168 169

Part II VISION 4GL language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

171

5

173 174 176 178 181 184 186 188 190 191 196 197 199 200 201 204 206 208 213 215 217 221 223 226 228 230 232 234 236 238 240

Script statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALTER SCHEMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALTER TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEGIN_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BEGIN WORK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BREAKPOINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CANCEL FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHANGE CURRENT RECORD TO . . . . . . . . . . . . . . . . . . . . . . . . . . CHOOSE FORM USING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLEAR COMMAND QUEUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLEAR TO ADD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLOSE CONNECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLOSE PIPELINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COMMIT WORK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE CONNECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE PIPELINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE SCHEMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE SERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE TIMER EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE VIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DEFINE CONNECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DEINSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE CURRENT RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE CURRENT SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE SELECTED ROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE TIMER EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


Contents

DESTROY CONNECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

241

DESTROY SERVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

242

DISABLE ZOOM TO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

243

DISMISS FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

244

DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

246

DISPLAY FILE CHOOSER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

250

DISPLAY NOTICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

254

DROP SCHEMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

256

DROP TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

258

DROP VIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

260

ENABLE ZOOM TO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

262

END_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

268

ERASE NOTICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

269

EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

270

EXECUTE COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

272

EXECUTE_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

274

EXECUTING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

277

EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

280

EXTERN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

281

FOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

285

FREE_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

287

FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

289

GRANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

295

IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

297

INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

299

INSERT INTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

301

INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

303

MAKE CURRENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

308

METHOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

310

NEXT ACTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

313

OPEN CONNECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

317

POSITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

318

PREPARE_SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

319

PRINT FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

322 7

6

8

PRIVATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PUBLIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QUEUE COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RAISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RAISE EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REFRESH CURRENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REFRESH DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REJECT OPERATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REJECT RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RESIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RESTART ON FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RETRIEVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ROLLBACK WORK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEND MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SEND SUPER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UPDATE CURRENT RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UPDATE SELECTED ROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VALUES TO RETURN ARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WAIT FOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WRITE PIPELINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

323 333 342 345 346 348 351 352 355 356 358 359 361 363 365 367 370 373 377 378 389 393 395 398 401 404 406 409 411 413 415 418

System functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acquire_global_uvns$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423 424


Contents

acquire_local_uvns$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

425

acquire_uohost$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

426

aud_mode$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

427

background$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

428

beep$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

430

binarylen$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

431

char_code_to_str$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

432

check_dirty$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

433

child_forms$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

436

clip_str$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

437

close_message_file$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

438

convert_timezone$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

439

copy_in$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

440

current_date$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

443

current_datetime$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

444

current_form$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

445

current_record_count$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

446

current_record_num$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

447

current_time$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

448

current_timezone$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

449

dap_4gl_errcode$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

450

dap_td_count$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

451

dap_td_errcode_i$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

452

dap_ti_errcode$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

455

date_to_mdy$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

457

datetime_adjust$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

459

datetime_diff$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

461

db_type$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

463

dbms_status$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

465

dbms_status_i$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

466

dde_get_data$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

468

dde_get_hot_links$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

470

dde_get_links$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

472

dde_get_response$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

474 9

10

dde_initiate_hot_link$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

476

dde_initiate_link$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

479

dde_request_data$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

482

dde_send_command$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

485

dde_send_data$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

487

dde_terminate_hot_links$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

490

dde_terminate_link$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

492

display_tooltips$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

495

encrypt_db_password$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

496

explicit_mode$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

497

first_visible_record_number$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

499

flush_to_disk$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

500

gen_where$() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

501

get_line_of_text$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

505

get_message$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

506

get_password$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

508

getenv$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

509

glob_str_compare$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

512

group_id$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

515

group_name$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

516

is_current_record_stored$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

517

l_allow_interrupt$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

519

l_wait_time$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

521

last_command$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

523

last_command_name$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

525

mdy_to_date$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

527

null_convert$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

529

open_message_file$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

531

os_type$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

532

pad_str_left$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

533

pad_str_right$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

535

push_shell$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

537

record_is_current$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

539

reg_exp_str_compare$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

540


Contents

set_cursor_mem_limit$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

544

set_image$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

546

set_interrupt$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

547

set_scrolling_list$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

548

show_dirty$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

550

sleep$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

553

sp_compute$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

554

sp_return$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

556

sp_select$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

559

sql_clear$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

561

sql_code$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

562

sql_errmsg$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

563

sql_errmsg_count$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

564

sql_errmsg_i$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

566

sql_state$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

568

status$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

569

str_search$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

577

str_to_char_code$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

578

str_to_date$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

579

str_to_datetime$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

581

str_to_time$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

582

str_to_val$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

583

strlen$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

585

subbinary$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

587

substitute_str$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

588

substr$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

589

sync_pipelines$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

591

system$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

592

to_amount$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

594

to_binary$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

595

to_bool$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

596

to_date$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

597

to_datetime$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

598

to_float$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

599 11

to_julian$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

600

to_num$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

601

to_string$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

602

to_string_using$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

604

to_text$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

606

to_time$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

608

to_value$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

609

trim_bytes$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

610

tx_mode$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

612

ui_type$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

615

unique_sequence$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

617

user_id$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

618

user_name$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

619

val_to_str$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

620

yesno$( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

622

Predefined C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

625

uacldb( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

626

uacldbp( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

629

uaclGetDatetime( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

632

uacllda( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

634

uaclPutDatetime( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

637

uaclrid( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

639

uacltx( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

641

uaclwhr( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

644

Appendix A: Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

649

Appendix B: External files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

659

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

661

7

12


Contents

13

14


About this manual This manual is one of a set that describes the Unify VISION application development system. This manual, Unify VISION: 4GL Reference, describes how to write form scripts and provides a reference to all of the statements and system functions in VISION 4GL. This manual uses the following typographical conventions to differentiate Unify VISION features:

Dependencies This manual contains information that is specific to Unify VISION when used with any supported DBMS, user interface, or operating system. Shaded areas in syntax descriptions indicate features that are restricted to a particular user interface, operating system, or DBMS. Windows

The term Windows indicates Windows 95, Windows 98, and Windows NT operating systems. Information that is identified as specific to Windows 95 also applies to Windows 98.

Syntax

About this manual

boldface

Boldface words are literal strings that you must type exactly as shown.

italic words

Italic words indicate arguments, variables, numbers, or expressions that you must provide. Examples are table names, column names, and constants.

UPPERCASE

Boldface UPPERCASE words are Unify VISION reserved words, such as attribute names, VISION 4GL statements, and preferences. 15

UPPERCASE

Other UPPERCASE words represent Unify VISION types, such as FLOAT and TEXT.

()

Parentheses enclosing an item in the syntax indicate that several elements make up a single item. If the parentheses are in boldface type, they are part of the syntax and must be included.

[]

Square brackets indicate that the enclosed word or item is optional and may be left out. If the brackets are in boldface type, they are part of the syntax and must be included.

|

Vertical bars between options mean that you can choose one of the listed options, but only one of them.

{}

Curly braces indicate that you must select one of the listed options.

[...]

Ellipsis points indicate that you can repeat the immediately preceding item any number of times, as needed.

Narrative text Manual Title

Titles of manuals are shown in italics, for example, Unify VISION: Developing an Application.

“Title”

Chapter and section titles are enclosed by a pair of quotation marks.

Special paragraphs This manual contains specially marked paragraphs that contain noteworthy information: Tip

Warning

Related information

16

A “Tip” paragraph contains a suggested action or other helpful information. A “Warning” paragraph cautions against an action that could cause data loss or corruption of the database. A “Related information” paragraph directs you to other manuals that contain additional information about the topic.


Part I Language fundamentals

17

18


1 Writing scripts This chapter describes the fundamentals of writing VISION 4GL scripts: the elements of a script script conventions a suggested script organization Also included is DBMS-specific information about these topics: references to database objects SYBASE SQL Server temporary tables SYBASE SQL Server and the browse feature

19

Creating scripts

All VISION 4GL and C function definitions reside in a script file. Each class is associated with its own script. You access a script through VISION Script Editor only.

VISION Script Editor In VISION Script Editor you add templates for allowable methods and then supply VISION 4GL statements and functions to complete the method. For example, the following illustration shows a sample script for a form class. The method list contains the names of all sections and methods that can be inserted in the script for a form class:

Method list

Script text

Related information

20

For more information about how to use VISION Script Editor, see “Using VISION Script Editor” in Unify VISION: Developing an Application. Unify VISION: 4GL Reference

Script components When the user performs an action on a form, VISION Runtime Manager executes statements in the method associated with that action. The following tables list examples of user actions and the methods that are executed. Examples of user actions When the user performs this action:

VISION Runtime Manager executes the

Clicks on a button associated with a developer-defined command

COMMAND

Double clicks on a field

ON DOUBLE CLICK

Exits the application

ON EXIT

Finds a record

ON FIND

statements in the following methods

Changes data in a field WHEN FIELD CHANGES Clicks in a field

ON FIELD

Clicks in another field AFTER FIELD Closes the form

ON DISMISS FORM

Clears the form to add ON CLEAR TO ADD a record Clears the form to find ON CLEAR TO FIND a record Displays the next record

ON NEXT RECORD

Displays the previous record

ON PREVIOUS RECORD

Zooms to another form ON ZOOM Form commands

ON CHOOSE NEXT FORM ON NEXT FORM ON PREVIOUS FORM

(continued on next page) Chapter 1: Writing scripts

21

Examples of user actions (continued) When the user performs this action:

VISION Runtime Manager executes the

Record commands

ON NEXT RECORD ON PREVIOUS RECORD

statements in the following methods

Returns a value from a ON RETURN VALUES form

The following table provides a list of the most frequently used tasks and the corresponding script statements or system functions. VISION 4GL language components

Task

Script statement or system function

Display a message

DISPLAY NOTICE DISPLAY

yesno$( ) Assign a value to a variable

SET

Display a form

CREATE FORM

Declare a local variable

PRIVATE PUBLIC

Close a form

DISMISS FORM CANCEL FORM

Return values to a form

VALUES TO RETURN ARE

Execute a conditional statement

FOR REPEAT WHILE IF

Exit the application

EXIT

Print a form

PRINT FORM

Handle runtime errors DBMS_ERROR HANDLER INSTALL

(continued on next page) 22


VISION 4GL language components (continued)

Task

Script statement or system function

Send information from a Unify VISION application to another program

DDE_EVENT HANDLER INSTALL CREATE PIPELINE WRITE PIPELINE

Request a lock on a record

SLOCK XLOCK

Debug a form

Use VISION Debugger BREAK BREAKPOINT

Use the preprocessor

Related information

Chapter 1: Writing scripts

Send a message from one form to another

MESSAGE_HANDLER SEND MESSAGE

Execute database statements

ALTER SCHEMA ALTER TABLE CREATE SCHEMA CREATE TABLE CREATE VIEW DELETE DELETE SELECTED ROW DROP SCHEMA DROP TABLE DROP VIEW

GRANT INSERT INTO REVOKE SELECT SLOCK UNLOCK UPDATE UPDATE SELECTED ROW XLOCK

For a complete descriptions of foundation classes and runtime operations, see Unify VISION: Class Reference.

23

Script conventions The VISION 4GL syntax descriptions assume the following general conventions about scripts: Methods Methods are optional. If you do not include a method, the default action is performed according to the specifications you gave for the form or field in VISION Designer. Because script methods are event driven, you can arrange them in any order you prefer. For instance, statements in a BEFORE FIND method are always executed before an interactive database search regardless of where you have placed this method in your script. Methods are optional in a script, unless otherwise noted in the description. The BEGIN and END keywords are not required in a method. Comments Comments cannot span methods. A comment that starts in one method must terminate in that same method. A comment that starts outside a method must end before the next method. Statements Each method contains one or more statements. A method can include as many statements as needed. Statement order within a method determines execution order. Statements must be placed within a method, unless otherwise noted

in the description. You can use either a single statement or a statement block anywhere that statement appears in the syntax listings unless otherwise noted in the description. A statement_list is made up of one or more VISION 4GL statements. A statement_block is also made up of one or more statements. However, if the statement_block has more than one statement, it must be introduced with the keyword BEGIN and concluded with the keyword END. A semicolon (;) is required to terminate an SQL statement. Semicolons are optional for terminating VISION 4GL statements. 24


System functions All system functions have a dollar sign ($) as the last character. You must include the $ character when you use a system function. All system functions must include parentheses in the function call, regardless of whether the function has parameters. When a system function returns a value, you can choose whether to use this value in the script. System functions must be placed within methods. Spaces between the system function parameters shown in the “Syntax” subsection are optional. Commas between parameters are required. An entire array variable cannot be passed to Unify VISION system functions or to 3GL functions directly. However, the values of individual elements of an array can be passed to a function.

Optional script elements Optional elements in a script are: a file header preprocessor declarations external file and function declarations Related information

For information about preprocessor declarations and external files, see “Using the preprocessor” starting on page 123.

The order of script elements Certain elements of your script, if used, must be arranged in a specific order: External function declarations must be placed before the script header. Methods must be placed after the header. FIELD subsections must be grouped together under the related FIELD method. Chapter 1: Writing scripts

25

Using Help with VISION Script Editor Online help is provided for VISION 4GL statements, methods, predefined functions, and system functions. You can access the help while writing scripts in VISION Script Editor and copy the statement or method text to the VISION Script Editor window. There is no help for the toolbar or status line in VISION Script Editor. To access the help, choose Help ! Indexed Help from any window in VISION Development Environment, then choose VISION Script Editor

and then the category of help that you want. To copy and paste the text into a script, follow these steps for either Windows or UNIX:

26

Windows

Select the text to be copied and issue the Copy command from the Help window’s Edit menu. In VISION Script Editor use the Paste command from the Edit menu to paste into your script.

UNIX

You cannot select text in the help window. Instead, Issue the Copy command from the Help window’s Edit menu. This brings up a window with the selectable text. Select the text to be copied and press the OK button. In VISION Script Editor use the Paste command from the Edit menu to paste into your script.


Connecting to a database VISION 4GL includes statements and system functions for connecting to a database or for changing the database connection.

Database connection statements When you write scripts, you can specify database connections in the following statements and clauses: CHOOSE FORM USING CREATE FORM ENABLE ZOOM TO ON CHOOSE NEXT FORM USING CONNECTION clause

The USING CONNECTION clause is used with DBMS SQL statements, such as SELECT, INSERT, DELETE, or CREATE. The clause can also be used with transaction statements, such as BEGIN WORK, COMMIT WORK, and ROLLBACK WORK or with locking statements, such as SLOCK, XLOCK, or UNLOCK. Tip

To monitor your database connections from scripts, query the following read-only attributes: FORM_CONNECTION_NAME and FORM_CONNECTION_SOURCE.

Database-dependent system functions Several system functions also depend on a database connection. For the following system functions, the connection that is used is the connection for the form that is associated with the script that called the function: check_dirty$( ) db_type$( ) get_password$( ) l_allow_interrupt$( ) Chapter 1: Writing scripts

l_wait_time$( ) show_dirty$( ) sql_clear$( )

27

For the following system functions, the database connection that was used for the most recently executed DBMS SQL statement is used, regardless of the associated form’s database connection. dbms_status$( ) sql_code$( ) sql_errmsg$( )

sql_state$( ) status$( )

The connection that was used for the most recently executed stored procedure is used for the following system functions, regardless of the associated form’s database connection. sp_compute$( ) sp_return$( ) sp_select$( ) If the tx_mode$( ) system function is supported for the DBMS, the function affects all transactions in the application.

DBMS-specific statements and clauses Some VISION 4GL statements or clauses are used only with a specific DBMS, and others have DBMS-specific usage. See the “Support” section in statement and clause descriptions for DBMS-specific usage. Portability guideline

ANSI standard SQL statements To ensure application portability, use only ANSI standard SQL statements and VISION 4GL statements that work the same on every DBMS. If you want to take advantage of DBMS-specific VISION 4GL usage, execute the statements conditionally, based on the database value that is returned by the db_type$( ) system function. DBMS-specific SQL extensions Similarly, if you want to use DBMS-specific SQL extensions, make sure that all SQL statements are in BEGIN_SQL . . . END_SQL statement blocks that are executed conditionally, based on the database value that is returned by the db_type$( ) system function.

The SQL statements that appear in the statement block between BEGIN_SQL and END_SQL can be any SQL statements that are recognized by the DBMS, including DBMS-specific SQL extensions. Returning primary key values Because not every DBMS supports primary keys, use the VALUES TO RETURN statement to return values from a zoom form; do not use the Return Key option on the Zoom Properties panel for the form object. 28


Tip

On almost every DBMS, DML and DDL statements cannot be mixed in the same transaction. Perform a COMMIT or ROLLBACK WORK before executing a dynamic SQL statement if the statement contains DDL. You may also find it advantageous to call sql_clear$( ) after executing dynamic DDL.

ODBC interface For an application that is used with a database that is accessed through ODBC, scripts and function scripts can contain SQL conformance level Core SQL Grammar statements. The statements must be enclosed in a BEGIN_SQL . . . END_SQL statement block.

ORACLE

If you are using ORACLE version 7, you can use both ORACLE SQL and PL/SQL statements in scripts and function scripts if the statements are enclosed in a BEGIN_SQL . . . END_SQL statement block. Unify VISION supports the ORACLE Version 7 deferred binding and deferred parsing for variables.


29

Referring to database objects You can refer to database objects in VISION 4GL scripts. The information in this section describes these types of database object references: qualified table or column names case sensitivity (and case conversions) in database object names table name synonyms

Qualifying table or column names In Unify VISION, you can qualify a table or column name with the name of the database object that owns, or contains, the table or column. The owning database object that is specified depends on the DBMS. For INFORMIX, you can often qualify a table name by the owner name and qualify a column name by the table name. For INGRES, you can qualify a table name by the owner name and qualify a column name by the table name. For ODBC, if supported by the underlying DBMS, you can qualify a table name by the owner name and qualify a column name by the table name. For ORACLE, you can specify the name of the user that owns the table or column. For SYBASE SQL Server, you can specify the name of the database that contains the table or column. You can also specify the owner of the table or column. For Unify DataServer, you can specify the name of the schema that contains the table or column. In addition to the optional qualification, when you specify a database object name, the DBMS may require you to specify the name in uppercase or lowercase or enclosed in quotation marks (”name”). An alternative that is also allowed if supported by the DBMS is to refer to a table by a synonym. 30


Tip

If you do not know the names of your database tables, look in your DBMS manuals to find out how to get a list of table names. Usually you can use the DBMS version of SQL and some set of commands to display data dictionary information. For example, if you are using Unify DataServer, you can run Interactive SQL/A and use the TABLES command to display a list of table names.

INFORMIX

Depending on the version and mode of INFORMIX, you use one of the following formats to refer to tables. If you are using INFORMIX OnLine, to refer to tables, use this format: [owner_name.]table_name To refer to columns, use this format: [[owner_name.]table_name.]column_name If you are using MODE ANSI, you must qualify the table name by the owner name. If you do not qualify the table name, you will receive a compile error for the script. If the table is not a MODE ANSI table, the owner name portion is ignored. If you are using INFORMIX SE, you cannot qualify the table name or column name by the owner name. The owner-table name combination must be unique in the application. The owner name is the login name of the owner of the database object and may contain uppercase letters.

INGRES

(If you are using INGRES on Windows through ODBC, also see your INGRES ODBC driver documentation.) To refer to INGRES tables, use this format: [owner_name.]table_name To refer to columns, use this format: [table_name.]column_name Chapter 1: Writing scripts

31

You cannot specify the owner name as well as the table name when you specify a column name. When you specify column names, you can use correlation names for tables that are referenced in the select, delete, update, create integrity, and create rule statements. Use this format: [correlation_name.]column_name Correlation names are typically shortened versions of the table name. For example, s is the correlation for a table named salesreps, shown in the following example:

ODBC interface For ODBC, if the underlying DBMS supports database object names qualified by the owner name and table name, you can use the following database object name formats. To refer to tables, use this format: [owner_name.]table_name To refer to columns, use this format: [[owner_name.]table_name.]column_identifier

ORACLE

To refer to ORACLE database tables, use this format: [user_name.]table_name To refer to columns, use this format: [[user_name.]table_name.]column_name If a Unify VISION object has the same name as a database column, use quotation marks (”) to distinguish the object name from the database column name. For example, if you have a database column called ADDRESS1 and also have an object address1, the object name must be enclosed by quotation marks ”address1”. 32


SYBASE SQL Server To refer to SYBASE SQL Server database tables, use this format: [[database_name.][owner_name].]table_name Use this format to refer to columns: [[database_name.][owner_name].]table_name.column_name To qualify the table or column name by the database name and omit the owner name, include the dot as placeholder, as shown here: database_name..table_name[.column_name] Placeholder for owner name

If you do not include the SYBASE SQL Server database name, Unify VISION uses the database that is specified by the DBNAME external preference. If you do not specify the owner name, Unify VISION obtains the owner name for that table from the SYBASE SQL Server system views.

Unify DataServer To refer to Unify DataServer database tables, use this format: [schema_name.]table_name To refer to columns, use this format: [[schema_name.]table_name.]column_name

Database object name case sensitivity VISION Designer stores database object names in the same case as they

are entered. Any target table column names that are not used on the form are stored in the form file in the same case as they appear in the database data dictionary. To evaluate database object names, Unify VISION uses the same name matching algorithms as the current DBMS, as described in the following subsections. Chapter 1: Writing scripts

33

INFORMIX

On INFORMIX, database object names are always converted to lowercase. For example, the table names company, Company, and COMPANY, are all evaluated as company. When you use MODE ANSI, user names are by default converted to uppercase unless the name is enclosed in quotation marks (”user_name”). For example, the user names smith and Smith are both evaluated as SMITH, while the name ”smith” is evaluated as smith.

INGRES

To evaluate database object names and user names for INGRES, Unify VISION converts all database object names and all user names to lowercase. For example, if an INGRES developer types EMP as the target table name when defining a form with VISION Designer, Unify VISION matches the name with a database table named emp.

ODBC interface On a database that is accessed through the ODBC interface, database object name case sensitivity depends on the DBMS and is determined at runtime. See your ODBC online documentation and DBMS manuals for information about case sensitivity.

ORACLE

To enable Unify VISION to find the correct database objects, when you name ORACLE database objects, follow these rules: If you use SQL*Plus to create the database object and do not enclose the object name in double quotation marks (name), the name is converted to uppercase (NAME) when it is stored in the data dictionary. When you ask Unify VISION to find the database object, you must enter the name in all-uppercase letters. That is, if the database object name was created without quotation marks as Company, COMPANY, or company, it must be specified as COMPANY. 34


If you create the database object and enclose the object name in double quotation marks (”Name”), the name is stored exactly as entered (Name). When you ask Unify VISION to find the database object, you must type the name exactly as it was created and use the quotation marks. That is, if the database object name was created with quotation marks as ”Company”, ”COMPANY”, or ”company”, you must specify the name exactly as it was created (”Company”, ”COMPANY”, or ”company”). Example

The following examples illustrate the use of quotation marks to specify ORACLE database object names. In the first and third examples, because

the objects are named without quotation marks, you must specify the names in all-uppercase letters (EMPLOYEE and SALARY). In the second example, because the objects are named with double quotation marks, you must specify the names exactly as they appear between the quotation marks (Employee and Salary). ORACLE database object name case conversions

If this SQL*Plus statement is used to create the The object name is database object: stored as: CREATE TABLE EMPLOYEE (SALARY NUMBER)

EMPLOYEE SALARY

CREATE TABLE ”Employee” (”Salary” Number)

Employee Salary

CREATE TABLE employee (salary number)

EMPLOYEE SALARY

The ORACLE rules for referring to database object names also apply to user names and passwords, as shown in the following table.


35

ORACLE user name and password case conversions

If this SQL*Plus statement is used to grant the user The user name is access to the database: stored as: GRANT CONNECT TO James IDENTIFIED BY jjj ;

JAMES JJJ

GRANT CONNECT TO ”James” IDENTIFIED BY ”jjj” ;

James jjj

Tip

Unify VISION also supports use of the ORACLE 7 authentication of the user name by the operating system. The operating system login user name is then used to log in to the database. To specify this option, specify a user name of ”/” and no password; for example, set the DBUSER external preference to the value ”/”. See your ORACLE 7 Server Administrator’s Guide for information about authenticating users.

SYBASE SQL Server On SYBASE SQL Server, all database object names and user names are case sensitive. You must enter database object names and user names exactly as they are defined.

Unify DataServer On Unify DataServer, all database object names and user names are case sensitive. You must enter database object names and user names exactly as they are defined.

Using table name synonyms You can also specify a table by its synonym, if one has been defined. In VISION Designer, when you design a form that has a target table, you select the target table name from the Data Source list box on the Database Attributes panel. Table name synonyms are displayed as well as other table names. 36


Creating SYBASE SQL Server temporary tables from scripts The information in this section applies to only the SYBASE SQL Server DBMS. SYBASE SQL Server temporary tables are visible to only the application

that created them. They are not visible to other applications and can be accessed only through the connection under which they were created. SYBASE SQL Server does not allow DDL (data definition language) statements in a transaction. Therefore, on detecting a DDL statement, VISION Runtime Manager opens a secondary connection to SYBASE SQL Server to execute the statement.

However, because the application is using the primary connection, the application cannot access any temporary table that was created under the secondary connection. To make sure that the application can use the temporary table, you must create it under the primary connection. From a script, to create the temporary table in the primary connection, end the current transaction and perform DDL statements in a BEGIN_SQL . . . END_SQL statement block, as shown in this example: tx_mode$(FALSE); /* Turn off automatic transaction handling */ COMMIT WORK; /* End current transaction */ BEGIN_SQL /* Start the SQL command block */ create table #tmp_table_name ( . . . ); /* Create the table: SYBASE SQL statements */ END_SQL /* End the SQL command block */ SET $return_value_var TO status$(ā); /* Save the status return value */ tx_mode$(TRUE) /* Turn automatic transaction handling back on */ COMMIT WORK; /* Restart the deferred transaction */

Because SYBASE SQL Server will automatically drop the temporary table when the application terminates, you do not need to drop the table from the VISION 4GL script. However, if the application needs to drop the table, do it within the BEGIN_SQL . . . END_SQL statement block, using the “create table” example as a guide. The SYBASE SQL Server SELECT INTO #temporary_table_name statement may also create a temporary table. If you use this statement, Chapter 1: Writing scripts

37

make sure that you enclose it in the BEGIN_SQL . . . END_SQL statement block, as shown in the previous example. These guidelines apply only to temporary tables. If you create normal tables, they can be accessed through all connections to the server, regardless of the connection under which they were created.

38


Processing queries and using the browse feature with SYBASE SQL Server The information in this section applies to only the SYBASE SQL Server DBMS. Processing queries and using the browse feature with SYBASE SQL Server has a few functional differences because Unify VISION uses SYBASE SQL Server DB-Library functions to connect to the SYBASE server. Unify VISION must maintain a current transaction for each server connection. Each database request, such as creating a selected set or updating rows, must be completed or canceled before starting a new request in the same transaction.

Writing database queries for SYBASE SQL Server Therefore, when you write database queries, especially when you use the browse feature with Unify VISION with SYBASE SQL Server, follow these guidelines: Qualify queries so that the number of rows that satisfy the query is limited to only the rows that the application needs. For example, do not set up zoom forms that can return an excessive number of rows that are never accessed by the user. (See “Using the browse feature with SYBASE SQL Server,” on page 40.) Do not use the browse feature on a form in record consistency. After the selected set is built, Unify VISION must reread the first record to make it current. Therefore, the first select request, which created the set in browse mode, must be completed. Unfortunately, this defeats the purpose of browsing on a very large set of records. Instead, open the form in set consistency or in no consistency. In either case, the first row is not reread, the first subset of records appears quickly, and browse mode is retained. Do not execute an interactive command or VISION 4GL statement that initiates another SQL statement. Executing such a statement causes the browse set to be completed before the requested action takes place, which causes browse functionality to be again lost. Chapter 1: Writing scripts

39

These are some of the actions that initiate another SQL statement: executing a DBMS SQL SELECT, UPDATE, or DELETE statement executing an interactive add, update or delete operation executing a find for sets of records on either a Next form or a zoomed-to form executing a stored procedure

Using the browse feature with SYBASE SQL Server When you use the browse feature and the selected set is cleared or the browse mode form is exited to go to the previous form, the select request that created the set is canceled. In this case, Unify VISION informs SYBASE SQL Server to cancel execution of the current request and flush any pending results. When SYBASE SQL Server cancels the current select request, each remaining record must still be processed. Therefore, the end user may see some delay when clearing a selected set or exiting a form in browse mode, especially if the entire requested set is fairly large.

40


Embedded SQL statements Unify VISION allows you to use SQL statements in your script to perform non-interactive database operations. The flexibility of SQL allows your script to include the following features: access to multiple tables and views joining of tables portability with other databases inclusion of database-specific extensions to SQL optimal database access methods other statements and features provided by the DBMS, such as triggers and stored procedures Unify VISION automatically recognizes some keywords as SQL statements: DML statements

DDL statements

COMMIT WORK DELETE INSERT ROLLBACK WORK SELECT UPDATE

ALTER SCHEMA ALTER TABLE CREATE SCHEMA CREATE TABLE CREATE VIEW DROP SCHEMA DROP TABLE DROP VIEW GRANT REVOKE

These are standard database statements as specified by the international standards for SQL. However, in addition to these statements, you can include other database statements by enclosing them within an SQL statement block. An SQL statement block can include any statements that are provided by your database other than statements requiring user interaction. An SQL statement block is delimited by the VISION 4GL BEGIN_SQL and END_SQL statements. When VISION Runtime Manager encounters an SQL statement, it automatically prepares the statement for processing by the database. The Chapter 1: Writing scripts

41

database determines the optimal access method to be used and then executes the statement. If not contained in a statement block or EXECUTING clause, SQL statements must be terminated by a semicolon (;). Related information

For complete information about SQL statement blocks and how you can use DBMS features with Unify VISION, see the syntax descriptions for BEGIN_SQL and END_SQL.

Including variables When you use SQL statements in a script, you can include Unify VISION variables as parameters within the statements. If a form name is not specified, a Unify VISION variable must be prefixed by a dollar sign ($), for example: $emp_number A dollar sign prefix is not required if the form name is specified, for example: emp_form:emp_number

You can use functions and other elements in a similar manner, for example: SELECT emp_name, emp_number FROM employee WHERE emp_sdate > $date_function($in_str);

Database interface When your script is compiled, Unify VISION elements are automatically prepared in a manner recognized by the database. If errors occur during compilation of the script that are due to SQL statements, you receive a warning message, but the script is successfully compiled. 42


At runtime, VISION Runtime Manager substitutes the appropriate value in place of the variable or other element. Restrictions and conditions Unify VISION provides the values of database parameters to the database at runtime. However, the database cannot alter the values of variables in your script. Therefore, you cannot change the value of a script element, such as a counter or index, in an SQL statement. Perform operations to script elements in VISION 4GL statements only; such statements have no effect in an SQL statement. Portability guideline

To ensure portability, observe the following restrictions when Unify VISION variables are used as dynamic arguments to SQL statements:

A Unify VISION object cannot be used as the argument of an aggregate (set) function. You must specify a literal column name. In the BETWEEN predicate of a WHERE clause, at least one element must be a literal column name. At least one element of an IN predicate must be a literal column name. At runtime, all Unify VISION variables used as dynamic parameters in SQL statements must have been previously defined. NULL is an acceptable value; however, UNDEFINED is not a permitted value.

The EXECUTING clause An SQL SELECT statement can contain a Unify VISION EXECUTING clause. To set the value of a scalar variable, the EXECUTING clause is required for Unify VISION to select all rows that match the WHERE clause. If the EXECUTING clause is omitted, only the first matching row is selected. The EXECUTING clause is not required to set the values of an array. Related information

For information about the EXECUTING clause, see the syntax description given on page 277.

The locking clauses An SQL SELECT statement can contain one of the Unify VISION locking clauses: SLOCK or XLOCK. Chapter 1: Writing scripts

43

To ensure optimal performance, security, and portability of your application, use the Unify VISION locking statements rather than the locking mechanisms provided by your database. Related information

For information about the locking clauses, see the syntax descriptions for SLOCK and XLOCK in this manual.

Example The following example shows a SELECT statement that includes an EXECUTING clause. SET i TO 0 SET name[i], number TO SELECT AND SLOCK emp_name, emp_number FROM employee WHERE emp_sdate > str_to_date $($in_str) AND emp_number > $in_number EXECUTING BEGIN IF name[i] = mname THEN BEGIN DELETE SELECTED ROW; SET i to i + 1 END END

44


Dynamic SQL

Dynamic SQL enables you to compose and execute an SQL statement at runtime. In static SQL, you must type in the SQL statement, including tables, columns and rows, into your script. With dynamic SQL, the names of columns, rows, and tables are variables. The variables can be typed in by the user or they can be defined in the script. When the application is running, the SQL statements are constructed in memory as your application is executed. In another example, the form may ask the user to enter any SQL statement in a field. In this case, the entire statement is unknown. In both of these cases, you need to set up a script that is prepared to receive variables from the user.

Passing parameters to SQL statements In dynamic SQL, an unknown variable or statement is passed from the application to the script, the statement is prepared, and then executed. After the statement is executed, the statement can be executed at a later time, or the memory used by the statement can be released. Unknown variables are called parameters. Dynamic SQL has two types of parameters: input and output. Input parameters are the values that the user types at runtime or are variables in a script. Output parameters are the values the database returns to the application. The following illustration shows the relationship between your form and your script when the user types in input parameters:

Form Input parameters

Form script

Prepared statement DBMS

Output parameters


executes statement

45

Writing a dynamic SQL section in a script In dynamic SQL, you can execute a statement immediately or you can prepare the statement and execute it later in the script or pass it to a function to be executed. Whether you decide to execute it immediately or later depends on how often you will execute the SQL statement. The advantage of preparing a statement is that you can store the prepared statement in an SQL handle and reuse the SQL handle in the future. An SQL handle is used to refer to statements that have been prepared. Throughout this guide, examples of SQL handles always have the _hndl suffix to clearly show that the object is a handle, for example, update_hndl. After you have prepared a handle, you can reuse the same handle any number of times. For a statement that is executed a single time only, for fastest execution use the EXECUTE_SQL statement only. You do not need to prepare or free this statement. The PREPARE_SQL and EXECUTE_SQL statement combination is required only for multiple executions. Examples of executing a statement immediately and preparing the statement are described in the following paragraphs. Example

For example, the following dynamic SQL statement immediately updates the prices column to 5 dollars in all rows in the order table: EXECUTE_SQL 'UPDATE order_tbl SET prices = 5';

In the next example, the price is updated to the value entered by the user: FIELD text1 ON FIELD INPUT EXECUTE_SQL 'UPDATE order_tbl SET prices = ?' using $text1;

Example

In this example, the UPDATE statement is prepared by using the PREPARE_SQL statement and the UPDATE statement is stored in an SQL handle called update_hndl. Later in the script, the EXECUTE_SQL statement executes the statement contained in update_hndl. ON CREATE PREPARE_SQL 'UPDATE order_tbl SET prices = ?' into $update_hndl; . . . ON NOT CURRENT EXECUTE_SQL $update_hndl USING $text1;

46


To execute the contents of the update_hndl statement again, the same EXECUTE_SQL statement is repeated: EXECUTE_SQL $update_hndl USING $text1;

Example

After you have finished using the SQL handle, you use the FREE_SQL statement to release memory resources. The following example frees the resources held by the update_hndl SQL handle: FREE_SQL $update_hndl;

Describing the SQL statement After preparing a statement, you can get information about both sets of parameters. Getting information about parameters is called describing the parameters. A description is not required to execute a statement specified by the user. However, your script may need parameter information at a later time. Unify VISION provides attributes to describe the input and output parameters. In some products, the language provides a statement called DESCRIBE to allow you to view the values of the input parameters. In Unify VISION, the parameters are already described and you can access the description by using SQL handle attributes. To get information about input parameters on some DBMSs, you use these attributes: INPUT_ACCELL_TYPE[ ] INPUT_COUNT INPUT_DB_COLUMN_TYPE[ ] INPUT_DB_COLUMN_TYPE_CODE[ ] INPUT_PRECISION[ ] INPUT_SCALE[ ]

Similarly, after the DBMS receives the dynamic SQL statement, it returns results. These results are called output parameters. Unify VISION provides these attributes to display the value of the output parameters: OUTPUT_ACCELL_TYPE[ ] OUTPUT_COUNT OUTPUT_DB_COLUMN_TYPE[ ] OUTPUT_DB_COLUMN_TYPE_CODE[ ] OUTPUT_NAME[ ] OUTPUT_PRECISION[ ] OUTPUT_SCALE[ ]

On SYBASE SQL Server, the values of these attributes are valid after the statement is executed. Chapter 1: Writing scripts

47

Each attribute is prefixed with an OUTPUT or INPUT term to reflect the parameter type. The following paragraphs describe the dynamic SQL attributes: ACCELL type

Describes the data type of the input or output parameter. Input data types are a Unify VISION data type, for example, STRING or NUMERIC.

Database column type Describes the DBMS column type. By default, the value of this attribute is the same as the value of the ACCELL_TYPE attribute except when the value is DATE_TIME. Database column type code Describes the DBMS column type by displaying a database code. The DBMS codes are database dependent. One usage of database column type codes is to distinguish between an AMOUNT or FLOAT data type. Another example is to determine if the database column is the DATE_TIME data type. With the database column code, you can set the OUTPUT_ACCELL_TYPE to either DATE or TIME. Precision

Specifies the number of significant digits in a AMOUNT or NUMERIC database column. In a STRING field, precision specifies the number of characters in the database column. In a FLOAT field, precision specifies the number of bits.

Scale

Specifies the number of digits to the right of the decimal point in an exact NUMERIC field.

Using an SQL handle An SQL handle references an SQL statement. Similarly to all other objects in Unify VISION, you declare the object the first time you use it. An SQL handle is an object that must be UNDEFINED before you use it. An SQL handle has three states: invalid, inactive, and active. If you prepare a statement by storing the statement in an SQL handle and then 48


execute the handle, the SQL handle will execute successfully because the handle was active. The state changes to invalid if the SQL handle is freed. Database operations can change the handle to inactive. If you execute the handle at a later time, the SQL handle may have changed state to inactive. Only valid SQL handles execute a statement correctly.

Events The following events change the state of an SQL handle: The SQL handle no longer contains a statement because you released the contents by using the FREE_SQL statement. On some databases, the database committed or rolled back the transaction associated with an SQL handle. The current schema has changed. Invalid PREPARE_SQL string_expression INTO handle

PREPARE_SQL (SYBASE SQL Server only) Free SQL handle

Free SQL handle

EXECUTE_SQL SQL_handle_name or PREPARE_SQL Inactive

Active

Database operations, such as a commit or rollback

For SYBASE SQL Server, the SQL handle attributes have invalid values until after the EXECUTE_SQL statement. An SQL handle has three states that are stored in two attributes: IS_VALID and IS_PREPARED.


49

Attributes that describe state of SQL handle IS_VALID

IS_PREPARED

State of SQL handle class

FALSE

NULL

Invalid. The SQL handle is not currently associated with a particular statement. Attributes contain default values and should not be referenced.

TRUE

TRUE

Active. Statement is prepared and ready for execution. Attributes accurately contain values based on the prepared statements.

TRUE

FALSE

Inactive. The SQL handle is associated with a statement but the statement is not prepared. The EXECUTE_SQL statement automatically prepares the statement again if you do not use the PREPARE_SQL statement first. STATEMENT_TEXT and CONNECTION_NAME attributes contain the last prepared statement. All other attributes are set to default values and should not be referenced.

Permitted operations With an SQL handle, you can perform the following tasks: Reference attributes, for example: SET temp TO titles_hndl:OUTPUT_ACCELL_TYPE

Pass SQL handles as reference parameters to a function, for example: calculate_pay(titles_hndl)

50


Execute VISION 4GL statements PREPARE_SQL, EXECUTE_SQL, and FREE_SQL, for example: ON CREATE PREPARE_SQL 'UPDATE order_tbl SET prices = ?' into $update_hndl; . . . EXECUTE_SQL $update_hndl USING $text1; FREE_SQL $update_hndl;

Creating a handle You can create an SQL handle by using it in a PREPARE_SQL statement. If an undefined general variable is passed to a function as a reference parameter and the function prepares an SQL statement into that variable, then the variable becomes an SQL handle. The variable is an SQL handle in the function and the calling script.

Example The following example uses many of the dynamic SQL statements and attributes. The script assumes that the user will enter an SQL SELECT statement into the text1 field. After the user clicks on a button with the developer-defined command execute_dsql, the script executes the following steps: Declares an array called answer that stores the rows returned from a SELECT statement. Prepares the SQL statement entered in the text1 field into an SQL handle called user_hndl. Verifies that text1 has a valid SQL statement. If errors were found during preparation of text1, the user is asked to reenter or modify the SQL statement. Verifies that the user wants to execute that SQL statement. If a column is of DATE_TIME data type, the user is asked to choose the appropriate data type to be stored in the database. Executes the user_hndl and stores the result of the SELECT statement into the answer general array variable. Chapter 1: Writing scripts

51

#include "sscodes.h" FORM CLASS form0 PUBLIC MATRIX answer[1 to UNKNOWN ESTIMATING 10, 1 TO UNKNOWN ESTIMATING 10] COMMAND execute_dsql BEGIN PREPARE_SQL $text1 INTO $user_hndl; IF (status$() != SS_NORM) THEN DISPLAY 'Wrong syntax. Modify your statement again.' FOR FYI_MESSAGE WAIT; ELSE BEGIN DISPLAY NOTICE 'Execute ' + $user_hndl:STATEMENT_TEXT + ' for the ' + $user_hndl:CONNECTION_NAME + ' database?' LABELS 'YES' DEFAULT, 'NO' RESULT INTO user_answer IF user_answer = 0 THEN BEGIN FOR (SET $j to 1; $j cost RETURN K, C;

The sp_items( ) stored procedure is declared in the following VISION 4GL EXTERN statement: EXTERN STORED ROW_VALUED FUNCTION sp_items(ge_value) ;

After being declared, sp_items( ) is called in the VISION 4GL script by using the following statements: SET $cnt TO 0 ; SET $key, $item_cost TO sp_items(100.00) EXECUTING BEGIN . . . SET $cnt TO $cnt + 1 ; END

Related information


For the syntax and usage description of the sp_return$( ) system function, see page 556.

55

Calling INGRES database procedures (UNIX only. Database procedures are not supported on Windows.) VISION 4GL scripts can include calls to INGRES database procedure. Database procedures are pre-compiled sets of SQL statements that are executed when called by other programs, such as a Unify VISION

application. Declaring INGRES database procedures Before being used, an INGRES database procedure must be declared as a function in the VISION 4GL EXTERN statement. When you declare the database procedure, you must specify its type, name, and parameters. An INGRES database procedure must be declared as a STORED function, with type NUMERIC. (For INGRES, the only type allowed for a STORED function is NUMERIC; ROW_VALUED is not allowed.) Related information

For the syntax and usage description for the EXTERN statement, see page 281. Using INGRES NUMERIC database procedures All INGRES NUMERIC database procedures return the numeric argument of the RETURN statement that was executed to terminate the procedure. The VISION 4GL sp_return$( ) system function can also be used to return the numeric return value, of the last call to a database procedure. INGRES NUMERIC database procedures can be used only within these

boundaries: All parameters must be passed by value. All select statements in a database procedure must assign their results to local variables. A select statement in a database procedure can return only a single row of data; additional rows are ignored. If a database procedure is called by a rule, the RETURN statement cannot be used to return a value to the application. If the database procedure is executed by firing a rule, instead of by using the execute procedure statement, actions specified by the whenever sqlmessage clause are ignored. 56


You can use a NUMERIC database procedure wherever a function can be used. Example

In the following example, an INGRES NUMERIC database procedure named dbp_limit( ) returns 1 when a customer’s charge is greater than the account limit and returns 0 when the charge is less than the limit. The database procedure definition contains these SQL statements: create procedure dbp_limit (custid char(30), charges money) as begin if (select cust_id, chrg_lim from customers where cust_id = :custid and chrg_lim > :charges) return 1; else return 0; endif; end;

Note that colons are used to indicate the procedure’s parameters. The database procedure is declared in a VISION 4GL EXTERN statement: EXTERN STORED NUMERIC FUNCTION dbp_limit(custid, charges) ;

After being declared, dbp_limit( ) can be called in the 4GL script by script by using either of the following statement groups: SET $acct_stat TO dbp_limit($custid,$charges) ;

OR dbp_limit($custid,$charges) ; SET $acct_stat TO sp_return$() ;

The sp_return$( ) system function shown in the example obtains the return value of the last call to a stored procedure. Related information

For the syntax and usage description of the sp_return$( ) system function, see page 556. Using INGRES database procedures as statements A call to an INGRES database procedure can also be used alone as a statement, independent of a SET statement. In this case, any NUMERIC return is discarded because the statement has no variables to assign values to. You can obtain the return value by using the sp_return$( ) system function.


57

Calling ODBC stored procedures If the underlying DBMS supports stored procedures, you can declare and call them from VISION 4GL scripts.

Declaring stored procedures To declare the stored procedure, use the EXTERN statement with the STORED keyword. Specify the stored procedure return type as VOID or as a Unify VISION data type, such as NUMERIC. The FUNCTION clause in the EXTERN statement must correspond to the stored procedure definition in the database. The parameter names in the parameter list must match the parameter names specified in the stored procedure definition.

Calling stored procedures After you declare the stored procedure, you can use it like any other function, but you must use the stored procedure exactly as it is declared. For example, if the stored procedure is a function but is declared as a procedure (VOID), or the stored procedure is a procedure but is declared as some other function type, such as STRING or NUMERIC, a runtime error is generated. Related information

For the syntax and usage description for the EXTERN statement, see page 281.

Calling ORACLE stored procedures The information in this section applies to only the ORACLE DBMS, version 7. You can call ORACLE version 7 stored procedures from VISION 4GL scripts. To use an ORACLE version 7 stored procedure with a Unify VISION application, simply follow the guidelines outlined in this section for creating, declaring, and calling the stored procedure. 58


Creating a stored procedure for use with a Unify VISION application When you define an ORACLE version 7 stored procedure that will be used with a Unify VISION application, follow these guidelines: Write the stored procedure in ORACLE PL/SQL. In the stored procedure definition, declare parameters in the PL/SQL stored procedure definition as IN, IN/OUT, or OUT. Note that only scalar data types are supported by VISION 4GL and that boolean types cannot be passed to and from PL/SQL. See your PL/SQL Version 2.0 manual for information about allowed data type conversions. You must define all the parameters for a remote stored procedure before you call it. If all parameters are not defined, a status$( ) value of SS_UNDACL is returned. For local stored procedures, ORACLE OUT parameters can be UNDEFINED. If the type of the result parameter is undefined, the type is derived from the type defined in the stored procedure. If any IN or IN/OUT parameter is UNDEFINED in Unify VISION, a status$( ) value of SS_UNDACL is returned. All parameters are defined from the types defined for them in Unify VISION. Parameter values are passed to and from the ORACLE version 7 stored procedure using the Unify VISION type. If the actual stored procedure expects a different type, then the ORACLE PL/SQL processor tries to convert the type. If the PL/SQL processor cannot convert the type, a runtime error is generated, and a status$( ) value of SS_DBINT is returned. Boolean values and variables cannot be used as parameters to stored procedures, because ORACLE version 7 does not support the passing of boolean parameters to and from PL/SQL. If you try to pass a boolean value from Unify VISION, a runtime error is generated with a status$( ) return value of SS_UNSPTP. If you try to call a stored procedure that expects a boolean value, a runtime error is generated with status$( ) return value of SS_UNDBTP. (You can use the to_num$( ) system function to convert a boolean value to integer so that it can be passed to a PL/SQL stored procedure. After the integer value is returned from the stored procedure, you can use the to_bool$( ) system function to convert the value to boolean.) Chapter 1: Writing scripts

59

The maximum length supported for LONG, VARCHAR2, and CHAR is the same as supported in PL/SQL. If the number of parameters that are specified in a stored procedure declaration does not match the number in the stored procedure definition, a runtime error is generated with a status$( ) return value of SS_PARNTMCH when the stored procedure is called. If the parameter mode as specified in the stored procedure declaration is not compatible with the mode of the stored procedure as defined, runtime errors are generated when the stored procedure is called. For example, if the stored procedure is declared as RESULT but is defined as ORACLE IN, or is declared as VALUE but is defined as ORACLE OUT or IN/OUT, a status$( ) value of SS_MDNTMCH is returned. All other stored procedure errors return the status$( ) value SS_DBINT. The description of such errors can be found by calling database error functions.

Declaring ORACLE stored procedures To declare the ORACLE version 7 stored procedure, follow these steps: 1. In the EXTERN statement of a VISION 4GL script, declare the stored procedure as a function of type STORED. 2. Specify the function return type as VOID or as a Unify VISION data type, such as NUMERIC. ROW_VALUED stored procedures are not supported by ORACLE (calling a ROW_VALUED stored procedure generates a runtime error with a status$( ) return value of SS_INVLSPTYP.) 3. The stored procedure name can be specified in the declaration with the ORACLE notation: schema_name.package_name.procedure_name@db_link 4. Declare the stored procedure function parameters as scalar, not list or matrix variables. If parameters are IN parameters in the stored procedure, declare them as value parameters in EXTERN. If parameters are OUT or IN/OUT parameters in the stored procedure, declare them as RESULT parameters in EXTERN. The EXTERN declaration is used to determine whether an ORACLE version 7 stored procedure is declared as a procedure (VOID) or as a function that returns a value with the specified Unify VISION data type. 60


The VISION compiler will compile the VISION 4GL script whether or not the stored procedure is available at compile time.

Calling ORACLE stored procedures After you declare an ORACLE version 7 stored procedure, you can use the stored procedure like any other function, but the stored procedure must be used exactly as it is declared. For example, if the stored procedure is a function but is declared as a procedure (VOID), or the stored procedure is a procedure but declared as some other function type, such as STRING or NUMERIC for example, a runtime error is generated. The error that is generated depends on whether the stored procedure is in the current database or in a database that is accessed through a database link: If the stored procedure is in the local database, the status$( ) return value is SS_INVLSP. If the stored procedure is in a database that is accessed through a database link, the status$( ) return value is SS_DBINT. To obtain the specific database error that occurred, call an error message routine. When you call the stored procedure, if the stored procedure name is not qualified by the database connection name, the stored procedure is run under the current form’s database connection.

Warning

Do not try to use overloaded functions with Unify VISION applications. If you have a stored procedure that you customarily overload (see your ORACLE PL/SQL User’s Guide and Reference), you can declare and call only one of its variations per VISION 4GL script. However, you can declare and call one of the other variations of the stored procedure from another script. Use the OSPCACHESZ external preference to control the caching of ORACLE stored procedures. If the use of a stored procedure does not match the actual stored procedure in the database, one or more errors will occur.


61

Calling SYBASE SQL Server stored procedures The information in this section applies to only SYBASE SQL Server databases. VISION 4GL scripts can include calls to SYBASE SQL Server stored procedures. SYBASE SQL Server stored procedures are pre-compiled sets of Transact-SQL statements that are executed when called by other programs, such as a Unify VISION application.

To use stored procedures with Unify VISION application, simply follow the guidelines in this section for declaring and using stored procedures. Other topics include these: using SELECT statements in stored procedures matching parameter data types for stored procedures using system functions to monitor stored procedures system function scope in nested SELECTs in stored procedures returning RESULT parameters using stored procedures as statements defining macros as stored procedures When you call the stored procedure, if the stored procedure name is not qualified by the database connection name, the stored procedure is run under the current form’s database connection.

Declaring SYBASE SQL Server stored procedures Before being called from a VISION 4GL script, a stored procedure must be declared as a function in the EXTERN statement. When you declare the stored procedure, you must specify its type, name, and parameters. A SYBASE SQL Server stored procedure type can be either ROW_VALUED or NUMERIC.

Related information

62

For the syntax and usage description for the EXTERN statement, see page 281. Unify VISION: 4GL Reference

Using ROW_VALUED stored procedures A ROW_VALUED stored procedure returns rows from one or more SELECT statements that are executed from the stored procedure. The stored procedure can be used by itself or in place of a SET . . . SELECT statement. For SYBASE SQL Server, a ROW_VALUED stored procedure can be used wherever a function can be used. Used as a function, a ROW_VALUED stored procedure yields a numeric return status. You can also use the VISION 4GL sp_return$( ) system function to obtain a numeric return status for a ROW_VALUED stored procedure or use a Transact-SQL OUTPUT parameter to return a RESULT parameter. Note that the results of a ROW_VALUED stored procedure cannot be stored to an array variable. Example

In the following example, a ROW_VALUED stored procedure named sp_items( ) is used in place of a SET . . . SELECT statement. The sp_items( ) stored procedure selects data from a table named items, where each selected row has an item cost greater than the argument passed to sp_items( ). For SYBASE SQL Server, the stored procedure definition contains these Transact-SQL statements: CREATE PROC sp_items @cost money AS SELECT item_key, item_cost FROM items WHERE item_cost > @cost

The sp_items( ) stored procedure is declared in the following VISION 4GL EXTERN statement: EXTERN STORED ROW_VALUED FUNCTION sp_items(cost) ;

After being declared, sp_items( ) is called in the VISION 4GL script by using the following statements: SET $cnt TO 0 ; SET $key, $item_cost TO sp_items(100.00) EXECUTING BEGIN . . . SET $cnt TO $cnt + 1 ; END


63

Note that the same parameter name (cost) must be used to declare the stored procedure in the EXTERN statement as was used to create the stored procedure. Related information

For the syntax and usage description of the SET statement, see page 378. For the syntax and usage description of the sp_return$( ) system function, see page 556. Using NUMERIC SYBASE SQL Server stored procedures You can use a NUMERIC type stored procedure wherever a function can be used. For a NUMERIC stored procedure, use the VISION 4GL sp_return$( ) system function to obtain a numeric return status for a NUMERIC stored procedure or use a Transact-SQL OUTPUT parameter to return a RESULT parameter. If a NUMERIC stored procedure includes a SELECT statement for choosing database rows, the row values are discarded.

Example

In the following example, a NUMERIC stored procedure named sp_limit( ) returns 1 when a customer’s charge is greater than the account limit and returns 0 when the charge is less than the limit. The stored procedure definition contains these Transact-SQL statements: CREATE PROC sp_limit @cust_ID char(30), @charges money IF (SELECT cust_ID, chrg_lim FROM customers WHERE cust_ID = @cust_ID AND chrg_lim > @charges) RETURN 1 ELSE RETURN 0

The stored procedure is declared in a VISION 4GL EXTERN statement: EXTERN STORED NUMERIC FUNCTION sp_limit(cust_ID, charges) ;

After being declared, sp_limit( ) can be called in the VISION 4GL script by using either of the following statement groups: SET $acct_stat TO sp_limit($cust_ID,$charges) ;

OR sp_limit($cust_ID,$charges) ; SET $acct_stat TO sp_return$() ;

64


The sp_return$( ) system function shown in the example obtains the return status of the last call to a stored procedure. Related information

For the syntax and usage description of the sp_return$( ) system function, see page 556. Returning RESULT parameters NUMERIC and ROW_VALUED stored procedures can return RESULT parameters. For SYBASE SQL Server, RESULT parameters are equivalent to Transact-SQL OUTPUT parameters.

A RESULT parameter cannot be UNDEFINED. Status and RESULT parameter values can be obtained only after the stored procedure has finished executing. Selected row values are obtained as each row is processed. Using SELECT statements in stored procedures A ROW_VALUED stored procedure can contain one or more SELECT statements. SELECT statements are useful only in ROW_VALUED stored procedures. If a NUMERIC stored procedure contains SELECT statements, the selected rows are cancelled and ignored. To execute multiple SELECT statements in a ROW_VALUED stored procedure, you need only one VISION 4GL SET statement that includes the call to the stored procedure. The SET statement must have an EXECUTING block when the stored procedure returns values from more than one selected row. Leaving the EXECUTING block ends execution of the stored procedure. If each SELECT statement returns a different number of column values, the SET statement must accommodate the largest number of column values returned. For example, if the first SELECT returns one column value, the second SELECT returns three column values, and the third SELECT returns five column values, the SET statement must contain five variables. For SYBASE SQL Server, a SELECT statement in a stored procedure can also contain a COMPUTE clause. When multiple values are returned by multiple SELECT statements or COMPUTE clauses, the variable_list in the SET statement must contain as many variables as the largest number of returned values. Chapter 1: Writing scripts

65

Example

The following example stored procedure contains three SELECT statements that return one, three, and five columns. Therefore, the SET statement assigns values to five variables. Stored procedure

First SELECT Second SELECT

Third SELECT

. . . SELECT col1 FROM table1 . . . SELECT col1, col2, col3 FROM table2 ORDER BY col1 . . . SELECT col1, col2, col3, col4, col5 FROM table3 . . .

Needs 1 variable Needs 3 variables

Needs 5 variables

Required number of variables = 5 SET $var1, $var2, $var3, $var4, $var5 TO stored_proc() EXECUTING . . .

Unify VISION SET statement

Matching data types in stored procedures If the variables in the VISION 4GL SET statement are field variables, target variables, or target field variables, their data types must match the data types of the results returned by the SELECT statements in the stored procedure. If the variables in the SET statement are general variables, the data types need not match. The data type of a general variable changes automatically with each executing loop of the SET statement, depending on the data type of the value assigned to the variable. Before each executing loop of the SET statement, Unify VISION resets all variables to UNDEFINED, as shown in the following example:

Reset variables to UNDEFINED

66

SET $var1, $var2, $var3, $var4, $var5 TO stored_proc() EXECUTING . . .


Using system functions to monitor stored procedures To determine the action to take on the values returned from a stored procedure, you can use one or more of the following system functions: sp_compute$( ) Returns TRUE if the last row returned by the stored procedure is the result of a SYBASE SQL Server Transact-SQL COMPUTE statement. sp_return$( )

Returns the return status of the last call to a stored procedure. If the stored procedure does not have a RETURN statement, sp_return$( ) returns 0.

sp_select$( )

Returns the index of the current SELECT in the stored procedure. The first SELECT returns 1; the second SELECT returns 2, and so on.

You can use the sp_compute$( ), sp_return$( ), and sp_select$( ) system functions to monitor stored procedures. You can use sp_compute$( ) and sp_select$( ) at any time; use sp_return$( ) only after the stored procedure has completed execution. Example

EXECUTING block


In the following example, the SET statement assigns values returned from multiple SELECT statements performed by the stored_proc stored procedure. The EXECUTING block of the SET statement uses sp_select$( ) and sp_compute$( ) to determine which actions to take. SET $var1, $var2, $var3, $var4, $var5 TO stored_proc() EXECUTING SWITCH sp_select$() BEGIN CASE 1: /* $var1 contains value returned by SELECT #1 . . . CASE 2: IF (sp_compute$()) THEN /* $var1 and $var2 contain values returned by COMPUTE clause */ . . . ELSE /* $var1, $var2, and $var3 contain values /* returned by SELECT #2 . . . CASE 3: /* $var1, $var2, $var3, $var4, and $var5 /* contain values returned by SELECT #3 . . . END

*/

*/ */

*/ */

67

Related information

For the syntax and usage of the SET statement with stored procedures, see page 378.

System function scope in nested stored procedure calls When several stored procedure calls are nested in one EXECUTING block, each stored procedure call can have an EXECUTING block, which in turn can contain one or more calls to a system function. The scope of each system function depends on the function’s context, as shown in the following example. sp_call1 results: sp_select$( ) & sp_compute$( )

SET $p1, $p2 TO sp_call1() EXECUTING BEGIN . . . SET $p1, $p2 TO sp_call2() EXECUTING BEGIN . . . END . . .

sp_call2 result: sp_return$( )

SET $p1, $p2 TO sp_call3() EXECUTING BEGIN . . . END . . .

END

Related information

sp_call2 results: sp_select$( ) & sp_compute$( )

sp_call3 results: sp_select$( ) & sp_compute$( )



For the syntax and usage for the following statement and system functions, see the indicated pages: SET statement (page 378) sp_compute$( ) system function (page 554) sp_return$( ) system function (page 556) sp_select$( ) system function (page 559)

68


Using stored procedures as statements A call to a stored procedure can also be used alone as a statement, independent of a SET statement. In this case, any return, whether NUMERIC or ROW_VALUED, is discarded because the statement has no variables to assign values to. However, RESULT parameters can be returned. You can also obtain the return status by using the sp_return$( ) system function.

Defining macros as stored procedures SELECT statements and ROW_VALUED stored procedure calls can be used similarly. In a header file, you can define a macro that uses either a stored procedure or a SELECT expression.

In this example, a header file contains two definitions for a macro named ITEMSEL. The first definition uses the sp_items( ) stored procedure to define ITEMSEL, and the second definition uses a SELECT expression. The definition that is used depends on whether SPS_AVAIL is defined. #ifdef SPS_AVAIL #define ITEMSEL(amt) sp_items(amt) #else #define ITEMSEL(amt) SELECT item_key, item_cost \ FROM items WHERE item_cost > amt #endif

The VISION 4GL script that uses the ITEMSEL macro would contain the following statements: SET $cnt TO 0 ; SET $key, $item_cost TO ITEMSEL(100.00) EXECUTING BEGIN SET $cnt TO $cnt + 1 ; END


69

Using Unify DataServer stored procedures To use a Unify DataServer stored procedure, you must first use the SQL/A CREATE PROCEDURE statement to create the stored procedure. After creating the stored procedure, you can call it from a application. SQL statements within a stored procedure must conform to the syntax requirements of Unify DataServer. You cannot embed VISION 4GL

statements or clauses within the stored procedure. Related information

For complete information about how to create stored procedures, see your Unify DataServer manuals. Declaring the Unify DataServer stored procedure To declare a stored procedure, follow these guidelines: 1. Before calling the stored procedure, use EXTERN statement to declare the stored procedure as a function of type STORED. 2. Specify the function return type as VOID or as a data type that is compatible with the DBMS data type, such as NUMERIC. 3. Declare the stored procedure function parameters as scalar, not list or matrix variables. 4. Make sure that the number of parameters that are specified in the stored procedure declaration is the same as the number in the stored procedure definition (CREATE PROCEDURE statement). The EXTERN declaration is needed to determine whether the stored procedure is declared as a procedure (VOID) or as a function that returns a value with the specified data type. If a stored procedure contains a call to another stored procedure, the compiler will compile the calling stored procedure regardless of whether the called stored procedure is available at compile time. Calling stored procedures You can call a stored procedure like any other function. For example, you can use the SET statement to assign the value returned by a stored procedure to a variable.

70


When you call the stored procedure, the stored procedure is run under the current database connection.

Nested stored procedure calls Stored procedures and triggers can be nested. When several stored procedure calls are nested in one EXECUTING block, each stored procedure call can have an EXECUTING block, which in turn can contain one or more calls to a system function.


71

72


2 Script functions This chapter describes the fundamentals of writing Unify VISION script functions: types of functions defining a function using a function executing functions with timers error-handler functions building links for data transfer (Windows)

73

Types of functions

A function is a set of statements that perform a task in your application. Functions are used to divide large tasks into modular units or to group a set of procedures that are used repeatedly throughout a form or application. Functions can accept arguments, process or convert data, and return a value. Unify VISION provides predefined system functions that perform common information processing tasks. If needed, you can also create your own functions. You can create two types of functions: global functions local functions Although the types of functions are similar, each has a different purpose and scope. The following table summarizes the types of functions you can use and how they are created. Summary of Unify VISION function features Features

Global function

Statement types VISION 4GL

Local function VISION 4GL

Definition

Each function is contained The function is defined in its own script. like a method within the script where it is used.

Declaration

Declared in the form header of every script where it is used.

No declaration is required

(continued on next page) 74


Summary of Unify VISION function features (continued) Features Advantages

Global function Recursive

Local function Fast execution

Can contain local functions

Easily accesses local variables of the form

Can be called from any script

Within any single script, you can include up to 1,000 local developer-defined functions.

Global functions A global function can be called from any script within an application. Use these functions to perform tasks that are required throughout your application. A global function contains these elements: a function header local variable definitions (optional) local function definitions (optional) function body formal parameter definitions A global function has the following advantages: A global function can be called from any script in your application. A global function can define its own local functions. A global function can be recursive; that is, it can call itself. You must define each global function in its own script. Global functions scope variables the same way as scripts do; a global function can access the variables in all of its ancestor forms. Chapter 2: Script functions

75

To call a global function from any script, you must declare the function in the script where it is called. Within a global function, you can define local functions. These local functions can be called within the global function body. Related information

For instructions for creating a global function, see “Defining a class in VISION Class Browser” in Unify VISION: Developing an Application.

Scope of global functions The scope of a global function includes any script that uses the EXTERN statement to declare the global function.

Scope of global function variables A global function can access the following values: arguments passed to the function local variables defined within the global function local functions defined within the global function global functions declared within the global function script variables on previously active forms The parameters and local variables of a global function can be accessed within the global function and within any of the local functions that are defined within it. Parameters of a global function are added to the list of local variables. When resolving variable references within a global function, VISION compiler follows the normal Unify VISION variable scoping rules. VISION compiler first checks for a form prefix. If no form prefix exists, VISION compiler checks the function definition for a variable declaration in the PRIVATE clause or one of its parameters. If the variable is not declared locally, VISION Runtime Manager checks the current, calling form and, if the variable is not referenced on this current form, VISION Runtime Manager then checks the previously active forms for the variable definition. 76


Example

The following script statements show an example of a global function definition. The highlighted area shows a local function definition within the global function.

AMOUNT FUNCTION calculate_pay(gross_salary, days_in_period, RESULT taxes) PRIVATE net_salary, net_pay LOCAL AMOUNT FUNCTION get_netpay(gross_salary, RESULT taxes) PRIVATE the_taxrate, net_pay BEGIN SET the_taxrate TO SELECT tax_rate FROM rates WHERE lower_sal = $gross_salary; SET taxes TO (gross_salary * the_taxrate) SET net_salary TO $gross_salary - taxes RETURN (net_salary) END BEGIN SET taxes TO 00.00 SET net_salary TO get_netpay(gross_salary, taxes) SET net_pay TO (net_salary / days_in_period ) RETURN (net_pay) END

Variables defined in a script are available only if the form is active. When you reference variables on other active forms within a global function, you must make sure that the form you specify is active whenever the global function is called. If the form is not active, the reference fails. Tip

To improve performance, when referencing variables on previously active forms, include the form name prefix (form:) in all references.

Local functions A local function can be called only from within the script where it is defined. Use a local script function to perform a task that must be repeated several times in a single form or function, to increase readability, or for modularity. Chapter 2: Script functions

77

A local function has the following advantages: A local function can usually be executed more quickly than a global function. A local function can conveniently access local variables of the calling form or global function. A local function can be defined in these objects: a global function a script for a form class A local function contains these elements: formal parameter definitions (optional) a function header including these formal parameters local variable definitions (optional) function body Because the use of a local function is restricted to the form where it is defined, you do not need declare a local function. Defining a local function is equivalent to defining a new method. The function body is equivalent to the statements of a script method. At runtime, the local function is part of the current form. When the local function is defined within a script, you can refer to local variables on the calling form simply by name. You do not need the form prefix (form:) with form variables. Local functions cannot define other local functions. Scope of local functions The scope of a local function is all methods of the script that contains the function definition. If the script includes several local function definitions, a local function can also be called by any succeeding local function definitions. A local function can be called from any place where a local variable can be accessed within the script. You can call a local function in any of the form methods. 78


VISION compiler handles a function name in a manner similar to a

variable name; there must be a definition of the function name to access, or call, the function. The script file that contains the call to the function must contain a function definition.

Scope of local function variables A local function can access the following values: local variables defined within the local function variables defined within the script or function variables on previously activated forms The parameters and local variables of a local function can be accessed only within the local function body. VISION compiler generates unique names for each of these variables. Therefore, references to parameters and local variables in a local function do not refer to any other variable definitions, even variables of the same name defined elsewhere within the script. When resolving variable references within a local function, VISION compiler follows the normal Unify VISION variable scoping rules. It first checks for a form prefix. If no form prefix exists, it checks the function definition or parameter for a variable declaration in the PRIVATE clause. If the variable is not declared locally, VISION Runtime Manager checks the current, calling form or function, and if the variable is not referenced there, VISION Runtime Manager then checks the previously active forms for a variable definition. If a local function is defined within a global function, the local function can refer to variables defined within the global function. To improve performance, when referencing variables on other active forms, include the form name prefix (form:) in all references. When you reference variables on other active forms from within a local function, you must make sure that the form you specify is active when the calling form or function is active. If the form or function is not active, the reference fails. In a global function, local functions must be defined after the global function header and before the global function body. The local function definitions follow any local variable definitions. Chapter 2: Script functions

79

In a script, all local functions must be defined after the form definition statement (FORM) and before the form methods. The local function definitions follow any local variable definitions. Example

The following script statements show an example of a local function definition. The highlighted area is the local function definition for calculate_benefit( ) within the script benefits. FORM benefits PRIVATE net_salary, net_pay LOCAL VOID FUNCTION calculate_benefit (RESULT cum_benefit, benefit_rate, days_in_period) PRIVATE benefit BEGIN SET benefit TO benefit_rate * days_in_period SET cum_benefit TO cum_benefit + benefit RETURN END

... FIELD pay_period METHOD ON FIELD INPUT SET days_in_period TO SELECT num_days FROM pay WHERE period_num = $pay_period; METHOD AFTER FIELD SET years_in_company TO current_date$() - starting_date SET v_rate, p_rate TO SELECT vaca_rate, pers_rate FROM leave WHERE years = $years_in_company; calculate_benefit(vacation, v_rate, days_in_period) calculate_benefit(personal, v_rate, days_in_period ) DISPLAY vacation FOR cum_vacation DISPLAY personal FOR cum_personal

80


Defining a function A script function is created in the script associated with a form class. The script function consists of two elements: the FUNCTION header statement the function body

The function header The function header is the first line of the function definition. This statement defines the function by providing the following information: the type of function: global or local the data type of the value returned by the function the function name the function parameters The keyword FUNCTION identifies the statement as a function header. Related information

For a complete description of the FUNCTION statement, see page 289.

Defining a global or local function The first item in the function header is the function type. The function type is indicated by the inclusion or absence of the keyword LOCAL. The function type specifies whether the function is a local or global function.

Defining return values If the function returns a value, the function header contains the data type of the value to be returned. If no value is returned, the header contains the keyword VOID. Chapter 2: Script functions

81

The RETURN statement provides a convenient way to leave a function. This statement can also include the value to be returned. This return value can be a variable or an expression. You can include the RETURN statement anywhere in the function body.

Defining function names Function names follow the same naming conventions as other Unify VISION variables. Global and local function names cannot exceed 44 characters. Do not include a $ character as the last character of your function name. All Unify VISION system functions have the $ character as the last character of the function name. This character tells VISION compiler to look in system archives for the function definition. For a global function name, you must make sure that the function name is unique within all scripts that call the global function. Any script that calls the global function must not have any local functions with the same name as the global function. For a local function, the function name must be unique within the script in which the local function is defined. The script that defines and calls the local function must not have any local variables or other local functions with the same name.

Defining function parameters You can pass arguments to Unify VISION functions by using function parameters. These optional parameters are local variables for the function. To do so, you must define a parameter list in the function header. The parameter names cannot be duplicated in the function’s local variable list. Three types of parameters can be used in a Unify VISION function: value parameters result parameters reference parameters 82


Example

In the following example, the function parameter list has two parameter definitions: LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)

The first parameter, gross_salary, is a value parameter. The second parameter, taxes, is a result parameter.

Value parameters At the time of the function call, a value parameter receives the actual value of the corresponding argument. A value parameter is treated as a local variable and is initialized with the argument value when the function is called. Each time a function is called, VISION Runtime Manager initializes the value parameters with the value and data type of the corresponding function argument in the function call. When you change the value of a value parameter within a function, you are changing only the value of a variable local to the function. When execution returns to the calling program, the argument value is unchanged.

Result parameters A result parameter is also a local variable. It too is initialized with the argument value when the function is called. However, if you change the value of a result parameter within a function, you also change the value of the argument variable. As the function exits, the value of the result parameter is copied back into the argument variable after the function returns. When execution returns to the calling program, the argument variable’s value is changed. The argument variable now contains a new value: the value of the result parameter. Because the result parameter value is copied back into the argument variable, you can use result parameters to return values to the calling function. You can then use the value of this result parameter value in the calling function. Chapter 2: Script functions

83

Reference parameters When a function calls a parameter by reference, the value of the parameter is not copied to the function. Instead, only the location of the array or variable is used to provide access to the value. The type of reference parameter is identified by a keyword: LIST

For a one-dimensional array.

MATRIX

For a two-dimensional array.

REF[ERENCE] For a simple (scalar) variable.

Writing the function body The body of the function contains Unify VISION statements for executing functions. The function body is specified by a statement block consisting of Unify VISION statements surrounded by the keywords BEGIN and END. Statements within the function body can access local variables defined by the function, unqualified variables (variables that are not preceded by a form name), and variables on other active forms (when they are preceded by the form name). Certain Unify VISION statements have special conditions or restrictions on their use in a function. Related information

84

For a list of statements that are valid in a function body, see the description of the FUNCTION statement beginning on page 289.


Using a function To use a Unify VISION function within a script, follow these steps: 1. Include a function call in the script. 2. Declare the function within the script. Each of these steps is described in the sections that follow.

Calling the function You call both local and global functions with the same calling syntax that you use to call external functions or Unify VISION system functions. The following restrictions and conditions apply to making function calls: A global function name must be the same as the function itself. For example, if you create a global function called func2 in VISION Development Environment, and execute the Edit Script command, VISION Development Environment automatically enters NUMERIC FUNCTION func0( ) in your script. If you rename your global function, you must also rename it in the script. A global function can recursively call itself. It can also call other global functions if these functions are declared with the EXTERN statement within the global function script file. A local function can call a global function only if the global function is declared with the EXTERN statement within the script. When you define a local function within a global function script, the local function can call any global functions declared within the global function. A global function can call any local functions that are defined in the global function. A local function may not be recursive; it can call only other local functions that are defined within the same script file. If a file contains several local function definitions, a local function can call any other local functions that precede it in the file. A local function cannot call a local function that is defined later in the file. Chapter 2: Script functions

85

Both local and global functions can call any Unify VISION system functions. They can also call external C language functions as long as these external functions are declared in the same file with the EXTERN statement. Because a global function is executed as a separate form, some Unify VISION system functions are reset when execution of the function is

begun. Restarted functions include these system functions: aud_mode$( ) check_dirty$( ) current_record_count$( ) current_record_num$( ) is_current_record_stored$( ) last_command$( ) status$( ) record_is_current$( ) When VISION Runtime Manager encounters a call to a global function, it searches the class libraries in the class library list for the function. The class libraries are searched in the order that they are specified in the class library list. When the function is located, it is executed and no other class libraries in the list are searched. If the function is not found in any of the class libraries, VISION Runtime Manager then looks in the current class library. If the function is still not found, an error occurs. Tip

Related information

When using one of these restarted functions, save the value of the function in a variable or pass in the value as an argument to the global function. Then use the variable or argument within the global function to access the value for the calling form. For information about the class library list, see the Class Libraries panel description in the “Partition profile and partition group profile editors” chapter of Unify VISION: Developing an Application. Syntax for calling a function To call a function from within a script, you use this function call syntax: function_name ( arguments )

86


The function name must be listed exactly as it is defined in the FUNCTION statement. Like Unify VISION variable names, Unify VISION function names are case sensitive. For example, if the function name is defined as get_netpay, you cannot call the function with the name GET_NETPAY or Get_NetPay. Regardless of whether your function has parameters, you must include a pair of parentheses in the function call. For example, if the function display_empid( ) has no parameters, the following statement shows a sample function call for the display_empid( ) function: SET exit_stat TO display_empid()

Returning a value If a function returns a value, you must include some way for using the function return value when you call this function: Either: Save the return value to use elsewhere in the calling function. or Use the return value once. If you want to use this return value several times in the calling function, you can use the SET statement to assign the return value to a variable, for example: SET net_pay TO get_netpay( emp_gross, emp_taxes )

The data type of the variable in the calling function must match the data type of the return value as it is defined in the function header. Mismatched data types return unexpected data. If you need a value only once, you can use the value directly in the calling function. For example, the following IF statement calls get_netpay( ) and uses the return value: IF ( get_netpay( emp_gross, emp_taxes ) < 10,000.00 ) THEN

If you attempt to use the return value of a function that has been defined as VOID, you will receive an UNDEFINED value. Chapter 2: Script functions

87

Declaring the function When you call a function within a script, VISION compiler must determine whether the function name variable refers to a function rather than to an Unify VISION variable. If the script file does not contain the function definition, you must include a function declaration within the script file. A function declaration is different from a function definition: function definition

The function header, variables and statements that describe what the function does.

function declaration

Tells VISION compiler that the function name variable refers to a function defined in another script.

To declare a global function within a script, use the EXTERN statement. The EXTERN statement declares external functions within a script. This statement is the function declaration for a function with a definition that is not included in the same file as the function call. Example

The following example shows a call to a global function. EXTERN SCRIPT NUMERIC FUNCTION calculate_pay (gross_salary, days_in_period, RESULT taxes) #include sscodes.h" FORM payperiod FIELD emp_lname METHOD ON FIELD INPUT SET emp_number, emp_gross TO SELECT emp_id, gross_sal FROM employee WHERE emp_lname = $emp_lname; IF (status$() = SS_NORM) THEN BEGIN SET emp_id:CLEAR_FIND_EXP TO emp_number NEXT ACTION IS FIND END ELSE BEGIN DISPLAY 'Invalid Employee Name' FOR FYI_MESSAGE WAIT

88


END

RESTART ON FIELD

FIELD pay_period METHOD ON FIELD INPUT SET days_in_period TO SELECT num_days FROM periods WHERE period_id = $pay_number; METHOD AFTER FIELD SET emp_taxes TO $00.00 SET emp_net TO calculate_pay(emp_gross, days_in_period, emp_taxes)

Chapter 2: Script functions

89

Using ORACLE system functions in scripts The information in this section applies only to the ORACLE DBMS. If you are using Unify VISION with the ORACLE DBMS, you can use ORACLE system functions in VISION 4GL scripts. To use an ORACLE system function, use the ORACLE DUAL table. This table is automatically created when a user is created. Use ORACLE system functions only in SQL DML statements, such as SELECT or INSERT. In other VISION 4GL statements, use VISION 4GL system functions. Example

The following example shows how to access the TRUNC( ) system function through VISION 4GL and the DUAL table. SET $dvar TO SELECT TRUNC($a/$b, 2) FROM DUAL;

Related information

For more information about ORACLE system functions, see your ORACLE DBMS manuals.

90


Executing functions with timers A timer is an application event that is executed after a specified time period. When the timer event is activated, a specified global function is executed. This section describes the following tasks: example of a timer declaring a timer event creating a timer event deleting a timer event

Timer event example For example, to display up-to-the-minute stock market quotations, you could install a timer at regular intervals. Each time the timer event occurs, its global function is executed to read an external file and update the stock market information on the screen. Related information

For complete descriptions of the timer statements described in this section, see “Script statements” in this manual.

Declaring a timer event handler function You must declare a timer event handler function before it can be referenced in a CREATE TIMER EVENT statement. The timer event handler function must be global and declared in an EXTERN VISION TIMER FUNCTION statement.

Creating a timer event You must create the timer event by using the CREATE TIMER EVENT statement. The CREATE TIMER EVENT statement installs a request for a timer event. When the timer expires, the specified function is executed. The specified function must have been previously declared and defined as a TIMER FUNCTION. Timer events can occur only once per installation. To execute a timer event function again, the timer event request must be reinstalled. Chapter 2: Script functions

91

Deleting a timer event For a variety of reasons, you may want to delete a timer event before its time limit has elapsed. For example, if you have requested a find operation to be performed in 10 seconds, you may want to remove that request after user input. To remove a specific timer event, use the DELETE TIMER EVENT statement. To delete all timer events, use the DELETE ALL TIMER EVENTS statement. The DELETE TIMER statements remove the timer event request from various internal queues, thus preventing the timer event from being executed.

92


Error-handler functions In a script you can define and install functions for handling runtime errors. This section describes these tasks: elements of a script used by error-handler functions defining an error function declaring the error-handler function installing an error-handler function By default, runtime errors are displayed to the user in a popup window. Errors can result from interactive actions by the user or from script conditions. You can use an error-handler function to suppress display of an error message, depending upon the condition. Suppressed error messages are instead written to the file specified by the AMGR_ERFL external preference. To suppress display of an error message, use a RETURN (TRUE) statement in the function body. If the function body includes no RETURN clause or specifies RETURN (FALSE), the standard error message window appears. When you use VISION Debugger to debug an application or form, all error messages are displayed, regardless of error-handler specifications. Example

In this example, the default error message window is allowed to appear when a specific user error occurs: IF (error_info[ERRNUM] = Ć8835) THEN RETURN (FALSE);

Elements used by an error-handler function Error-handler functions use the following Unify VISION features: DEINSTALL, EXTERN, FUNCTION, and INSTALL statements

status$( ) system function dbmserrs.h, sscodes.h, and scrpterr.h header files Chapter 2: Script functions

93

To use an error-handler function, follow these steps: 1. First create it as a global function. 2. Declare and install the function in the script where it is called. You can also deinstall an error-handler function in places where it is no longer required.

Defining an error handler You define the error-handler function in a separate script. The file can include the dbmserrs.h, sscodes.h, and scrpterr.h header files. These files are located in the $VISION_HOME/include directory. The dbmserrs.h file defines values passed to the error-handler function. The sscodes.h file defines the values returned by the status$( ) system function. The scrpterr.h file defines the values passed to a SCRIPT_ERROR function. Example

The following example shows a file that defines an error handler named deadlock_handler: #include #include DBMS_ERROR FUNCTION deadlock_handler (LIST error_info) BEGIN IF (error_info[INTR_FLAG] = TRUE) THEN DISPLAY NOTICE 'Warning! Deadlock!'; ROLLBACK WORK; END;

Example

The following example shows a file that defines a script error handler named script_err_handler: #include SCRIPT_ERROR FUNCTION script_err_handler (LIST error_info) BEGIN IF (error_info[FATAL] = TRUE) THEN DISPLAY NOTICE WITH TEXT 'User warning! Exiting the application!' WAIT; RETURN (TRUE); END;

94


Declaring a DBMS error handler In the script, you must declare a DBMS error-handler function as a global FUNCTION, using the following syntax: EXTERN SCRIPT DBMS_ERROR FUNCTION function_name (LIST error_info)

The error handler function returns its status in a reference parameter (LIST error_info); this parameter is a one-dimensional array consisting of the following six elements, as defined in the dbmserrs.h file: 0

ACC_STATUS (NUMERIC) Provides the status return value. Values are

the same as those returned by the status$( ) system function. 1

DBMS_ERR

2

DBMS_OPRN (NUMERIC) Provides the value defined in the

(NUMERIC) Provides the error code returned by the DBMS. Values are the same as those returned by the dbms_status$( ) system function. dbmserrs.h file for the database operation type.

3

INTR_FLAG

(BOOL) Indicates whether the operation was interactive (TRUE) or noninteractive (FALSE).

For an interactive operation: 4

INTR_OPRN

(NUMERIC) Specifies the operation (add, commit, delete, find, or update) that caused the error.

For a noninteractive operation: 4

CODE_SECTION

Specifies the method as defined in the dbmserrs.h file. 5

FUNC_NAME (STRING) If the error is caused by a noninteractive

operation within a function, provides the function name.

Declaring a script error handler In the script, you must declare a script error-handler function as a global FUNCTION, using the following syntax: EXTERN SCRIPT SCRIPT_ERROR FUNCTION function_name (LIST error_info) Chapter 2: Script functions

95

The script error handler function returns its status in a reference parameter (LIST error_info); this parameter is a one-dimensional array consisting of the following six elements, as defined in the scrpterr.h file: 0

FATAL

(BOOL) Indicates whether the operation was fatal (TRUE) or recoverable (FALSE).

1

ERRNUM

(NUMERIC) The error number returned by VISION Runtime Manager.

2

ERRTEXT

(STRING) The text of the error message returned by VISION Runtime Manager.

3

OBJREF

(OBJECT_REF) The OBJECT_REF of the object that caused the error.

For an interactive operation: 4

ISFORM

(BOOL) Indicates whether the error was caused by a form (TRUE) or a global function (FALSE).

For a global function script error: 5

FUNCNAME

(STRING) Specifies the name of the global function that caused the error.

For a script error: 5

CODESEC

(STRING) Specifies the name of the method that caused the error.

6

CODELINE

(NUMERIC) Specifies the line number in the script where the error occurred.

Installing an error handler You must use the INSTALL statement to activate the error handler as needed. The INSTALL statement enables you to specify specific errors and to identify each installation of a particular error handler. You can de-install an error handler when it is not needed by using the DEINSTALL statement. 96


Example

The following example shows portions of a script that installs and deinstalls an error handler named deadlock_handler, which is assigned an identifier named $deadlockid. This error handler is called only for the SS_DEADLOCK status return error. #include EXTERN SCRIPT DBMS_ERROR FUNCTION deadlock_handler(LIST error_info) ON CREATE INSTALL DBMS_ERROR HANDLER deadlock_handler FOR EVENTS SS_DEADLOCK IDENTIFIED BY $deadlockid ... ON DESTROY DEINSTALL $deadlockid


97

Returning information about ORACLE version 7 or SYBASE SQL error messages The information in this section applies to only the ORACLE DBMS, version 7and SYBASE SQL. ORACLE Version 7 and SYBASE SQL can return multiple error messages

for a single executable statement. The error messages are returned as one long string that contains embedded error numbers. In a VISION 4GL script, to obtain information about the messages that were returned for a statement, use these system functions: sql_errmsg_count$( ) sql_errmsg_i$( ) dbms_status_i$( ) If you have existing scripts that obtain error message information through the dbms_status$( ) system function and the sql_errmsg$( ) system function, you can expect the following results: dbms_status$( ) returns the first error code found in the string of multiple messages. sql_errmsg$( ) returns the entire string of multiple messages. Note that the sql_state$( ) system function is not supported for ORACLE or SYBASE SQL databases.

98


Handling SYBASE SQL Server errors The information in this section applies to only SYBASE SQL Server. Special handling may be required for two types of SYBASE SQL Server errors: transaction abort errors trigger errors

Handling SYBASE SQL Server transaction abort errors Transaction abort errors are errors that cause SYBASE SQL Server to abort the transaction. Although SYBASE SQL Server can generate multiple errors for a single statement, Unify VISION gives you information about only the most recent error, unless it is a transaction abort error. For transaction abort errors, you need to know not only that the transaction has been aborted, but also what error caused the transaction to be aborted. For example, if you try to insert the value 99999 into a tinyint column, SYBASE SQL Server generates an “overflow” error and a “Transaction has been aborted” error. How transaction abort errors are handled in Unify VISION applications depends on whether you perform interactive operations or perform noninteractive operations through VISION 4GL. Obtaining error messages for interactive operations When you use Unify VISION interactively and the server aborts the transaction, two error message boxes are displayed, one after the other. The first message indicates the cause of the error. The second message is a message that the server has aborted your transaction. For example, if you use a trigger to insert a record, but the insert fails because of a duplicate key value, the first message reads “Attempt to store a duplicate key,” and the second message reads ’Transaction has been aborted.” Chapter 2: Script functions

99

Obtaining error messages for noninteractive operations through VISION 4GL When you use VISION 4GL, if you want to display both error messages, you must use these system functions: 1. Use the status$( ) system function to obtain the status code for the error. For example, status$( ) returns -4 (SS_DUPK) when an attempt is made to store a duplicate key. 2. Use the dbms_status$( ) system function to determine whether the last statement that caused an error aborted the transaction. For example, if the transaction was aborted, dbms_status$( ) returns the SYBASE SQL Server error code 3618. 3. Use the sql_errmsg$( ) system function to retrieve the corresponding SYBASE SQL Server message text. For example, for error code 3618, sql_errmsg$( ) returns “Transaction has been aborted.”

Handling SYBASE SQL Server trigger errors Each SYBASE SQL Server table can have triggers defined for insert, update, and delete operations. These triggers are activated (fired) after an insert, update, or delete operation is performed on the table and can execute any valid SYBASE SQL Server command. If the work performed by the insert, update, or delete operation that fired the trigger needs to be undone, a ROLLBACK statement must be executed. The rollback aborts the entire current transaction, aborting the current Unify VISION transaction as well. To handle trigger errors, you need to be able to generate information about trigger results, transaction rollback operation status, and error severity, as described in the following subsections.

Generating information about trigger results Because SYBASE SQL Server triggers cannot return a status through the operation that fired the trigger, you must use the raiserror and print statements to generate information about the trigger’s results. Both statements call the SYBASE SQL Server error handler. 100


The error number that is given to the error handler is different from the normal SYBASE SQL Server error numbers. The following table shows the ranges of error numbers that can be passed: Statement

Error number range

print

0

none (SYBASE SQL Server errors)

1 through 20000

raiserror

20001 or above

Either print or raiserror can send a string to be used for an error message to the error handling routine. The raiserror statement can also send an error number in the range of 20001 or higher. Unify VISION accepts the error numbers sent by print or raiserror and saves the strings so that the appropriate message can be displayed. To control how Unify VISION handles the SYBASE SQL Server errors, you can use the SYBASE_MSGS and SYBASE_RB_ERRNUMS external preferences. To indicate which messages should be sent to Unify VISION, use the SYBASE_MSGS external preference, which contains a list of strings separated by commas: Value

Result

none

Send SYBASE SQL Server error messages only

Errors

Send raiserror messages

Messages

Send print messages

Errors,Messages

Send raiserror and print messages

Messages,Errors

Send raiserror and print messages

These string values can be specified in uppercase or lowercase. The default value is Errors. If multiple errors are sent per database operation by using multiple calls to either print or raiserror, only the last status and message is sent to Unify VISION depending on the message severity (see “Determining Error Severity” on page 102). Chapter 2: Script functions

101

To be able to indicate whether a rollback was performed, use the SYBASE_RB_ERRNUMS external preference, which contains a comma separated list of error numbers in the raiserror range of greater than 20000. Single numbers can appear in the comma separated list. A dash (–) in the first or last character indicates that the range is open-ended. For example: 20001 20001–21000 22000,23000–23010,30000– –27500 The default value is 20001–, which assumes that every raiserror causes a rollback. When raiserror gets an error number that is in any of the listed ranges, an error status informs Unify VISION that a rollback has occurred, thus preventing an internal system error. The effect is similar to executing a ROLLBACK WORK statement. If the error given to raiserror indicates that a rollback has occurred, the SYBASE_MSGS external preference is ignored, and the Unify error is returned to VISION Runtime Manager.

Rollback guarantee To ensure that the transaction is rolled back when the raiserror error number indicates that a transaction was aborted, Unify VISION executes an implicit rollback transaction operation. This ensures that an aborted transaction is always rolled back, regardless of whether you have explicitly issued a ROLLBACK WORK statement. Determining error severity Because multiple print and raiserror calls are possible, Unify VISION must determine which one is the most important. The following list indicates the types of errors in order of priority: 1. raiserror that indicates that a rollback occurred 2. SYBASE SQL Server errors (1 through 20000) 3. raiserror that indicates no rollback occurred 4. print (0) 102


For example, if raiserror sends an error that indicates that a rollback (1) was performed, and print is performed (4) at the same time, the rollback raiserror is given priority. If two errors of the same priority are received, the most recent error (the second) is given higher priority and sent to Unify VISION.

Unify VISION errors A Unify VISION error number is displayed on the screen with the message given in the statement. Three error messages (numbers –11228, –11229, and –11230) can be sent to Unify VISION for an error that resulted from an interactive operation. Each error message represents one of the developer-defined errors that result from a call to print or raiserror. Related information

For the syntax and usage of the ROLLBACK WORK statement, see page 367. For the descriptions of the SYBASE_MSGS external preference and the SYBASE_RB_ERRNUMS external preference, see “External preferences syntax descriptions” chapter in Unify VISION: Application Reference.


103

Building links for data transfer In Windows, data is transferred between applications through dynamic data exchange (DDE). DDE enables two applications that are on a single machine to send messages to each other and transfer data between them. One application acts as the client, which requests and receives data from another application. The application that sends data to the client application acts as the server. The application can act as a client to one application and as a server to another application. Windows DDE protocol enables three types of links: cold

A link in which the client requests the data each time that the data is needed. The server sends the data only when it is requested by the client.

hot

A link in which the client requests the data only once. The server sends the data to the client whenever the data changes.

warm

A link in which the server notifies the client that the data has changed. The server does not send the data until the client requests it.

You can build both hot and cold DDE links between the application and other Windows applications. You cannot use warm links with a Unify VISION application.

Building a link When you build a link, you use the VISION 4GL INSTALL statement to install a global function that acts as a DDE event handler. To deinstall the DDE event handler function, you use the VISION 4GL DEINSTALL statement. The event handler function is used by Unify VISION to capture DDE messages and pass them to the application through VISION 4GL. The action taken depends on the message received. 104


Handling DDE messages that are received The INSTALL statement lets you install a global event handler function for each DDE message that a server can receive from a client or that a client can receive from a server. A client can trigger these events in a DDE server: EXECUTE_COMMAND INITIATE_HOT_LINK INITIATE_LINK RECEIVE_DATA

REQUEST_DATA TERMINATE_HOT LINK TERMINATE_LINK

A server can trigger these events in a DDE client: RECEIVE_DATA TERMINATE_HOT_LINK TERMINATE_LINK

You can use the DEINSTALL statement to deinstall one or all of the global functions that are handling DDE events. Sending DDE messages In addition to using the INSTALL and DEINSTALL statements to install DDE event handler functions, you can use several system functions to send DDE messages from one application to another. dde_get_data$( ) dde_get_hot_links$( ) dde_get_links$( ) dde_get_response$( ) dde_initiate_hot_link$( ) dde_initiate_link$( )

dde_request_data$( ) dde_send_command$( ) dde_send_data$( ) dde_terminate_hot_link$( ) dde_terminate_link$( )

All of these system functions return a numeric status code. For example, a status of DDE_SUCCESS indicates that the function was successfully completed. All other status values indicate that the function failed for a specific reason. The status codes that can be returned by the DDE system functions are defined in the ddecodes.h header file in the release include directory. Related information

For a complete description of the DEINSTALL statement, see page 230. For a complete description of the INSTALL statement, see page 303. For information about DDE-related system functions, see “System functions” in this manual.


105

Building a cold link A cold link consists of the sequence of events summarized in the following diagram. Cold link events

Client

Server Initiate link for application, topic

Acknowledge application and topic availability Request data item Send data item Terminate link Terminate link

The method used for each event depends on whether the application is acting as a server or as a client. 1. The client application initiates a link for a specific application and topic. For example, the client application initiates a link for the vision application and the CUSTOMER topic. If the application is acting as a server, use the INSTALL statement to install a global function to handle an initiate link message sent by the client. If the application is acting as a client, use the dde_initiate_link$( ) system function to broadcast an initiate link message to all applications that support DDE. 2. The server application acknowledges whether the application and topic are available. If the application is acting as a server, return the relevant status in the initiate link event handler function. If the application is acting as a client, the return status for the dde_initiate_link$( ) function indicates the success or failure of the link. 106


3. If the requested application and topic are available, the client requests a data item. For example, the client application requests the ADDRESS data for the CUSTOMER topic that is associated with the vision application. If the application is acting as a server, use the INSTALL statement to install a global function to handle a request data message sent by the client. If the application is acting as a client, use the dde_request_data$( ) system function to send a request data message. 4. The server either sends the data item or sends a message that the data item is not available. If the application is acting as a server, the request data event handler function returns either the value of the data item or an undefined value if the data item is not available. If the application is acting as a client and the data item is available, its value is stored in the result data variable that was specified as an argument for the dde_get_data$( ) function. Client event 3 (the client request for data) and server event 4 must be repeated each time the data item is needed.

5. Either the server or the client can send the first message to terminate the link. The server sends the message if the data is no longer available; the client sends the message if the data is no longer needed. If the application is acting as a server, use the dde_terminate_link$( ) system function to send a terminate link message to the client. Use the INSTALL statement to install a global function to handle a terminate link message sent by the client. If the application is acting as a client, use the dde_terminate_link$( ) system function to send a terminate link message to the server. Use the INSTALL statement to install a global function to handle a terminate link message sent by the server. Chapter 2: Script functions

107

Building a hot link A hot link consists of the sequence of events summarized in the following diagram. Hot link events

Client

Server

Initiate a link (conversation) for an application, topic Acknowledge application and topic availability Initiate a hot link for a data item Acknowledge data item availability

Send data item when it is updated Terminate the hot link for the data item Terminate the hot link for the data item Terminate link (conversation) for the application and topic Terminate link (conversation) for the application and topic

The method used for each event depends on whether the application is acting as a server or as a client. 1. The client application initiates the link for a specific application and topic. For example, the client application initiates a link for the vision application and the CUSTOMER topic. If the application is acting as a server, use the INSTALL statement to install a global function to handle an initiate link message sent by the client. If the application is acting as a client, use the dde_initiate_link$( ) system function to broadcast an initiate link message to all applications that support DDE. If acknowledged positively, a conversation is initiated between the client and server. 108


2. The server application acknowledges whether the application and topic are available. If the application is acting as a server, return the relevant status in the initiate link event handler function. If the application is acting as a client, the return status for the dde_initiate_link$( ) function indicates whether a server is available to service the request. If the application and topic are available and a link is initiated, a conversation is opened between the client and server. 3. If the requested application and topic are available, the client initiates a hot link for a specific data item that is needed. For example, the client application indicates that it needs the ADDRESS data for the CUSTOMER topic that is associated with the vision application. If the application is acting as a server, use the INSTALL statement to install a global function to handle an initiate hot link message sent by the client. If the application is acting as a client, use the dde_initiate_hot_link$( ) system function to indicate that a data item is needed by the client. 4. The server acknowledges whether the data item is available. If the application is acting as a server, return the relevant status in the initiate hot link event handler function. If the application is acting as a client, the return status for the dde_get_response$( ) function indicates the success or failure of the link. After a conversation is opened between the client and server, the client can initiate hot links for any of the data items that are associated with the topic. Thus, for each conversation opened by dde_initiate_link$( ), the client can initiate a number of hot links (dde_initiate_hot_link$( )). 5. The server sends the data item each time the data is updated. If the application is acting as a server, use the dde_send_data$( ) system function to send the data item value to the client application. If the application is acting as a client, use the INSTALL statement to install a global function to handle a receive data message sent by the server. Chapter 2: Script functions

109

6. Either the server or the client can send the message to terminate the hot link for the data item. The server can send the message if the data item is no longer available. The client can notify the server when the data item is no longer needed. If the application is acting as a server, use the dde_terminate_hot_link$( ) system function to send a terminate hot link message to the client. Use the INSTALL statement to install a global function to handle a terminate hot link message sent by the client. If the application is acting as a client, use the dde_terminate_hot_link$( ) system function to send a terminate hot link message to the server. Use the INSTALL statement to install a global function to handle a terminate hot link message sent by the server. 7. The server acknowledges that the client no longer needs the data item (terminates the hot link for the data item). If the application is acting as a server, and the terminate hot link message is received, the hot link is terminated, regardless of whether the INSTALL statement was used to install a global function to handle terminate hot link events. If the application is acting as a client, the return status for the dde_terminate_hot_link$( ) function indicates the success or failure of the terminate hot link message. 8. Either the server or the client can send the message to terminate the link for the application and topic (closes the conversation between the client and server). If the application is acting as a server, use the dde_terminate_link$( ) system function to send a terminate link message to the client. Use the INSTALL statement to install a global function to handle a terminate link message sent by the client. If the application is acting as a client, use the dde_terminate_link$( ) system function to send a terminate link message to the server. Use the INSTALL statement to install a global function to handle a terminate link message sent by the server.

Writing DDE event handler functions When you write global DDE event handler functions, follow the guidelines given in this section. The guidelines are presented in the form 110


of tables that summarize the expected syntax and return values for each function. You must provide the arguments and return values; Unify VISION does not provide them. Use the EXTERN statement to declare each global DDE event handler function. Use the INSTALL statement to install the function, and use DEINSTALL to deinstall the function. Make sure that the name of the function that is declared in the EXTERN statement is the same as the function name that is passed to the INSTALL statement. The examples that start on page 117 illustrate how the global DDE event handler functions are used with the DDE system functions to handle links between Unify VISION clients and servers.

For execute command DDE events Write a Boolean DDE event handler function to handle execute command messages. If this function is installed, it will be called when a client asks Unify VISION to execute a command. The execute command event handler function is responsible for execution of the requested command. Event: Execute command Syntax:

BOOL FUNCTION exec_command_func(client_ID,

command_name) where exec_command_func is the name of the function to handle execute command events. Arguments:

(NUMERIC) client_ID The link ID of the client that asked for the command to be executed. The link ID is passed to the function by VISION Runtime Manager. (STRING) command_name The name of the command to be executed.

Return Values: TRUE

The command has been executed successfully.

FALSE The command could not be executed

successfully.


111

For initiate hot link DDE events Write a Boolean DDE event handler function to handle initiate hot link messages. If this function is installed, it will be called when a client sends an initiate hot link message for a specific data item. This function returns TRUE if the hot link will be established. After the hot link is established, the server will use the dde_send_data$( ) function to send the client a new copy of the data item each time that the data is updated. Event: Initiate hot link Syntax:

BOOL FUNCTION init_hot_link_func(client_ID, item)

where init_hot_link_func is the name of the function to handle initiate hot link events. Arguments:

(NUMERIC) client_ID The link ID of the client that is to send the request for a hot link. The client link ID is passed to the function by VISION Runtime Manager. (STRING) item The name of the item for which data was requested.

Return Values: TRUE

The hot link will be established.

FALSE The hot link will not be established.

112


For initiate link DDE events Write a Boolean DDE event handler function to handle initiate link messages. If this function is installed, it will be called when a client sends an initiate link message. Event: Initiate link Syntax:

BOOL FUNCTION init_link_func(client_ID,

application, topic) where init_link_func is the name of the function to handle initiate link events. Arguments:

(NUMERIC) client_ID The link ID of the client that requested the link. The link ID is passed to the function by VISION Runtime Manager. (STRING) application The application that was specified by the client. (STRING) topic The topic that was specified by the client.

Return Values: TRUE

The DDE link will be established.

FALSE The DDE link will not be established.


113

For receive data DDE events Write a Boolean DDE event handler function to handle receive data messages. If this function is installed, it will be called when a client sends data to a server or a server sends data to a client. Event: Receive data Syntax:

BOOL FUNCTION

receive_data_func(client_or_server_ID, item, data) where receive_data_func is the name of the function to handle receive data events. Arguments:

(NUMERIC) client_or_server_ID The link ID of the client or server that sent the data. The ID is passed to the function by VISION Runtime Manager. (STRING) item The name of the data item for which data was sent. (TEXT) data The data value that was sent.

Return Values: TRUE

Informs the client or server that the data has been accepted.

FALSE Informs the client or server that the data has

been rejected.

114


For request data DDE events Write a string DDE event handler function to handle request data messages and support cold links. If this function is installed, it will be called when a client sends a request data message. Event: Request data Syntax:

TEXT FUNCTION request_data_func(client_ID, item)

where request_data_func is the name of the function to handle request data events. Arguments:

(NUMERIC) client_ID The link ID of the client that requested the data. The ID is passed to the function by VISION Runtime Manager. (STRING) item The name of the data item for which data is requested.

Return Values: Defined_TEXT_value The value of the requested data. Undefined The application cannot provide the requested data.


115

For terminate hot link DDE events Write a void DDE event handler function to handle terminate hot link messages. This function will be called when a client sends a terminate hot link message. The DDE hot link is terminated regardless of whether the function is installed. Event: Terminate hot link Syntax:

VOID FUNCTION term_hot_link_func(link_ID, item)

where term_link_func is the name of the function to handle terminate link events. Arguments:

(NUMERIC) client_or_server_ID The link ID of the client or server that asked to terminate the hot link. The client or server ID is passed to the function by VISION Runtime Manager. (STRING) item The name of the data item that is being sent to the client by the server.

Return Values: None

116


For terminate link DDE events Write a void DDE event handler function to handle terminate link messages. This function will be called when a client sends a terminate link message. The DDE link is terminated regardless of whether the function is installed. Event: Terminate link Syntax:

VOID FUNCTION

term_link_func(client_or_server_ID) where term_link_func is the name of the function to handle terminate link events. Arguments:

(NUMERIC) client_or_server_ID The link ID of the client or server that asked to terminate the link. The ID is passed to the function by VISION Runtime Manager.

Return Values: None

Examples The following examples show how to create cold and hot links between Unify VISION and other Windows applications.

Cold link server example In this example, Microsoft Excel is the DDE client and the Unify VISION application is the DDE server. Excel macro

The Microsoft Excel macro obtains a customer name from the Unify VISION application and transfers the value to the calling cell. WChan=INITIATE("SCRIPT", "CUSTOMER") =REQUEST(WChan, "NAME") =TERMINATE(WChan) =RETURN()


117

The following VISION 4GL statements enable the Unify VISION application to act as a DDE server for the Excel macro. Topic is defined as a table name, and Item is defined as a column in that table, so that the table and column names can be used in a SET statement. BOOL FUNCTION DDEInitiateLink(Client, Application, Topic) BEGIN IF ($Application = "VISION") AND ($Topic = "CUSTOMER") BEGIN SET $custclient TO $Client /* custclient is a global */ RETURN (TRUE) /* initiate link */ END RETURN (FALSE) /* DO NOT initiate link */ END TEXT FUNCTION DDERequestData(Client, Topic, Item) PRIVATE tmp BEGIN IF ($custclient = $Client) /* custclient is a global */ SET $tmp TO SELECT $Item FROM $Topic RETURN ($tmp) END RETURN (UNDEFINED) END

Form script statements

The following statements are in a script: EXTERN SCRIPT BOOL FUNCTION DDEInitiateLink(val, val, val) EXTERN SCRIPT STRING FUNCTION DDERequestData(val, val) INSTALL DDE_EVENT HANDLER DDEInitiateLink FOR EVENTS INITIATE_LINK IDENTIFIED BY $initid INSTALL DDE_EVENT HANDLER DDERequestData FOR EVENTS REQUEST_DATA IDENTIFIED BY $reqid

Hot link server example In this example, Microsoft Excel is the DDE client, and the Unify VISION application is the DDE server. Excel macro

A Microsoft Excel data cell contains this macro: =vision|CUSTOMER!NAME

118


Form script statements

The following VISION 4GL statements enable the Unify VISION application to act as a DDE server for a hot link. These statements are in a script. EXTERN EXTERN EXTERN EXTERN EXTERN EXTERN EXTERN EXTERN

SCRIPT SCRIPT SCRIPT SCRIPT SCRIPT SCRIPT SCRIPT SCRIPT

BOOL TEXT BOOL BOOL BOOL BOOL VOID VOID

FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION

DDEInitiateLink(val, val, val) DDERequestData(val, val) DDEStartHotLink(val, val) DDEStopHotLink(val, val) DDEReceiveData(val, val, val) DDEExecuteCmd(val, val) DDEAcknowledge(val, val, val) DDETerminate(val)

The following matrix array is used to keep track of the active hot links. Unify VISION searches through the array in the WHEN FIELD CHANGES methods to determine whether an active hot link exists for a particular variable. LOCAL MATRIX hotlinks[1 TO UNKNOWN, 1 to 4], numhotlinks SET numhotlinks TO 0

The following INSTALL statements can be put in the BEFORE APPLICATION section of the master application script. The DDE event handler global functions are called when DDE events are received by Unify VISION. INSTALL DDE_EVENT HANDLER DDEInitiateLink FOR EVENTS INITIATE_LINK IDENTIFIED BY $initid INSTALL DDE_EVENT HANDLER DDERequestData FOR EVENTS REQUEST_DATA IDENTIFIED BY $reqid INSTALL DDE_EVENT HANDLER DDEStartHotLink FOR EVENTS INITIATE_HOT_LINK IDENTIFIED BY $reqid INSTALL DDE_EVENT HANDLER DDEStopHotLink FOR EVENTS TERMINATE_HOT_LINK IDENTIFIED BY $reqid INSTALL DDE_EVENT HANDLER DDEReceiveData FOR EVENTS RECEIVE_DATA IDENTIFIED BY $reqid INSTALL DDE_EVENT HANDLER DDEExecuteCmd FOR EVENTS EXECUTE_COMMAND IDENTIFIED BY $reqid


119

Global function scripts

The following global functions are placed in their own script files. BOOL FUNCTION DDEInitiateLink(Client, Application, Topic BEGIN IF ($Application = "VISION") BEGIN IF ($Topic = "CUSTOMER") SET $custclient TO $Client /* custclient is a global */ RETURN(TRUE) /* initiate link */ END RETURN (FALSE) /* DO NOT initiate link */ END

This function adds active hot links to the hotlinks array. BOOL FUNCTION DDEStartHotLink(linkid, item) BEGIN SET numhotlinks TO dde_get_hot_links$(hotlinks) RETURN (TRUE) END

This global function removes a hot link from the hotlinks array when the hot link is terminated by the client. BOOL FUNCTION DDEStopHotLink(linkid, item) BEGIN SET numhotlinks TO dde_get_hot_links$(hotlinks) RETURN (TRUE) END

120


Cold link client example In this example, Microsoft Excel is the DDE server and the Unify VISION application is the DDE client. Form script statements

The following VISION 4GL statements enable the Unify VISION application to act as a DDE client for Microsoft Excel. SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id) IF ($stat = DDE_SUCCESS) THEN BEGIN SET $stat TO dde_request_data$($server_id, 'CELL1', $data, 10000) /* time out after 10 seconds */ IF ($stat = DDE_SUCCESS) THEN BEGIN /* $data contains the value of CELL1 in the Excel */ /* spread sheet Sheet1 */ END END

Hot link client example In this example, Microsoft Excel is the DDE server, and the Unify VISION application is the DDE client. The following VISION 4GL statements enable the Unify VISION application to act as a DDE client for Microsoft Excel. BOOL FUNCTION DDEReceiveData(Link_id, Item, Data) BEGIN SET $screen_field TO $Data RETURN TRUE END EXTERN SCRIPT BOOL FUNCTION DDEReceiveData(val, val, val) INSTALL DDE_EVENT HANDLER DDEReceiveData FOR EVENTS RECEIVE_DATA IDENTIFIED BY $reqid SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id)


121

IF ($stat = DDE_SUCCESS) THEN BEGIN SET $stat TO dde_initiate_hot_link$($server_id, 'CELL1', 10000) /* time out after 10 seconds */ IF ($stat = DDE_SUCCESS) THEN BEGIN /* Excel should now send CELL1 to VISION whenever */ /* the value changes. VISION receives the data */ /* through the ReceiveData event handler global /* function. END END

*/ */

Time-out handling example In this example, the Unify VISION application is the DDE client. BOOL FUNCTION DDEReceiveData(Link_id, Item, Data) BEGIN SET $screen_field TO $Data RETURN TRUE END EXTERN SCRIPT BOOL FUNCTION DDEReceiveData(val, val, val) INSTALL DDE_EVENT HANDLER DDEReceiveData FOR EVENTS RECEIVE_DATA IDENTIFIED BY $reqid SET $stat TO dde_initiate_link$('Excel', 'Sheet1', $server_id) IF ($stat = DDE_SUCCESS) THEN BEGIN SET $stat TO dde_request_data$($server_id, 'CELL1', $data, 10000) /* time out after 10 seconds */ WHILE ($stat = DDE_TIMEOUT) BEGIN SET $stat TO DDE_DENYREQ IF (yesno$('Do you want to continue waiting for a DDE response?', 0) ) THEN BEGIN SET $stat TO dde_request_data$($server_id, 'CELL1', $data, 10000) END END END

122


3 Using the preprocessor This chapter describes how to use a C preprocessor with Unify VISION: defining preprocessor variables defining variable values including external files in a script

123

Using a preprocessor Within a script, you can use standard preprocessor statements. These preprocessor statements allow you to define special preprocessor variables to perform conditional code compilation. These variables can also be used to define macros. In addition, the preprocessor allows you to include external operating system files in your VISION 4GL scripts. When a script is compiled it is first processed by a preprocessor. The preprocessor checks the script file for special preprocessor statements and performs the indicated modifications on the script. A preprocessor statement begins with a pound sign (#) in column 1. The # character is followed by a preprocessor keyword that describes the compiler directive. By using preprocessor statements in your script, you can: conditionally compile code define preprocessor variables define preprocessor macros include external files into the script

124


Defining preprocessor variables

You can use the preprocessor statement #define to define variables that the preprocessor recognizes. The two forms of this statement are: #define variable #define variable value The first form defines a preprocessor variable. The second form both defines a preprocessor variable and assigns it a value. By convention, preprocessor variable names are in UPPERCASE letters. Within the script, you can use the following preprocessor statements to test whether this variable is defined: #ifdef variable #ifdef variable ... #endif #else ... #endif Between the #ifdef and the #endif statements you can include either VISION 4GL statements or other preprocessor statements. If you use the

#else statement, include one set of statements (executed if the #ifdef variable is defined) between the #ifdef and the #else statements and the second set (executed if the #ifdef variable is not defined) between the #else and the #endif statements.

Using the #define statement A common use of the #define statement is to define a debugging preprocessor variable and then to surround debugging statements in your script with the #ifdef and #endif statements based on whether this debug variable is defined. Chapter 3: Using the preprocessor

125

In the following example, a SET/SELECT statement verifies that the customer table has a row with the key value entered in customer_number. If the SET/SELECT encounters an error and the preprocessor variable DEBUG is defined, the DISPLAY statement displays the status$( ) error value in a notice box. #define DEBUG #include “sscodes.h” FORM customer_entry PUBLIC status_error FIELD customer_number METHOD ON FIELD INPUT SET customer_entry:cust_id TO SELECT cust_id FROM customer WHERE cust_id = customer_entry:customer_number; IF ( ( SET status_error TO status$() ) = SS_NORM ) THEN BEGIN DISPLAY ’Customer ID already defined. Please try again’ FOR FYI_MESSAGE RESTART ON FIELD END ELSE IF ( status_error SS_NOREC ) THEN BEGIN DISPLAY ’Database Error’ FOR FYI_MESSAGE #ifdef DEBUG DISPLAY ’status= ’ + error FOR FYI_MESSAGE #endif END

To “undefine” the DEBUG variable, you can either surround the #define DEBUG statement with comment symbols or you can use the preprocessor statement #undef DEBUG.

Using the #define variable statement To define a preprocessor variable and assign a value to this variable, you use the second form of the #define statement: #define variable value If the preprocessor variable is already defined, this form of the #define statement assigns a value to the variable. 126


The preprocessor variable can be redefined by another #define statement and you can use previously defined variables within a variable definition. Do not use aVISION 4GL keyword or variable as the name of a preprocessor variable. You can use this form of the #define statement to: create a macro create mnemonic names for program constants

Creating preprocessor macros To create a macro, you assign a string of VISION 4GL statements to a preprocessor variable. Within the VISION 4GL statements, you can use the preprocessor variable name anywhere you want to use the associated string of statements. When your script is processed by the preprocessor, occurrences of the macro name are expanded: the preprocessor variable is replaced with the VISION 4GL statements. You can use a macro only after it has been defined. You can include macro definitions within a file with the #include statement. For example, the following preprocessor statement tests whether the return code of the status$( ) system function is successful: #define

OK_STATUS

status$() =

SS_NORM

You can then use the preprocessor variable OK_STATUS anywhere you need to test the success of an operation, for example: IF ( OK_STATUS ) THEN DISPLAY 'Operation Successful' FOR FYI_MESSAGE WAIT

The macro definition can extend over multiple lines if you place the backslash character (\) at the end of each line of the definition. You can also define parameters for a preprocessor macro. Parameters are useful for inserting VISION 4GL variables into the macro definition when the macro is expanded. Chapter 3: Using the preprocessor

127

Using parameters in a macro definition #define LOCKCHECK(error) \ SWITCH error \ BEGIN \ CASE SS_LMOUT: \ DISPLAY 'Locking Error Encountered' \ FOR FYI_MESSAGE WAIT \ CASE SS_NORM: \ DISPLAY 'Selected Row(s) Available' \ FOR FYI_MESSAGE WAIT \ DEFAULT: \ DISPLAY 'Database Error: ' + \ to_string$(error) \ FOR FYI_MESSAGE WAIT \ END

The following lines are expanded when the LOCKCHECK macro is processed: SET db_stat TO status$() LOCKCHECK(db_stat)

The following lines are generated after expansion of the macro: SET db_stat TO status$() SWITCH db_stat BEGIN CASE SS_LMOUT: DISPLAY 'Locking Error Encountered' FOR FYI_MESSAGE WAIT CASE SS_NORM: DISPLAY 'Selected Row(s) Available' FOR FYI_MESSAGE WAIT DEFAULT: DISPLAY 'Database Error: ' + to_string$(db_stat) FOR FYI_MESSAGE WAIT END

Defining program constants The #define statement is also useful for creating names for program constants. For example, you can use #define to define names for the constant values in a SWITCH statement. The SWITCH statement must have constant values in the CASE clauses. 128


The statements shown in the following example define four shipping codes as preprocessor variables. It then uses the preprocessor variable names within the SWITCH statement instead of the integer shipping code values. These mnemonic preprocessor variables make the code easier to read. #define #define #define #define

UNKNOWN 0 RECEIVED 1 WAITING 2 SHIPPED 3 ... SWITCH ship_code BEGIN CASE RECEIVED: DISPLAY 'Received' FOR ship_status CASE WAITING: DISPLAY 'Waiting' FOR ship_status CASE SHIPPED: DISPLAY 'Shipped' FOR ship_status CASE UNKNOWN: DISPLAY 'Unknown' FOR ship_status END

Chapter 3: Using the preprocessor

129

Including external files You can use the preprocessor statement #include to include operating system files in your script. This statement has the form: #include file_name where file_name is the name of the include file. This file name can be either an absolute file path name or a relative path name. If the path name is relative, it is relative to the directory where you are compiling the script. It is a C language and fourth generation language convention to name all include files by appending a .h suffix. When the script is processed by the preprocessor, the #include statement is expanded: the include file name is replaced by the contents of the include file. These include files can contain either VISION 4GL statements or other preprocessor statements. Example

The following statements use the #include statement to include two external files in the script. The first #include includes the preproc.h file that contains other preprocessor statements that can be used in the script. The second #include includes the externs.h file that contains external function declarations that can be used in the script. #include #include FORM example METHOD ON CREATE #ifdef DEBUG DISPLAY 'Entering ON CREATE section' FOR FYI_MESSAGE WAIT #endif IF NOT ( open_message_file$(MESFILE) ) THEN BEGIN DISPLAY OPENERR FOR FYI_MESSAGE WAIT write_errlog (OPENERR, 'serious') END

The preproc.h file contains: #define DEBUG #define MESFILE '/usr/application/messages' #define OPENERR 'There was an error opening the error file'

130


And the externs.h file contains: EXTERN SCRIPT BOOL FUNCTION is_variable(variable_name) EXTERN SCRIPT NUMERIC FUNCTION get_unique (table_name) EXTERN C NUMERIC FUNCTION write_errlog(msg, status) EXTERN MESSAGE_HANDLER corporate_logo RETURNING STRING EXTERN MESSAGE_HANDLER profit USING (this_year, last_year) RETURNING INTEGER

Related information

Chapter 3: Using the preprocessor

Some Unify VISION system functions require #include statements. For complete information about how to use system functions, see “System functions” beginning on page 423.

131

132


4 Tokens and operators This chapter describes the operators and expressions you can use in VISION 4GL statements: tokens and symbols object operators assignment operators arithmetic operators relational operators logical operators bitwise operators null values undefined values

133

Operators An operator indicates the action to be performed upon an operand. Most operators are special characters, such as the equal sign (=). Other operators are VISION 4GL keywords, such as SET. The following table shows the types of operators you can use in a VISION 4GL script. Each type of operator is described in this manual.

Types of operators used in scripts Category

Operator

Description

Object

:

Member

–>

Dereference

SET

(Binary)Variable and attribute assignment

=>

(Binary/Unary) Clear-to-find expression assignment

+

(Binary/Unary) Binary addition and concatenation; unary plus

–

(Binary/Unary) Binary subtraction; unary minus

*

(Binary) Multiplication

/

(Binary) Division

%

(Binary) Modulus

Assignment operators

Arithmetic operators

(continued on next page)

134


Types of operators used in scripts (continued) Category

Operator

Description

Relational operators

(Binary) Greater than

=

(Binary) Greater than or equal to

=

(Binary) Equality

(Binary) Inequality

LIKE

String pattern-matching or pattern-exclusion operator (_ and % metacharacters)

SHLIKE

String pattern-matching or pattern-exclusion operator (? and * metacharacters)

AND

(Binary) Logical AND

OR

(Binary) Logical OR

NOT

(Unary) Logical negation

&

(Binary) Bitwise AND

|

(Binary) Bitwise inclusive OR

^

(Binary) Bitwise exclusive OR

~

(Unary) Bitwise negation (ones complement)

Null value operators

IS NULL

(Unary) Null value equality

IS NOT NULL

(Unary) Null value inequality

Undefined value operators

IS UNDEFINED (Unary) Undefined value equality

Logical operators

Bitwise operators

Chapter 4: Tokens and operators

IS NOT UNDEFINED

(Unary) Undefined value inequality

135

Operands An operand is an expression. Depending upon the associated operator, an operand may have restrictions on its data type. Operands must be defined and the operand data types must be compatible. Unify VISION performs some automatic type conversion as needed before performing the operations. The resulting type is determined by the data types of the operands and the operation. Most operators are binary and require two operand values: operand1 operator operand2 In SQL statements only one operand of a binary operation can be a Unify VISION variable. A few Unify VISION operators are unary operators. A unary operator requires only a single operand: operator operand1 operand1 operator In SQL statements a Unify VISION variable cannot be used as the operand of a unary operation.

Precedence of operators When several operators appear in a single expression, Unify VISION must determine an order for evaluating them. To determine operator evaluation order, Unify VISION uses precedence and associativity rules. Precedence is the order or priority in which operators are applied to operands. Unify VISION applies operators of higher precedence before those of lower precedence. Associativity is the direction in which Unify VISION evaluates operators at the same precedence level. Associativity is either right to left or left to right. Many operators are at the same level of precedence. To determine when to evaluate operators at the same level of precedence, Unify VISION uses associativity rules. The following chart shows the precedence and associativity rules for all Unify VISION operators. The operators are listed in order of decreasing precedence. 136


Precedence and associativity rules for Unify VISION operators Precedence*

Operator : –> () NOT

~ + (unary) – (unary) * / % + (binary) – (binary) < > = =

Associativity left to right left to right right to left

left to right

left to right left to right

IS NULL IS NOT NULL IS UNDEFINED IS NOT UNDEFINED LIKE SHLIKE

& | ^

left to right

AND OR SET

left to right left to right left to right Not applicable

=>

* Operands grouped between parallel lines have the same precedence.


137

Expressions An expression can be made up of several elements: operators developer-defined Unify VISION variables system variables function return values constants object attributes Expressions can appear in a variety of VISION 4GL statements: logical expressions in conditional statements and clauses arguments of functions operands of operators database values The following list shows examples of Unify VISION expression syntax: ( expr ) expr1 = expr2 expr1 expr2 expr1 + expr2 expr1 – expr2 expr1 * expr2 expr1 / expr2 expr1 % expr2 expr1 & expr2 expr1 | expr2 expr1 ^ expr2 + expr – expr expr1 < expr2 expr1 > expr2 expr1 >= expr2 expr1 => expr expr1 >= expr2 expr1 –> expr2 SET variable TO expr SET variable TO SELECT column FROM table attribute form:attribute [form:][$]variable:attribute field_array[ ] field_array[subscript] field_array[subscript]:attribute field_array[row, column] field_array[row, column]:attribute variable:attribute form:variable:attribute variable [NOT] LIKE ’mask’ ESCAPE ’escape_character’ variable [NOT] SHLIKE ’mask’


139

Tokens and symbols This section describes symbols, delimiters, and metacharacters that can be used in application development.

Form script tokens Special symbols and delimiters are used in statements and expressions to separate or identify the elements of a script: ()

A pair of parentheses enclose function arguments or delimit expressions.

$

In SQL statements a dollar sign ($) must precede all Unify VISION variable names; it is optional in other statements. All Unify VISION system function names are suffixed by a dollar sign ($). The dollar sign distinguishes a Unify VISION system function from developer-defined functions and database column names. Do not use a dollar sign when you define or call your own functions. If a dollar sign is required in the syntax of a database SQL statement, it must be prefixed by a backslash (\$).

&

The & token can be used as a prefix to field names in a field validation rule to specify the value of a field. Preceding this token you can use one of three operators:

Greater than

!

Not equal to

Example

Meaning

) obj_ref_exp –> identifier [ ( [parm[, parm . . . ] ] ) ] obj_ref_exp

An expression that evaluates to an OBJECT_REF data type that identifies the object to be operated on.

identifier

Specifies an attribute, variable, or method defined for the class of object identified by obj_ref_exp.

parm

If identifier refers to a method defined for the class, specifies the name of a parameter to be passed for the method invocation.

In a script, you can use a dereference operator (–>) to reference objects identified by the OBJECT_REF data type. The dereference operator permits the referencing of objects at runtime, whereas the colon operator (:) references objects only at compile time. The dereference operator can be used to reference attributes, variables, and methods of an object. Typical uses for the dereference operator include: to reference an object ID passed into an ON DRAG DROP method. to reference the parent form to reference the parent object to reference variables between subforms to send synchronous messages to Form and Service objects rather than using the SEND MESSAGE statement You can reference the parent of a child by using the PARENT_ID attribute. For objects on a form, the PARENT_ID is the parent form. For a form, the parent is the previous form. The PARENT_ID of the first form in an application is always NULL. The dereference operator can be used to send a synchronous message to a Service or Form object. obj_ref_exp identifies the object to which the Chapter 4: Tokens and operators

143

message is directed. identifier specifies the method to be invoked on the destination object. The return value of the method is returned as the result of the dereference operator. The dereference operator cannot be used in the following cases: RETURN VALUES INTO clause

accessing individual array elements RESULT parameters

Tip

Example

To reference variables between two subforms within the same form, store the subform object IDs in global variables. In the following example, the dereference operator references the value of the text1 field, and the value is stored in the current_value variable. SET text1_id TO text1:OBJECT_ID SET current_value TO text1_id->VALUE

In the next example, the dereference operator references attributes of the created form. COMMAND display_sample BEGIN CREATE FORM 'sample' OF CLASS runtime1 OBJECT_REF INTO $form_id SET $form_id->TX_MODE_FORM_CREATION TO 'COMMIT' SET $form_id->VISIBLE TO TRUE END

In the next example, the to_string$( ) system function is used to test the current transaction mode by displaying the contents of a dereferenced object: DISPLAY 'The transaction mode is ' + to_string$(form_id->TX_MODE_FORM_CREATION) FOR FYI_MESSAGE WAIT

This example invokes the m1 method on the object identified by objid, where m1 is a synchronous message. set $rtnvalue TO objid->m1(p1,p2,p3)

144


Related information

See the following related script statement and system functions: SEND MESSAGE (page 373)

acquire_global_uvns$( ) (page 424) acquire_local_uvns$( ) (page 425) dap_4gl_errcode$( ) (page 450) dap_td_count$( ) (page 451) dap_td_errcode_i$( ) (page 452) dap_ti_errcode$( ) (page 455) status$( ) (page 569) See Unify VISION: Class Reference for information about related classes: UONameService class UONameService::resolve( ) UONameService::bind( ) Service class Form::OBJECT_ID Service::OBJECT_ID


145

Assignment operators An assignment operator assigns a specific value to a variable or attribute. VISION 4GL provides two types of assignment operations: the SET statement the clear-to-find expression

SET statement The VISION 4GL assignment operator is the SET statement. You can use the SET statement to change the values of variables and their attributes: general variables field variables target variables target field variables variable and form attributes system variables The SET statement automatically performs some type conversions if the operands have different data types. You can also use the SET statement to clear the value of a variable. For a complete description and examples of the SET statement, see page 378.

Clear-to-find The clear-to-find expression operator is a pair of characters: => (= followed by > with no space between). You can use this operator to change the value of clear-to-find expressions. Clear-to-find expressions exist only for target field and target variables. They establish search criteria to use during a database search. 146


The clear-to-find expression operator specifies a “less than,” “greater than,” or range of values as search criteria for a target field or target variable. You can use this operator with target field and target variables of any data type except BOOLEAN. Use the SET statement to assign a clear-to-find expression to the field target or target variable’s CLEAR_FIND_EXP target attribute. The following table shows the different forms of the => operator.

Forms of the => operator Clear-to-find expression

Search criteria

expr =>

Values greater than expr

=> expr

Values less than expr

expr1 => expr2

Values in the range from expr1 through expr2. expr1 and expr2 must be the same data types.

Variables containing null values can be used with the => operator. However, if the clear-to-find expression evaluates to a null value, the database search will not find any matching database rows. Variables containing UNDEFINED values are illegal operands for the clear-to-find expression operator. Invalid operands result in a runtime error. For examples of clear-to-find expressions, see the description for the SET statement.


147

Arithmetic operators Arithmetic operators are not defined for BOOLEAN operands.

Addition expr1 + expr2 The + operator is the addition operation for variables with the data types NUMERIC, FLOAT, AMOUNT, DATE and TIME. The following table shows the data types that are compatible with the + operator. Operations on other combinations of data types are invalid. Results of addition First operand

Second operand

Result

AMOUNT

NUMERIC FLOAT AMOUNT

AMOUNT AMOUNT AMOUNT

DATE

NUMERIC

DATE

DATETIME

NUMERIC

DATETIME 1

FLOAT

NUMERIC FLOAT AMOUNT

FLOAT FLOAT AMOUNT

NUMERIC

NUMERIC FLOAT AMOUNT DATE 2 DATETIME TIME 2

NUMERIC FLOAT AMOUNT DATE DATETIME 1 TIME

TIME

NUMERIC

TIME

1 If a NUMERIC value is added to a datetime value, the NUMERIC value is treated as the number of days to add to the date portion. 2 If a NUMERIC value is added to a TIME value, the NUMERIC value is treated as number of minutes. If a NUMERIC value is added to a DATE value, the NUMERIC value is treated as number of days. 148


Concatenation expr1 + expr2 The plus sign (+) is the concatenation operator for STRING, TEXT, and BINARY values. When you concatenate two strings, you join them with no spaces between them. Concatenation can be performed on STRING, TEXT, and BINARY values only. A concatenation with a null operand always results in a null value. Concatenating an operand with a zero-length operand returns the original value.

Results of concatenation First operand

Second operand

Result

BINARY

BINARY

BINARY

STRING

STRING TEXT

STRING TEXT

TEXT

STRING TEXT

TEXT TEXT

Subtraction expr1 – expr2 The – operator is the subtraction operation for variables with the data types NUMERIC, FLOAT, AMOUNT, DATE and TIME. This operator is not valid for variables of the STRING, TEXT, BINARY, or BOOLEAN data types. The following table shows the results of the subtraction operation between data types. Operations on other combinations of data types are invalid.


149

Results of subtraction operation First operand

Second operand

Result

AMOUNT

AMOUNT FLOAT NUMERIC


DATE

DATE NUMERIC

NUMERIC DATE

DATETIME

DATETIME NUMERIC DATE

NUMERIC 1 DATETIME 2 NUMERIC 3

FLOAT


AMOUNT FLOAT FLOAT

NUMERIC



TIME

NUMERIC TIME

TIME NUMERIC

1 If a DATETIME value is subtracted from a DATETIME value, the difference in number of days is the result. 2 If a NUMERIC value is subtracted from a datetime value, the NUMERIC value is treated as number of days and subtracted from the date portion of the DATETIME value. 3 If a DATE value is subtracted from a DATETIME value, the difference in number of days is the result. A NUMERIC result is produced by the subtraction of two NUMERIC values. Any subtraction involving an AMOUNT value produces an AMOUNT result. Subtraction involving a FLOAT value produces a FLOAT result unless one of the operands is an AMOUNT value (result is then an AMOUNT). Subtraction performed on two DATE values produces a NUMERIC result. This result is the number of days between the two dates. Similarly, subtracting two TIME values produces a NUMERIC result that is the number of minutes between the times. If a NUMERIC value is subtracted from a TIME value, the NUMERIC value is treated as number of minutes and the result is a TIME value. If a 150


NUMERIC value is subtracted from a DATE value, the NUMERIC value is treated as number of days and the result is DATE value.

Multiplication and division expr1 * expr2 expr1 / expr2 The * operator is the multiplication operation for variables with the data types NUMERIC, FLOAT, and AMOUNT. The / operator is the division operation for variables with the data types NUMERIC, FLOAT, and AMOUNT. Neither of these operators is defined for the BOOLEAN, DATE, TIME, TEXT, BINARY, or STRING data types. The following table shows data types that are compatible with the * and / operators. Operations on other data types are incompatible.

Results of multiplication and division operations First operand

Second operand

Result

AMOUNT



FLOAT


AMOUNT FLOAT FLOAT

NUMERIC



A NUMERIC result is produced only by the multiplication of two NUMERIC values. Any multiplication involving an AMOUNT value produces an AMOUNT result. Multiplication involving a FLOAT value produces a FLOAT result, unless one of the operands is an AMOUNT value (result is then an AMOUNT). Division by zero produces a runtime error. Make sure that the second operand of the / operator never evaluates to zero. Chapter 4: Tokens and operators

151

Modulus expr1 % expr2 The % operator is the modulus operation for the NUMERIC data type. This operator is not defined for any other data types. The modulus operator performs remainder division as in the C programming language. That is, the result of an expression with the modulus operator is the remainder after dividing expr1 by expr2. Division by zero produces a runtime error. Make sure that the second operand of the % operator never evaluates to zero. The following table shows the result of the % operator. Other data types are incompatible with the modulus operation. Result of the modulus operator First operand

Second operand

Result

NUMERIC

NUMERIC

NUMERIC

Unary positive and negative + expr – expr The unary + operator indicates a positive value for a NUMERIC, FLOAT, or AMOUNT operand. The unary – operator indicates a negative value for a NUMERIC, FLOAT, or AMOUNT operand. All unsigned values are assumed to be positive. Neither of these operators is defined for any other data types. The following table shows the data types that are compatible with the unary + and – operators. Unary operations on other data types are invalid. Results of unary operations

152

Operand

Result

AMOUNT

AMOUNT

FLOAT

FLOAT

NUMERIC

NUMERIC Unify VISION: 4GL Reference

Relational operators VISION 4GL provides six binary relational operators:

=

equal

not equal

>

greater than

>=

greater than or equal to

expr2 expr1 >= expr2 expr1 < expr2 expr1 operator is the relational “greater than” operation. The >= operator is the relational “greater than or equal to” operator. The ) sign or a “less than” sign ( 2), or SQL_REAL column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert ODBC SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, SQL_SMALLINT, SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC, SQL_NUMERIC(X,1), SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert ODBC SQL_NUMERIC(X,2), SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, or SQL_SMALLINT column type to FLOAT. ORACLE The PRIVATE clause can be used to override the default data type conversion for a target variable that obtains data from a date-time column. The DATE keyword specifies that the target variable data type is to be DATE. The TIME keyword specifies that the target variable data type is to be TIME. By default, ORACLE DATE column types are converted to the DATE data type. The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert ORACLE LONG, CHAR, or VARCHAR2 column types to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert ORACLE CHAR or VARCHAR2 column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert ORACLE FLOAT or NUMBER(X,Y) (where Y is not 0 or 2) column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert ORACLE FLOAT, NUMBER(X,Y) (where Y is not 2), DECIMAL, INTEGER, or SMALLINT column type to AMOUNT. Chapter 5: Script statements

327

The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert ORACLE NUMBER(X,2), NUMBER(X,0), DECIMAL, INTEGER, or SMALLINT column type to FLOAT. SYBASE SQL Server The PRIVATE clause can be used to override the default data type conversion for a target variable that obtains data from a date-time column. The DATE keyword specifies that the target variable data type is to be DATE. The TIME keyword specifies that the target variable data type is to be TIME. By default, SYBASE SQL Server datetime column types are converted to the DATE data type. The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert SYBASE SQL Server datetime column types to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert SYBASE SQL Server char(n), varchar(n), nchar(n), nvarchar(n) column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert SYBASE SQL Server money, smallmoney, float, real, decimal(X,Y), or numeric(X,Y) (where Y > 0) column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert SYBASE SQL Server float, real, decimal(X,Y), numeric(X,Y) (where Y > 0), int, tinyint, smallint, decimal(X,0), or numeric(X,0) column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be NUMERIC; in a FLOAT header, the FLOAT data type can be used to convert SYBASE SQL Server money, smallmoney, int, tinyint, smallint, decimal(X,0), or numeric(X,0) column type to FLOAT. Data type conversions are not allowed in stored procedures. Unify DataServer The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert Unify DataServer TEXT column types to STRING. 328


The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert Unify DataServer STRING column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert Unify DataServer AMOUNT, HUGE AMOUNT, or FLOAT column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert Unify DataServer FLOAT, NUMERIC(9), SMALLINT, or INTEGER column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert Unify DataServer AMOUNT, HUGE AMOUNT, NUMERIC(9), SMALLINT, or INTEGER column type to FLOAT.

Example

The following clause declares a one-dimensional array with a subscript range of seven elements from 0 to 6. PRIVATE LIST days_of_the_week[0 TO 6]

The next clause declares a two-dimensional array with an upper bound of three for both rows and columns. PRIVATE MATRIX tic_tac_toe[1 TO 3,1 TO 3]

The next example declares a two-dimensional array called songs that has an estimated number of rows and columns. This declaration is useful for dynamic SQL when you do not know how many columns are to be selected from a table during runtime: PRIVATE MATRIX songs[1 TO UNKNOWN ESTIMATING 40, 0 to UNKNOWN ESTIMATING 51]

The next example declares a two-dimensional array called company_records having nine columns in each row. When records are selected, approximately 100 records are expected. PRIVATE company_records[1 TO UNKNOWN ESTIMATING 100,1 TO NUM_COLUMNS] . . . METHOD ON CREATE SET NUM_COLUMNS TO 9

This example declares multiple target variables and specifies their data types. FORM orders PRIVATE order_date DATE, ship_date TIME, index

Chapter 5: Script statements

329

The following example converts a database date-time column to a STRING field and uses the field in various database statements. The dttm_tbl database table contains a date-time column named dttm_field. An integer column i is also used. FORM sample /* Define the target date–time column as a string field */ PUBLIC dttm_field STRING; FIELD dummy METHOD AFTER FIELD /* Initialize temporary variables */ SET dttm_value TO ’12/3/1992 10:10:11.996AM’; SET ndttm_value TO ’12/3/1992 10:10:12.996AM’; SET dttm_field TO ’something’ /* Insert data into database */ INSERT INTO dttm_tbl VALUES ( 110, $dttm_value ); SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110 EXECUTING BEGIN DISPLAY $dttm_field FOR FYI_MESSAGE WAIT; END /* Update the datetime value in the database */ UPDATE dttm_tbl SET dttm_field = $ndttm_value WHERE dttm_field = $dttm_value; /* Determine whether column has been updated */ SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE dttm_field = $ndttm_value EXECUTING BEGIN DISPLAY $dttm_field FOR FYI_MESSAGE WAIT; END /* Delete the inserted row from the database */ DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

SYBASE SQL

The following example script converts a database date-time column to a Unify VISION Server STRING field and uses the field in various database statements. The SYBASE SQL Server dttm_tbl database table contains a datetime column named dttm_field. An integer column i is also used. FORM sample /* Define the target datetime column as a string field */ PRIVATE dttm_field STRING;

330


FIELD dummy METHOD AFTER FIELD /* Initialize temporary variables */ SET dttm_value TO ’12/3/1992 10:10:11.996AM’; SET ndttm_value TO ’12/3/1992 10:10:12.996AM’; SET dttm_field TO ’something’ /* Insert dat into database */ INSERT INTO dttm_tbl VALUES ( 110, $dttm_value ); SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110 EXECUTING BEGIN DISPLAY $dttm_field FOR FYI_MESSAGE WAIT; END /* Update the datetime value in the database */ UPDATE dttm_tbl SET dttm_field = $ndttm_value WHERE dttm_field = $dttm_value; /* Determine whether column has been updated */ SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE dttm_field = $ndttm_value EXECUTING BEGIN DISPLAY $dttm_field FOR FYI_MESSAGE WAIT; END /* Delete the inserted row from the database */ DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

See also

Script language EVENT (page 270) PUBLIC (page 333)


331

Related See Unify VISION: Class Reference for information about the following attributes: information COLUMN_BOUNDED COLUMN_LOWER_BOUNDS COLUMN_UPPER_BOUNDS DIMENSION LIST_INDEX

LIST_LOWER_BOUNDS LIST_UPPER_BOUNDS ROW_BOUNDED ROW_LOWER_BOUNDS ROW_UPPER_BOUNDS

For information about LIST, and MATRIX see “Identifiers” in Unify VISION: Application Reference.

332


PUBLIC Declarations

Syntax

DBMS dependent

PUBLIC variable_description [ [, variable_description] . . . ]

variable_description For a scalar variable, variable_description has the following syntax: [ AMBIGUOUS ] variable_name [data_type] For a one-dimensional array variable_description has the following syntax: [ AMBIGUOUS ] LIST array

[ [ROWS] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ] } ] For a business event, variable_description has the following syntax: EVENT event_name ( [parmlist] )

For a two-dimensional array, variable_description has the following syntax: [ AMBIGUOUS ] MATRIX array [ [ ROWS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]}, [ COLUMNS ] num_expr TO { num_expr | UNKNOWN [ ESTIMATING num_expr ]}] Shaded portions of the syntax are DBMS dependent.

Support

Support for date_type is DBMS dependent. INFORMIX

The data_type options of the PUBLIC declaration are supported for INFORMIX with the enhancements described on page 335.

ORACLE

The data_type options of the PUBLIC declaration are supported for ORACLE with the enhancements described on page 338.

SYBASE SQL

The data_type options of the PUBLIC declaration are supported for SYBASE SQL Server with the enhancements described on page 338.

Server

Unify DataServer

The DATE and TIME data_type options of the PUBLIC declaration are not supported for Unify DataServer. See also page 339. Chapter 5: Script statements

333

Arguments

variable_name An identifier for the variable. The variable name can have up to 44 characters. These characters include both uppercase and lowercase letters (a-z, A-Z), numeric characters (0-9), and the underscore character (_). The first character of the variable name must be a letter. A dollar sign ($) prefix is optional. Because system variables are suffixed by a dollar sign, the variable name must not be terminated by the dollar sign ($) character. data_type

For a target table column, specifies the Unify VISION data type: AMOUNT BINARY BOOL DATE DATETIME FLOAT

INTEGER NUMERIC OBJECT_REF STRING TEXT TIME

In the PUBLIC section of a script, data_type specifies the data type to which the variable is to be converted. Data type conversion compatibility is DBMS dependent, as described under “Description.”

Description

array

The name of a one-dimensional (LIST) or two-dimensional (MATRIX) array.

num_expr

A numeric expression for delimiting the lower or upper bounds of an array.

parmlist

See EVENT.

The PUBLIC statement is an optional statement for any class definition. The PUBLIC statement declares public local variables. A PUBLIC variable that has the same name as a target table column is treated as a target variable regardless of the class in which it is defined. Public local variables for a class are created when an object of that class is created. The local variables are created before the constructor for the class, ON CREATE, is invoked. Public local variables are destroyed when the object containing the variables is destroyed. The local variables are destroyed after the destructor for the class, ON DESTROY, is invoked.

334


Public local variables for a global function are created when that function is invoked. The variables are destroyed when the function returns. The variables are accessible by name from any method or local function of the class or any derived class. Public local variables are also accessible by name from any other object. Access to a variable can be achieved through the use of the object_name:variable_name syntax, or through the use of the dereference operator and the object ID for the object, through normal parameter passing, or through resolution at runtime of AMBIGUOUS variables. The AMBIGUOUS clause specifies a variable to be ambiguous. Array declarations You can specify the lower and upper subscript bounds for each dimension of an array. The bounds of the array must be enclosed by brackets—[ ]. LIST indicates a one-dimensional array. MATRIX indicates a two-dimensional array. The bounds of an array can be specified by any expression that is equivalent to an integer. To optimize memory usage, you can use a variable to dynamically declare the bounds when a form is activated. The lower bounds of an array can be any positive or negative integer, up to the maximum allowed by your operating system for long integers. By default, the lower bound is 1. For an unbounded array, use the keyword UNKNOWN to indicate that the upper limit of a row is unknown or unlimited. You can specify an estimated upper bound by using the phrase UNKNOWN ESTIMATING numeric expression. By default, if the estimating clause is omitted, the estimated upper bound is 100. To verify whether an array has an upper bound, use the ROW_BOUNDED and COLUMN_BOUNDED attributes. To determine the type of an array, use the DIMENSION attribute. INFORMIX

The PUBLIC clause can be used to override the default data type conversion for a target variable that obtains data from a date-time column. The DATE keyword specifies that the target variable data type is to be DATE. The TIME keyword specifies that the target variable data type is to be TIME. By default, INFORMIX DATE column types are converted to the DATE data type; in a FORM header, the STRING data type can be used to convert an INFORMIX DATE column type to STRING. By default, INFORMIX DATETIME YEAR TO DAY column types are converted to the DATE data type, DATETIME HOUR TO MINUTE column types are converted to the TIME data type, and other DATETIME column types are converted to the STRING data type Chapter 5: Script statements

335

The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert an INFORMIX TEXT column type to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert INFORMIX CHARACTER(n) or VARCHAR column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert INFORMIX FLOAT, DOUBLE PRECISION[(n)], SMALL FLOAT, DEC[IMAL][(m,[n])], NUMERIC[(m,[n])], or MONEY[(m,[n])] column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert INFORMIX FLOAT, DOUBLE PRECISION[(n)], SMALL FLOAT, DEC[IMAL][(m,[n])], NUMERIC[(m,[n])], INT[EGER], or SMALLINT column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert INFORMIX INT[EGER], SMALLINT, or MONEY[(m,[n])] column type to FLOAT. By default, INFORMIX DATETIME YEAR TO DAY column types are converted to the DATE data type, DATETIME HOUR TO MINUTE column types are converted to the TIME data type, and other DATETIME column types are converted to the STRING data type. INGRES

The PUBLIC clause cannot be used to override the default data type conversion for a target variable that obtains data from a date-time column. INGRES date-time column types are converted to the STRING data type. The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert an INGRES text or varchar(n) column type to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert INGRES char(n) or c column type to TEXT. 336


The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert INGRES float4, real, float, float8, double precision, or money column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert INGRES integer, integer4, smallint, integer2, integer1, float4, real, float, float8, or double precision column type to NUMERIC. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert INGRES integer, integer4, smallint, integer2, integer1, or money column type to FLOAT. At runtime, the target variable types that are defined in the PUBLIC clause must match the data types defined in VISION Designer. You cannot specify the data type option in a PUBLIC clause that is in a global or local function, or for a nontarget variable. ODBC The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert ODBC SQL_LONGVARCHAR column type to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert ODBC SQL_CHAR or SQL_VARCHAR column type to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert ODBC SQL_NUMERIC(X,2), SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC, SQL_NUMERIC(X,1), SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert ODBC SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, SQL_SMALLINT, SQL_FLOAT, SQL_DOUBLE, SQL_NUMERIC, SQL_NUMERIC(X,1), SQL_NUMERIC(X,Y) (where Y > 2), or SQL_REAL column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert ODBC SQL_NUMERIC(X,2), SQL_INTEGER, SQL_NUMERIC(X,0), SQL_TINYINT, or SQL_SMALLINT column type to FLOAT. Chapter 5: Script statements

337

ORACLE The PUBLIC clause can be used to override the default data type conversion for a target variable that obtains data from a date-time column. The DATE keyword specifies that the target variable data type is to be DATE. The TIME keyword specifies that the target variable data type is to be TIME. By default, ORACLE DATE column types are converted to the DATE data type. The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert ORACLE LONG, CHAR, or VARCHAR2 column types to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert ORACLE CHAR or VARCHAR2 column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert ORACLE FLOAT or NUMBER(X,Y) (where Y is not 0 or 2) column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert ORACLE FLOAT, NUMBER(X,Y) (where Y is not 2), DECIMAL, INTEGER, or SMALLINT column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert ORACLE NUMBER(X,2), NUMBER(X,0), DECIMAL, INTEGER, or SMALLINT column type to FLOAT. SYBASE SQL Server The PUBLIC clause can be used to override the default data type conversion for a target variable that obtains data from a date-time column. The DATE keyword specifies that the target variable data type is to be DATE. The TIME keyword specifies that the target variable data type is to be TIME. By default, SYBASE SQL Server datetime column types are converted to the DATE data type. The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert SYBASE SQL Server datetime column types to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert SYBASE SQL Server char(n), varchar(n), nchar(n), nvarchar(n) column types to TEXT. 338


The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert SYBASE SQL Server money, smallmoney, float, real, decimal(X,Y), or numeric(X,Y) (where Y > 0) column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert SYBASE SQL Server float, real, decimal(X,Y), numeric(X,Y) (where Y > 0), int, tinyint, smallint, decimal(X,0), or numeric(X,0) column type to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be NUMERIC; in a FLOAT header, the FLOAT data type can be used to convert SYBASE SQL Server money, smallmoney, int, tinyint, smallint, decimal(X,0), or numeric(X,0) column type to FLOAT. Unify DataServer The STRING keyword specifies that the target variable data type is to be STRING; in a FORM header, the STRING data type can be used to convert Unify DataServer TEXT column types to STRING. The TEXT keyword specifies that the target variable data type is to be TEXT; in a FORM header, the TEXT data type can be used to convert Unify DataServer STRING column types to TEXT. The NUMERIC keyword specifies that the target variable data type is to be NUMERIC; in a FORM header, the NUMERIC data type can be used to convert Unify DataServer AMOUNT, HUGE AMOUNT, or FLOAT column type to NUMERIC. The AMOUNT keyword specifies that the target variable data type is to be AMOUNT; in a FORM header, the AMOUNT data type can be used to convert Unify DataServer FLOAT, NUMERIC(9), SMALLINT, or INTEGER column types to AMOUNT. The FLOAT keyword specifies that the target variable data type is to be FLOAT; in a FORM header, the FLOAT data type can be used to convert Unify DataServer AMOUNT, HUGE AMOUNT, NUMERIC(9), SMALLINT, or INTEGER column types to FLOAT.

Example

The following clause declares a one-dimensional array with a subscript range of seven elements from 0 to 6. PUBLIC LIST days_of_the_week[0 TO 6]


339

The next clause declares a two-dimensional array with an upper bound of three for both rows and columns. PUBLIC MATRIX tic_tac_toe[1 TO 3,1 TO 3]

The next example declares a two-dimensional array called songs that has an estimated number of rows and columns. This declaration is useful for dynamic SQL when you do not know how many columns are to be selected from a table during runtime: PUBLIC MATRIX songs[1 TO UNKNOWN ESTIMATING 40, 0 to UNKNOWN ESTIMATING 51]

The next example declares a two-dimensional array called company_records having nine columns in each row. When records are selected, approximately 100 records are expected. PUBLIC company_records[1 TO UNKNOWN ESTIMATING 100,1 TO NUM_COLUMNS] . . . METHOD ON CREATE SET NUM_COLUMNS TO 9

This example declares multiple target variables and specifies their data types. FORM orders PUBLIC order_date DATE, ship_date TIME, index

The following example converts a database date-time column to a STRING field and uses the field in various database statements. The dttm_tbl database table contains a date-time column named dttm_field. An integer column i is also used. FORM sample /* Define the target date–time column as a string field */ PUBLIC dttm_field STRING; FIELD dummy METHOD AFTER FIELD /* Initialize temporary variables */ SET dttm_value TO ’12/3/1992 10:10:11.996AM’; SET ndttm_value TO ’12/3/1992 10:10:12.996AM’; SET dttm_field TO ’something’ /* Insert data into database */ INSERT INTO dttm_tbl VALUES ( 110, $dttm_value ); SET dttm_field TO SELECT dttm_field FROM dttm_tbl WHERE i = 110 EXECUTING BEGIN DISPLAY $dttm_field FOR FYI_MESSAGE WAIT; END

340


/* Update the datetime value in the database */ UPDATE dttm_tbl SET dttm_field = $ndttm_value WHERE dttm_field = $dttm_value; /* Determine whether column has been updated */ SET sale_id TO SELECT dttm_field FROM dttm_tbl WHERE dttm_field = $ndttm_value EXECUTING BEGIN DISPLAY $sale_id FOR FYI_MESSAGE WAIT; END /* Delete the inserted row from the database */ DELETE dttm_tbl WHERE dttm_field = $ndttm_value;

See also

Script language EVENT (page 270) PRIVATE (page 323) RAISE EVENT (page 346)

For information about LIST and MATRIX see “Identifiers” in Unify VISION: Related information Application Reference.


341

QUEUE COMMAND Script statement: queued command execution

Syntax

QUEUE COMMAND { command_name | defined_command }

Arguments

command_name The keyword for a VISION Runtime Manager command. The following table lists valid keywords and their equivalent VISION Runtime Manager commands.

342

command_name

Equivalent VISION Runtime Manager command

ADD_UPDATE ARRANGE CANCEL_FORM CASCADE CHOOSE _FORM CLEAR_TO_ADD CLEAR_TO_FIND DELETE DISMISS_FORM EXIT FIND FIRST_RECORD LAST_RECORD NEXT_FIELD NEXT_FORM NEXT_PAGE NEXT_RECORD NEXT_SET NEXT_TAB PREVIOUS_FIELD PREVIOUS_PAGE PREVIOUS_RECORD PREVIOUS_SET PREVIOUS_TAB RECALL_ERROR_MESSAGE RETURN_VALUES TILE ZOOM

uv_add_update uv_arrange uv_cancel_form uv_cascade none uv_clear_to_add uv_clear_to_find uv_delete uv_dismiss_form uv_exit uv_find uv_first_record uv_last_record uv_next_field uv_next_form uv_next_page

uv_next_record uv_next_set uv_next_tab uv_previous_field uv_previous_page

uv_previous_record uv_previous_set uv_previous_tab uv_recall_error_message uv_return_values uv_tile uv_zoom Unify VISION: 4GL Reference

defined_command The name of a developer-defined user command. This command must be defined in the COMMAND method.

Description

The QUEUE COMMAND statement places a request to execute the specified command in the pending command queue. The queued command will be executed when Unify VISION is about to retrieve user input. Queued commands are executed in the current context. In most cases, the current context is the form associated with the script where this statement appears. If a QUEUE COMMAND cannot be executed because the command cannot be found on the current form, no error is given and all of the remaining queued commands are lost.

Restrictions This statement can be executed within any method, or from a local or global function. At least one field on the form must have the FOCUSABLE attribute set to TRUE. Otherwise, the next form operation is automatically executed instead of the command specified in the QUEUE COMMAND statement. This statement cannot be used in a global function that is used by a service object.

Example

This statement executes a developer-defined command named mycommand. QUEUE COMMAND mycommand

This statement executes the VISION Runtime Manager uv_zoom command. QUEUE COMMAND ZOOM

See also

Script language CLEAR COMMAND QUEUE (page 196)


343

System functions last_command$( ) (page 523) last_command_name$( ) (page 525)

See Unify VISION: Class Reference for information about related classes and methods: Related information Methods BEFORE RECORD ON EXIT Classes COMMAND

344


RAISE Script statement: raise specified object to front

Syntax

RAISE object_ref

Arguments

object_ref

Description

The RAISE statement displays the specified object in front of any other overlapping objects. If the specified object is a primary form, it is raised to the top of the stacking order of windows on the screen.

A variable that specifies an object reference.

Restrictions The RAISE statement can be used in all VISION 4GL methods.

Example

This example displays the form identified by fcompany_form_instance. RAISE $fcompany_form_instance


345

RAISE EVENT Script statement: publish business event

Syntax

RAISE EVENT event_name [ USING (expression[[, expression] . . . ) ]

Arguments

event_name

Specifies the name of the business event to be raised.

expression

Specifies the parameters to be passed to each business event handler installed by objects subscribing to the event.

Description

The RAISE EVENT statement performs a publish or raise operation on the event identified by event_name. event_name must be an EVENT declared in the PUBLIC section of the class in which the RAISE EVENT statement occurs. When an event is raised, an asynchronous message is sent to each subscribing object, thereby notifying those objects of the occurrence of the event. Objects can subscribe to an event by installing a business event handler with the INSTALL statement.

The EVENT definition can optionally specify parameters to be sent when the event is raised. Since the messages sent to the subscribers are one way, the mode of each of the parameters can only be specified as VALUE. The number of parameters as well as their respective data types specified in expression must match the parameters specified in the event definition. Use the status$( ) system function to determine the success of a RAISE EVENT statement. In failure cases, use the dap_ti_errcode$( ), dap_td_errcode_i$( ), dap_td_errcnt$( ), and dap_4gl_errcode$( ) system functions to determine the exact cause of the failure. An unsuccessful attempt to deliver a message to a subscribing object is treated as nonfatal and is ignored. The application raising the event will not be notified of any such errors. 346


Restrictions The RAISE EVENT statement can be used in all VISION 4GL methods.

See also Script language DEINSTALL (page 230) EVENT (page 270) INSTALL (page 303) PUBLIC (page 333)

System functions dap_4gl_errcode$( ) (page 450) dap_td_count$( ) (page 451) dap_td_errcode_i$( ) (page 452) dap_ti_errcode$( ) (page 455) status$( ) (page 569)

See Unify VISION: Class Reference for information about related classes: Related information Form Service


347

REFRESH CURRENT Script statement: refresh field values

Syntax

REFRESH CURRENT { RECORD | SET }

Description

The REFRESH CURRENT RECORD statement retrieves the values of the current record from the associated database table row. The REFRESH CURRENT SET statement retrieves the values of all records in the current selected set from the associated database table rows. If an associated table row has been deleted from the target table, the affected record is deleted from the selected set and the statements refresh the record values regardless of consistency mode and the current values of the fields. The fields are updated to reflect the current values in the database. Additionally, any WHEN FIELD CHANGES methods are executed for every field in the record because they are all re-retrieved from the database. When a form uses the no consistency mode for retrieving records, no locks of any type are requested when the selected set is displayed. Therefore, during the time that the user views the records in the selected set, another form within the application, user, or process can modify the values in the associated target table rows. You can use the REFRESH CURRENT statement to modify the values displayed to match those currently stored in the database. The REFRESH CURRENT statement is valid only in add/update/delete mode and for forms that have a target table. It is not valid in find mode or for forms that have no target table. If REFRESH CURRENT is used with a form under set consistency, it has no effect. If the REFRESH CURRENT RECORD statement is used with a form under record consistency, it has no effect. The REFRESH CURRENT SET statement can be used to refresh records for a form under record consistency. You can use the status$( ) system function to test the success of the REFRESH CURRENT statement. A successful refresh operation returns a value of 0 (SS_NORM). Failure of this statement returns one of these possible values: 5 –12 –45 –60 –121

348

SS_NOCUR SS_NOTUP SS_LMOUT SS_NORID SS_RMOD Unify VISION: 4GL Reference

If the current record is deleted, another record in the selected set becomes current and a next record operation is executed. If the selected set contains only one record, when that record is deleted, a clear-to-add operation is executed and any statements remaining in the current method are not executed. If the current record has no unique identifier in the database row, all column values must be used to identify the associated row. If the value of any column in the associated row has been changed, the row cannot be identified; therefore, the current record will be deleted, and status$( ) will return a value of SS_NOTUP.

Restrictions This statement is invalid in the following methods: AFTER FIND BEFORE FIND FUNCTION (global only) ON FIND ON CREATE

Example

This example uses a global function named ChangeState( ) to update a table. Because the function updates columns other than the column passed in, a form that calls this function must refresh the current record. /* * Updates the State for a given customer. Also changes the * Region, based on the state. Any form calling this function * should refresh its data. * * Requires function RegionFromState(). */ EXTERN SCRIPT STRING FUNCTION RegionFromState(TheState); NUMERIC FUNCTION ChangeState( CustomerID, NewState ) /* LOCAL definitions */ PRIVATE NewRegion; BEGIN SET NewRegion TO RegionFromState($NewState); UPDATE customers set Region = $NewRegion, State = $NewState where CustomerID = $CustomerID; RETURN(status$()); END; /* ChangeState() */


349

If the State field on the Customers form has been changed, the script calls the ChangeState( ) function to update other column values in the target table. Because the update operation can change the values of the associated table row, the current record must be refreshed. #include ”sscodes.h” EXTERN SCRIPT NUMERIC FUNCTION ChangeState(CustID, NewState); FORM CLASS Customers METHOD AFTER UPDATE IF $StateHasChanged THEN BEGIN SET $tResult TO ChangeState($CustomerID, $State); IF $tResult SS_NORM THEN DISPLAY NOTICE ’Error ’ + to_string$($tResult) + ’ updating the Customers State/Region information.\n’ + ’Try again later or contact the DBA!’ LABELS ’Bummer!’ DEFAULT RESULT INTO $tDummy; ELSE REFRESH CURRENT RECORD;/* ChangeState() may have changed it */ END

See also

System functions status$( ) (page 569)

For information about record consistency and locking, see “Managing transactions and Related information locks” in Unify VISION: Developing an Application.

350


REFRESH DISPLAY Script statement: refresh video display Reviewer:

CR 75089: New REFRESH DISPLAY statement. 01/03/2000. alc.

Syntax

REFRESH DISPLAY

Description

The REFRESH DISPLAY statement causes the screen to be immediately redrawn. Use this statement to refresh the screen during execution of long sections of VISION 4GL statements that would otherwise prevent the screen from being redrawn until execution finished. Using this statement in a loop can impact performance.

Restrictions This statement can be executed in any method or from a local or global function. However, REFRESH DISPLAY is not valid in service object or in a function called by a service object.

See also

“Writing scripts” (page 19) and “Script functions” (page 73).


351

REJECT OPERATION Script statement: reject user command

Syntax

REJECT OPERATION

Description

The REJECT OPERATION statement prevents the user from performing a specific user operation. The table on the next page shows the methods that can include the REJECT OPERATION statement. For each method, the table also lists the user operation that is rejected. VISION Runtime Manager continues executing any remaining statements in the method after the REJECT OPERATION statement completes. In addition, any AFTER method (AFTER ADD, AFTER DELETE, AFTER FIND, AFTER UPDATE) that corresponds to a BEFORE method is also executed.

For example, if REJECT OPERATION is in the BEFORE ADD method, VISION Runtime Manager executes all statements in BEFORE ADD and all statements in the AFTER ADD statement as well. If REJECT OPERATION is in the BEFORE FIND method, VISION Runtime Manager executes all statements in BEFORE FIND and AFTER FIND but does not execute the ON FIND method. If an AFTER method is not to be executed when a REJECT OPERATION is used in the BEFORE method, you can use a BOOL “reject flag” and test this “reject flag” in the AFTER method. If the reject flag is TRUE, the REJECT OPERATION occurred and the AFTER statements are not executed. Otherwise, the AFTER statements are executed.

352


Method

Rejected operation

BEFORE FIND

uv_find

BEFORE ADD

uv_add_update

BEFORE UPDATE

uv_add_update

BEFORE DELETE

uv_delete

ON CANCEL FORM

uv_cancel_form

ON CLEAR TO FIND

uv_clear_to_find

ON DISMISS FORM

uv_dismiss_form

ON EXIT

uv_exit

ON NEXT FORM

uv_next_form

ON NEXT RECORD

uv_last_record uv_next_record uv_next_set

ON PREVIOUS RECORD

uv_first_record uv_previous_record uv_previous_set

ON RETURN VALUES

uv_return_values

ON ZOOM

uv_zoom

Restrictions The REJECT OPERATION statement is valid only in the following methods: BEFORE ADD BEFORE DELETE BEFORE FIND BEFORE UPDATE ON CANCEL FORM ON CLEAR TO FIND ON DISMISS FORM


ON EXIT ON NEXT FORM ON NEXT RECORD ON PREVIOUS RECORD ON RETURN VALUES ON ZOOM

353

Example

This script sample prevents anyone with a user name other than “Alexander” from executing an add operation. If the user named “Alexander” adds a new row, the AFTER ADD method displays a status message. If some other user tries to add a row, the status message is not displayed even though the AFTER ADD method is executed. METHOD BEFORE ADD SET $valid_add TO TRUE IF ( user_name$() ’Alexander’ ) THEN BEGIN REJECT OPERATION SET $valid_add TO FALSE END METHOD AFTER ADD IF $valid_add THEN DISPLAY ’New row added to the Database’ FOR FYI_MESSAGE WAIT

See Unify VISION: Class Reference for information about related methods: Related information Methods BEFORE ADD BEFORE DELETE BEFORE FIND BEFORE UPDATE ON CANCEL FORM ON CLEAR TO FIND ON DISMISS FORM ON EXIT ON NEXT FORM ON NEXT RECORD ON PREVIOUS RECORD ON ZOOM

354


REJECT RECORD Script statement: record selection

Syntax

REJECT RECORD

Description

The REJECT RECORD statement discards a target table row found during an interactive find operation. Within the ON FIND method, you can process each target table row as it is selected. You can use the REJECT RECORD statement to prevent a record from being added to the selected set. The rejected row does not have a selected set record created and cannot be viewed by the user. If the selected row is not rejected, VISION Runtime Manager creates a selected set record for the row. Under set consistency, all rows in the selected set are read-locked; the row that corresponds to the rejected record is not unlocked.

Restrictions This statement is valid only in an ON FIND method.

Example

This script sample uses the REJECT RECORD statement to prevent the database row for “Smithers” from being added to the selected set. Because it is not in the selected set, this row cannot be selected, viewed, or updated. METHOD ON FIND IF ( emp_last_name = ’Smithers’ ) THEN REJECT RECORD

Related See for information about related methods: information Unify VISION: Class Reference Methods AFTER FIND BEFORE FIND ON FIND


355

REPEAT Script statement: execute statement list

Syntax

REPEAT statement_list UNTIL logical_expression

Arguments

statement_list One or more VISION 4GL statements. If there is more than one statement, do not begin and end the statements with the keywords BEGIN and END. logical_expression Any Unify VISION BOOL expression. The expression is evaluated at the end of each loop iteration. The statement_list is executed until this expression becomes TRUE.

Description

The REPEAT statement executes statement_list until logical_expression is TRUE. VISION Runtime Manager executes statement_list as long as the logical_expression is FALSE. To execute the REPEAT statement, VISION Runtime Manager first executes statement_list. Next, it evaluates logical_expression to determine whether to re-execute statement_list. This expression determines the number of times that the statement body is executed. If logical_expression evaluates to TRUE, the REPEAT loop exits. If logical_expression evaluates to FALSE, statement_list is re-executed. If logical_expression contains a null value, it evaluates to FALSE. If logical_expression contains a variable, this variable must have an initial value assigned before the UNTIL clause of the REPEAT statement so that the logical_expression can be evaluated the first time. VISION Runtime Manager continues the process of executing the statement_list and testing the logical_expression until logical_expression is TRUE. When the logical_expression is TRUE, the REPEAT loop ends.

356


Because VISION Runtime Manager evaluates the logical expression in a REPEAT statement after each execution of the statement body, the REPEAT statement is always executed at least once.

Restrictions The REPEAT statement can be used in all VISION 4GL methods.

Example

This REPEAT statement displays the value 100 in the current form field, then the values 99, 98, and so on until the value 50 is displayed; the loop is then exited. SET index TO 100 REPEAT DISPLAY index SET index TO index – 1 UNTIL index < 50

See also

Script language BREAK (page 184) CONTINUE (page 204)


FOR (page 285) WHILE (page 413)

357

RESIZE Script statement: resize unbounded array

Syntax

RESIZE { LIST array TO num_expr [ ROWS ] | MATRIX array TO num_expr { ROWS | COLUMNS } [, num_expr { ROWS | COLUMNS } }

Arguments

array

The array name as declared in a PUBLIC or PRIVATE declaration.

num_expr

A numeric expression for the number of elements in the array.

Description

The RESIZE statement changes the size of an unbounded dimension of an array to the new size specified by num_expr. New elements are initialized with a value of UNDEFINED. Use this statement to reset the upper bounds of an array to the actual number of elements in the array. Bounded dimensions and the lower bound of an array cannot be resized.

Restrictions This statement is valid in all VISION 4GL methods.

Example

In this example, two arrays supply values to a list box. The RESIZE statement removes all rows from both the food and labels arrays. PRIVATE LIST food [1 TO UNKNOWN], LIST box_labels [1 TO UNKNOWN] SET food[1] TO ’baked potato’ SET food[2] TO ’fries’ SET box_labels[1] TO ’low fat’ SET box_labels[2] TO ’high fat’ set_scrolling_list$(alistbox, box_labels, food) RESIZE LIST food TO 0 ROWS RESIZE LIST box_labels TO 0 ROWS

See also

358

PUBLIC (page 333)


RESTART ON FIELD Script statement: re-execute user input on field

Syntax

RESTART [ ON ] FIELD

Description

The RESTART ON FIELD statement causes VISION Runtime Manager to begin execution of the ON FIELD method again. RESTART ON FIELD lets the user enter input again by restarting the ON FIELD method. When VISION Runtime Manager encounters a RESTART ON FIELD statement, it discontinues execution of the current ON FIELD method. VISION Runtime Manager then returns to the beginning of the ON FIELD method and begins execution. Any statements in the current method that follow the RESTART ON FIELD statement are not executed after the RESTART ON FIELD statement is executed. You can test information entered by the user in the ON FIELD method. You use the INPUT statement to stop for user input. If the input is not correct, you can require that the user reenter it by including the RESTART ON FIELD statement in ON FIELD. You can use the DISPLAY statement to display an appropriate error message explaining why the input must be reentered.

Restrictions The RESTART ON FIELD statement is valid only in an ON FIELD or an ON DATA ACCEPT method.

Example

This script sample receives input from the field sc_name_field. After the user enters a value, the input value is passed to a user function, namechk( ). FIELD sc_name_field METHOD ON FIELD INPUT IF (NOT namechk($sc_name_field)) THEN BEGIN DISPLAY ’Letters, blanks, apostrophes, hyphens only’ FOR FYI_MESSAGE WAIT RESTART ON FIELD END


359

If namechk( ) returns FALSE, the input is not valid. An error message is then displayed in the fyi_message system information field, and RESTART ON FIELD restarts the ON FIELD method.

See also

Script language INPUT (page 299)

See Unify VISION: Class Reference for information about related methods and Related information attributes: Methods ON FIELD

Attributes EDIT_ACTION

360


RETRIEVE Script statement: read external file

Syntax

RETRIEVE [ TEXT | BINARY ] variable_name FROM FILE string_expression

Arguments

variable_name The name of the variable that is to contain the data retrieved from string_expression. string_expression The directory search path and file name of the data file that the data is to be retrieved from. The expression can be either a string constant or string variable.

Reviewer:

CR 53363: RETRIEVE should return status and not error when file doesn’t exist. 01/03/2000. alc.

Description

The RETRIEVE statement reads the contents of BINARY or TEXT files. If the file does not exist or cannot be opened or read, the variable value is set to UNDEFINED. Use the status$( ) system function to verify the results of the RETRIEVE statement: If the file does not exist, the status is SS_NOFIL. If the file cannot be opened, the status is SS_FLACS. An error results in these cases: The argument used as the string_expression is not a STRING expression. The variable is not a general, TEXT, or BINARY variable. The result is undefined or null. Windows Each carriage return/line-feed sequence is changed to a line-feed character.


361

Restrictions The RETRIEVE statement can be used in all VISION 4GL methods.

Example

This example retrieves a memorandum contained in the memo file and places it into a local text variable named $memo. RETRIEVE TEXT $memo FROM FILE ’memo’

See also

362

Script language STORE (page 393)


RETURN Script statement: terminate execution of a function

Syntax

RETURN [ ( return_value ) ]

Arguments

return_value

The value to return to the calling function. This value can be an expression, a variable or a constant. The value must have the same data type as the function’s return value, defined in the function’s FUNCTION statement. For a SCRIPT_ERROR function, specify TRUE to suppress the error window. Specify FALSE to permit display of the standard error window. If the RETURN bool clause is omitted, the default value is TRUE.

Description

The RETURN statement terminates execution of a VISION 4GL function. When VISION Runtime Manager reaches the RETURN statement, it evaluates any result parameters and exits from the function. You can use this statement anywhere within a VISION 4GL function. You can include more than one RETURN statement in a single function. For functions that do not return values, the use of the RETURN statement in the function body is optional. If control passes to the end of the function body without encountering a RETURN statement, VISION Runtime Manager performs the RETURN statement automatically and does not return a value. For functions that do return values, you must use this statement to return the value. To return values, include the return value within parentheses after the RETURN keyword. If control passes to the end of the function body without encountering a RETURN statement, VISION Runtime Manager returns an undefined value. Make sure that the data type of the value being returned matches the function’s return value defined in the FUNCTION statement.


363

Restrictions The RETURN statement is valid only in a FUNCTION method.

Example

This script sample defines a local function called get_netpay( ). This local function uses the RETURN statement to return the AMOUNT value of net_salary. LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes) PRIVATE the_taxrate, net_pay BEGIN SET the_taxrate TO SELECT tax_rate FROM rates WHERE lower_sal = $gross_salary SET taxes TO (gross_salary * the_taxrate) SET net_salary TO gross_salary – taxes RETURN (net_salary) END

See also

364

Script language FUNCTION (page 289)


REVOKE SQL DDL statement

Syntax

DBMS dependent

[ USING [ CONNECTION ] connection ] REVOKE SQL_clause ; Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax required by the DBMS.

Arguments

connection

The keyword DEFAULT or a string expression that specifies the name of a database connection, for example: USING CONNECTION DEFAULT

or USING CONNECTION ’emps’

The keyword DEFAULT specifies the default connection that was specified for the application. A string expression must match one of the entries in the database connection map (DCM) file. SQL_clause

Any of the keywords or statements permitted by the DBMS within a REVOKE command.

Description

When VISION Runtime Manager encounters the REVOKE statement, it prepares the statement for processing by the database. Because this statement is executed by the DBMS, it must conform to the syntax requirements of the DBMS; extensions provided by the DBMS can also be included. The optional USING clause specifies the name of a database connection for this statement only. The optional keyword CONNECTION can be used to enhance readability of the clause. If no connection is specified, the connection of the current form is used. Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.


365

Restrictions The REVOKE statement can be used in all VISION 4GL methods.

Example

This REVOKE statement drops SELECT privileges on the emp_salary column of the emp_table from all PUBLIC users. REVOKE SELECT (emp_salary) ON TABLE emp_table FROM PUBLIC;

See also

Script language GRANT (page 295)

Related For complete syntax information, see the documentation provided by the DBMS information vendor. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.

366


ROLLBACK WORK Script statement: abort current transaction

Syntax

[ USING [ CONNECTION ] connection ] ROLLBACK WORK [ DEMOTING LOCKS ]

Support

Support for this feature is DBMS dependent.

DBMS dependent

The DEMOTING LOCKS clause is supported for Unify DataServer only; it has no effect on any other DBMS. ODBC

The ROLLBACK WORK statement has no effect.

ORACLE

Supported.

SYBASE SQL

Supported.

Server Unify DataServer

Supported. The optional DEMOTING LOCKS clause retains all records of the selected set but demotes exclusive locks to shared locks, regardless of the form consistency level.

Arguments

connection



The keyword DEFAULT specifies the default connection that was specified for the application. A string expression must match one of the entries in the database connection map (DCM) file. Chapter 5: Script statements

367

Description

The ROLLBACK WORK statement causes the database to abort the current transaction and begin a new one. The DBMS handles backing out all uncommitted database operations, interactive and non-interactive, in the current transaction. The optional USING clause specifies the name of a database connection for this statement only. The optional keyword CONNECTION can be used to enhance readability of the clause. If no connection is specified, the connection of the current form is used. Transaction rollback is possible only if the database has transaction logging and logging is enabled. When the current transaction is aborted, the following events occur: All current locks are released. All uncommitted update, delete, and insert operations are undone. The user does not see any changes on the screen when ROLLBACK WORK is executed. The current form is still displayed along with any data on the form. If the aborted transaction contains a selected set, all records in the selected set no longer have locks, even if the records still display on the form. If the form uses the Browse feature, the current selected set may have been only a subset of all matching records. In this case, the full selected set is lost when the transaction aborts. The user cannot use uv_next_set or uv_next_record to see additional subsets of the selected set. To regain the locked selected set, use NEXT ACTION IS CLEAR_TO_FIND to clear the form. If necessary you can recreate the selected set with NEXT ACTION IS FIND. After the transaction is aborted, VISION Runtime Manager continues to execute any VISION 4GL statements that follow the ROLLBACK WORK statement within the method.

Restrictions The ROLLBACK WORK statement is invalid in the ON FIND method and the EXECUTING clause. 368


Example

This example attempts an INSERT after the user inputs the form field doinsert. If the database insert fails, the transaction is aborted and execution returns to the previous form. FIELD doinsert METHOD AFTER FIELD INSERT INTO stock (st_number, st_description, st_unit_price) VALUES ($snum, $sdesc, $price); IF (status$() SS_NORM) THEN BEGIN ROLLBACK WORK NEXT ACTION IS DISMISS_FORM END

See also

Script language BEGIN WORK (page 181) COMMIT WORK (page 201) UNLOCK (page 398)

System functions tx_mode$( ) (page 612)

Related For information about transaction control, see “Managing transactions and locks” in information Unify VISION: Developing an Application. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.


369

SELECT SQL DML statement

Syntax

DBMS dependent

[ SET_statement ] [ USING [ CONNECTION ] connection ] SELECT SQL_clause { EXECUTING_clause |;}

Shaded portions of the syntax are DBMS dependent.

Support

This statement must conform to the syntax specified by the DBMS.

Arguments

SET_statement A VISION 4GL SET statement.

connection



The keyword DEFAULT specifies the default connection that was specified for the application. A string expression must match one of the entries in the database connection map (DCM) file. SQL_clause

The clauses permitted by the DBMS within a SELECT command.

EXECUTING_clause A VISION 4GL EXECUTING clause.

Description

The SELECT statement initiates a non-interactive find operation. Unify VISION variables can be used in the selection list but must be prefixed by a dollar sign ($) and used as part of an expression.

370


The set of rows to be selected is determined by a WHERE clause. As the DBMS searches the tables, the logical_expression for each row is evaluated and the value is returned. If the logical_expression evaluates to TRUE for a row, SELECT selects the row. If the logical_expression evaluates to FALSE or to a null value, the row is not selected. If no WHERE clause is specified, the first row in the table is selected. To select all table rows, you must include an EXECUTING clause with SELECT. If the SELECT statement includes a locking clause, locks are requested for all selected rows. Use the Unify VISION status$( ) system function to test the success of a SELECT statement. The optional USING clause specifies the name of a database connection for this statement only. The optional keyword CONNECTION can be used to enhance readability of the clause. If no connection is specified, the connection of the current form is used. If an EXECUTING clause is not included, the SELECT statement must be terminated by a semicolon (;).

INFORMIX A WHERE clause cannot include a column having the TEXT or BYTE data type.

ORACLE A WHERE clause cannot include a column having the LONG or LONG RAW data type.

Restrictions The SELECT statement can be used in all VISION 4GL methods. The ROLLBACK WORK statement is invalid within the EXECUTING clause unless ROLLBACK WORK DEMOTING LOCKS is specified. Chapter 5: Script statements

371

Example

This SELECT statement selects the first row in the employee table. The emp_last_name value is then assigned to the Unify VISION variable one_name. SET one_name TO SELECT employee.emp_last_name FROM employee WHERE emp_no = $emp_no;

See also

Script language EXECUTING (page 277) SET (page 378)

Related For information about multiple database connections, see “Getting started” in Unify information VISION: Developing an Application. See Unify VISION: Application Reference for information about this related external preference: DBFETCHCOUNT

See Unify VISION: Class Reference for information about this related attribute: FIND_COUNT

372


SEND MESSAGE Script statement: message handler execution

Syntax

SEND [ ONEWAY ] [ ASYNC[HRONOUS] ] MESSAGE method_name TO obj_ref_exp [ USING (expression [, expression . . . ] ) ] [ IDENTIFIED BY message_handle ] [ RETURNING return_variable ]

Arguments

method_name The name of the method to be invoked on the object specified by obj_ref_exp. To use a variable so that the method name can be determined at runtime, use the format $method_name, for example, $method_idx. Otherwise, method_name is interpreted as a literal. obj_ref_exp

An expression that evaluates to an OBJECT_REF data type that identifies the object to which the message is directed.

expression

Specifies the actual parameters to be passed to the specified method.

message_handle If the IDENTIFIED BY clause is specified, message_handle receives the value of the message handle associated with the message request. The message handle can later be used for checking the status of the message and for performing a WAIT FOR operation on a message request. return_variable Receives the return value of the method invocation, if any. If obj_ref_exp is an ActiveX object, return_variable can be an array.

Description

The SEND MESSAGE statement sends a message to an object to invoke the specified method on the specified object. Any object of a class derived from the service or form foundation classes can receive messages. obj_ref_exp must be a reference to an object of one of these classes. The object can be located within the same partition as the object sending the message or within a different partition on the same or different systems connected via a network. The object can be replicated or non-replicated.


373

The method to be invoked is identified by method_name. The method must be defined as a developer-defined method in the declaration for the class. The USING clause specifies a comma-separated list of parameters to be passed to the method. The number of parameters as well as their types must match the corresponding method declaration in the class script where the message is declared. The RETURNING clause specifies a variable for receiving the value returned by the method invocation. If the RETURNING clause is specified, the type of method_name cannot be VOID. The ONEWAY clause specifies that the message is to be sent without an acknowledgement message. One-way messages cannot return any result parameters or a method result. The ASYNCHRONOUS clause specifies that the message is to be sent asynchronously. When asynchronous messaging is specified, the SEND MESSAGE operation returns immediately upon sending the message. The sending partition does not wait for the invocation of the method to be completed. The IDENTIFIED BY clause specifies a variable for receiving the value of the message handle associated with a message request. The message handle can subsequently be used for checking the status of the message and for waiting for the completion of the message using the WAIT FOR statement. The message handle continues to refer to this specific message request until the variable is either destroyed or the variable is reused in a subsequent SEND MESSAGE statement. If the ASYNCHRONOUS clause is specified, the assignment of result parameters and the method return value is not performed until a WAIT FOR statement is executed using the associated message handle. If the ASYNCHRONOUS clause is specified and the method to be invoked has RESULT parameters or a non-VOID method return value, the IDENTIFIED BY clause must also be specified. If the ASYNCHRONOUS clause is specified and obj_ref_exp refers to an object that is implemented within the same partition as the object sending the message, the invocation of the method on the destination object can occur before the successful completion of the WAIT FOR statement on the associated message handle. A partition should not rely on occurrence before the WAIT FOR statement is executed. If a partition requires notification of the completion of an asynchronous method invocation, the application must perform a WAIT FOR operation that specifies the message handle returned by the SEND MESSAGE. 374


Use the message handle specified in the IDENTIFIED clause to check the status of the message. The message handle contains attributes that are used specifically for error processing. This is the preferred method for error processing. If the IDENTIFIED clause was not specified, use the status$( ) system function to determine the success of a SEND MESSAGE statement. In failure cases, use the dap_ti_errcode$( ), dap_td_errcode_i$( ), dap_td_errcnt$( ), and dap_4gl_errcode$( ) system functions to determine the exact cause of a failure. If obj_ref_exp refers to a replication group and the initial attempt to deliver a message to a member of the group is unsuccessful, Unify VISION automatically attempts to deliver the message to another member of the group. The SEND MESSAGE statement can fail in these cases only if an attempt to deliver the message to every member of the group has failed. In many cases, parameters are used as out only by the method. If these parameters are of type LIST or MATRIX, before executing SEND MESSAGE the sender of the message should resize the parameter to 0 rows and 0 columns. This can greatly reduce the amount of data being sent in a message, thus increasing performance and reducing network traffic. Messages can be sent using two different mechanisms: by using Unify Object Broker or by using direct, local messaging. Direct local messaging is used when the object reference specified for the destination of the message request is a local object reference. When a nonlocal object reference is specified, Unify Object Broker is used to deliver the message. Nonlocal object references are obtained from service objects, system management objects, any object reference obtained from a UONameService object, or any object reference being passed in as a parameter from another partition. When a local object reference is specified and either the ONEWAY or ASYNCHRONOUS clause is used, Unify Object Broker is used to deliver the message.

Restrictions SEND MESSAGE is invalid in the following VISION 4GL methods: ON DRAG ENTER ON DRAG LEAVE ON DRAG START

If one or more parameters of a method are declared with the REFERENCE clause, obj_ref_exp must be a local object reference (obj_ref_exp:TRANSPORT must be LOCAL). Local object references are valid for objects of the form class only. Chapter 5: Script statements

375

Example

In this example, the SEND MESSAGE statement notifies the subform that the user has modified the account order (ORDACCKEY) field. The value parameter in the USING clause corresponds to the parameter of the METHOD NewKey in the $SubformBillTo subform. FIELD ORDACCKEY METHOD BEFORE FIELD SET $SaveKey TO $ORDACCKEY; METHOD AFTER FIELD if $SaveKey $ORDACCKEY THEN SEND MESSAGE NewKey TO $SubformBillTo USING ($ORDACCKEY);

In this example, the application locates the service object named invoice_srv using the resolve method provided by the global name service. It then sends a message to invoice_srv specifying the execution of the method invoice_fax on invoice_srv . SET $nmsrv_objref TO acquire_global_uvns$(); SEND MESSAGE resolve TO $nmsrv_objref USING (’invoice_srv’, $inv_objref); SEND MESSAGE invoice_fax to $inv_objref USING ($invoice_id);

See also

Script language WAIT FOR (page 411)

System functions acquire_global_uvns$( ) (page 424) acquire_local_uvns$( ) (page 425) dap_4gl_errcode$( ) (page 450) dap_td_count$( ) (page 451) dap_td_errcode_i$( ) (page 452) dap_ti_errcode$( ) (page 455) status$( ) (page 569)

Related For information about building and managing a partitioned application, see Unify information VISION: Developing an Application. See Unify VISION: Class Reference for information about related classes and methods: Form::OBJECT_ID GENERAL_DATA::TRANSPORT MSG_HANDLE Service Service::OBJECT_ID Service::TRANSPORT UONameService UONameService::bind( ) UONameService::resolve( )

376


SEND SUPER Script statement: invoke a method

Syntax

SEND SUPER [ USING ( expression [ , expression . . . ] ) ] [ RETURNING variable ]

Arguments

expression

Specifies a parameter to be passed to the method invocation.

variable

Receives the value of the method result, if any.

Description

The SEND SUPER statement invokes an inherited method. When a derived class is defined, the derived class can override one or more methods defined in the base class. When an overridden method is invoked, the behavior defined for that method in the base class is not automatically invoked. The inherited behavior is invoked only by the execution of a SEND SUPER statement in the overridden method. If the method declaration contains a parameter list, the parameters are automatically passed to the method in the base class. The optional USING clause overrides the default parameters. If the method that is being invoked is a non-VOID method, the RETURNING clause can be used to receive the result of the method invocation.

Restrictions The SEND SUPER statement is invalid in the following VISION 4GL methods: ON CREATE ON DESTROY

See also

Script language METHOD (page 310)


377

SET Script statement: assign variable or attribute value

Syntax

DBMS dependent

SET

{ |

{ variable | attribute } TO expression {variable_list | list_var | matrix_var } TO { SELECT_statement | row_valued_function_call | EXEC_SQL_statement } [ EXECUTING_clause ] }

[;]

Support

The row_valued_function_call argument is valid only for a stored procedure where the FUNCTION type is specified as ROW_VALUED.

Arguments

variable

Any valid Unify VISION variable, including an array element. The variable is set to the value of the expression. The expression and the variable must be type compatible. variable can be an array if expression dereferences an ActiveX object method that returns an array or an attribute of an ActiveX object that is an array.

variable_list

One or more Unify VISION variable names separated by commas. Each variable is assigned the value of the corresponding column in the SELECT_statement, row_valued_function_call, or EXEC_SQL statement clause. If fewer variables are specified than the number of SELECT list elements, a runtime error occurs. If you specify more variables than the number of SELECT list elements, the unused variables are set to UNDEFINED. (INFORMIX only/SYBASE SQL Server only) When setting target variables, field variables, and target field variables to values returned by a ROW_VALUED stored procedure call, the data type of each variable must be compatible with the data type of the corresponding database column. For general variables, the variables take the types of the values returned by the stored procedure call.

list_var

378

A one-dimensional array (type LIST) to store the output from the SELECT statement. Only the first row of any selected rows is retained. Each element in the LIST is set to its corresponding select list element. If the number of select list elements is greater than the Unify VISION: 4GL Reference

maximum size of the array, the status$( ) system function returns SS_NUMCOLS. If the array is unbounded, the SELECT expression is always successful, unless there is not enough memory. If the SET statement runs out of memory while the first row is selected, all of the array elements are set to undefined before status$( ) system function returns SS_NOMEM. matrix_var

A two-dimensional array to store the output from the SELECT statement. An EXECUTING clause is prohibited in the EXECUTE_SQL statement for matrix variables. The number of columns in the array corresponds to the number of select list elements in the SQL statement. The number of rows corresponds to the number of rows selected. Each row in the array corresponds to a selected row. Size errors can occur when the bounds of the matrix are too small. If the number of columns returned by the SELECT declaration is larger than the COLUMNS specified in the LOCAL statement, no records are returned and the status$( ) system function returns SS_NUMCOLS. If the number of rows returned by the SELECT declaration is larger than the ROWS specified in the LOCAL declaration, records are returned only up to the limits declared; records that exceed the limit are not included and status$( ) system function returns SS_NUMROWS. If the matrix includes more columns than the number of select expressions, the unused columns are set to UNDEFINED. Size errors can occur when the matrix is unbounded. If insufficient memory is available to contain the selected rows, the array is resized to [0,0] and status$( ) system function is set to SS_NOMEM.

attribute

Any Unify VISION attribute (for example, form attribute, field attribute, or command attribute) that is settable in a script. When the SET statement is executed to set a command attribute, the command must be defined in the current form. If the command is not defined in the current form, a runtime error is displayed.


379

connection



The keyword DEFAULT specifies the default connection that was specified for the application. A string expression must match one of the entries in the database connection map (DCM) file. If you are using an SQL handle, do not specify a connection. expression

Any valid Unify VISION expression. The SET statement assigns expression to the variable or attribute. expression can be an array if variable dereferences an ActiveX object method that returns an array or an attribute of an ActiveX object that is an array.

SELECT_statement

Any valid SQL SELECT statement. The SELECT statement can include locking clauses and an EXECUTING block. row_valued_function_call (SYBASE SQL Server only) The name of a ROW_VALUED stored procedure, in the following format: [USING [ CONNECTION ] connection ] function_name([parameter_list]) The function_name must be the name of a stored procedure that is declared as ROW_VALUED. The parameter_list is one or more input parameters, separated by commas, that are passed to the stored procedure. If a default value for an input parameter has been specified in the stored procedure definition, you can indicate that you want to use the default value by replacing the parameter name with the keyword UNDEFINED: function_name(UNDEFINED) 380


EXEC_SQL_statement

Any valid EXECUTE_SQL statement that executes a SELECT statement. EXECUTING_clause A VISION 4GL EXECUTING clause.

Description

The SET statement is the VISION 4GL assignment statement. This statement can set variables of all Unify VISION data types. It can also set the Unify VISION variable and form attributes. If variable is a field variable, the displayed value changes when the variable’s value changes. If variable is a target variable, the new target column value is not added to the database until the current record is added or updated. If variable is a general variable, the variable’s data type is determined when you assign the first value to the variable. To change the data type of a general variable, you must first set the variable to UNDEFINED and then assign the value of the new data type. You cannot assign the NULL constant to an undefined general variable. If the SELECT statement finds no matching database rows, the value of variable is set to UNDEFINED. You cannot change the data type of a field, target, or target field variable. The SET statement is not only a statement; it is also an expression. Unlike most VISION 4GL statements, the SET statement has a value. The value of the SET expression is the value of variable or attribute. You can use the SET statement wherever a Unify VISION expression is valid.

Warning

Because the SET statement is also an expression, make sure that the placement of SET within your statements is unambiguous. Do not use the SET statement after a statement that ends with an optional expression unless you terminate the previous statement with a semicolon (;). In most statements, the use of a semicolon (;) is optional. However, it is required in this case to distinguish the statements. If the previous statement is not terminated, the SET statement is interpreted as an expression belonging to the previous statement.


381

The SET statement cannot be used within a database SQL statement. ActiveX objects variable can be set to an array for an ActiveX object method that returns an array or an attribute of an ActiveX object that is an array where the return results are of type LIST or MATRIX. The variable destination array is resized to 0 or 0,0. The return values in the ActiveX array are assigned to the destination array starting at the lower bounds of each array. The destination array type must match the type returned by the method. If the destination array is bounded and the return value array is larger than the bounds, status$( ) returns SS_NUMCOLS or SS_NUMROWS. If the destination array is unbounded, the assignment is successful, provided that sufficient memory is available. If memory is insufficient, the destination array is resized to 0 or 0,0, and status$( ) returns SS_NOMEM. If a MATRIX destination array includes more columns that the number of columns in the returned array, the unused columns are set to UNDEFINED. If the number of columns in the destination array is less than the number of columns in the returned array, status$( ) returns SS_NUMCOLS. INFORMIX SYBASE SQL Server A ROW_VALUED stored procedure can contain one or more SELECT statements.

Restrictions This statement can be used in all VISION 4GL methods.

Example

The following paragraphs show examples of some of the ways you can use the SET statement to set variables, attributes, expressions, and so on. Selecting variable values This SET statement selects the first row in the employee table. The emp_last_name value is then assigned to the Unify VISION variable one_name.

382


SET one_name TO SELECT employee.emp_last_name FROM employee

The next example shows how to display the current form field’s value and then select the first name from employee where last_name is “Smith” and assign it to var1. You must end the DISPLAY statement with the statement terminator. DISPLAY; SET var1 TO SELECT emp_first_name FROM employee WHERE emp_last_name = ’Smith’

Setting variable attributes The next SET example sets the UPDATEABLE field attribute of the field variable screen_field to FALSE. Setting the UPDATEABLE field attribute to FALSE means that the user cannot edit the field’s value. SET screen_field:UPDATEABLE TO FALSE

The next SET statement assigns the value TRUE to the BOOL variable valid_add. SET valid_add TO TRUE

The next SET statement assigns the value 0 to the three variables, var1, var2, and var3. SET var1 TO SET var2 TO SET var3 TO 0

Setting clear-to-find expressions To set the initial search criteria for the NUMERIC target field variable inumber (on the form inventory) to inventory numbers in the range 100 to 500 (inclusive): SET inventory:inumber:CLEAR_FIND_EXP TO 100 => 500

To set the initial search criteria for the AMOUNT target field variable price (on the form inventory) to all prices greater than $25,525.50: SET inventory:price:CLEAR_FIND_EXP TO 25,525.50 =>

To set the initial search criteria for the NUMERIC target field variable count (on the form inventory) to inventory items with counts less than ten (10): Chapter 5: Script statements

383

SET inventory:count:CLEAR_FIND_EXP TO => 10

To set the initial search criteria for the NUMERIC target field variable location (on the form inventory) to the location code of the current warehouse: SET inventory:location:CLEAR_FIND_EXP TO $warehouse

To negate search criteria, use the NOT metacharacter in the first position, for example: SET inventory:location:CLEAR_FIND_EXP TO ’!warehouse’

In any position other than the first, this character always represents a literal. To search for a literal character in the first position, override the NOT metacharacter by enclosing it with brackets: [!]. The NOT metacharacter is valid only in an equality test; in a range of values, the NOT metacharacter and brackets are treated as literal values. The NOT metacharacter is defined by the NOT_METACH external preference. Setting clear-to-add expressions The following examples show a variety of ways to set clear-to-add expressions. To set the initial value for the NUMERIC target field variable order_time (on the inventory form) to 4 weeks: SET inventory:order_time:CLEAR_ADD_EXP TO 4

To set the initial value for the NUMERIC target field variable location (on the inventory form) to the location code to indicate the current warehouse: SET inventory:location:CLEAR_ADD_EXP TO $warehouse

Setting variables with system functions The next SET statement assigns the null value to the NUMERIC variable total. Because assigning the NULL constant to an undefined general variable is not valid, this SET statement converts the NULL constant to a NUMERIC null value with the to_num$( ) type-conversion function. SET total TO to_num$(NULL)

384


Setting array values This example sets the initial value of a field array cell: SET array2[5]:CLEAR_ADD_EXP TO $base + 5

FOR (SET $index TO 1; $index 5000 ;


421

See also

Script language COMMIT WORK (page 201) EXECUTING (page 277) INSERT (page 301) SELECT (page 370) SLOCK (page 389) UNLOCK (page 398)

System functions status$( ) (page 569)

For information about transaction locking, see “Managing transactions and locks” in Related information Unify VISION: Developing an Application. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application. See Unify VISION: Class Reference for information about the following related method: Methods ON CHOOSE NEXT FORM

422


6 System functions This chapter provides complete descriptions of all VISION 4GL and system functions. The descriptions appear in alphabetical order. Each description includes several parts:

Syntax

Presents the syntax for the system function. BOLDFACE words are keywords. Shaded areas indicate features that are restricted to a particular user interface, operating system, or DBMS. Italicized words within the syntax are described under Arguments.

Support

Describes restrictions or dependencies, if any.

Arguments

Describes the italicized arguments shown in the syntax. Only system functions have arguments.

Return values Describes the values returned by the system function. Description

Describes usage and any special conditions and notes.

Example

Gives a sample that shows how the function or variable might be used.

See also

Lists other subjects in this manual that are related to the function or variable.

Related information Lists subjects in other manuals that provide additional information related to this function or variable. 423

acquire_global_uvns$( ) System function: return global name service reference

Syntax

acquire_global_uvns$( [ transport:hostname:port_ID ] )

Arguments

transport

Identifies the network transport type. Specify T for TCP/IP.

hostname

Identifies the name of the host machine that the name service resides on.

port_ID

Identifies either the exact port number that the service is listening on, or a name entry in /etc/services on hostname that specifies the port number for the service.

Return values

(OBJECT_REF)

Description

The system function acquire_global_uvns$( ) provides a mechanism for constructing an object reference to a global name service. The object reference can then be used for communicating with the name service for performing operations such as locating and registering objects on the network.

The object reference of the global name service object.

transport:hostname:port_ID specifies the location of the name service to which you want an object reference. If no location is specified or is specified as an empty string, acquire_global_uvns$( ) returns an object reference to the default global name service for that partition.

See also

Script language

System functions

CREATE SERVICE (page 217) SEND MESSAGE (page 373)

acquire_local_uvns$( ) (page 425)

See Unify VISION: Class Reference for information about related classes and methods: Related information UONameService class UONameService::resolve( ) UONameService::bind( ) UOPartitionGroup class

424


acquire_local_uvns$( ) System function:return local reference

Syntax

[ #include “uvns_xfc.h” ] acquire_local_uvns$( )

Return values

(OBJECT_REF)

Description

The acquire_local_uvns$( ) system function returns an object reference for the local name service object.

See also

Script language

The object reference of the local name service object.

SEND MESSAGE (page 373)

System functions acquire_global_uvns$( ) (page 424)

See Unify VISION: Class Reference for information about related classes and methods: Related information UONameService class UONameService::resolve( ) UONameService::bind( )

Chapter 6: System functions

425

acquire_uohost$( ) System function: identify host service

Syntax

acquire_uohost$( [ transport:hostname:port_ID ] )

Arguments

transport

Identifies the network transport type. Specify T for TCP/IP.

hostname

Identifies the name of the host machine that the name service resides on.

port_ID

Identifies either the exact port number that the service is listening on, or a name entry in /etc/services on hostname that specifies the port number for the service.

Return values

(OBJECT_REF)

Description

The system function acquire_uohost$( ) returns an object reference that identifies the host service running on a particular host in the network.

The object reference of the UOHost object.

This object reference can then be used for communication with that host service for performing operations such as starting and stopping partitions and partition groups on that host. transport:hostname:port_ID specifies the location of the host service to which you want an object reference. If no location is specified or is specified as an empty string, acquire_uohost$( ) returns an object reference to the default host name service for that partition.

See Unify VISION: Class Reference for information about related classes: Related information UOHost class

426


aud_mode$( ) System function: determine current form mode

Syntax

aud_mode$( )

Return values

(BOOLEAN)

Description

TRUE

The current form mode is add/update/delete mode.

FALSE

The current form mode is find mode.

The aud_mode$( ) system function determines whether the current form mode is add/update/delete mode. Use this function in an ON NEXT FORM or ON DISMISS FORM section to determine the current mode of operation from which the user executed the uv_next_form command or uv_dismiss_form. This function is also useful in the COMMAND section when a function key has an action defined in both form modes. The aud_mode$( ) function can be used to separate the definition for the add/update/delete mode action from the definition for the find mode action.

Example

In this example, the search range for the account numbers is set to 100 only if the current form mode is find mode. If VISION Runtime Manager located records and was in add/update/delete mode, the application moves to the next form. METHOD ON NEXT FORM IF ( aud_mode$() = FALSE ) THEN BEGIN SET acct:$acctno:SEARCH_RANGES TO ’100’ NEXT ACTION IS FIND END


427

background$( ) System function: execute an operating system command in the background

Syntax

UNIX:

background$( shell, command_string ) Windows: background$( ’’, command_string )

Arguments

shell

(STRING) (UNIX only) The directory search path and file name of the shell to be used for executing the command. If shell is null or a zero-length string—two apostrophes (’’), the shell is determined by following the normal search hierarchy: 1. the command line 2. the SHELL preference 3. (Unify DataServer only) the SHELL preference set in dbname.cf 4. the SHELL preference set in the application preferences file (vision.uvp)

command_string (STRING) The string containing the command or application to be executed.

Return values

0

The command specified by command_string was executed successfully.

UNDEFINED

The command_string is not a valid operating system command.

system_value

(UNIX) The operating system could not execute the command_string, so the background$( ) system function returned the value from the operating system function system( ). (Windows) The operating system could not execute the command_string, so the background$( ) system function returned the value from the operating system function WinExec( ).

428


Description

Execution of background processes is dependent on the operating system, as described in the following paragraphs. UNIX

For UNIX, the background$( ) system function executes an operating system command so that its progress and results are not displayed on the screen. The command can be any command that you can execute from the operating system prompt. Windows NT For Windows NT, this function runs a program in the background and attaches a console window to main( ). The system_value returns the value from the operating system function CreateProcess( ).

Example

The following example uses the background$( ) system function to format and print a report if the user answers yes in the print_report field. The report is executed by the operating system without altering the application display. FIELD print_report METHOD AFTER FIELD IF (print_report = TRUE) THEN background$(’/bin/sh’,’nroff –ms report1 | lpr’)

Windows NT

See also

background$(’’, ’c:\\winnt\\system32\\cmd.exe /c dir > c:\\tmp.txt’);

System functions push_shell$( ) (page 537) system$( ) (page 592)

For information about the application preferences file, see “Deploying the application” Related information in Unify VISION: Developing an Application.


429

beep$( ) System function: sound the bell on the workstation

Syntax

beep$ ( beep_count )

Arguments

beep_count

Return values

None.

Description

The beep$( ) system function sounds a beep on the user’s workstation. Use this function to alert the user to some special event such as an error message, invalid action, or important task.

(NUMERIC) The number of bell characters to send to the terminal.

This system function has no effect if the user has disabled the bell on the workstation.

Example

This example causes three beeps when the item’s quantity-on-hand in inventory reaches zero. IF ( finventory:$nv_q_on_hand = 0 ) THEN BEGIN beep$(3) DISPLAY ’No more items in inventory — Time to reorder!’ FOR FYI_MESSAGE WAIT END

See also

430

Script language DISPLAY (page 246)


binarylen$( ) System function: determine the length of a binary value

Syntax

binarylen$( binary_value )

Arguments

binary_value

(BINARY) A binary value.

Return values

(NUMERIC)

A NUMERIC value for the length of the binary_value in bytes is returned. If the BINARY value has a NULL value, a NULL NUMERIC value is returned.

Description

The binarylen$( ) system function determines the length in bytes of a BINARY value.

Example

This example extracts a set of integers from a list of 4-byte integers. FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1) BEGIN SET $start TO $idx * 4; SET $end TO $start + 4; SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end)); END;

See also

Script language subbinary$( ) (page 587)


431

char_code_to_str$( ) System function: convert an integer into a character string

Syntax

char_code_to_str$ ( ascii_value )

Arguments

ascii_value

(NUMERIC) The decimal ASCII value to be translated into a character.

Return values

(STRING)

The single character representation of the ASCII value ascii_value.

Description

The char_code_to_str$( ) system function translates an integer ascii_value into a single character string. The ascii_value must be an integer in the range 0 to 255 (valid ASCII values). This function is used primarily to include non-printing characters in strings.

Example

This SET statement uses char_code_to_str$( ) to assign the ASCII representation of ^c (CTRL c) to the variable ctrlC. SET ctrlC TO char_code_to_str$(3)

See also

432

System functions str_to_char_code$( ) (page 578)


check_dirty$( ) System function: determines status of dirty data

Syntax

check_dirty$( )

Support


DBMS dependent

INFORMIX

The application is always allowed to access dirty data; therefore, check_dirty$( ) always returns TRUE.

INGRES

The check_dirty$( ) function always returns the current value of the show_dirty$( ) flag. check_dirty$( ) returns TRUE if dirty data reads are enabled; the function returns FALSE if dirty data reads are disabled.

ODBC

The application is not allowed to access dirty data; therefore, check_dirty$( ) always returns FALSE.

ORACLE

check_dirty$( ) always returns TRUE.

SYBASE SQL

The application is not allowed to access dirty data; therefore, check_dirty$( ) always returns FALSE.

Server

Unify DataServer

Fully supported. The check_dirty$( ) system functions returns TRUE if the selected set or the current record contains locked records and FALSE if the selected set contains no dirty data.

Return values

(BOOLEAN) TRUE

Where check_dirty$( ) is fully supported, TRUE indicates that the selected set or the current record contains dirty data.

FALSE

The selected data does not contain dirty data.


433

Description

If fully supported by the underlying DBMS, the check_dirty$( ) system function determines whether the results of a database access encountered dirty data. Dirty data is data in a database row that was write-locked by another transaction when the current transaction tried to access it. If a row is write-locked, it is usually because some other transaction is updating, deleting, or adding the row. The data in this write-locked row might be in the process of being updated or deleted by another transaction. The write-locked row might not have the same column values in the database when the exclusive lock is released. If the row has been deleted, the values might not even exist. If the DBMS supports the show_dirty_data option, you can use the Unify VISION system function show_dirty$( ) to specify whether dirty data is brought into the application. If the application allows dirty data, column values for write-locked rows are brought into the application. If the application does not allow dirty data, column values for write-locked rows are not brought into the application. The check_dirty$( ) system function returns the results of the connection defined for the current form, not for the last executed connection. Unify DataServer You can use check_dirty$( ) to determine whether dirty data was accessed: If the application allows dirty data and if the database accessed write-locked rows, check_dirty$( ) returns TRUE. If no dirty data was encountered, check_dirty$( ) returns FALSE. If the application does not allow dirty data, column values for write-locked rows are not brought into the application. You can use check_dirty$( ) to determine whether any write-locked rows were accessed, even though their column values are not available. If the application does not show dirty data, UNDEFINED values can occur for write-locked rows in two possible ways: an interactive find operation: if the current transaction is running at record consistency a non-interactive find: if the SELECT statement does not include a locking clause

434


You can use check_dirty$( ) with either of these find operations to determine whether a selected row is write-locked. For an interactive find operation, you can call check_dirty$( ) in the ON FIND section to check each selected row for dirty data. If you do not want to include the dirty data, use the REJECT RECORD statement. You could also use check_dirty$( ) in the AFTER FIND section to determine whether any rows have dirty data. For a non-interactive find operation, you can use the check_dirty$( ) function in the EXECUTING clause of SELECT to check each selected row for dirty data or after the SELECT statement to check whether any selected rows have dirty data.

Example

In this example, check_dirty$( ) checks the results of a database search on a target table. If the selected set contains dirty data, the application asks whether the user wants to continue using the selected set. If the end user answers NO, the application clears the selected set. METHOD AFTER FIND IF check_dirty$() THEN BEGIN IF ( NOT yesno$(’Set contains dirty data. Continue?’, 0) ) THEN NEXT ACTION IS CLEAR_TO_FIND END

See also

System functions show_dirty$( ) (page 550)

For information about dirty data and transaction control, see “Managing transactions Related information and locks” in Unify VISION: Developing an Application.


435

child_forms$( ) System function: return a list of child form references

Syntax

LOCAL_declaration

... child_forms$( parent_form_ref, child_form_refs, num_child_forms )

Arguments

PRIVATE_declaration A PRIVATE or PUBLIC declaration that specifies an unbounded list, for example, PRIVATE LIST child_form_ref [1 TO UNKNOWN ESTIMATING 10].

parent_form_ref An expression that identifies the object reference of the parent form. child_form_refs The unbounded list for receiving the object references for child form instances. num_child_forms The number of child form instances found.

Return values

None.

Description

The child_forms$( ) system function returns a list of references and a count of all child forms for a given parent form. The list of references begins with 1.

Related See Unify VISION: Class Reference for information about related methods: information ON NEW CHILD

436


clip_str$( ) System function: remove leading and trailing blanks

Syntax

clip_str$ ( value )

Arguments

value

(STRING/TEXT) The string or text from which to remove leading and trailing blanks.

Return values

(STRING)

The clipped string or text (with leading and trailing blanks removed).

Description

The clip_str$( ) system function removes leading and trailing blanks from a string or text value. For text values, leading and trailing newline characters are also removed. If value is a null or a zero-length value, clip_str$( ) returns value. This function does not remove embedded blanks. This function is useful for removing extra blanks from a database string column.

Example

This example extracts a menu item from mnu_table and stores the clipped menu item in mnu_item. SET mnu_item TO SELECT mnu_item_name FROM mnu_table WHERE mnu_id = $id; SET mnu_item TO clip_str$(mnu_item)

See also

System functions strlen$( ) (page 585) substr$( ) (page 589)


437

close_message_file$( ) System function: close message file

Syntax

close_message_file$( )

Return values

None.

Description

The close_message_file$( ) system function closes a previously opened message file. Only one message file can be open at a time. Messages are stored in a message file in a special format. For a complete description of the message file format, see the description for the Unify VISION system function get_message$( ).

Example

In this example, open_message_file$( ) opens the message file /usr/apps/messages. If this message file can be opened, the code sample retrieves a message from it using get_message$( ). After the message is retrieved, the message file is closed by close_message_file$( ). IF ( open_message_file$(’/usr/apps/messages’) = 0 ) THEN BEGIN DISPLAY get_message$(100) FOR FYI_MESSAGE WAIT close_message_file$() END

See also

438

System functions get_message$( ) (page 506) open_message_file$( ) (page 531)


convert_timezone$( ) System function: convert a datetime value from one time zone value to another time zone

Syntax

convert_timezone$( value, TZ1, TZ2 )

Arguments

value

(DATETIME) The value to be converted.

TZ1

(STRING or keyword) A string expression for a time zone specification; must be in POSIX standard machine-independent format or the LOCAL keyword.

TZ2

(STRING or keyword) A string expression for a time zone specification; must be in POSIX standard machine-independent format or the LOCAL keyword.

Return values

(DATETIME)

The datetime value of the value argument converted from the TZ1 to the TZ2 time zone specification.

Description

The convert_timezone$( ) function converts the specified value (using the TZ1 time zone specification) to a datetime value with the TZ2 time zone specification. If the LOCAL keyword is specified for either time zone specification (TZ1 or TZ2), it is translated to be the local time zone.

See also

System functions

current_timezone$( ) (page 449)

Example

This example uses the convert_timezone$( ) function to convert a datetime value from the UTZ+3 time zone to the VTZ + 2WTZ time zone; the value 12/25/99 17:15:00.000 is returned: SET d2 to convert_timezone$(12/25/99 16:15:00.000, ’UTZ+3’, ’VTZ+2WTZ’)

TZ_CONVERSION Related information


439

copy_in$( ) System function: string building

Syntax

copy_in$ ( RESULT buffer, start_offset, end_offset, in_value )

Arguments

buffer

(STRING/TEXT/BINARY) Specifies the variable to copy characters into. Returns with contents changed.

start_offset

(NUMERIC) Specifies offset for first character of destination field.

end_offset

(NUMERIC) Specifies offset for last character of destination field.

in_value

(STRING/TEXT/BINARY/NUMERIC) Specifies the variable to move characters from.

Return values

None.

Description

This routine is used to copy characters from a variable (in_value) into a portion of another variable (buffer). This is a copy of some number of characters into a logical destination field within the buffer. The start_offset in the destination buffer indicates the first character of the logical field within the destination buffer where the characters will be copied to. The first character of the destination field is indicated by a value of 1. Although the description of this routine is mostly character-oriented, when the destination buffer is of type BINARY, this routine is byte-oriented instead of character-oriented. That is, a start_offset value of 2 indicates the second byte instead of the second character. This distinction is only apparent when characters are encoded into a multi-byte character set such as Unicode.

440


The end_offset in the destination buffer indicates the last character of the logical field within the destination variable where the characters are copied to. This is used to protect the destination buffer from being overwritten. It marks the right edge of the destination field. The start_offset and end_offset must be greater than 0. The start_offset must be less than or equal to the end_offset. The end_offset must be less than or equal to the size of the buffer. If the start_offset and end_offset are equal, that means that one character only is copied from the in_value. Because of the limits on the values of start_offset and end_offset, a request for a copy is always a request to copy at least one character. The characters moved from the in_value always start with the first character. The destination field size can be larger than the size of in_value. The characters that are not overwritten by the in_value remain the same as before the call. If the size of in_value is greater than the destination field size indicated by the start_offset and end_offset parameters, then the copy moves only characters from the in_value to the destination up to the size of the destination field. If the buffer is type BINARY, then the in_value can only be of type BINARY or NUMERIC. If the buffer is type TEXT or STRING, then the in_value can only be of type TEXT or STRING. If in_value is type NUMERIC, then it is assumed to be the decimal value of a single byte to copy into the destination buffer. The value must be from 0 to 255 inclusive.

See also

System functions

pad_str_right$( ) (page 535) trim_bytes$ ( ) (page 610)


441

Example

This example uses the copy_in$( ) function to create three string fields within a 100-character buffer: BUTTON PutMsg METHOD ON CLICK(thebutton) BEGIN if ( fOpen ) then BEGIN set seedMsg to to_binary$( ’ ’ ); set Message to pad_str_right$( $seedMsg, str_to_char_code$(’ ’), 100 ); copy_in$( Message, 1, 5, to_binary$(to_string$(current_time$( ))) ); copy_in$( Message, 7, 18, to_binary$(to_string_using$( current_date$( ), ’AAA DD, YYYY’ ) ) ); copy_in$ ( Message, 20, 100, to_binary$($sFreeFormString ) );

Related For more information about MQSeries, see Unify VISION:Interconnecting Applications information with Enterprise Integrator.

442


current_date$( ) System function: retrieve current date

Syntax

current_date$( )

Return values

(DATE )

Description

The current_date$( ) system function obtains the current date from the operating system. This date is in the same format as the Unify VISION data type DATE.

Example

In this example, current_date$( ) assigns the current date to the ld_date_found variable if this variable was undefined.

The DATE value of the current date as retrieved from the operating system.

FIELD ld_date_found METHOD AFTER FIELD IF ( fleads:ld_date_found IS UNDEFINED ) THEN SET fleads:ld_date_found TO current_date$()

See also

System functions current_time$( ) (page 448) date_to_mdy$( ) (page 457)


443

current_datetime$( ) System function: return current local system datetime

Syntax

current_datetime$( )

Return values

(DATETIME)

Description

The current_datetime$( ) function returns the current local system time as a datetime value.

See also

System functions

The value of type DATETIME equal to the current datetime as retrieved from the operating system.

current_date$( ) (page 443) current_time$( ) (page 448)

Example

This example uses the current_datetime$( ) function to return a datetime value; for instance, 11/04/97 15:04:26.125: SET logon_time to current_datetime$()

444


current_form$( ) System function: retrieve current form ID

Syntax

current_form$( )

Return values

(OBJECT_ID)

Description

The current_form$( ) system function obtains the object ID of the current form. If there is no current form, current_form$( ) returns UNDEFINED.


The object ID of the current form as retrieved from the operating system.

445

current_record_count$( ) System function: return the number of records in selected set

Syntax

current_record_count$( )

Return values

(NUMERIC) >0

The number of records in the selected set.

0

The form is in find mode, or no records have been selected.

Description

The current_record_count$( ) system function determines the number of records in the selected set. While the form is in find mode, this function always returns zero (0). After completing a successful find, the function returns the number of records selected from the database. This record count is adjusted if records are added to or deleted from the selected set.

Example

In this example, current_record_count$( ) determines whether a database search has successfully located matching records. If no records have been found, the user is asked to reenter the search criteria. METHOD AFTER FIND IF ( current_record_count$() = 0 ) THEN BEGIN DISPLAY ’Search found no records, please reenter search criteria’ FOR FYI_MESSAGE WAIT NEXT ACTION IS CLEAR_TO_FIND END

See also

Script language CHANGE CURRENT RECORD TO (page 190)

System functions current_record_num$( ) (page 447) record_is_current$( ) (page 539)

446


current_record_num$( ) System function: return current record number

Syntax

current_record_num$( )

Return values

(NUMERIC)

Description

>0

The relative number of the current record within the selected set.

0

The form is in find mode, or no records have been selected.

The current_record_num$( ) system function determines the relative number of the current record within the selected set. For example, if the selected set contains five records and the third record in this set is displayed on the form, current_record_num$( ) returns the value 3. When the uv_clear_to_add command is executed, the current record number is one greater than the current record count.

Example

In this example, current_record_num$( ) and current_record_count$( ) determine whether the current record is the last record of the selected set. If the current record is the last record, this code puts the form in add/update/delete mode. METHOD ON NEXT RECORD IF ( current_record_num$() = current_record_count$() ) THEN NEXT ACTION IS CLEAR_TO_ADD

See also

System functions current_record_count$( ) (page 446) record_is_current$( ) (page 539)


447

current_time$( ) System function: retrieve the current time

Syntax

current_time$( )

Return values

(TIME)

Description

The current_time$( ) system function obtains the current time from the operating system. This time is in the same format as the Unify VISION data type TIME.

Example

In this example, current_time$( ) assigns the current time to the time_entered variable if time_entered is undefined.

The TIME value of the current time as retrieved from the operating system.

FIELD time_entered METHOD AFTER FIELD IF ( time_entered IS UNDEFINED ) THEN SET time_entered TO current_time$()

See also

448

System functions current_date$( ) (page 443)


current_timezone$( ) System function: return current time zone

Syntax

current_timezone$( )

Return values

(STRING)

Description

The current_timezone$( ) function returns the current time zone in a POSIX standard format. The time zone specification can then be used with the convert_timezone$( ) system function or the TZ_CONVERSION attribute.

The current time zone in POSIX standard format.

If a POSIX-compliant time zone specification cannot be obtained from the operating system, a null STRING value is returned.

See also

System functions

convert_timezone$( ) (page 439)

Example

This example uses the current_timezone$( ) function to return a POSIX standard time zone, for instance, PST8PDT: SET tz to current_timezone$() IF tz IS NOT NULL THEN SET newDate to convert_timezone$($oldDate, ’PST8PDT’, $tz)

TZ_CONVERSION Related information


449

dap_4gl_errcode$( ) System function: service object runtime errors

Partitioned applications only

Syntax

dap_4gl_errcode$( object_ref )

Support

This system function is available for Partitioned applications implementations only.

Arguments

object_ref

An expression that specifies the object reference of a service object.

Return values

(NUMERIC)

Error message number that occurred during the last method invocation on the specified service object.

Description

The dap_4gl_errcode$( ) system function returns the VISION Runtime Manager error code that occurred after a method was invoked on a service object. Use this system function in your client application to determine what errors occurred in your service objects.

“Building and managing a partitioned application” in Unify VISION: Developing an Related information Application

450


dap_td_count$( ) System function: transport-dependent errors


Syntax

dap_td_count$( object_ref )

Support


Arguments

object_ref

An expression that specifies the object reference of a service object.

Return values

(NUMERIC)

The number of a transport-dependent errors that occurred during the last method invocation for object_ref.

Description

The dap_td_count$( ) system function returns the number of transport-dependent errors that occurred for the last method invocation on the service object identified by object_ref. If the status$( ) system function returns SS_DAP_TD, use this system function to receive more detailed information.

See also

System functions dap_4gl_errcode$( ) (page 450) dap_td_errcode_i$( ) (page 452) dap_ti_errcode$( ) (page 455)

“Building and managing a partitioned application” in Unify VISION: Developing an Related information Application


451

dap_td_errcode_i$( ) System function: transport-dependent errors


Syntax

#include dap_td_errcode_i$( VALUE object_ref, VALUE index )

Support

The dap_td_errcode_i$( ) system function is available for Partitioned applications implementations only.

Arguments

object_ref

An expression that specifies an object reference.

index

One of the following values:

Return values

(NUMERIC)

0

Specifies the transport that was being used when the error occurred.

1

For the URPC transport, specifies a URPC error.

2

For the URPC transport, specifies an unmapped Netwise error.

Transport-dependent status code that occurred during the last method invocation on the specified service object.

For index value of 0: 1

DAP_T_LOCAL

A local transport was used for the last SEND MESSAGE statement identified by this object reference. 2

DAP_T_URPC A URPC transport was used for the last SEND MESSAGE statement identified by this object

reference. 452


For index value of 1: 1

URPC_MAX_CONN

The maximum number of supported connections was exceeded. 2

URPC_CONN_DEAD

The connection was closed by the server. The server exited normally as a result of the last method invocation. 3

URPC_UNMAPPED An unmapped URPC error occurred.

4

URPC_CONN_REFUSED

The attempt to connect to the server for this object reference was refused. 5

URPC_NOMEM

The transport layer was unable to allocate sufficient memory for the operation.

Description

The dap_td_errcode_i$( ) system function returns information about the transport-specific error that occurred for the last method. If the status$( ) system function returns SS_DAP_TD, use the dap_td_errcode_i$( ) system function to receive more detailed information.

Example

In this function, the status returned by the last method determines the error-checking system function used to display an error message. If the status$( ) system function returns SS_DAP_INT, the dap_td_errcode_i$( ) system function returns the transport-dependent error numbers. #include #include VOID FUNCTION checkDAPerror( REF dapObj, VALUE objStat ) PRIVATE msg, inx; BEGIN IF $objStat != SS_NORM THEN BEGIN


453

SET msg TO ’A DAP error has occurred.\nObject Info:\n\n’ + ’Class Name: ’ + $dapObj–>CLASS_NAME + ’\n’ + ’Instance Name: ’ + $dapObj–>OBJECT_NAME + ’\n’ + ’Transport: ’ + $dapObj–>TRANSPORT + ’\n\n’; SWITCH $objStat BEGIN CASE SS_DAP_4GL: SET msg TO msg + ’Server 4gl Error: ’ + to_string$(dap_4gl_errcode$($dapObj)); CASE SS_DAP_TI: SET msg TO msg + ’Transport–Independent Error: ’ + to_string$(dap_ti_errcode$($dapObj)); IF dap_ti_errcode$($dapObj) = DAP_SERVER_FATAL THEN BEGIN SET msg TO msg + ’\nFatal Server 4gl Error: ’ + to_string$(dap_4gl_errcode$($dapObj)); END CASE SS_DAP_INT: SET msg TO msg + ’Transport–Dependent Error:\nError Count: ’ + to_string$(dap_td_count$($dapObj)) + ’\nError Codes: ’; FOR ( SET inx to 0; inx < dap_td_count$($dapObj); SET inx TO inx + 1 ) BEGIN SET msg TO msg + to_string$(dap_td_errcode_i$($dapObj, inx)) + ’ ’; END DEFAULT: SET msg TO msg + ’Unknown Error: ’ + to_string$($objStat); END DISPLAY msg FOR FYI_MESSAGE WAIT; END END; /* checkDAPerror() */

See also

System functions dap_td_count$( ) (page 452)

“Building and managing a partitioned application” in Unify VISION: Developing an Related information Application.

454


dap_ti_errcode$( ) System function: transport-independent error code


Syntax

#include dap_ti_errcode$( object_ref )

Support


Arguments

object_ref

An expression that specifies the object reference of the name service object.

Return values

(NUMERIC)

Transport-independent status code that occurred during the last method invocation for object_ref:

0

DAP_NOERROR

No error message was received. 1

DAP_SERVER_EXIT

The server exited normally as a result of the last method invocation. 2

DAP_SERVER_FATAL

A fatal runtime error occurred on the server during the last method invocation. Use the dap_4gl_errcode$( ) system function to return the runtime error that occurred. 3

DAP_SERVER_KILL

The server was killed during the last method invocation. 4

DAP_NOMEM

The server was unable to allocate sufficient memory to invoke the specified method; however, the server is still available. Chapter 6: System functions

455

Description

The dap_ti_errcode$( ) system function returns the transport-independent status code for the last method invocation for object_ref. Use this system function if the status$( ) system function returns SS_DAP_TI to receive more detailed information.

See also

System functions dap_4gl_errcode$( ) (page 450) dap_td_errcode_i$( ) (page 452) status$( ) (page 569)

Related “Building and managing a partitioned application” in Unify VISION: Developing an information Application.

456


date_to_mdy$( ) System function: convert the date or datetime value to numeric values

Syntax

date_to_mdy$( date, month, day, year )

Arguments

date

(DATE/DATETIME) The DATE or DATETIME value to be converted.

month

(NUMERIC) A variable to receive the month of the converted date. This parameter is an Unify VISION result parameter.

day

(NUMERIC) A variable to receive the day of the converted date. This parameter is an Unify VISION result parameter.

year

(NUMERIC) A variable to receive the year of the converted date. This parameter is an Unify VISION result parameter.

Return values

Description

The return values for this function are returned through the arguments month, day, and year. The actual return value for this function is undefined.

The date_to_mdy$( ) system function converts date to three NUMERIC values: month, day, year. These three values correspond to the month, day, and year of the DATE value in date. The year is returned as a four-digit number. For DATETIME arguments, the month, day, and year of the date portion of the datetime argument are returned. If the argument has an undefined date portion, then all returned arguments are undefined.


457

Example

In this example, date_to_mdy$( ), mdy_to_date$( ), and current_date$( ) are used to create a DATE variable with a date of five years from the current date. SET today_date TO current_date$() date_to_mdy$(today_date, month, day, year) SET year TO year + 5 SET five_years TO mdy_to_date$(month, day, year)

See also

458

System functions current_date$( ) (page 443) mdy_to_date$( ) (page 527) str_to_date$( ) (page 579) to_date$( ) (page 597)


datetime_adjust$( ) System function: modifies a date, time, or datetime value by an interval amount

Syntax

datetime_adjust$( dt, interval, value )

Arguments

dt

(DATE, DATETIME, TIME) An expression to be modified by the value and interval arguments.

interval

(STRING) The type of interval to use in the adjustment; must be one of the following strings (case insensitive): ’Year’ ’Month’ ’Day’ ’Hour’ ’Minute’ ’Second’ ’Millisecond’

value

(NUMERIC) An integer that determines the number of interval units by which to adjust the dt argument. The integer can be negative in which case the interval is subtracted from the dt argument.

Return values

(DATE, DATETIME, TIME) The adjusted date, datetime, or time value. The data type of the returned value is the same as the data type of the dt argument.

Description

The datetime_adjust$( ) function returns a datetime value equal to the dt argument plus value number of the interval argument. For instance, a dt argument of 1/31/97 with a value argument of 2 with an interval argument of ’Year’ returns 1/31/99. The value of the interval argument must be appropriate for the data type of dt. For example, you cannot give a date expression and an interval of ’Second’, because the date value contains no seconds.


459

If the resulting date is invalid, it is decreased until a valid date is reached. For instance: 1/31/97 +1 month returns 2/28/97 1/31/96 +1 month returns 2/29/96 2/29/96 + 1 year returns 2/28/97

Example

This example uses the datetime_adjust$( ) function to return a new datetime value, 02/04/98 15:04:26.125: SET dt to 11/04/97 15:04:26:125 SET dt to datetime_adjust$($dt, ’month’, 3) /* add a quarter to the date */

460


datetime_diff$( ) System function: return the difference between two date, time, or datetime values

Syntax

datetime_diff$( dt1, dt2, interval )

Arguments

dt1

(DATE, DATETIME, TIME) An expression that is compared with the dt2 expression.

dt2

(DATE, DATETIME, TIME) An expression that is compared with the dt1 expression.

interval

(STRING) The type of interval to return; must be one of the following strings (case insensitive): ’Year’ ’Month’ ’Day’ ’Hour’ ’Minute’ ’Second’ ’Millisecond’

Return values

(NUMERIC)

Description

The datetime_diff$( ) function returns a NUMERIC result of the difference between the two dt1 and dt2 arguments based on the interval value. The absolute value of the difference is returned, so the order of dt1 and dt2 does not matter.

The difference between the two expressions based on the interval argument value.

The difference is the amount of that interval difference between the two expressions, truncated to the lowest integer value. The data type of the expressions must be applicable to that interval (for instance, neither expression can be of type time if the interval is ’Day’). Chapter 6: System functions

461

When you compare datetime values with any interval except milliseconds, partial intervals are truncated to the nearest whole integer value. For instance, the following example returns a value of 1 because the difference is 36 hours or 1.5 days and the remaining hours are truncated, leaving a result of 1: datetime_diff$(11/1/97 12:00, 11/3/97 00:00, ’day’)

Time values always default to 00:00 (midnight). If a time interval is requested and either expression is of type DATE, the time value for that expression is assumed to be 00:00. If a time interval is requested and either expression is of type TIME (so there is no date), then the date portions are considered identical and the difference is based on the time values only.

See also

System functions

to_datetime$( ) (page 598)

Example

This example uses the datetime_diff$( ) function to return intervals: SET days to datetime_diff$($dt1, $dt2, $interval)

The following table shows the results for a few example cases: dt1

dt2

interval

returned value

11/1/97 00:00 1/3/98 00:00 year 11/1/97 00:00 1/3/98 00:00 month 11/1/97 00:00 1/3/98 00:00 day 63 11/3/97 00:00 1/1/98 00:00 year 11/3/97 00:00 1/1/98 00:00 month 11/3/97 00:00 1/1/98 00:00 day 59 1/1/97 2/2/97 12:14 Day 32 1/1/97 1/1/97 12:14 Hour 12 12/31/97 12/31/97 Second 12:00 1/1/96 Hour 12 2/28/97 12:22 1/1/97 Month 1 11/1/97 1/3/98 Year 0 11/1/97 1/3/98 Monyh 2 11/1/97 1/3/98 Day 63 11/1/97 1/1/99 Year 1 12:00 1:30 Hour 1 11/1/97 12:10:00 11/1/97 12:20:50

462

0 2 0 1

0

Minute 10


db_type$( ) System function: determine current database type

Syntax

db_type$( )

Return values

(STRING)

The name of the current DBMS type. ’INFORMIX’ Specifies that INFORMIX is the data source. ’INGRES’

(UNIX) Specifies that INGRES is the data source.

’ODBC_ACCESS’

Specifies that MS Access is the data source. ’ODBC_DBASE’

(Windows) Specifies that dBASE is the data source. ’ODBC_DBASE3’

(Windows) Specifies that dBASE III is the data source. ’ODBC_Ingres’(Windows) Specifies that INGRES is the data source. ’ODBC_DBASE4’

(Windows) Specifies that dBASE IV is the data source. ’ODBC_WATCOM SQL’

(Windows) Specifies that Watcom SQL is the data source. ’ODBC_Watcom SQL’

(Windows) Specifies that Watcom SQL is the data source.


’ORACLE’

Specifies that ORACLE is the data source.

’SYBASE’

Specifies that SYBASE SQL Server is the data source.

’U2000’

Specifies that Unify DataServer is the data source. 463

Description

The db_type$( ) system function enables you to write statements specific to a particular DBMS. db_type$( ) takes no arguments and returns the name of the current DBMS type as a string. The db_type$( ) system function returns the database type of the current form, not the database type of the last executed connection. If used within a service class script, the db_type$( ) system function returns the database type of the current service’s database connection, not the database connection of the calling form. INFORMIX The db_type$( ) system function returns ”INFORMIX” but does not indicate the version or mode (OnLine, SE, or MODE ANSI).

Example

This example causes an error message to appear if the user enters the [ metacharacter while using the ORACLE DBMS. IF db_type$() = ’ORACLE’ THEN DISPLAY ’”[” metacharacter not supported’ FOR FYI_MESSAGE WAIT

See also

System functions os_type$( ) (page 532) ui_type$( ) (page 615)

For information about multiple database connections, see “Getting started” in Unify Related information VISION: Developing an Application. For information about related external preferences, see “External preferences syntax descriptions” in Unify VISION: Application Reference: DBTYPE

464


dbms_status$( ) System function: return DBMS status code

Syntax

dbms_status$( )

Return values

(NUMERIC)

Description

The dbms_status$( ) system function returns a specific status code from the DBMS. The values returned are specific to each DBMS.

A return code supplied by the database.

The dbms_status$( ) system function returns the value returned by the most recently executed SQL statement, regardless of the current database connection.

Example

In this example, dbms_status$( ) determines whether any records were found in a non-interactive find operation. If no records were found, the emp_name variable is set to a string of spaces. SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id; IF (NOT_FOUND_STAT = dbms_status$()) THEN SET emp_name TO ’ ’;

See also

System functions sql_code$( ) (page 562) sql_errmsg$( ) (page 563)

sql_state$( ) (page 568) status$( ) (page 569)

For information about DBMS status codes, see the documentation provided by the Related information DBMS vendor. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.


465

dbms_status_i$( ) System function: error message handling

Syntax

dbms_status_i$(index)

Support


DBMS dependent

INFORMIX

The dbms_status_i$( ) system function is not supported for INFORMIX. The function always returns NULL.

ORACLE

Supported.

SYBASE SQL

Supported.


The dbms_status_i$( ) system function is not supported for Unify DataServer. The function always returns NULL.

Arguments

index

Index, ranging from 1 to n, that indicates the message in the list of error messages that was generated by the last call to the database.

Return values

error_code

(NUMERIC) The ORACLE-specific error code that corresponds to the index-indicated error message in the error message string that was generated by the last call to the database.

NULL

The index value is out of range, or the underlying DBMS is not supported.

Description

466

The dbms_status_i$( ) system function returns the DBMS error code that corresponds to the index-indicated error message in the error message string that was generated by the last database operation that generated a call to the server. The database operation can be initiated by either VISION Runtime Manager or a developer-defined C function. Unify VISION: 4GL Reference

Example

This example displays the last error code received from the DBMS. FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY dbms_status_i$(inx) FOR FYI_MESSAGE WAIT END

See also

System functions sql_errmsg_count$( ) (page 564) sql_errmsg_i$( ) (page 566)


467

dde_get_data$( ) System function: DDE

Windows only

Syntax

dde_get_data$(handle, RESULT result_data, time_out)

Support

The dde_get_data$( ) system function is supported for Windows only.

Arguments

handle

(NUMERIC) The result parameter that was returned from the dde_request_data$( ) system function. The value of this variable uniquely identifies a request. After the request is retrieved by the dde_get_data$( ) system function, the handle is invalid.

result_data

(TEXT RESULT) This result parameter must be a variable name. If the server sends the value for the requested item, the value is placed in this variable.

time_out

(NUMERIC) Number of milliseconds that VISION Runtime Manager should wait for a reply from the server.

Description

The dde_get_data$( ) system function is used to retrieve the data that was requested by the dde_request_data$( ) system function. If the data is sent successfully, the function returns DDE_SUCCESS and places the data in the result_data variable. If the dde_get_data$( ) system function times out, it cannot be called again until the response is retrieved.

Return values

DDE_SUCCESS

(NUMERIC) The data was successfully received and placed in result_data. DDE_NEGACK (NUMERIC) The server cannot carry out the DDE request.

468


DDE_TIMEOUT

(NUMERIC) The server did not reply by the end of the specified number of milliseconds (time_out). DDE_NOLINK (NUMERIC) The handle that was passed to this system function is not

valid. For a complete list of values that can be returned by the DDE system functions, see the dde_codes.h file in the include directory.

Example

In this example, the call to dde_get_data$( ) is in a global event handler function, handleRequest, that handles request data events for a DDE client. /******************************************************************** * hndlreq.fs ********************************************************************/

#include #include EXTERN SCRIPT STRING FUNCTION strCat(val, val, val, val, val) EXTERN SCRIPT VOID FUNCTION dispErr(val, val, val) BOOL FUNCTION handleRequest( handle, funcstat, timeout, REFERENCE data ) PRIVATE errstr, /* error string */ timeoutstr, /* error message for timeout */ nolinkstr, /* error message for DDE_NOLINK */ poststr, /* error message for DDE_POSTFAIL */ getResp, /* if TRUE, get the response again */ status /* status return from dde_get_data$ */ BEGIN . . . SET $getResp TO TRUE While ($getResp = TRUE) BEGIN /* * get the data that was requested by dde_request_data$() */ SET $status TO dde_get_data$($handle, $data, $timeout) . . .

See also

System functions dde_get_response$( ) (page 474) dde_request_data$( ) (page 482)


469

dde_get_hot_links$( ) System function: DDE

Windows only

Syntax

dde_get_hot_links$(hot_links_array)

Support

The dde_get_hot_links$( ) system function is supported for Windows only.

Arguments

hot_links_array (MATRIX) A developer-defined two-dimensional, unbounded array of four columns.

Description

The dde_get_hot_links$( ) system function fills the hot_links_array with the information about the active DDE hot links and returns the number of active hot links. The array contains one row for each active hot link and contains this information: link_type

(STRING) Keyword that indicates whether the application is acting as a DDE server (’server’) or a DDE client (’client’).

server_link_ID (NUMERIC) Server identifier that was returned by the dde_initiate_link$( ) system function. client_link_ID (NUMERIC) Client identifier that was passed to the application through an initiate_link DDE event handler global function installed by the INSTALL statement. item

(STRING) Name of the data item whose value is being passed through the hot link.

The information in the hot_links_array array can help you to track the application’s active DDE hot links.

Return values 470

(NUMERIC)

The number of active hot links. Unify VISION: 4GL Reference

Example

In this example, the LOCAL clause is used to define a general array variable named hot_links and a general variable named numlinks. The hot_links array is used to store the hot link information obtained by the dde_get_hot_links$( ) system function. The dde_get_hot_links$( ) function also returns the number of active hot links, which is stored in the numlinks variable by the SET statement. The call to the dde_get_hot_links$( ) system function is in a developer-defined function named showHotLinks. /********************************************************************** * showhot.fs **********************************************************************/ EXTERN SCRIPT VOID FUNCTION updStatus(val) VOID FUNCTION showHotLinks( ) PRIVATE idx, /* loop index */ numlinks, /* number of active DDE links */ matrix hot_links[1 TO unknown, 1 TO 4] /* DDE hot link info */ BEGIN /* * fill the array $hot_links with the information about all of the * currently active links */ SET $numlinks TO dde_get_hot_links$($hot_links) updStatus(’*********** Active DDE Hot Links ***********’) /* search the array $hot_links for a link which is a DDE client */ FOR (SET $idx TO 1 ; $idx @cost RETURN @cnt

First the sp_items stored procedure is declared in an EXTERN statement: EXTERN STORED ROW_VALUED FUNCTION sp_items(ge_value) ;

Then sp_items( ) is called in the VISION 4GL script by using the following statements: SET $cnt TO 0 ; SET $key, $item_cost TO sp_items(100.00) EXECUTING BEGIN /* Process $key and $item_cost here */ END SET $cnt TO sp_return$()

See also

Script language EXTERN (page 281) SET (page 378)

System functions sp_compute$( ) (page 554) sp_select$( ) (page 559)

Related For information about multiple database connections, see “Getting started” in Unify information VISION: Developing an Application.

558


sp_select$( ) System function: determine index of SELECT statement

Syntax

sp_select$( )

Support


DBMS dependent

INFORMIX

Because INFORMIX stored procedures always return a fixed number of elements, the sp_select$( ) system function always returns 0.

INGRES

The sp_select$( ) system function always returns 1.

ORACLE

The sp_select$( ) system function is not supported for ORACLE. Therefore, this function returns 0.

SYBASE SQL

Supported.


The sp_select$( ) system function is not supported for Unify DataServer. Therefore, this function returns 0.

Return values

(NUMERIC) 1 or higher


The index of the current SELECT in the stored procedure. The first SELECT returns 1; the second SELECT returns 2; and so on.

559

Description

The sp_select$( ) system function determines which of a stored procedure’s SELECT statements is currently being executed. You can use this function when your stored procedure contains multiple SELECT statements, and you want to perform specific tasks based on the SELECT statement executed. You can use the sp_select$( ) system function anywhere you would use an expression. The sp_select$( ) system function returns the value returned by the most recently executed stored procedure, regardless of the current database connection.

Example

The following example uses the sp_select$( ) system function to determine which SELECT statement generated the last values returned from the stored procedure stored_proc( ). SET $var1, $var2, $var3, $var4, $var5 TO stored_proc() EXECUTING BEGIN SWITCH sp_select$() BEGIN CASE 1: /* Values in $var1 through $var5 are returned by SELECT #1 */ . . . CASE 2: /* Values in $var1 through $var5 are returned by SELECT #2 */ . . . CASE 3: /* Values in $var1 through $var5 are returned by SELECT #3 */ . . . END END

See also

Script language EXTERN (page 281) SET (page 378)

System functions sp_compute$( ) (page 554) sp_return$( ) (page 556)

For information about multiple database connections, see “Getting started” in Unify Related information VISION: Developing an Application.

560


sql_clear$( ) System function: close and clear buffered commands

Syntax

sql_clear$( )

Return values

(BOOLEAN)

Description

TRUE

All commands have been cleared from the buffer.

FALSE

The buffer could not be cleared or closed.

The sql_clear$( ) system function closes and clears all buffered commands. Use this function whenever database objects, such as a schema or table, are changed by DDL statements, or to free memory after commands that will not be executed again. You need not use this statement with DDL statements that cause automatic clearing: ALTER, CREATE, GRANT, and REVOKE.

Example

This example uses the sql_clear$( ) function to clear all buffered commands after a table view has been dropped. DROP VIEW high_salary; sql_clear$()


561

sql_code$( ) System function: return DBMS status code

Syntax

sql_code$( )

Return values

(NUMERIC)

Description

The sql_code$( ) system function returns an integer status field. The values returned are specific to each DBMS.

Value of the sqlcode return field for embedded SQL.

If the DBMS does not provide an SQL code value, the function returns NULL. The sql_code$( ) function is provided for compatibility with existing DBMS products only and is not recommended for use with new applications. For new applications, use the sql_state$( ) function instead. The sql_code$( ) system function returns the value returned by the most recently executed SQL statement, regardless of the current database connection.

Example

In this example, an error message is displayed if the UPDATE operation is not successful. UPDATE emp SET salary = salary * 1.1 IF (sql_code$() UENOERR) THEN DISPLAY ’Update failed’ FOR FYI MESSAGE WAIT

See also

System functions dbms_status$( ) (page 465) sql_errmsg$( ) (page 563)


For information about SQL codes, see the documentation supplied by the DBMS Related information vendor. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.

562


sql_errmsg$( ) System function: retrieve SQL error message

Syntax

sql_errmsg$( )

Return values

(STRING)

Description

The sql_errmsg$( ) system function returns the error message that corresponds to the last SQL statement executed. The messages returned are specific to each DBMS.

The error message returned as a result of execution of the last SQL command, up to a maximum of 2048 characters.

The sql_errmsg$( ) system function returns the value returned by the most recently executed SQL statement, regardless of the current database connection.

Example

This example displays the DBMS message when any error occurs in the database. SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id; IF dbms_status$() NORM THEN DISPLAY ’DBMS Message: ’ + sql_errmsg$() FOR FYI_MESSAGE WAIT

See also

System functions dbms_status$( ) (page 465) sql_code$( ) (page 562)


Related For information about error messages, see the documentation supplied by the DBMS information vendor. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.


563

sql_errmsg_count$( ) System function: error message handling

Syntax

sql_errmsg_count$( )

Support


DBMS dependent

INFORMIX

The sql_errmsg_count$( ) system function is not supported for INFORMIX. The function always returns NULL.

INGRES

The sql_errmsg_count$( ) system function is not supported for INGRES. The function always returns NULL.

ORACLE

Supported.

SYBASE SQL

Supported.


The sql_errmsg_count$( ) system function is not supported for Unify DataServer. The function always returns NULL.

Arguments

None

Return values

num_msgs

564

(NUMERIC) The number of messages that are contained in the list of error messages that was generated by the last call to the database.


Description

The sql_errmsg_count$( ) system function returns the number of error messages that were generated by the last database operation that generated a call to the server. Such a database operation is initiated by either VISION Runtime Manager or a developer-defined C function.

Example

This example displays the last error message received from the DBMS. FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY sql_errmsg_i$(inx) FOR FYI_MESSAGE WAIT END

See also

System functions dbms_status_i$( ) (page 466) sql_errmsg_i$( ) (page 566)


565

sql_errmsg_i$( ) System function: error message handling

Syntax

sql_errmsg_i$(index)

Support


DBMS dependent

INFORMIX

The sql_errmsg_i$( ) system function is not supported for INFORMIX. The function always returns NULL.

INGRES

The sql_errmsg_i$( ) system function is not supported for INGRES.

ORACLE

Supported.

SYBASE SQL

Supported.


The sql_errmsg_i$( ) system function is not supported for Unify DataServer. The function always returns NULL.

Arguments

index

Return values

err_msg_string (STRING) The text of the index-indicated error message in the list of error messages that was generated by the last call to the database. NULL

566

Index, ranging from 1 to n, that indicates the message in the error message string that was generated by the last call to the database.

The index value is out of range, or the underlying DBMS is not supported.


Description

The sql_errmsg_i$( ) system function returns the text of the index-indicated error message in the error message string that was generated by the last database operation that generated a call to the server. The database operation can be initiated by either VISION Runtime Manager or a developer-defined C function. Call the sql_errmsg_i$( ) function immediately after calling sql_errmsg_count$( ). Make sure that you do not generate any additional calls to the server between the calls to sql_errmsg_count$( ) and sql_errmsg_i$( ).

Example

This example displays the last error message received from the DBMS. FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY sql_errmsg_i$(inx) FOR FYI_MESSAGE WAIT END

See also

System functions dbms_status_i$( ) (page 466) sql_errmsg_count$( ) (page 564)


567

sql_state$( ) System function: retrieve SQL status field

Syntax

sql_state$( )

Return values

(STRING)

Description

The sql_state$( ) system function returns a five-character SQL status field. The first two characters are the character class code, as defined by the ANSI standard for SQL. The next three characters are the character subclass. The values returned are specific to each DBMS.

Value of the sqlstate field of the SQL communications area.

If the DBMS does not provide an sqlstate value, the function returns NULL. The sql_state$( ) system function returns the value returned by the most recently executed SQL statement, regardless of the current database connection.

Example

In this example, the fyi_message system information field displays a message if the emp table no longer exists in the database. UPDATE emp SET vacation = vacation + 1 IF ( sql_state$() = ’30500’ ) DISPLAY ’emp table not found’ FOR FYI_MESSAGE WAIT

See also

System functions dbms_status$( ) (page 465) sql_code$( ) (page 562)

sql_errmsg$( ) (page 563) status$( ) (page 569)

For information about SQL status codes, see the documentation supplied by the DBMS Related information vendor. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.

568


status$( ) System function: determine success or failure of last operation

Syntax

[ #include ”sscodes.h” ] status$( )

Return values

(NUMERIC) 0

An error has occurred, and the operation was not successful.

SS_NORM

The database operation was successful (SS_NORM is 0).

For a complete list of status$( ) return values, see the table following the function description.

Description

The status$( ) system function obtains the success of certain Unify VISION operations: SQL statements, database operations, CREATE PIPELINE, RETRIEVE, and STORE statements. When checking the status$( ) return value, use the return value names from the sscodes.h file in your script. To use the status$( ) return value names, you must use the Unify VISION preprocessor statement #include to include the sscodes.h header file in your script. This header file contains definitions for the status$( ) return value names. It is located in the include directory of the Unify VISION release. Use this function to verify the success or failure of the most recent operation. With status$( ) you can check the status of database statements such as INSERT, SELECT, DELETE, UPDATE, SLOCK, and XLOCK. The status$( ) system function returns the value returned by the most recently executed statement, regardless of the current database connection. The status return numbers correspond to the following status return values: Positive integers 1 2 3


SS_BDENV SS_NOCRF SS_DFCNV

4 5

SS_FINAC SS_NOCUR

6 7

SS_NOENV SS_PROMO

569

Negative integers

–1 –2 –3 –4 –5 –6 –7 –8 –9 –11 –12 –14 –15 –16 –18 –19 –20 –21 –22 –23 –24 –25 –26 –27 –28 –29 –35 –37 –38 –39 –40 –43 –44 –45 –46 –47 –48 –49 –50 –52 –53 –54 –55 570

SS_AFLST SS_BDDOM SS_DUPBT SS_DUPK SS_FLCR SS_FLOPN SS_KEYRQ SS_INTS SS_MXSCN SS_NOREF SS_NOTUP SS_RDACS SS_REF SS_RMEM SS_STFUL SS_WRACS SS_SYSER SS_FINNA SS_UPDNA SS_DELNA SS_ADDNA SS_NOMEM SS_DIRT SS_NOFIL SS_FLACS SS_FLSK SS_NOREC SS_NOUP SS_NODEL SS_SMUP SS_SMDEL SS_NOLCK SS_SMLCK SS_LMOUT SS_USSER SS_UDFDB SS_S2U SS_BDSCN SS_NIMP SS_BDSEL SS_DBTYP SS_DBLEN SS_CMBF

–56 –57 –58 –59 –60 –61 –69 –70 –71 –74 –75 –76 –77 –78 –79 –80 –82 –83 –84 –85 –86 –87 –89 –90 –91 –92 –93 –94 –95 –96 –97 –98 –99 –100 –101 –103 –104 –105 –106 –107 –108 –109 –110

SS_FUNIP SS_CONV SS_EOSCN SS_NOTID SS_NORID SS_BDNAM SS_PART SS_ILLA SS_NODB SS_NODF SS_DFERR SS_NOVAL SS_ILTST SS_NOCMB SS_NONUL SS_NTLCK SS_TXIL SS_FLCL SS_BTOPN SS_BTERR SS_HKERR SS_NODEM SS_LMINT SS_NOSHM SS_SHMV SS_NOAT SS_VRSION SS_DBCLS SS_NOLOG SS_RFLD SS_DBMOD SS_UNVIEW SS_DBINT SS_OVRFLW SS_DDMLFL SS_DBRES SS_NETER SS_DEADLCK SS_LOGOFF SS_SLOGFUL SS_COLSPEC SS_SETSMM SS_DB2A Unify VISION: 4GL Reference

–111 –112 –113 –114 –115 –116 –117 –118 –119 –120 –121 –122 –123 –124 –125 –126 –127 –128 –129 –130 –131 –132

–133 –134 –135 –136 –137 –138 –139 –140 –141 –142 –143 –144 –145 –146 –147 –148 –149 -150 -151 -152 -153

SS_RDONLY SS_UDE SS_UDERB SS_AROVR SS_DIVZ SS_NLEXP SS_HPMEM SS_UNDACL SS_NRIDCOL SS_NOCON SS_RMOD SS_PARNTMCH SS_MDNTMCH SS_UNDBTP SS_UNSPTP SS_DUPNUL SS_NOTHNDL SS_NOTSTR SS_INVHNDL SS_HNDLNTAL SS_SYNEXEC SS_NUMUSING

SS_NOTSELECT SS_BADTYPE SS_NUMROWS SS_NUMCOLS SS_ONECON SS_INVLSP SS_INVLSPTYP SS_INVOBJREF SS_NO_LICENSE SS_NO_METHOD SS_PARM_COUNT SS_PARM_MODE SS_PARM_TYPE SS_DAP_4GL SS_DAP_TI SS_DAP_TD SS_INV_ASYNC SS_APPMAN_ERR SS_ORB_ERROR SS_SERV_TERM SS_DATA_SOURCE_COMM_ERROR

The following list describes the meaning of each return value. Return Status

Description

SS_ADDNA

Add operation not allowed on form.

SS_AFLST

Bad DIS list found performing an add/update operation.

SS_APPMAN_ERR SS_AROVR

An AppMan error has occurred.

An arithmetic overflow has occurred.

SS_BADTYPE Destination variables do not have an allowable type. SS_BDDOM

Domain check failed.

SS_BDENV

Bad format in preference.

SS_BDNAM

Match item has wrong selection file name.

SS_BDSCN

Scan identifier is not found.

SS_BDSEL

Attempt to enter search item in selection table failed.

SS_BTERR

Fatal error in B-tree access; rebuild B-tree.

SS_BTOPN

Error opening B-tree.

SS_CMBF

Column group not allowed.


571

SS_COLSPEC

Invalid column specification.

SS_CONV

Internal type conversion error.

SS_DAP_4GL

A runtime error occurred within a service object. Check dap_4gl_errcode$( ) for the error code.

SS_DAP_TD

A transport specific internal error occurred. Check dap_td_errcode_i$( ).

SS_DAP_TI

A transport-independent partitioned application error occurred. Check dap_ti_errcode$( ) for the specific code.

SS_DATA_SOURCE_COMM_ERROR SS_DB2A

/* Data source communication error */ Invalid database column type to Unify VISION type.

SS_DBCLS

Could not close the database.

SS_DBINT

DBMS error. Check dbms_status$( ) and sql_errmsg$( ).

SS_DBLEN

Bad DBMS length.

SS_DBMOD

Database has been modified.

SS_DBRES

Out of some database resource.

SS_DBTYP

Unknown DBMS type.

SS_DDMLFL

Deferred DML failure.

SS_DEADLCK Deadlock encountered; transaction aborted.

572

SS_DELNA

Delete operation not allowed on form.

SS_DFCNV

Default value conversion error.

SS_DFERR

Error in retrieving default value for a column on insert for column with a value that is not specified.

SS_DIRT

Returned data may be dirty. It was read without first obtaining a lock.

SS_DIVZ

Attempted division by zero.

SS_DUPBT

Duplicate found in NODUPS B-tree while adding a row.

SS_DUPK

Attempt to store a duplicate key.

SS_DUPNUL

Duplicate key or NOT NULL violation.

SS_EOSCN

End of scan (rows not found).

SS_FINAC

Column inaccessible.

SS_FINNA

Find operation not allowed on form.

SS_FLACS

Denied access to file.

SS_FLCL

Failed to close a file.

SS_FLCR

Error creating file.

SS_FLOPN

Unable to open sort/merge file.

SS_FLSK

File seek error.

SS_FUNIP

Tried to free a NIL pointer to a database value.

SS_HKERR

Hand table entry error. Unify VISION: 4GL Reference

SS_HNDLNTAL SQL handle is not allowed. SS_HPMEM

No heap memory is available.

SS_ILLA

Illegal argument encountered.

SS_ILTST

Illegal test specified in scan.

SS_INTS

Interrupted search.

SS_INV_ASYNC Invalid use of SEND ASYNC MESSAGE. SS_INVHNDL

Specified SQL handle is not currently valid.

SS_INVLSP

The stored procedure was declared as a procedure but was defined as a function or was declared as a function but was defined as a stored procedure.

SS_INVLSPTYP An invalid stored procedure type was declared. SS_INVOBJREF The object reference on method invocation was not valid. SS_KEYRQ

Key column is required.

SS_LMINT

Lock manager initialization failed.

SS_LMOUT

Unable to acquire lock due to exclusive lock conflict.

SS_LOGOFF

Transaction logging is not enabled.

SS_MDNTMCH The parameter mode specified in the stored procedure declaration doesn’t match the parameter mode in the stored procedure definition. SS_MXSCN

Too many active scans.

SS_NETER

Network error encountered.

SS_NIMP

Feature not implemented.

SS_NLEXP

A null value was used in an expression.

SS_NO_LICENSE The feature or message transport required for the operation is not licensed. SS_NO_METHOD The interface for the specified object does not include the method specified. SS_NOAT

Could not attach shared memory at the appropriate address: usually caused by another shared memory attach occurring before Lock Manager. Call opendb( ) first in your program to ensure correct attach address.

SS_NOCMB

Column Group not allowed.

SS_NOCON

No connection specified for query.

SS_NOCRF

No row current for column.

SS_NOCUR

No row current for default value.

SS_NODB

Could not get the inode of the database.

SS_NODEL

None of the rows were deleted.

SS_NODEM

Request was not a demotion request.

SS_NODF

There is no default value for this column.


573

SS_NOENV

Configuration variable not found.

SS_NOFIL

File does not exist.

SS_NOLCK

None of the rows were locked.

SS_NOLOG

There is no transaction log file (for rollback).

SS_NOMEM

Out of memory.

SS_NONUL

Attempt to use a null in a column where null is not allowed.

SS_NOREC

No rows selected.

SS_NOREF

Attempt to reference nonexistent row.

SS_NORID

Invalid row ID.

SS_NORM

SUCCESS.

SS_NOSHM

Out of shared memory.

SS_NOTHNDL Variable is not an SQL handle. SS_NOTID

Invalid table ID.

SS_NOTSELCT Statement must be a SELECT statement. SS_NOTSTR

Expression or variable is not of type STRING.

SS_NOTUP

Row already deleted.

SS_NOUP

None of the rows were updated.

SS_NOVAL

There is no value associated with this column.

SS_NRIDCOL

No row ID for update, insert, or delete operation.

SS_NTLCK

Transaction being committed has no locks.

SS_NUMCOLS Not enough columns in the destination variable list. SS_NUMROWS Not enough rows in the destination matrix. SS_NUMUSING Number of actual parameters in USING clause is too small. SS_ONECON

Only one database connection can be open at one time.

SS_ORB_ERROR SS_OVRFLW

Unify Object Request Broker Error.

Conversion overflow.

SS_PARM_COUNT The number of parameters supplied does not match the number of parameters in the interface. SS_PARM_MODE The mode of a supplied parameter does not match the mode specified in the interface. SS_PARM_TYPE The type of a supplied parameter does not match the type specified in the interface. SS_PARNTMCH The number of parameters in the stored procedure declaration doesn’t match the number of parameters in the stored procedure definition. SS_PART 574

Partial success in DBMS operation. Unify VISION: 4GL Reference

SS_PROMO

Lock granted, promotion occurred.

SS_RDACS

No read permission on row or table.

SS_RDONLY

A prohibited operation was attempted on a read-only database table.

SS_REF

Key cannot be changed because references to it exist.

SS_RFLD

Add rejected: not all required columns were entered.

SS_RMEM

No more space in database to add row.

SS_RMOD

The record was modified by another user.

SS_S2U

An illegal Unify VISION to DBMS data type conversion.

SS_SETSMM

The number of columns in the SELECT statement does not correspond to the number of variables in the SET statement.

SS_SERV_TERM

DAP Server Terminated.

SS_SHMV

Mismatch between the lock manager code and the shared memory data structures (incompatible version): reload with new code and/or remove shared memory segment.

SS_SLOGFUL

(Sybase SQL Server only) Syslogs is full; dump transaction log.

SS_SMDEL

Partial delete, some rows were not deleted.

SS_SMLCK

Partial lock; some rows not locked.

SS_SMUP

Partial update, some rows were not updated.

SS_STFUL

Selection table full.

SS_SYNEXEC EXECUTING clause is not allowed. SS_SYSER

Internal system error.

SS_TXIL

Invalid transaction ID.

SS_UDE

A developer-defined error has occurred.

SS_UDERB

A developer-defined rollback error has occurred.

SS_UDFDB

There was an undefined database column value in an INSERT, UPDATE, or SELECT statement.

SS_UNDACL

An undefined variable was used in an SQL statement or stored procedure.

SS_UNDBTP

An attempt was made to call a stored procedure that expects a boolean value.

SS_UNSPTP

An attempt was made to pass an unsupported data type to a stored procedure, or an attempt was made to use a variable with an unsupported data type for an OUT parameter.

SS_UNVIEW

Attempt to use an unusable view.

SS_UPDNA

Update operation not allowed on form.

SS_USSER

Internal error. Call Customer Support.

SS_VRSION

Incompatible lock manager version.

SS_WRACS

No write permission on row or table.


575

Example

In this example, status$( ) tests the success of the INSERT statement. If the insert operation was not successful, the user is notified by a message in the fyi_message system information field. #include ”sscodes.h” ... INSERT INTO EMPLOYEE IF ( status$() SS_NORM ) THEN DISPLAY ’Cannot Insert the Record’ FOR FYI_MESSAGE WAIT

See also

Script language CREATE PIPELINE (page 213) DEINSTALL (page 230) INSERT (page 301) INSTALL (page 303) SLOCK (page 389) UPDATE SELECTED ROW (page 406)

System functions dbms_status$( ) (page 465) sql_code$( ) (page 562) sql_errmsg$( ) (page 563) sql_state$( ) (page 568)


576


str_search$( ) System function:

NUMERIC

Syntax

str_search$( sourceString, searchString )

Arguments

sourceString

(STRING | TEXT) The string value to search; must be a defined, non-NULL, non-empty STRING value. The searchString argument cannot contain metacharacters or new line characters.

searchString

(STRING) The character pattern searched for.

Return values

NUMERIC

The position in sourceString of the first character of searchString or NULL if searchString was not found.

Description

The str_search$() system function returns the position of the beginning of searchString within sourceString. The first character of sourceString has a position of 1. If searchString occurs more than once in sourceString then the position of the first occurrence only is returned. If searchString does not occur in sourceString then NULL will be returned. sourceString must be a defined, non-NULL STRING or TEXT value.


577

str_to_char_code$( ) System function: convert string or text character

Syntax

str_to_char_code$( character )

Arguments

character

Return values

(NUMERIC)

(STRING/TEXT) The string or text containing the character to be translated.

For valid character: An integer ASCII value in the range 0 to 255. For null character: A null NUMERIC value.

Description

The str_to_char_code$( ) system function converts a single character string or text into its decimal ASCII value.

Example

This SET statement sets the digit variable to the numeric value of the character. IF ( char >= ’0’ AND char 30 ) THEN BEGIN DISPLAY ’Title too long—abbreviate to 30’ FOR FYI_MESSAGE WAIT RESTART ON FIELD END END


585

This example determines whether the memo variable is larger than the 2000 character limit for a text view. If memo contains more than 2,000 characters, it will be opened by the vi editing program. If memo is small, it will be edited within the form field. FIELD ”memo” METHOD ON FIELD BEGIN IF strlen$($memo) > 2000 THEN BEGIN SET tmp_cmd to ’vi ’ + $memo:FILE_PATH system$(tmp_cmd) END ELSE INPUT; END

See also

586

System functions clip_str$( ) (page 437) substr$( ) (page 589)


subbinary$( ) System function: extract portion of binary value

Syntax

subbinary$( binary_value, startsub, endsub )

Arguments

binary_value (BINARY) A BINARY value that contains the binary data to be extracted. startsub

(NUMERIC) A NUMERIC integer for the starting point within binary_value.

endsub

(NUMERIC) A NUMERIC integer for the ending point within binary_value.

Return values

(BINARY)

A BINARY value is returned. For a null binary_value, a NULL value is returned.

Description

The subbinary$( ) system function obtains a portion of binary data from a BINARY value. It returns the data that starts at the startsub index within binary_value and ends at the endsub index. The first character of binary_value has an index value of 1. If startsub is out of the valid range of binary_value, subbinary$( ) returns a zero-length BINARY value. If endsub is greater than the length of binary_value, subbinary$( ) returns all of binary_value starting at startsub (which is shorter than the length you requested with endsub).

Example

This example extracts a set of integers from a list of 4-byte integers. FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1) BEGIN SET $start TO $idx * 4; SET $end TO $start + 4: SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end)); END;

See also

System functions binarylen$( ) (page 431)


587

substitute_str$( ) System function

Syntax

STRING | TEXT

substitute_strs$( STRING | TEXT sourceString, MATRIX substitutionPairList )

Arguments

sourceString

( STRING/TEXT) The value that contains one or more strings to be substituted. sourceString must be a non-NULL, non-empty STRING or TEXT type. The sourceString argument cannot have new line characters in it.

substitutionPairList ( MATRIX) A set of substitution pairs, each pair consisting of a string and a substitutionValue.

Return values

(STRING/TEXT)

Description

Each row in the matrix, substitutionPairList, defines a substitution pair. There must be at least one but no more than 128 rows in substitutionPairList. There must be two columns in each row. A substitution pair consists of a string and a substitutionValue. The value in the first column identifies the string. The string must be a defined, non-NULL, non-empty STRING value. The substitutionValue must be a defined, non-NULL, STRING or TEXT value.

A copy of the original sourceString with each string replaced with its corresponding substitutionValue.

The substitute_strs$() system function scans sourceString for occurrences of each string. Each occurrence of a string will be replaced with its corresponding substitutionValue.

588


substr$( ) System function: extract a string from a value

Syntax

substr$( value, startsub, endsub )

Arguments

value

(STRING or TEXT) The string that contains the substring or subtext to be extracted.

startsub

(NUMERIC) The starting index within value.

endsub

(NUMERIC) The ending index within value.

Return values

(STRING/TEXT) For non-null value, a STRING value is returned if value is of type STRING; a TEXT value is returned if value is of type TEXT. For a null value, a NULL value is returned.

Description

The substr$( ) system function obtains a substring from a value. It returns the substring that starts at the startsub index within string and ends at the endsub index. The first character of value has an index value of 1. If startsub is out of the valid range of value, substr$( ) returns a zero-length string. If endsub is greater than the length of value, substr$( ) returns all of value starting at startsub (which is shorter than the length you requested with endsub).


589

Example

In this example, substr$( ) is used to divide the emp_phone string into an area code (in area_code) and a local telephone number (in local_phone). This example sample assumes that the telephone number in emp_phone is 14 characters long and contains the telephone number in the form (xxx) yyy–yyyy. SET area_code TO substr$(emp_phone, 2, 4) SET local_phone TO substr$(emp_phone, 6, 13)

This example extracts the document header from document_text. SET $tmp_text TO substr$(document_text,1,doc_header_length)

See also

590

System functions clip_str$( ) (page 437) strlen$( ) (page 585)


sync_pipelines$( ) System function: pause for pipeline to close

Syntax

sync_pipelines$( )

Description

The sync_pipelines$( ) function causes execution of the partition to stop until all child processes associated with closed pipelines have terminated. A child process is one started by a CREATE PIPELINE statement. By default, the execution of the CLOSE PIPELINE is stopped for a maximum of one second waiting for the child processes to complete execution. You can use the sync_pipelines$( ) function to stop execution of your partition until all of the child processes have terminated, no matter how long it takes. Use this function when the processing of your partition is dependent on the completion of a process in a pipeline. Child processes associated with open pipelines are not affected by the sync_pipelines$( ) function.

See also

Script language CREATE PIPELINE (page 213)

Example

This example uses the sync_pipelines$( ) function to wait until the RPT process is complete: CREATE PIPELINE $pipe ’RPT script –’, ’sort’, ’uniq’ OUTPUT ’resultfile’; CLOSE PIPELINE $pipe; sync_pipeline$(); system$(’cp resultfile /datafiles/report’);

Related information


For more information about related classes and methods, see Unify VISION: Class Reference

591

system$( ) System function: execute an operating system command

Syntax

system$( command_string )

Arguments

command_string (STRING) The string that contains the command or application to be executed.

Return values

(NUMERIC) 0

The operating system has successfully executed command_string.

UNDEFINED

The command_string is not a valid string expression.

system_value

If the operating system cannot execute command_string, system$( ) returns the value from the operating system function system( ). (Windows) The failure code returned by the WinExec( ) function.

Description

The system$( ) system function executes an operating system command. An operating system command is a command that you would type in at the operating system prompt. UNIX

This function starts a command shell and gives this shell the command_string as input. The shell executes the commands in command_string and then exits. The type of shell that is executed is determined by the setting of the SHELL preference. Windows NT For Windows NT this function starts a command shell and gives this shell the command_string as input. The shell executes the commands in command_string and then exits. The type of shell that is executed is determined by the setting of the SHELL preference. 592


Example

This example uses system$( ) to call the edit editor when the user answers “YES” in the see_totals field. FIELD see_totals METHOD AFTER FIELD IF ( see_totals = TRUE ) THEN system$(’edit /acctapp/totals’)

Windows

This example uses system$( ) to call the notepad editor when the user clicks on button1 with the developer-defined command view_readme. COMMAND view_readme BEGIN system$ (’notepad c:\\acctapp\\read.me’) END

A backslash is required when executing commands built into command.com. To use backslashes, you must precede each backslash with a second backslash: \\. The commands del, copy, ren, and dir are examples of commands that are built into command.com. The following example deletes the amount file after the user clicks on a button. COMMAND delete_file BEGIN set tmpfile to ’\\tmp\\amount’; system$ (’c:\\winnt\\system32\\cmd.exe /c del ’+ $tmpfile); END

See also

System functions background$( ) (page 428) push_shell$( ) (page 537)


593

to_amount$( ) System function: convert a number to an amount

Syntax

to_amount$( number )

Arguments

number

(NUMERIC/FLOAT/BINARY) The value to be converted.

Return values

(AMOUNT)

The AMOUNT value of number.

Description

The to_amount$( ) system function converts a number to an AMOUNT value. The number can be a NUMERIC, FLOAT, or BINARY value. If number is a BINARY value, its length is assumed to be compatible with the length of an AMOUNT value. The to_amount$( ) function can accept an AMOUNT argument. This function returns the AMOUNT value without converting it. If number is a null value, to_amount$( ) returns a null AMOUNT value.

Example

In this example, to_amount$( ) sets the AMOUNT variable amount_val to the AMOUNT value of the two fields dollars and cents. Two NUMERIC values are converted to a single AMOUNT variable. SET money TO (dollars * 100) + cents SET amount_val TO to_amount$(money)

See also

594

System functions to_binary$( ) (page 595) to_bool$( ) (page 596) to_date$( ) (page 597) to_float$( ) (page 599) to_num$( ) (page 601)

to_string$( ) (page 602) to_string_using$( ) (page 604) to_text$( ) (page 606) to_time$( ) (page 608) val_to_str$( ) (page 620)


to_binary$( ) System function: convert a value to a binary value

Syntax

to_binary$( value )

Arguments

value

A value of any type.

Return values

(BINARY)

The binary value of value.

Description

The to_binary$( ) system function converts a value to a BINARY value. The value to be converted can be of any type. For a null value, a NULL BINARY value is returned. The to_binary$( ) function can accept a BINARY argument. It returns the BINARY value without converting it.

Example

This example creates a BINARY variable that contains a list of integers. FOR (SET $idx TO 0; $idx < num_elements; SET $idx TO $idx + 1) BEGIN SET $intlist TO $intlist + to_binary$($numeric_array[$idx]); END;

See also

System functions null_convert$( ) (page 529) to_amount$( ) (page 594) to_bool$( ) (page 596) to_date$( ) (page 597) to_float$( ) (page 599)


to_num$( ) (page 601) to_string$( ) (page 602) to_text$( ) (page 606) to_time$( ) (page 608) val_to_str$( ) (page 620)

595

to_bool$( ) System function: convert a number to a boolean value

Syntax

to_bool$( number )

Arguments

number

Return values

(BOOLEAN)

Description

(NUMERIC/BINARY) The value to be converted.

TRUE

number is nonzero ( 0).

FALSE

number is zero (0).

The to_bool$( ) system function converts a number to a BOOLEAN value. If number is a null value, to_bool$( ) returns a null BOOLEAN value. If number is a BINARY value, its length is assumed to be compatible with the length of a NUMERIC value. The to_bool$( ) function can accept a BOOLEAN argument. This function returns the BOOLEAN value without converting it.

Example

This IF statement uses to_bool$( ) to check whether the expression “num_val + num_val2” is zero. IF ( to_bool$(num_val + num_val2) ) THEN DISPLAY ’num_val + num_val2 is nonzero’ FOR FYI_MESSAGE WAIT

See also

596

System functions null_convert$( ) (page 529) to_amount$( ) (page 594) to_binary$( ) (page 595) to_date$( ) (page 597) to_float$( ) (page 599) to_num$( ) (page 601)



to_date$( ) System function: convert a number or a datetime value to a date

Syntax

to_date$( value )

Arguments

value

(NUMERIC/BINARY/DATETIME) The value to be converted.

Return values

(DATE)

The DATE value of number.

Description

The to_date$( ) system function converts a number to a DATE value. The number can be any NUMERIC or BINARY value in the range of DATE values valid in the database. If number is a BINARY value, its length is assumed to be compatible with the length of a DATE value. The to_date$( ) function can accept a DATE argument. This function returns the DATE value without converting it. For DATETIME arguments, the returned date is the date portion of the datetime argument. If the datetime argument has an undefined date portion, then the returned date is undefined. If number is a null value, to_date$( ) returns a null DATE value.

Example

This SET statement uses to_date$( ) to set the DATE variable date_val to the DATE value of 200. The DATE value of 200 is 6/04/90. SET date_val TO to_date$(200)

See also

System functions date_to_mdy$( ) (page 457) mdy_to_date$( ) (page 527) null_convert$( ) (page 529) str_to_date$( ) (page 579) to_amount$( ) (page 594) to_binary$( ) (page 595) to_bool$( ) (page 596)


to_datetime$( ) (page 598) to_float$( ) (page 599) to_num$( ) (page 601) to_string$( ) (page 602) to_text$( ) (page 606) to_time$( ) (page 608) val_to_str$( ) (page 620)

597

to_datetime$( ) System function: convert a value to datetime

Syntax

to_datetime$( value)

Arguments

value

(DATE, TIME, BINARY) The value to be converted.

Return values

(DATETIME)

A value of type DATETIME converted from the value argument.

Description

The to_datetime$( ) function converts the specified value to a value of type DATETIME. If value is a NULL value, a null-valued datetime is returned. The value is converted by the rules for assignment-compatible data types. If value is a DATE value, the time portion of the result is 00:00:00.00 (midnight). If value is a TIME value, the date portion of the result is undefined. If value is a BINARY value, its length is assumed to be compatible with the length of a DATETIME value. The to_datetime$( ) function can accept a DATETIME argument. This function returns the DATETIME value without converting it.

See also

System functions

str_to_datetime$( ) (page 581)

Example

This example uses the to_datetime$( ) function to convert a date value to datetime; for instance, the following sets dt to 01/02/97 00:00.000: SET d to 01/02/97 SET dt to_datetime$(d)

For information about conversion of compatible data types, see “Data types” in Unify Related information VISION: Application Reference.

598


to_float$( ) System function: convert a number to float

Syntax

to_float$( number )

Arguments

number

(NUMERIC/AMOUNT/BINARY) The value to be converted.

Return values

(FLOAT)

The FLOAT value of number.

Description

The to_float$( ) system function converts a number to a FLOAT value. The number can be a NUMERIC, BINARY, or AMOUNT value. If number is a BINARY value, its length is assumed to be compatible with the length of a FLOAT value. The to_float$( ) function can accept a FLOAT argument. This function returns the FLOAT value without converting it.

If number is a null value, to_float$( ) returns a null FLOAT value.

Example

This SET statement uses to_float$( ) to set the FLOAT variable float_val to the FLOAT value of 897. The FLOAT value of 897 is 897.00. SET float_val TO to_float$(897)

See also

System functions null_convert$( ) (page 529) to_amount$( ) (page 594) to_binary$( ) (page 595) to_bool$( ) (page 596) to_date$( ) (page 597) to_num$( ) (page 601)



599

to_julian$( ) System function: return the number of Julian days in a value

Syntax

to_julian$( value )

Arguments

value

(DATE, DATETIME) The value to be converted; the date portion of a datetime value must be defined.

Return values

(NUMERIC)

The number of Julian days in the value argument.

Description

The to_julian$( ) function returns the number of Julian days represented by the month and day in the year. The Julian day is the integer number of the day’s placement in the year.

Example

This example uses the to_julian$( ) function to convert a value to its Julian equivalent; the value 60 is returned: SET julianDays to to_julian$(2/29/96 16:15:00)

600


to_num$( ) System function: convert a value to numeric

Syntax

to_num$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/FLOAT/TIME) The value to be converted.

Return values

(NUMERIC)

The NUMERIC value of value.

Description

The to_num$( ) system function converts a value to a NUMERIC value. This value can be of any type except STRING or TEXT. If the argument is a FLOAT or AMOUNT, it must be in the range between –231 and +231–1; otherwise, it is truncated. If the argument is a BOOLEAN, FALSE returns 0 and TRUE returns 1. If the argument is DATE or TIME, any value is legal and the inverse of the to_date$( ) or to_time$( ) functions will be performed. If value is a BINARY value, its length is assumed to be compatible with the length of a numeric value. The to_num$( ) function can accept a NUMERIC argument. This function returns the NUMERIC value without converting it. If value is a null value of type AMOUNT, BOOLEAN, DATE, FLOAT or TIME, to_num$( ) returns a null NUMERIC value.

Example

This SET statement uses to_num$( ) to set the NUMERIC variable num_val to the NUMERIC value of 8997.34. The NUMERIC value of 8997.34 is 8997. SET num_val TO to_num$(8997.34)

See also

System functions null_convert$( ) (page 529) str_to_val$( ) (page 583) to_amount$( ) (page 594) to_binary$( ) (page 595) to_bool$( ) (page 596) to_date$( ) (page 597)


to_float$( ) (page 599) to_string$( ) (page 602) to_text$( ) (page 606) to_time$( ) (page 608) val_to_str$( ) (page 620)

601

to_string$( ) System function: convert a value to string

Syntax

to_string$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/DATETIME/FLOAT/NUMERIC/ OBJECT_REF/TEXT/TIME) The value to be converted.

Return values

(STRING)

The string value of value.

Description

The to_string$( ) function converts value to a string. This value can have any of the following Unify VISION data types: NUMERIC, FLOAT, BOOLEAN, AMOUNT, DATE, TEXT, BINARY, or TIME. The to_string$( ) function converts value from one internal data type format to another. The val_to_str$( ) function converts value from one external (display) data type format to another. Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string containing the number. Amount values include the radix separator but not the currency symbol. Float values are not rounded. BOOLEAN values are converted to the strings “YES” or “NO”. DATE and TIME values are converted to their string equivalents. Text values are truncated at the first newline character. Binary values are truncated at the first newline or other control character or at the first unprintable character. For DATETIME arguments, the returned string is in the default datetime format with a two-digit year.

602


The to_string$( ) function can accept a STRING argument. This function returns the STRING value without converting it. If value contains a null value of any data type, to_string$( ) returns a null string. To return a string containing the null format for the data type associated with value, use the Unify VISION system function val_to_str$( ). The default null display character for strings is *. You can change the STRING null character by setting the STRNULLCH preference.

Example

The first SET statement uses to_string$( ) to assign the string “91” to char_val. SET char_val TO to_string$(91)

The next SET statement uses to_string$( ) to assign to date_str the string equivalent of the DATE value in in_date. If in_date has a DATE value of 7/12/87, date_str contains the string 07/12/87. If in_date contains a null value, date_str contains the null string ***********. SET date_str TO to_string$(in_date)

This last example statement uses to_string$( ) to convert the NULL constant into a null STRING value. This null value is then passed as an argument to the user-defined VISION 4GL function user_func( ). SET result TO user_func( to_string$(NULL) )

The NULL constant has no data type associated with it. To use this constant as an argument (or in any context where data type is required), the constant must be converted to a null value that has a data type. You can use any of the data type conversion functions (such as to_amount$( ), to_bool$( ), to_date$( ), to_float$( ), and to_time$( ) ) in the same way.

See also

System functions str_to_val$( ) (page 583) to_amount$( ) (page 594) to_binary$( ) (page 595) to_bool$( ) (page 596) to_date$( ) (page 597)


to_float$( ) (page 599) to_num$( ) (page 601) to_string_using$( ) (page 604) to_text$( ) (page 606) val_to_str$( ) (page 620)

603

to_string_using$( ) System function: format a value

Syntax

to_string_using$( value, format_string )

Arguments

value

(AMOUNT/DATE/DATETIME/FLOAT/NUMERIC/STRING/TEXT/TIME) The value to be formatted.

format_string

(STRING) The string that contains the formatting information.

Return values

(STRING)

The value formatted according to format_string.

Description

The to_string_using$( ) system function formats a value according to the format_string. This value can actually have any of the Unify VISION data types except OBJECT_REF. However, you can specify a format string only for the data types AMOUNT, DATETIME, FLOAT, NUMERIC, STRING, or TEXT. If value is a null value, to_string_using$( ) returns a string filled with the appropriate null character. The default null display character for strings is *. The null string returned has the length of format_string regardless of the format actually in this string. The format_string can include any of the display formats valid in the USING clause of the DISPLAY statement. The USING clause determines how AMOUNT, NUMERIC, FLOAT, and STRING values appear in the field window. If format_string is a null string or is a zero-length string, to_string_using$( ) uses a default string format. This format is the same format used by the DISPLAY statement when the USING clause is omitted. For DATETIME arguments, if the date portion of the datetime is undefined, then the format template cannot contain any date format template characters. This function is useful if you need to send formatted data over a pipeline. You can capture the results of a DISPLAY USING statement with to_string_using$( ).

604


Example

This SET statement uses to_string_using$( ) to set the STRING variable amount_str to the formatted value of the AMOUNT variable amount_val. If amount_val contains the value 1246.75, amount_str contains the string $1,246.75. SET amount_str TO to_string_using$(amount_val, ’$$,$$$.&&’)

See also

System functions to_amount$( ) (page 594) to_bool$( ) (page 596) to_float$( ) (page 599)

to_string$( ) (page 602) val_to_str$( ) (page 620)

For information about format templates, see “Format templates” in Unify VISION: Related information Application Reference.


605

to_text$( ) System function: convert a value to text

Syntax

to_text$( value )

Arguments

value

A value of any type.

Return values

(TEXT)

The text value of value.

Description

The to_text$( ) system function converts a value of any type to a TEXT value. If value is NULL, the value returned is NULL. Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string containing the number. Amount values include the radix separator but not the currency symbol. Float values are not rounded. BOOLEAN values are converted to the strings “YES” or “NO”. DATE, DATETIME, and TIME values are converted to their string equivalents. The to_text$( ) function can accept a TEXT argument. It returns the TEXT value without converting it. Binary values are truncated at the first newline or other control character or at the first unprintable character.

606


Example

This example creates a text variable that contains a list of employee names and hire dates. SET $first_name, $last_name, $hire_date TO SELECT first_name, last_name, hire_date FROM employee WHERE hire_date < $year_end EXECUTING BEGIN SET $tmp_text TO $tmp_text + $first_name + ’ ’ + $last_name + ’ ’; SET $tmp_text TO $tmp_text + to_text$($hire_date); SET $tmp_text TO $tmp_text + char_code_to_str$(013); END;

See also

System functions null_convert$( ) (page 529) to_amount$( ) (page 594) to_binary$( ) (page 595) to_bool$( ) (page 596)


to_date$( ) (page 597) to_float$( ) (page 599) to_num$( ) (page 601) to_string$( ) (page 602)

607

to_time$( ) System function: convert a number or a datetime to time

Syntax

to_time$( value )

Arguments

value

(NUMERIC/BINARY/DATETIME) The value to be converted.

Return values

(TIME)

The TIME value of number.

Description

The to_time$( ) system function converts a number to a TIME value. The number can be any integer and is interpreted as the number of minutes since midnight. If number is a BINARY value, its length is assumed to be compatible with the length of a TIME value. The to_time$( ) function can accept a TIME argument. This function returns the TIME value without converting it. If number is a null value, to_time$( ) returns a null TIME value. For DATETIME arguments, the returned time is the time portion of the datetime argument, truncated to hours and minutes.

Example

This SET statement uses to_time$( ) to set the TIME variable time_val to the TIME value of 572. The TIME value of 572 is 9:32. SET time_val TO to_time$(572)

See also

608

System functions null_convert$( ) (page 529) str_to_time$( ) (page 582) to_amount$( ) (page 594) to_binary$( ) (page 595)

to_bool$( ) (page 596) to_date$( ) (page 597) to_float$( ) (page 599) to_num$( ) (page 601)


to_value$( ) System function: pass macro arguments to SQL

Syntax

to_value$( value )

Arguments

value

Return values

Any Unify VISION constant, variable, or expression.

A Unify VISION object.

Description

The to_value$( ) system function allows macro arguments to be passed as Unify VISION objects to an SQL statement.

Example

When the select1 macro is expanded by the preprocessor, the to_value$( ) system function is recognized as a Unify VISION object. The value of arg1 is therefore prepared as a Unify VISION object within an SQL statement. #define select1(arg1) \ SELECT emp_last_name FROM employee WHERE emp_last_name = to_value$(arg1)


609

trim_bytes$( ) System function: string building

Syntax

trim_bytes$ ( buffer, trim_char )

Return values

(STRING/TEXT/BINARY) The same type as the buffer argument.

Arguments

buffer

(STRING/TEXT/BINARY) Specifies the variable to trim characters from.

trim_char

(STRING/NUMERIC) Specifies the value of the trim character.

Description

This function returns a value that is of the same type as the buffer argument. This returned value is a copy of the original buffer with any trailing characters of value trim_char removed. Although the description of this routine is mostly character-oriented, when the buffer parameter is of type BINARY, this routine is byte-oriented instead of character-oriented. This distinction is apparent only when characters are encoded into a multi-byte character set such as Unicode. If the buffer parameter is of type BINARY, then trim_char must be type NUMERIC. If the buffer parameter is of type STRING or TEXT, then trim_char must be type STRING. When trim_char is of type NUMERIC, it must have a value between 0 and 255 inclusive. It represents the decimal value of the byte to trim. When trim_char is of type STRING, the first character of the STRING is used as the character to trim.

610


If trim_char is a STRING of zero length, then no trimming is done and the returned value is a copy of buffer. This behavior is defined to be consistent with the pad_str_right$( ) system function. The trim_char parameter must not be NULL. If buffer is type STRING or TEXT, then this function will not remove trailing bytes that are part of the last multi-byte character. If the parameter buffer is NULL, then NULL is returned. This behavior is defined to be consistent with the pad_str_right$( ) system function.

Example

This example uses the trim_bytes$( ) function to remove trailing spaces: SET CustFld to substr$($Buffer, 11, 34) SET CustomName to trim_bytes$(CustFld, ’ ’)

See also

System functions

copy_in$( ) (page 440) pad_str_right$( ) (page 535)

For more information about MQSeries, see Unify VISION:Interconnecting Related information Applications with Enterprise Integrator.


611

tx_mode$( ) System function : enable transaction handling

Syntax

tx_mode$( mode )

Support


DBMS dependent

INFORMIX

Supported for INFORMIX SE only. The tx_mode$( ) system function has no effect for INFORMIX MODE ANSI.

INGRES

The tx_mode$( ) function has no effect because INGRES automatically starts a multi-step transaction at the first SQL statement after a connect, commit, or rollback statement.

ORACLE

The tx_mode$( ) system function has no effect for ORACLE.

SYBASE SQL

Supported.


The tx_mode$( ) system function has no effect for Unify DataServer.

Arguments

mode

Return values

(BOOLEAN)

612

One of the values TRUE, FALSE, or UNDEFINED.

TRUE

Automatic transaction handling is enabled.

FALSE

Automatic transaction handling is disabled.


Description

The tx_mode$( ) system function specifies whether automatic transaction handling is enabled or disabled. By default, the ACLTXMODE preference is set to TRUE and Unify VISION automatically begins and commits transactions. However, if the ACLTXMODE preference is set to FALSE, automatic transaction handling is disabled. When automatic transaction handling is disabled, transaction level specifications have no effect, and shared locks are released after a commit or rollback operation. You can use tx_mode$( ) to dynamically enable or disable automatic transaction handling, regardless of the setting of ACLTXMODE. To determine (but not change) the current transaction mode, specify the UNDEFINED argument for tx_mode$( ). The tx_mode$( ) system function returns the value returned by the most recently executed SQL statement, regardless of the current database connection. ODBC interface

The tx_mode$( ) has no effect.

Example

In this example, automatic transaction handling is first disabled, and then the current transaction, if any, is committed. A new transaction is then started to process and commit an update operation. tx_mode$(FALSE) COMMIT WORK BEGIN WORK UPDATE emp SET vac = vac + 8; COMMIT WORK

See also

Script language BEGIN WORK (page 181) CHOOSE FORM USING (page 191) COMMIT WORK (page 201) ROLLBACK WORK (page 367)


613

Related For information about transaction control, see “Managing transactions and locks” in information Unify VISION: Developing an Application. For information about related external preferences, see “External preferences syntax descriptions” in Unify VISION: Application Reference: ACLTXMODE

614


ui_type$( ) System function: determine user interface

Syntax

ui_type$( variable )

Arguments

variable

(STRING) A variable that returns the current presentation mode. OPENLOOK

OPEN LOOK graphical user interface

MOTIF

Motif graphical user interface

MSWINDOWS Windows user interface

Return values

Description

(BOOLEAN) TRUE

The ui_type$( ) function was completed successfully.

FALSE

The ui_type$( ) function failed because an internal error occurred.

The ui_type$( ) system function enables you to return at runtime information about the user interface being used. You can use the ui_type$( ) function to execute conditional script segments that are specific to a user interface. This function fails only when an internal error occurs.


615

Example

This example deletes a log file from the operating system. Since delete commands are operating system dependent, the developer must determine the operating system before deleting the file. The developer uses the ui_type$( ) function in combination with the background$( ) and system( ) functions to delete the file. COMMAND delete_amount /* Button on form displays ”Delete Amount Log File” */ BEGIN IF ui_type$($gui_mode) = FALSE THEN BEGIN /* Internal error should never occur */ DISPLAY NOTICE ’–55 Internal error. Please call your support person’ LABELS ’OK’ RESULT INTO uifunction_answer END ELSE IF $gui_mode = ’MSWINDOWS’ THEN /* Windows operating system */ BEGIN SET tmpfile TO ’\\tmp\\amount’; system$(’c:\\winnt\\command.com /c del ’ + $tmpfile) /* Deletes amount file */ END ELSE IF $gui_mode = ’OPENLOOK’ OR $gui_mode = ’MOTIF’ THEN /* UNIX operating system */ BEGIN SET tmpfile TO ’/tmp/amount’; background$(’/bin/csh’,’rm ’ + $tmpfile) /* Deletes amount file */ END END

See also

616

System functions db_type$( ) (page 463) os_type$( ) (page 532)


unique_sequence$( ) System function: return a unique numeric value

Syntax

unique_sequence$( )

Arguments

None.

Return values

(NUMERIC)

Description

Each time the unique_sequence$( ) system function is executed, it returns a unique NUMERIC value. The values returned are not necessarily a consecutive sequence.

Example

In this example, a new form is created. Its name is assigned a unique value by appending a unique sequence number. The unique numeric value is converted to a STRING value by the to_string$( ) system function.

A unique NUMERIC value.

VOID FUNCTION launch_a_form(form_class, RESULT name_of_form, RESULT form_object_id) BEGIN SET $name_of_form TO $form_class+’_’+to_string$(unique_sequence$()) CHOOSE FORM USING CHILD FORM $form_name OF CLASS $form_class OBJECT_REF INTO $form_object_id END


617

user_id$( ) System function: obtain user’s ID

Syntax

user_id$( )

Support

Support for this feature is platform dependent. UNIX

Supported.

Windows

For Windows, this function returns 0.

Return values

(NUMERIC)

The operating system user ID number of the user.

Description

The user_id$( ) system function obtains the user’s ID number from the operating system. This function is useful for recording the identity of the user who makes certain modifications to the database.

Example

In this example, user_id$( ) sets the emp_uid variable to the user ID of the user who is currently executing the application. METHOD BEFORE ADD SET emp_uid TO user_id$()

See also

618

System functions get_password$( ) (page 508) group_id$( ) (page 515)

group_name$( ) (page 516) user_name$( ) (page 619)


user_name$( ) System function: obtain the user’s login name

Syntax

user_name$( )

Support

Support for this feature is platform dependent. UNIX

Supported.

Windows

For Windows, the user_name$( ) system function returns the login name of the user.

Return values

(STRING)

The operating system login name of the user.

Description

The user_name$( ) system function obtains the user’s login name from the operating system user file. This function is useful for recording the identity of the user who makes certain modifications to the database.

Example

In this example, user_name$( ) sets the emp_name variable to the login name of the user who is currently executing the application. METHOD BEFORE ADD SET emp_name TO user_name$()

See also

System functions get_password$( ) (page 508) group_id$( ) (page 515)


group_name$( ) (page 516) user_id$( ) (page 618)

619

val_to_str$( ) System function: convert a value to string

Syntax

val_to_str$( value )

Arguments

value

(AMOUNT/BINARY/BOOLEAN/DATE/DATETIME/FLOAT/NUMERIC/ OBJECT_REF/TEXT/TIME) The value to be converted.

Return values

(STRING)

The string value of value. (Partitioned applications only) The value argument can include OBJECT_REF values.

Description

The val_to_str$( ) system function converts value to a string. Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a string containing the number. Amount values include the decimal point but not the dollar sign. Float values are not rounded. Boolean values are converted to the strings “YES” or “NO”. Date and time values are converted to their string equivalent. Text values are truncated at the first newline or other control character. Binary values are truncated at the first control character or at the first unprintable character. No leading or trailing spaces are included in the returned string. For DATETIME arguments, the returned string is in the default datetime display format. If value contains a null value, val_to_str$( ) returns a string containing the null value for the data type associated with value. To return a null string when value is null, use the system function to_string$( ).

620


The to_string$( ) function converts value from one internal data type format to another. The val_to_str$( ) function converts value from one external (display) data type format to another. The default null display character is *. You can change the null display characters by setting preferences: AMTNULLCH BOLNULLCH DATNULLCH DTTMNULLCH FLTNULLCH STRNULLCH TIMNULLCH TXTNULLCH

Example

This SET statement uses val_to_str$( ) to assign the string “91” to char_val. SET char_val TO val_to_str$(91)

This SET statement uses val_to_str$( ) to assign to date_str the string equivalent of the DATE value in in_date. If in_date had a DATE value of 7/12/87, date_str would contain the string 07/12/87. If in_date contained a null value, date_str would contain the null string for DATE: **********. SET date_str TO val_to_str$(in_date)

See also

System functions null_convert$( ) (page 529) str_to_val$( ) (page 583) to_amount$( ) (page 594) to_binary (page 595) to_bool (page 596)


to_date$( ) (page 597) to_float (page 599) to_num$( ) (page 601) to_string$( ) (page 602) to_string_using$( ) (page 604)

621

yesno$( ) System function: display a notice box

Syntax

yesno$( yes_no_msg, default_value )

Arguments

yes_no_msg

(STRING) A string containing the question to be displayed in a notice box.

default_value

(NUMERIC) An integer value to control the default response to the question’s possible values:

Return values

Description

1

Default response is “yes”.

0

Default response is “no”.

–1

No default; user response is required.

–2

Responses are auto-accepted; “yes” is the default value.

–4

Responses are auto-accepted, and the user must respond; there is no default value.

(BOOLEAN) TRUE

The user’s response to the yes_no_msg prompt is either “yes” or “YES”.

FALSE

The user’s response to the yes_no_msg prompt is either “no” or “NO”.

The yesno$( ) system function displays a prompt message, yes_no_msg, in a notice box and then waits for the user’s response. The default_value controls the default action for the response. If default_value is set to –1, the user must respond.

622


Example

This example uses yesno$( ) to ask the user whether to continue to the next record if the current record is not stored in the database. METHOD ON NEXT RECORD IF ( NOT (is_current_record_stored$() ) ) THEN BEGIN IF ( yesno$( ’You are about to lose your record changes. Save them?’, –1) ) THEN BEGIN DISPLAY ’Updating...’ for FYI_MESSAGE UPDATE CURRENT RECORD DISPLAY ’Record Updated’ FOR FYI_MESSAGE END END

If the current record is not stored and the user answers “yes” to the prompt: You are about to lose your record changes? Save them?

The current record is stored with the UPDATE CURRENT RECORD statement.


623

7 Predefined C functions This chapter contains complete descriptions of predefined C functions. These functions can be called by C-hooks which are global functions written in the C language. A discussion of C-hooks and their implementation is found in Unify VISION: Concepts. Descriptions of the predefined C functions appear in alphabetical order and include several parts:

Syntax

Presents the syntax for the function. BOLDFACE words are keywords. Italicized words within the syntax are described under Arguments.

Support

Describes restrictions or dependencies, if any.

Arguments

Describes the italicized arguments shown in the syntax.

Return values Describes the values returned by the function. Arguments

Describes values the variable can return.

Description

Describes usage, conditions, and notes.

Example

Gives a sample that shows how the function might be used.

See also

Lists related statements described in this manual.

Related information Lists chapters or topics in other manuals that are related to the function. 625

uacldb( ) Predefined C function

Syntax

Unify DataServer only

#include [ #include ] #include int uacldb(dbidp, status) UDBID *dbidp; USTATUS *status;

Support

Support for this feature is DBMS dependent. INFORMIX

The uacldb( ) C function is not supported for INFORMIX. The function returns TRUE with *dbidp set to 1.

INGRES

The uacldb( ) C function is not supported for INGRES. The function returns TRUE with *dbidp set to 1.

ORACLE

The uacldb( ) C function is not supported for ORACLE. The function returns TRUE with *dbidp set to 1.

SYBASE SQL

The uacldb( ) C function is not supported for SYBASE SQL Server. The function returns TRUE with *dbidp set to 1.

Server

Unify DataServer

Supported.

Arguments 626

dbidp

Pointer to the returned database ID. Unify VISION: 4GL Reference

Return values

Status values

Description

status

Pointer to the returned RHLI function system value.

USUCCESS

The operation was successful.

UFAILURE

A failure occurred during the operation. Check the status value for the error.

UENORM

Operation was successful. The dbidp parameter points to the database ID.

UEDBCLS

The database is closed.

The uacldb( ) function sets the passed parameter dbidp pointer to the location of the database identifier for the database opened by Unify VISION. All #include statements specified in the syntax are required in the caller’s source file.

Warning

Never attempt to close the database that has been opened by Unify VISION. Unify VISION automatically closes the database when the application exits. Unify VISION returns the database ID of the database connection of the current form. If the connection is not open, uacldb( ) also opens the connection.

Chapter 7: Predefined C functions

627

Example

The following example prints a message if the current database ID could not be retrieved. UDBID dbid; if (! uacldb(&dbid, &status)) { fprintf(stderr, ”Unable to get database ID: status = %ld\n”, status); } else { /* Get current process ID */ if (! uallpid(dbid, &npid, &pidl, &status)) { fprintf(stderr, ”Unable to get all process ID info: status = %ld\n”, status); } if (npid > 0) { free ((char *) pidl); }

See also

Predefined C functions uaclrid( ) (page 639) uacltx( ) (page 641)

See also Unify DataServer: SQL/A Language Reference. Related information For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.

628


uacldbp( ) Predefined C function

Syntax

SYBASE SQL Server only

#include #include #include int uacldbp(dbprocess, status) DBPROCESS **dbprocess; USTATUS *status;

Support


The uacldbp( ) function is not supported for INFORMIX.

INGRES

The uacldbp( ) C function is not supported for INGRES.

ORACLE

The uacldbp( ) function is not supported for ORACLE.

SYBASE SQL

Supported.


The uacldbp( ) function is not supported for Unify DataServer.

Arguments

dbprocess

Address of a pointer to the SYBASE SQL Server DBPROCESS structure.

status

Pointer to the returned function status value.


629

Return values

Status values

Description

TRUE


FALSE


UEDBCLS


UECMFATL

Internal error (nonfatal).

The uacldbp( ) C function sets the passed DBPROCESS pointer to the address of the SYBASE SQL Server database to be used by VISION Runtime Manager. The DBPROCESS structure is required to perform any database operation through the SYBASE DB-Library SQL Interface. C-hooks can use the SYBASE DB-Library SQL Interface functions with the pointer to the DBPROCESS structure obtained by calling this function. Call the uacldbp( ) function every time you call a C-hook to perform a SYBASE SQL Server DB-Library call. If a scan is active, uacldbp( ) saves the active scan in the nested query manager area. The sybfront.h and sybdb.h include files are used to call SYBASE SQL Server routines or declare SYBASE SQL Server variables. Attempting to call uacldbp( ) for an unsupported DBMS results in a null pointer. All #include statements specified in the syntax are required in the caller’s source file. Unify VISION returns the DBPROCESS for the connection of the current form. If the connection is not open, uacldbid( ) also opens the connection.

630


Example

The following example shows how the uacldbp( ) function can be used to acquire a pointer to the DBPROCESS structure and perform database operations. DBPROCESS *dbprocess; USTATUS status; /* get dbprocess */ if(!uacldbp(&dbprocess, &status)) { fprintf(stderr, ”Unable to get a pointer to DBPROCESS”); return(0); }

See also

Predefined C functions uaclwhr( ) (page 644)

For information about C-hook functions, see “Creating and calling 3GL functions” in Related information Unify VISION: Developing an Application. For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.


631

uaclGetDatetime( ) Predefined C function

Syntax

#include int uaclGetDatetime( dt, y, m, d, h, i, s, ms ) AVAL *dt; int *y, *m, *d, *h, *i, *s, *ms;

Arguments

Return values

Description 632

dt

The AVAL structure that contains the date, time, or datetime value.

y

Pointer to the returned year.

m

Pointer to the returned month.

d

Pointer to the returned day.

h

Pointer to the returned hour.

i

Pointer to the returned minute.

s

Pointer to the returned second.

ms

Pointer to the returned milliseconds.

1


0

A failure occurred during the operation.

This function will get the constituent parts from the dt AVAL structure and place the Unify VISION: 4GL Reference

integer values in each of the arguments pointed to by y, m, d, h, i, s, and ms. The dt argument may be of type DATETIME, DATE, or TIME. If it is of type DATE or TIME, only the appropriate arguments receive values. All #include statements specified in the syntax are required in the caller’s source file. For datetime values, if the date portion of dt is undefined, the returned date portion is 0/0/0.

See also

Predefined C functions uaclPutDatetime( ) (page 637)

For more information about using 3GL functions, see “Creating and calling 3GL Related information functions” in Unify VISION: Developing an Application.


633

uacllda( ) Predefined C function

Syntax

ORACLE only

#include [ #include ] #include int uacllda(lda, status) char **lda; USTATUS *status;

Support


The uacllda( ) C function is not supported for INFORMIX.

INGRES

The uacllda( ) C function is not supported for INGRES.

ORACLE

Supported.

SYBASE SQL

The uacllda( ) C function is not supported for SYBASE SQL Server.

Server

Unify DataServer

The uacllda( ) C function is not supported for Unify DataServer.

Arguments

Return values

634

lda

Pointer to the returned address of the ORACLE LDA structure.

status


TRUE


FALSE

A failure occurred during the operation. Check the status value for the error. Unify VISION: 4GL Reference

Status values

Description

UEDBCLS


UEINVAL

Invalid value; value is not valid on the current database.

UEFAULT

Invalid parameter passed.

UENORM

Operation successful.

The uacllda( ) function sets the pointer to the LDA (ORACLE login data area) structure for the ORACLE database used by VISION Runtime Manager. The LDA structure is required to perform any database operation through the ORACLE Call Interface (OCI). C-hooks can use the OCI functions with the pointer to the LDA structure obtained by calling this function. Attempting to call uacllda( ) for an unsupported DBMS results in a linking error. For more information, refer to the ORACLE OCI documentation. The #include statements specified in the syntax are required in the caller’s source file. Unify VISION passes the form connection information to the C function. If the connection is not open, uacllda( ) also opens the connection.

Example

The following example shows how the uacllda( ) function can be used to acquire a pointer to the LDA (ORACLE login data area) structure and perform database operations. This example finds all tables owned by the current user. LDA *lda; CDA crs1, crs2; USTATUS status; /* get lda */ if(!uacllda(&lda, &status)) { fprintf(stderr, ”Unable to get a pointer to LDA ); return(0); } /* open cursor */ if (oopen(&crs1, lda, (char *)0, –1, –1, (char *)0, –1)) { return(0); } /* parse query */


635

if (osql3(&crs1, ”select TNAME from TAB where TABTYPE=’TABLE’”, –1)) { return(0); } /* execute query */ if (oexec(&crs1)) { return(0); }


636


uaclPutDatetime( ) Predefined C function

Syntax

#include int uaclPutDatetime( dt, y, m, d, h, i, s, ms ) AVAL *dt; int y, m, d, h, i, s, ms;

Arguments

Return values

dt

The AVAL structure to contain the time, date, or datetime value.

y

The year in the datetime value.

m

The month in the datetime value.

d

The day in the datetime value.

h

The hour in the datetime value.

i

The minute in the datetime value.

s

The second in the datetime value.

1


0

A failure occurred during the operation.


637

Description

This function places the constituent parts of a time, date, or datetime value into the date, time, or datetime dt AVAL structure. If the data type of dt is unset, it is defined to be of type DATETIME. If the data type of dt is DATE or DATETIME, then the numeric arguments must result in a valid date value or 0/0/00 for datetime values. Otherwise, AVAL is returned as undefined in the dt structure. Arguments not applicable to the data type of dt are ignored. All #include statements specified in the syntax are required in the caller’s source file. For datetime values, if the y/m/d value is 0/0/0, then the date portion of dt is set to undefined.

See also

Predefined C functions uaclGetDatetime( ) (page 626)

For more information about using 3GL functions, see “Creating and calling 3GL Related information functions” in Unify VISION: Developing an Application.

638


uaclrid( ) Predefined C function

Syntax


#include #include #include URID uaclrid(status) USTATUS *status ;

Support


The uaclrid( ) C function is not supported for INFORMIX. The function returns FALSE with *status set to 0.

INGRES

The uaclrid( ) C function is not supported for INGRES. The function returns FALSE with *status set to 0.

ORACLE

The uaclrid( ) C function is not supported for ORACLE. The function returns FALSE with *status set to 0.

SYBASE SQL

The uaclrid( ) C function is not supported for SYBASE SQL Server. The function returns FALSE with *status set to 0.

Server

Unify DataServer

Supported.

Arguments

status

Pointer to the returned RHLI function system status value.

Return values

Row ID


UNULLRID

An attempt was made to access an unsupported DBMS or an error occurred


639

Status values

Description

UENOROW

The row ID cannot be retrieved.

UENOIMP

An attempt was made to access an unsupported DBMS.

The uaclrid( ) function retrieves the identifier of the row in the selected set that is currently being processed by pmgr. The row identifier is useful for retrieving text and binary information. The uaclrid( ) function is valid only on a form with a target table. This function should not be called by a C-hook that is called from a global function. Use uaclrid( ) only in add-update mode, not in find mode. If uaclrid( ) is called when there is no selected set, the function fails and the status value is set to UENOROW. The #include statements specified in the syntax are required in the caller’s source file.

Warning

See also

Do not modify displayable fields. Modifying columns of the row does not cause the AMGR display to be updated.

Predefined C functions uacldb( ) (page 626) uacltx( ) (page 641) uaclwhr( ) (page 644)

See also Unify DataServer: Writing RHLI Applications. Related information

640


uacltx( ) Predefined C function


Syntax

#include [ #include ] #include int uacltx(txidp, status) UTXID *txidp; USTATUS *status;

Support


The uacltx( ) C function is not supported for INFORMIX. The function always returns TRUE with *txidp set to 1.

INGRES

The uacltx( ) C function is not supported for INGRES. The function always returns TRUE with *txidp set to 1.

ORACLE

The uacltx( ) C function is not supported for ORACLE. The function always returns TRUE with *txidp set to 1.

SYBASE SQL

The uacltx( ) C function is not supported for SYBASE SQL Server. The function always returns TRUE with *txidp set to 1.

Server

Unify DataServer

Supported.

Arguments

txidp

Pointer to the returned Unify VISION current transaction ID.

status

Pointer to the returned RHLI function system value.


641

Return values

Status values

Description

TRUE


FALSE


UEILTX

The transaction ID is invalid.

UEDBCLS


For Unify DataServer, the uacltx( ) function stores the current transaction ID to the location specified by txidp. It is useful in C-hooks that call RHLI functions. Any of the status values returned by sqlcbtx( ) are possible. Refer to the Unify DataServer documentation. The #include statements specified in the syntax are required in the caller’s source file.

Warning

Never attempt to roll back or commit the current Unify VISION transaction through the RHLI. Use the ACCELL/4GL ROLLBACK WORK statement to roll back a Unify VISION transaction. A transaction can be committed either by using the ACCELL/4GL COMMIT WORK statement or by starting execution of a form at the Start Tx or Restart Tx transaction level. Unify VISION passes the form connection information to the C function. If the connection is not open, uacldb( ) also opens the connection.

Example

The following example prints a message if unable to retrieve the current transaction ID. UTXID txid; USTATUS stat; USTATUS statl[1]; UUSRINF usrinf; UOID uid; if (! uacltx(&txid, &stat)) {

642


fprintf(stderr, ”Unable to get a transaction ID: status = %ld\n”, stat); } else { /* Get info about current user */ uid = getuid(); if (! uinfusr(txid, 1, &uid, UCLASS2, &usrinf, statl, &stat)) { fprintf(stderr, ”Unable to get current user info: status = %ld\n”, stat); } }

See also

Predefined C functions uacldb( ) (page 626) uaclrid( ) (page 639)

See also Unify DataServer: SQL/A Language Reference. Related information For information about multiple database connections, see “Getting started” in Unify VISION: Developing an Application.


643

uaclwhr( ) Predefined C function

Syntax

#include #include #include char * uaclwhr(status) USTATUS *status

Arguments

status

Return values

Status values

644


If successful, returns a pointer to the WHERE clause, not including the keyword WHERE. This pointer remains in effect only until the next call to uaclwhr( ). (char *)0

Operation was not successful.

UENOROW

The row ID cannot be retrieved, for example, because there is no current row, because the form is in find mode, or because the form has no target table.

UENORM


UENOMEM

Insufficient memory is available.


Description

The uaclwhr( ) function is called only from a C function. In add/update/delete mode, the uaclwhr( ) function returns a pointer to a string that contains a WHERE clause. The WHERE clause can then be concatenated with other clauses to build a command to update, delete, or select the current record on the current form. This function is typically used to select text or binary columns associated with the current record. uaclwhr( ) is valid only on a form with a target table. This function should not be called by a C function that is called from a global function. Use uaclwhr( ) only in add/update/delete mode, not in find mode. If uaclwhr( ) is called when there is no selected set, the function fails and the status value is set to UENOROW. No privileges are needed to execute this function. However, permissions are required to perform database operations.

Example

This example shows a portion of a C program that builds and executes a query that selects the pic_data column for the current record. char sqltext[2048]; { strcpy(sqltext, ”SELECT pic_data FROM pic_tab WHERE ”); strcat(sqltext, uaclwhr(picstatus)); exec_sql(sqltext); /* function executes an SQL statement */ }

See also

Predefined C functions uacldb( ) (page 626) uacldbp( ) (page 629) uacllda( ) (page 634)


645

646


Appendixes

647

648


Appendix A: Reserved words The following words are reserved for use by Unify VISION and must not be used as identifiers in forms or scripts. However, keywords can be used in quoted identifiers. ACCELL ACCELL_TYPE ACCEPT ACLADD_UPDATE ACLCANCEL_FORM ACLDISMISS_FORM ACLEXIT ACLFIND ACLCLEAR_FIELD ACLCLEAR_TO_ADD ACLCLEAR_TO_FIND ACLCONTEXTHELP ACLDELETE ACLEXPLAIN_ERROR ACLFIRST_RECORD ACLINDEXEDHELP ACLLAST_RECORD ACLNEXT_FIELD ACLNEXT_FORM ACLNEXT_RECORD ACLNEXT_SET ACLPREVIOUS_FIELD ACLPREVIOUS_SET ACLRETURN_VALUES ACLSET_NULL ACLZOOM ACTION ACTION_ID ACTION_NAME ACTION_OBJECT_ID ACTION_OBJECT_NAME ACTIVATE ACTIVE ACTIVEX ACTIVEX_APPL_RUNNING ACTIVEX_CLASS_NAME

ACTIVEX_DEFAULT_VERB ACTIVEX_DISPLAY_AS_ICON ACTIVEX_OBJECT_TITLE ACTIVEX_SCALE_TO_FIT ACTIVEX_TYPE ACTIVEX_VERBS ADD ADD_ALLOWED ADD_UPDATE AFTER ALL ALTER AMBIGUOUS AMOUNT AND APPEND APPLICATION ARCHIVES ARE ARRANGE AS ASC ASCENDING ASYNC ASYNCHRONOUS AT AUD_ACTION AUD_LABEL AUD_ON_ENTRY AUTO_ACCEPT AUTO_COMMIT AUTO_COMPILE AUTO_CURRENT AUTO_EDIT AUTO_FIND AUTO_ZOOM 649

BACKGROUND BEFORE BEGIN BEGIN_SQL BINARY BLINK BOOL BORDER BOUNDED BOX BREAK BREAKPOINT BUSINESS_EVENT BUTTON BUTTON_PRESS BUTTON_RELEASE BUTTONS BY CACHED CANCEL CANCEL_ZOOM CANVAS CASCADE CASE CASE_CONVERSION CELL_LABEL CELL_VALUE CENTER CENTERED CHANGE CHANGES CHARACTERISTICS CHILD CHOOSE CLASS CLASS_ICON CLASS_NAME CLEAR CLEAR_ADD_EXP CLEAR_AFTER_AU CLEAR_FIND_EXP CLICK

650

CLICK_ON_FIELD CLOSE CODE_SECTION COL COL_ORIGIN COLOR_PALETTE_NAME COLUMN_BOUNDED COLUMN_INDEX COLUMN_LOWER_BOUNDS COLUMN_UPPER_BOUNDS COLUMNS COMMAND COMMIT COMMIT_HOLDING_LOCKS COMPILE_COMMAND COMPONENT_BACKGROUND COMPONENT_CLASS COMPONENT_FOREGROUND COMPONENT_LABEL COMPONENT_VALUE CONNECTION CONNECTION_NAME CONNECTION_SOURCE CONSISTENCY CONSISTENCY_MODE CONTINUE COPY CREATE CREATE_CMD CUR_FIELD CUR_NEXT_FIELD CURRENT CURRENT_FIELD_NAME CURRENT_FORM_ON_DESTROY CURRENT_NEXT_FIELD_NAME CURRENT_PAGE_ID CURRENT_PAGE_NAME CURSOR CURSOR_COLUMN CURSOR_POSITION CURSOR_ROW CUSTOM CUT


DATA DATA_FORMAT DATA_TYPE DATE DB_COLUMN_LENGTH DB_COLUMN_NAME DB_COLUMN_TYPE DB_LENGTH DB_TYPE DBMS_ERROR DBNAME DBPASSWORD DBPATH DBTYPE DBUSER DDE_EVENT DEFAULT DEFAULT_ITEM_NUMBER DEFAULT_OBJECT_NAME DEFINE DEINSTALL DELETE DELETE_ALLOWED DEMOTING_LOCKS DESCENDING DESCRIPTION DESIGN_COMMAND DESTROY DETAIL_FORM_NAMES DETAIL_KEY_NAMES DIMENSION DIRECTIVE DISABLE DISABLED DISMISS DISMISS_FORM DISPLAY DISPLAY_FORMAT

Appendix A: Reserved words

DISPLAY_JUSTIFY DOUBLE DRAG DRAG_ALLOWED DRAG_DROP_ALLOWED DRAG_ICON_NAME DRAG_INVALID_ICON_NAME DROP ECHOED EDIT_ACTION EDIT_MODE EDITOR ELSE ENABLE END END_X END_Y END_SQL ENTER ENTRY_POINT_CLASS_NAME ERASE ERROR ERROR_LOG_FILE ESTIMATED_COLUMN_COUNT ESTIMATED COUNT ESTIMATED_ROW_COUNT ESTIMATING EVENT EVENTS EXCEPT EXECUTE EXECUTE_COMMAND EXECUTING EXIT EXTERN

651

FALSE FIELD FIELD_BEEP_ERROR_MESSAGE FIELD_BEEP_ON_ERROR FIELD_ERROR_MESSAGE FIELD_LENGTH FIELD_NAME FIELD_VALIDATION_RULE FILE FILE_PATH FIND FIND_ACTION FIND_ALLOWED FIND_ALLOWED$ FIND_COUNT FIND_LABEL FIND_PROMPT FINDABLE FIRST FIRST_FIELD FIRST_FIELD_NAME FIRST_INSTANCE FIRST_RECORD FLOAT FOCUSABLE FOCUS_IN FOCUS_OUT FONT_FACE FONT_FAMILY FONT_SIZE FOR FORCE_HORIZONTAL_SCROLLING FORCE_VERTICAL_SCROLLING FOREGROUND

652

FORM FORM_CONNECTION_NAME FORM_CONNECTION_SOURCE FORM_LIST FORM_MODE FORM_NAME FORM_TEMPLATE_FILE FORM_STATE FORMS FREE_SQL FROM FUNCTION FUNCTION_KEY FUNCTIONS FYI_COL FYI_MESSAGE FYI_ROW GENERATE_METRICS GENERATE_TRANSACTIONS GRAB_MODE GRANT GROUP_BOX HANDLER HEIGHT HELP HELP_ARCHIVE HELP_DOCUMENTS HELP_FORM_NAME HELP_FORM_COL HELP_FORM_ROW HELP_TAG HOLDING HORIZONTAL_SCROLLBAR HOT_SPOT


ICON_NAME ICONIC IDENTIFIED IF IMAGE IMAGE_FORMAT IMAGE_NAME IMAGE_SCALE IMAGE_SCALING IN IN_MEMORY INCREMENT_AMOUNT INFO_LEVEL INFO_LEVEL$ INIT INITIATE_HOT_LINK INITIATE_LINK INPUT INPUT_ACCELL_TYPE INPUT_COUNT INPUT_DB_COLUMN_TYPE INPUT_DB_COLUMN_TYPE_CODE INPUT_PRECISION INPUT_SCALE INSERT INSTALL INSTANCE INTEGER INTERFACE INTERFACE_SOURCE INTERNAL INTO IS IS_DEFAULT


IS_DETAIL IS_MASTER IS_PREPARED IS_REPLICATED IS_VALID ITEM_BACKGROUND ITEM_COUNT ITEM_FOREGROUND ITEM_LABEL KEY KEYMAP KEYS LABEL LABEL_JUSTIFY LABEL_STRING LABELS LANGDIR LAST LAST_RECORD LEAVE LEFT LIKE LINE LIST LIST_INDEX LIST_LOWER_BOUNDS LIST_UPPER_BOUNDS LOCAL LOCATION LOCKED_IN_CACHE LOCKS LOG_ERRORS LOW_INTENSITY

653

LOWER MACINTOSH MASTER_KEY_NAMES MATRIX MAKE MAXIMUM_HEIGHT MAXIMUM_LABEL MAXIMUM_VALUE MAXIMUM_WIDTH MENU_ACTION_OBJECT_ID MENU_ACTION_OBJECT_NAME MENUBAR_OBJECT_ID MENU_LABEL MESSAGE METHOD_LIST METHOD_NAME METHOD_TEMPLATE_FILE MINIMUM_HEIGHT MINIMUM_VALUE MINIMUM_WIDTH MORE_PROMPT MOUSE_ENTER MOUSE_LEAVE MOVE MSG_DESTINATION MSG_ERRORDISPLAY MSG_ERRORS MSG_METHOD MSG_STATE MSWINDOWS MULTI_VALUED NEW NEXT NEXT_FIELD

654

NEXT_FIELD_NAME NO_CONSISTENCY NONE NOT NOTEBOOK NOTICE NULL NUMERIC OBJECT OBJECT_ID OBJECT_NAME OBJECT_REF OBJECT_SEARCH_PATH OCCURRENCES OF ON ONEWAY ONLY OPEN OPERATION OR ORDER ORDERED_BY ORIENTATION OUTPUT OUTPUT_ACCELL_TYPE OUTPUT_COUNT OUTPUT_DB_COLUMN_TYPE OUTPUT_DB_COLUMN_TYPE_CODE OUTPUT_NAME OUTPUT_PRECISION OUTPUT_SCALE OVERWRITE


PAGE PAGE_BORDERS PAINT PARENT_ID PARTITION PARTITIONGROUP_ASSIGNED PARTITIONGROUP_OBJECT_ID PARTITION_OBJECT_ID PASTE PERSISTENT PIPELINE POINTER POSITION PREPARE_SQL PREV_FIELD PREV_FORM PREV_INSTANCE PREVIOUS PREVIOUS_FIELD_NAME PREVIOUS_FORM_NAME PRINT PRIVATE PROJECT_LIST PUBLIC QUEUE RAISE RECEIVE_DATA RECORD RECORD_ACTION RECORD_CONSISTENCY RECORD_COUNT RECORD_NUMBER RECORD_STATE REF REFERENCE


REFERENCED_CLASS_NAME REFRESH REGISTER REJECT REPAINT REPEAT REPEATED REPLGROUP_NAME REPLGROUP_OBJECT_ID REPLGROUP_REGISTRY_OBJECT REPLICATE REPLICATED REQUEST_DATA REQUIRED RESCAN_RATE RESIZABLE RESIZE RESTART RESULT RETRIEVE RETRIEVE_VALUE RETURN RETURNING REVERSE REVOKE RIGHT ROLLBACK ROW ROW_BOUNDED ROW_INDEX ROW_LOWER_BOUNDS ROW_ORIGIN ROW_UPPER_BOUNDS ROW_VALUED ROWS RUN_COMMAND

655

SCHEMA SCREEN SCREEN_H SCREEN_W SCREEN_X SCREEN_Y SCRIPT SCRIPT_ERROR SCROLLING_LIST_SELECTOR SEARCH_PATH SEARCH_RANGES SEC SECOND SECONDS SELECT SELECTED SELECTED_SET_SCROLLBAR SEND SERVICE SET SET_CONSISTENCY SHELL SHLIKE SLIDER_MAXIMUM SLIDER_MAXIMUM_LABEL SLIDER_MINIMUM SLIDER_MINIMUM_LABEL SLOCK SQL_COLUMN_CONDITION SQL_OPTIONAL_CONDITION SQL_ORDER_BY_CLAUSE SQL_ORDER_BY_COLUMN SQL_WHERE_CLAUSE START STATEMENT_TEXT STIPPLED STOP_FOR_INPUT STORE STORED

656

STRING SUBCLASS SUPER SWITCH SYSTEM_HELP TAB_SIDE TAB_STOP TABLE TARGET_FIELD TARGET_TABLE TEMP_DIRECTORY TERMINAL_EMULATOR TERMINATE_HOT_LINK TERMINATE_LINK TEXT THEN THICKNESS THIS_INSTANCE TILE TIME TIMER TITLE TO TRANSACTION TRANSPORT TRIM TRUE TX TX_MODE_ADD_RECORD TX_MODE_BECOME_CURRENT TX_MODE_CLEAR_TO_ADD TX_MODE_CLEAR_TO_FIND TX_MODE_CREATE_FORM TX_MODE_DELETE_RECORD TX_MODE_DESTROY_FORM TX_MODE_FORM_CREATION TX_MODE_LOSE_CURRENCY TX_MODE_NOT_CURRENT TX_MODE_UPDATE_RECORD


UNCACHED UNDEFINED UNDERLINE UNKNOWN UNLOCK UNTIL UPDATE UPDATE_ALLOWED UPDATE_ALLOWED$ UPDATEABLE USAGE USE_BASE_WINDOW USERMENU USING UV_ADD_UPDATE UV_CANCEL_FORM UV_CLEAR_FIELD UV_CLEAR_TO_ADD UV_CLEAR_TO_FIND UV_CONTEXT_HELP UV_DELETE UV_DISMISS_FORM UV_EXIT UV_FIND UV_FIRST_RECORD UV_HELP_INDEX UV_LAST_RECORD UV_NEXT_FIELD UV_NEXT_RECORD UV_NEXT_SET UV_NEXT_TAB UV_PREVIOUS_FIELD UV_PREVIOUS_RECORD UV_PREVIOUS_SET


UV_PREVIOUS_TAB UV_RECALL_ERROR_MESSAGE UV_RECALL_FIELD UV_RETURN_VALUES UV_SET_NULL UV_ZOOM VALUE VALUES VERTICAL_SCROLLBAR VIEW VISIBLE VOID WAIT WHEN WHERE WHILE WIDTH WINDOW_HEIGHT WINDOW_STYLE WINDOW_WIDTH WITH WORK WRAP WRITE X XLOCK Y Z ZOOM ZOOM_INDICATOR

657

658


Appendix B: External files The following files, located in the release include directory, are required by some of the functions used in scripts. avalmacs.h

Defines macros for the AVAL structure.

chookinc.h

Defines all elements required for passing values to and from a function.

chooktb.c

Defines external C functions.

command.h

Defines return value names for user commands.

dbmserrrs.h

Defines the error information passed to a DBMS_ERROR function.

rhlierr.h

Defines database error status values.

scrpterr.h

Defines the error information passed to a SCRIPT_ERROR function.

sscodes.h

Defines the values returned by the status$( ) system function.

sybdb.h

(SYBASE SQL Server only) Defines the DBPROCESS structure.

sybfront.h

(SYBASE SQL Server only) Defines symbolic constants, such as function return values.

659

660


Glossary 3GL function

A type of external function written in a third-generation programming language, for example, the C programming language.

ancestor form A form in the form tree that is between the current form and the first form. See also child form; descendent form; parent form.

abort To terminate the application or the current transaction without saving changes.

ANSI (American National Standards

add/update/delete mode One of two methods of operation for a form during application execution. In add/update/delete mode the user can add new records to the database, modify existing records, or remove existing records. See also find mode.

application management event Any significant change in the state of a system resource or an application.

Institute) An organization that establishes voluntary industry standards for database systems.

ASCII (American standard code for

AMS (application management

information interchange) A standard set of codes that are used to represent characters on many computers. An ASCII file is a text file that consists of standard characters. See also binary file.

system) An integrated configuration of third-party software tools for distributing and managing applications in a distributed client/server environment.

attribute A value that defines a particular characteristic (for example, size) of an object. See also preference. BAROC (basic recorder of objects

AMS transaction

A measured interval during application runtime.

in C) (Tivoli Systems) A file format for defining the slots of an event class. 661

binary file A file that contains code in the format required by the computer processor.

Boolean An entity that has two possible values: TRUE or FALSE.

business event An event defined by a Unify VISION application. See also application management event.

cancel To dismiss the current form, dialog, or selection without executing any changes.

child form A form that is a direct descendent of a parent form. See also ancestor form; descendent form; parent form.

class The initial definition of any predefined object or developer-defined object contained in an application.

clause A discrete portion of a script statement. For example, the ON CHOOSE NEXT FORM method has a USING clause. 662

clear-to-find expression An expression specified by the CLEAR_FIND_EXP attribute that sets the initial search criteria for a target field. column The database entity that defines one data element in a table. See also row. column type The format in which the database stores column data. VISION data types are distinct from database column types. See also data type. command A user request that initiates an application operation. See also developer-defined command; operation; predefined command. commit Terminate a transaction and save all changes made by that transaction to the database, making the changes visible to other transactions. concurrency The ability for multiple users to simultaneously access a single database. created form A form that has been defined and initialized. Unify VISION: 4GL Reference

current field The active field on the current form.

DDL (data definition language) SQL statements that describe database

elements and their relationships. current form The form that has user input focus. current object The object that is selected. current record The record in the selected set that is currently active. custom manager A developer-built version of vision where the developer has added customized 3GL function calls. data type The format in which Unify VISION stores or displays data. Unify VISION data types are distinct from database column types. See also column type. database A set of tables defined and managed by the DBMS. database operation A VISION Runtime Manager process that affects values or rows in a database table.

declaration A script statement that supplies information about an identifier used in the script, such as the name and type of a global function. defined form A form that has been defined as a class in an object library. definition Statements that specify the actions to be performed by a function. dereference operator A symbol that indicates that the OBJECT_REF value on the left side identifies the object to be referenced on the right side, for example, text_ref–>VALUE descendent form A form created later than, and is a direct chain from, forms higher in the form tree. See also ancestor form; child form; parent form. developer-defined command A command class that has been defined by the developer in a COMMAND section of a script. See also command; predefined command. DDE (Dynamic Data Exchange)

database procedure A set of SQL statements that are stored under a name and can be called from a VISION 4GL script. Glossary

A method of interprocess communication based on the messaging system built into Microsoft Windows. 663

dirty data Database objects that are write-locked; the objects may or may not have been changed by a database operation, and they may contain uncommitted data. display format The format or layout to display a type of data. display-only Data that is read only, that is, data that cannot be edited or modified. distributed application An application that is divided into application partitions. DML (data manipulation language) SQL statements that manipulate

database information but do not affect the database design. executing form A form running under VISION Runtime Manager. explicit An operation that occurs as the result of a deliberate statement or user action, such as pressing a command key sequence. See also implicit. extension Syntax that differs from or supplements the ANSI standard syntax for SQL commands. 664

find mode One of two methods of operation for a form during application execution. In find mode the user can search for existing records that satisfy specific search criteria. See also add/update/delete mode.

fire To execute automatically when a specific event occurs. For example, a SYBASE SQL Server trigger can be fired when an update is applied to a database column. form class An area containing dialog options and images organized to display and retrieve information for a user. See also form instance

form instance A copy of a form class that is being executed by VISION Runtime Manager. See also form class.

form mode One of the methods of operation for a form: find mode or add/update/delete mode. form state In Unify VISION, a form instance can be in one of three states: defined, created, and current. See also created form; current form; defined form. Unify VISION: 4GL Reference

form tree At runtime, defined, created, and current forms are controlled by a tree structure, with the first form at the root of the tree.

global function A script that contains script functions or 3GL functions that are defined for all other scripts in the application. See also script.

implicit An operation that occurs automatically or by default whenever a specified condition occurs. See also explicit.

include file A file that contains declarations and definitions for variables that are used in a script.

input focus The object to which keyboard input is directed. Assigning focus to a form instance makes the form current. See also object.

instance A named activation of a class.

interactive database operation A database operation performed on the selected set that is initiated by the user or script. Glossary

keyword A word defined as part of the VISION 4GL script syntax. Keywords are also reserved words; they cannot be assigned definitions by developers. local function A method defined only within a form or global function. metacharacter A special character, such as an asterisk (*), that represents a range or pattern for matching search criteria. Sometimes called a wild card. Metacharacters are DBMS dependent. noninteractive database operation An operation on a database table that is initiated by an SQL statement or noninteractive script statement. null A value of a specific type that is empty. See also undefined. object In Unify VISION, any form, application, global function, or other type of entity recognized by Unify VISION. See also instance. object reference A handle that uniquely identifies an object instance in an application. Object references are assigned when the object is created, as in form activation. Object references are 665

stored in the Unify VISION data type OBJECT_REF.

operation The series of actions and script sections that are executed in response to an event, such as a user command.

parent form The immediate ancestor form of a form. See also ancestor form; child form; descendent form.

password A code that identifies the current user to the operating system or to the database.

predefined command A command provided by Unify VISION that executes a predetermined sequence of operations when selected by the user. Predefined commands include typical database operations and record manipulation. See also command; developer-defined command.

preference A variable that specifies a value to be used during application development or runtime execution. See also attribute. 666

raise Changing the stacking order of a window so as to hide another window. read lock An instruction that permits read access to database rows but prevents write access by all transactions. See also write lock. record A copy of a database row, displayed in a selected set. See also row. referential integrity The rules that govern data consistency, which guarantees that when a table is updated, all related tables and objects agree. repeating group An object (such as a button or field) that is repeated one or more times to display multiple records on a form. result parameter A value returned from a database procedure or stored procedure that can be used in other statements or function calls. return status A value returned from a method or function, a database procedure, or a stored procedure that indicates whether the function or method was completed successfully. Unify VISION: 4GL Reference

row The database object that consists of a unique set of related columns that constitute a single entry in a table. Sometimes called a tuple. One database row corresponds to one Unify VISION record. See also column; record.

rule A special database procedure that is executed (is fired) when an insert, update, or delete operation is executed. See also column; record.

runtime The execution of an application, as opposed to its development.

script Methods and statements that control execution of a form or other object at runtime. See also global function.

script statement A line in a script. A statement is associated with a method that determines when the statement is executed.

sort To arrange objects based on an ordering criteria. SQL (structured query language)

A relational database language that provides statements for creating, manipulating, or searching tables, based on an English keyword syntax. stippled Disabled, indicated by shading an object with small dots. stored procedure A set of database commands stored in and executed by the DBMS. subform A form contained in a form class. system information field A predefined field that is used to display system information. table The database entity that stores related rows. Sometimes called a relation. target table The database table that is associated with a specific form. TEC (Tivoli/Enterprise Console)

selected set A group of records that are copies of rows selected from a database table. Glossary

(Tivoli Systems) An application that collects, processes, and automatically responds to management events in a client/server environment. 667

timer An application event, defined by the developer, that is executed after a specified time period. TME (Tivoli/Management

Environment) (Tivoli Systems) An application management system (AMS) that can be used with Unify VISION to distribute and manage applications. transaction A set of one or more database operations that must be completed as a single unit. transaction abort error An error that causes the DBMS to abort the transaction. trigger A special stored procedure that is executed (fired) when an insert, update, or delete operation is executed. undefined Uninitialized; a variable that has no valid value or type associated with it. See also null. update An operation that changes an existing row in or adds a new row to the database table.

668

user Any person who uses a completed application. value parameter A function parameter that is defined as a local variable and initialized with a value when the function is called. When execution returns to the calling program, the argument value remains unchanged.

VISION 4GL

The Unify VISION fourth-generation language used to create scripts and global functions. VISION Runtime Manager The Unify VISION runtime

component that executes an application partition. write lock An instruction that prevents both read and write access to a specified database row or table by all transactions other than the transaction that placed the write lock. See also read lock. zoom form A type of child form that displays information related to the current form and that can return values to the current form.


Unify VISION: 4GL Reference - Support

Unify VISION: 4GL Reference - Support

Suggest Documents

INFORMIX-4GL Reference Manual Supplement - PACS Support

IBM Cognos PowerHouse 4GL QTP Reference

Informix 4GL Quick Syntax, Version 6.0 - PACS Support

Vision Support Services

Vision Support Services

Vision Support Services

The 4GL Alliance

MAX Reference - Avaya Support

Engaged Citizens - Unify

Leistung zÃ¤hlt - Unify

Business Value Assessment - Unify

Success Story - Unify

Unify Info Graphic 1

Engaged Citizens - Unify

Success Story - Unify

Performance matters - Unify [PDF]

A Unify Perspective

Team Setup Checklist - Unify

Unify Info Graphic 1

Project UNIFY - Special Olympics

Circuit Meeting Room - Unify

A Unify Perspective [PDF]

OpenScape Mobility - Unify

Success Story - Unify