Download Unify DataServer: RHLI Reference

Unify DataServer:
RHLI Reference
R
E 1996, 1997, 2001, 2005 by Unify Corporation, Sacramento, California, USA
All rights reserved. Printed in the United States of America.
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.
Unify Corporation values and appreciates any comments you may have concerning our products or this
document. Please address comments to:
Product Manager
Unify Corporation
2101 Arena Boulevard Ste. 100
Sacramento, CA 95834-1922
(800) 248-6439
(916) 928-6400
FAX (916) 928-6406
UNIFY, ACCELL, VISION, and the Unify Logo are registered trademarks of Unify Corporation. Unify
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 Informix Software, Inc., 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, MSĆDOS, and Windows are registered trademarks of Microsoft Corporation. All other
products or services mentioned herein may be registered trademarks, trademarks, or service marks of their
respective manufacturers, companies, or organizations.
Part Number: 7806-02
2
Contents
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
12
12
12
Function Names and Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
Function Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
Function Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Name Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Journal Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ordered Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Processing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
19
19
20
20
21
22
23
23
24
25
25
25
Returned Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
RHLI Application Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
Data Types and Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Converting Internal/External Data Formats . . . . . . . . . . . . . . . . . . .
Converting Internal to External Format . . . . . . . . . . . . . . . . . . .
Converting External to Internal Format . . . . . . . . . . . . . . . . . . .
Handling String Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling U_AMT data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
35
35
35
36
36
Referencing Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compile-Time Name Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Runtime Name Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
38
41
ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
3
4
Automatic ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Partial ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manual ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing Mapping Structures . . . . . . . . . . . . . . . . . . . . . . . . .
Using Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a Custom ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
45
46
47
48
48
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Status Values of Function Operations . . . . . . . . . . . . . . . . . . . . . . .
The Status and Statusl Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing for Partial Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing for Complete Failure . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving a Status Value Message . . . . . . . . . . . . . . . . . . . . . . .
Most Common RHLI Function Status Values . . . . . . . . . . . . . . . . .
System Error Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
51
51
52
53
54
54
61
61
Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type 2 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type 1 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type 0 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
62
62
63
63
Scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
66
Compiling and Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling With ucc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Loading Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
70
72
The RHLI Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
About the Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
77
77
The DBAUTH Structure: Schema Information . . . . . . . . . . . . . . . . . .
80
The DBBTREE Structure: B-tree Index Information . . . . . . . . . . . . . .
81
The DBCGRP Structure: Column Group Information . . . . . . . . . . . . .
83
The DBCOLNM Structure: Column Name Information . . . . . . . . . . .
85
The DBHASH Structure: Hash Table Index Information . . . . . . . . . . .
86
The DBINFO Structure: Database Information . . . . . . . . . . . . . . . . . .
88
The DBLINK Structure: Link Information . . . . . . . . . . . . . . . . . . . . . .
90
The DBTABLE Structure: Table Information . . . . . . . . . . . . . . . . . . . .
92
The DBTBLNM Structure: Table Name Information . . . . . . . . . . . . . .
99
The DBUSER Structure: User and Default Schema Information . . . . .
100
The DBVOLM Structure: Volume Information . . . . . . . . . . . . . . . . . .
101
Contents
Contents
The UACSINF Structure: Access Method Information . . . . . . . . . . . .
105
The UATHINF Structure: Schema Information . . . . . . . . . . . . . . . . . .
107
The UATHMAP Structure: Authorization ID Mapping . . . . . . . . . . . .
108
The UBTINF Structure: B-tree Information . . . . . . . . . . . . . . . . . . . . .
109
The UBTMAP Structure: B-tree ID Mapping . . . . . . . . . . . . . . . . . . .
111
The UCGPINF Structure: Column Group Information . . . . . . . . . . . .
112
The UCOLINF Structure: Column Information . . . . . . . . . . . . . . . . . .
113
The UCOLMAP Structure: Column ID Mapping . . . . . . . . . . . . . . . . .
116
The UDBINF Structure: Database Information . . . . . . . . . . . . . . . . . .
118
The UGRTDS Structure: Grant Privilege Descriptor . . . . . . . . . . . . . .
120
The UHSHMAP Structure: Hash Table ID Mapping . . . . . . . . . . . . . .
124
The UHTINF Structure: Hash Table Information . . . . . . . . . . . . . . . . .
125
The UJRNINF Structure: Journal Information . . . . . . . . . . . . . . . . . . .
127
The ULNKINF Structure: Link Information . . . . . . . . . . . . . . . . . . . .
129
The ULNKMAP Structure: Link ID Mapping . . . . . . . . . . . . . . . . . . .
130
The UNIPCOLL Structure: Column Access Information . . . . . . . . . . .
131
The UNIPEXT Structure: Column Conversion Information . . . . . . . .
140
The UOACOLS Structure: Ordered Access Row Order . . . . . . . . . . . .
141
The URVKDS Structure: Revoke Privilege Descriptor . . . . . . . . . . . .
142
The UTBLINF Structure: Table Information . . . . . . . . . . . . . . . . . . . .
145
The UTBLMAP Structure: Table ID Mapping . . . . . . . . . . . . . . . . . . .
148
The UTXINF Structure: Transaction Information . . . . . . . . . . . . . . . .
150
The UTXOPT Structure: Begin Transaction Options . . . . . . . . . . . . . .
152
The UUSRINF Structure: User Information . . . . . . . . . . . . . . . . . . . . .
154
The UVOLINF Structure: Volume Information . . . . . . . . . . . . . . . . . .
155
The UVOLMAP Structure: Volume ID Mapping . . . . . . . . . . . . . . . . .
158
Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
159
uabttx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
161
uaddath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
163
uaddbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
165
uaddcgp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
167
uaddcnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
169
uadddb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
171
5
6
uaddhsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
uaddlnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
175
uaddprf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
178
uaddprm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
180
uaddprv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
182
uaddtbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
185
uaddtnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
188
uaddusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
190
uaddvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
192
ualcscn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
194
ualctbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
196
uallath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
199
uallbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
201
uallcgp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
203
uallcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
206
uallhsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
208
ualllnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
210
uallpid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
212
ualltbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
214
ualltx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
216
uallusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
218
uallvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
220
ubegord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
222
ubegscn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
225
ubegtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
227
ubndath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
229
ubndbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
231
ubndcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
233
ubnddb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
235
ubndhsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
237
ubndlnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
239
ubndtbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
241
ubndusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
243
Contents
Contents
ubndvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
245
ucbgtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
247
uclritr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
249
uclsdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
251
uclsjrn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
253
ucmttx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
255
ucrypwd, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
257
udelrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
259
udrpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
261
udrpbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
263
udrpcgp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
265
udrpcnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
267
udrphsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
269
udrplnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
271
udrpprf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
273
udrpprm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
275
udrpprv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
277
udrptbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
280
udrptnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
282
udrpusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
284
udrpvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
286
uendord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
288
uendscn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
289
uexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
291
uextint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
292
ufchath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
295
ufchcnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
297
ufchjrn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
300
ufchlnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
302
ufchmsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
305
ufchord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
307
ufchrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
310
ufchscn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
312
7
8
ufchtbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
314
ufchtnm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
317
ufrescn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
319
uinfacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
321
uinfath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
323
uinfbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
326
uinfcgp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
329
uinfcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
332
uinfdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
335
uinfhsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
338
uinflck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
341
uinflnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
344
uinfsch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
347
uinfscn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
349
uinftbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
351
uinftx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
355
uinfusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
357
uinfvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
360
uinimsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
363
uinsand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
365
uinsbuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
367
uinsor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
372
uinsprj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
375
uinsrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
377
uinssrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
379
uinstbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
381
uintext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
382
ulckdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
385
ulckrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
387
ulcksch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
390
ulcktbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
392
ulogmsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
394
umapath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
396
Contents
Contents
umapbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
398
umapcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
400
umaphsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
402
umaplnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
404
umaptbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
406
umapvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
408
umodath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
410
umodbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
412
umoddb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
414
umodhsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
416
umodlnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
418
umodusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
420
umodvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
422
unumath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
424
unumcgp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
426
unumchd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
428
unumcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
430
unumprn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
432
unumrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
434
unumtbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
436
unumusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
438
unumvol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
440
uopndb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
442
uopnjrn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
447
upkfrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
449
uposord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
451
usetitr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
453
uskrord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
456
utrnctbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
458
uulkdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
460
uulkrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
461
uulksch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
463
uulktbl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
465
9
10
uupdrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLAddAttribute() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLCreateElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLDeleteAttribute() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLDeleteCurrentElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLDeleteCurrentElementValue() . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetAttributeCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetAttributeNames() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetAttributeValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetAttributeValues() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetCurrentElementName() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetErrorInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLGetValueOfCurrentElement() . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLModifyElementValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToFirstChild() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToLastChild() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToNextSibling() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToParentElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToPreviousSibling() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLMoveToRootElement() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLParse() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
uXMLSetAttributeValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
467
469
471
473
475
477
479
481
483
485
487
489
491
493
495
497
499
501
503
505
507
509
511
Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
513
Appendix A: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
An Ordered Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Name Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Journaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
515
516
520
524
528
532
534
536
539
542
Contents
About This Manual
This document is written for C programmers who want to access a Unify
DataServer database through the Relational Host Language Interface
(RHLI).
The RHLI is a library of more than 100 functions. To access the functions,
you must include RHLI header files and use Unify DataServer tools to
compile and load the C program that contains the functions.
You use the functions to create and change date in a Unify DataServer
database. For instance, you can use RHLI functions to perform the following
tasks:
create a database
define database structures
add data to a database
retrieve data from a database
modify data stored in a database
delete data stored in a database
retrieve information about database objects
The first chapter of this manual describes the categories of functions and
gives a brief description of each function. The chapter also describes the
function naming conventions. The second chapter describes the C
structures used with many of the functions. The third chapter describes
all of the RHLI functions in alphabetical order.
Related Documents
This manual describes the functions in reference-style format. For a
description of RHLI concepts, see Unify DataServer: Developing a
Database.
11
Syntax Conventions
Icons
This section describes the syntax and naming conventions used to
describe the functions described in this manual.
bold
Indicates a keyword, structure name, or data type that
must be entered as shown.
italic
Indicates an argument or parameter name that you
supply.
The manual uses the following icons:
Tip
A Tip contains helpful information.
Warning
A Warning cautions against actions that could cause data loss or damage
to the database.
Additional Help
Additional Help tells you where to find more information about described
topics.
Function Format
Each function description is divided into several parts:
Header
Name of the function.
Summary statement (following the header bar)
A brief statement of the function’s purpose.
12
Syntax
Syntax for the function.
Arguments
Required and optional arguments that are used when
calling the function.
Description
Function usage and any special conditions and notes.
Status Values
Indicates the status of the function’s operation.statusl is a list
of one or more values indicating the status of each object
operation corresponding to the object list for the function. Each
statusl value can be checked to determine which objects
incurred the error.
Security
Permissions required to execute the function if other than
a regular user.
Example
Example of function usage or a reference to the
Examples appendix.
See Also
Cross references to related information.
13
14
Function Names and
Categories
15
Chapter
Focus
This chapter describes the naming conventions, categories and returned
values of the RHLI functions.
16
Function Names and Categories
Function Naming Conventions
Each RHLI function has a seven-character name. The name is created by
combining the operation that the function performs and the object the
function operates on.
For instance, the ufchrow function fetches a row. The following diagram
shows how the function name consists of an operation and an object
abbreviation.
RHLI Function Naming Conventions
PREFIX
OPERATION
OBJECT
for all RHLI
the
object the
( prefix
) ( indicates
) ( database
)
functions
RHLI operation
operation acts on
The following tables list the operations and object abbreviations that
compose the RHLI function names.
Not every combination of the operations and object abbreviations create a
valid RHLI function.
Function Names and Categories
17
Operation Abbreviations Used in Function Names
Op
Description
Op
abt
add
alc
all
beg
bnd
cbg
cir
clr
cls
cmt
del
drp
end
exit
ext
abort
add
allocate
get all
begin/initiate
name bind
commit and begin
clear a condition
clear a condition
close
commit
delete
drop/delete
end/terminate
program termination
convert from external
format
fetch/reference
free/deallocate
grt
inf
ins
int
fch
fre
Description
grant
get information
insert
convert from internal
format
lck
lock
log
make a record of
map
map a compile-time ID to
a runtime ID
mod
modify
num
retrieve number of
opn
open
pkf
primary key fetch
pos
position
rvk
revoke
set
set a condition
skr
seek to a row
ulk
unlock
upd
update
Object Abbreviations Used in Function Names
Obj
Description
Obj
Description
and
ath
bt
cgp
chd
cnm
col
db
ext
scan “and” groups
authorizations/schemas
B-trees
column group
child of link relationship
column names
columns
databases
convert to external
format
hash tables
convert to internal format
interrupt
journal
links
messages
or
ord
prf
prj
prm
prn
scan “or” groups
ordered access
volume preferences
scan projection list
permissions
parent or link
relationship
privileges
database row
scan
scan sort
database table
table names
transaction
users
volumes
hsh
int
itr
jrn
lnk
msg
18
prv
row
scn
srt
tbl
tnm
tx
usr
vol
Function Names and Categories
Function Categories
Functions are categorized into the following eleven categories:
message handling
transaction management
locking management
security management
data definition
name binding
ID mapping
scanning
data manipulation
journal access
ordered access
Message Handling
Message functions access the message gathering facilities of the
database.
ufchmsg
uinimsg
ulogmsg
Transaction
Management
Transaction management functions begin, commit, and, abort
transactions.
uabttx
ubegtx
ucbgtx
ucmttx
uinftx
Function Names and Categories
Retrieve the message corresponding to a status value
Initialize the messageĆlogging facilities
Append a message to the error log
Abort a transaction
Start a transaction
Commit a transaction and start a new transaction
Commit a transaction
Retrieve transaction information
19
Locking
Management
Locking management functions manipulate locks on and retrieve lock
information for databases, tables, and rows.
uinflck
uinfsch
ulckdb
ulckrow
ulcksch
ulcktbl
uulkdb
uulkrow
uulksch
uulktbl
Security
Management
Security management functions grant and revoke permissions and
privileges to and from users and schemas.
uaddprm
uaddath
uaddprv
uaddusr
ucrypwd
udrpath
udrpprm
udrpprv
udrpusr
ufchath
uinfath
uinftx
uinfusr
umodath
umodusr
20
Retrieve data lock information
Retrieve table definition lock information
Lock a database
Lock a row
Lock a table definition
Lock a table
Unlock a database
Unlock a row
Unlock a table definition
Unlock a table
Grant schema access
Add a schema to the database
Grant user or schema privileges
Add a user to the database and/or set a user's default
schema
Encrypt a password
Drop a schema from the database
Revoke schema access
Revoke user or schema privileges
Drop a user from the database
Set a current schema for a user
Retrieve schema information
Retrieve transaction information
Retrieve user information
Modify a schema name
Modify a user name and default schema
Function Names and Categories
Data Definition
Data definition functions add, drop, and modify databases, volumes,
tables, columns, column groups, users, schemas, B-trees, links, and hash
tables.
uaddath
uaddbt
uaddcgp
uaddcnm
uadddb
uaddhsh
uaddlnk
uaddprf
uaddtbl
uaddtnm
uaddvol
udrpath
udrpbt
udrpcgp
udrpcnm
udrphsh
udrplnk
udrpprf
udrptbl
udrptnm
udrpvol
ufchcnm
ufchtnm
uinfacs
uinfath
uinfbt
uinfcgp
uinfcol
uinfdb
uinfhsh
uinflnk
uinftbl
uinfvol
Add a schema
Define a BĆtree
Add a column group to a table
Add a column name (or synonym)
Create a new, empty database
Define a hash table
Define a link
Add a volume preference for a table
Add a table
Add a table name (or synonym)
Add a volume
Drop a schema
Drop a BĆtree
Drop a column group from a table
Drop a column name (or synonym)
Drop a hash table
Drop a link
Drop a volume preference for a table
Drop a table
Drop a table name (or synonym)
Drop a volume
Fetch column names (or synonyms)
Fetch table names (or synonyms)
Retrieve access information
Retrieve schema information
Retrieve BĆtree information
Retrieve column group information
Retrieve column information
Retrieve database information
Retrieve hash table information
Retrieve link information
Retrieve table information
Retrieve volume information
continued
Function Names and Categories
21
Data Definition Functions (continued):
umodath
Modify a schema name
umodbt
Modify a BĆtree name
umoddb
Modify a database
umodhsh
Modify a hash table name
umodlnk
Modify a link name
umodvol
Modify a volume name
unumath
Retrieve number of schemas
unumchd
Retrieve number of rows in a table
unumcol
Retrieve number of columns in a table
unumprn
Retrieve number of rows in a table
unumtbl
Retrieve number of tables
Name Binding
Name binding functions obtain object IDs for database objects.
uallath
uallbt
uallcgp
uallcol
uallhsh
ualllnk
uallpid
ualltbl
ualltx
uallusr
uallvol
ubndath
ubndbt
ubndcol
ubnddb
ubndhsh
ubndlnk
ubndtbl
ubndusr
ubndvol
22
Retrieve a list of authorization IDs
Retrieve a list of BĆtree IDs
Retrieve a list of column group IDs
Retrieve a list of column IDs
Retrieve a list of hash table IDs
Retrieve a list of link IDs
Retrieve a list of process IDs
Retrieve a list of table IDs
Retrieve a list of transaction IDs
Retrieve a list of user IDs
Retrieve a list of volume IDs
Bind a schema name to an authorization ID
Bind a BĆtree name to a BĆtree ID
Bind column name to a column ID
Bind a database name to a database ID
Bind a hash table name to a hash table ID
Bind a link name to a link ID
Bind table name to a table ID
Bind a user name to a user ID
Bind a volume name to a volume ID
Function Names and Categories
ID Mapping
ID mapping functions map compile-time object IDs to runtime object IDs.
umapath
umapbt
umapcol
umaphsh
umaplnk
umaptbl
umapvol
Scanning
Map a compileĆtime BĆtree ID to its runtime ID
Map a compileĆtime column ID to its runtime ID
Map a compileĆtime hash table ID to its runtime ID
Map a compileĆtime link ID to its runtime ID
Map a compileĆtime table ID to its runtime ID
Map a compileĆtime volume ID to its runtime ID
Scanning functions set up and perform a scan on a table. A scan searches
for rows that meet the specified criteria, retrieves the desired columns
from each row and sorts the rows according to user-defined sort criteria.
ualcscn
ubegscn
uendscn
ufchscn
ufrescn
uinfscn
uinsand
uinsbuf
uinsor
uinsprj
uinssrt
uinstbl
Function Names and Categories
Map a compileĆtime authorization ID to its runtime
ID
Allocate a scan information structure
Begin a scan
End a scan
Retrieve the next row from a scan
Free or clear a scan information structure
Create a list used for scan data retrieval
Insert an AND group
Allocate a remote scan buffer
Insert an expression into an OR group
Add a column to the projection list of a scan
Insert a column to the sort criteria
Specify the target table for a scan
23
Data Manipulation
Data manipulation functions are used to access data from the database
and perform operations such as adding, updating, deleting or getting
information about a database row. The scanning functions are listed on
page 23.
ualctbl
uclritr
uclsdb
udelrow
uexit
uextint
ufchlnk
ufchrow
ufchtbl
uinsrow
uintext
unumath
unumcgp
unumchd
unumcol
unumprn
unumrow
unumtbl
unumusr
unumvol
uopndb
upkfrow
usetitr
uupdrow
24
Dynamically allocate a UNIPCOLL structure
Clear the process interrupt
Close the database
Delete a row
Terminate a process
Convert column values from external format to
internal format
Fetch the parent row through a link access method
Fetch a row
Fetch a row sequentially
Insert a row into a table
Convert column values from internal format to
external format
Retrieve the number of schemas in the database
Retrieve the number of columns in a column group
Retrieve the number of child rows for a link
Retrieve the number of columns in a table
Retrieve the number of parent rows for a link
Retrieve the number of rows in a table
Retrieve the number of tables in the database
Retrieve the number of users in the database
Retrieve the number of volumes in the database
Open the database for access
Fetch a row through its primary key
Set the process interrupt
Update a row
Function Names and Categories
Journal Access
Functions
Journal access functions read the contents of the transaction journal.
uclsjrn
ufchjrn
uopnjrn
Close the transaction journal
Fetch the next update operation from the transaction
journal
Open a transaction journal
Additional Help
For more information about the transaction journal, see Unify
DataServer: Managing a Database.
Ordered Access
Functions
Ordered access functions set up and perform an ordered access on a table.
ubegord
uendord
ufchord
uposord
uskrord
XML Processing
Functions
Begin an ordered access
End an ordered access
Retrieve a row from an ordered access
Position by values to a row within an ordered access
Position by row ID to a row within an ordered access
The XML processing functions perform operations on XML data..
uXMLAddAttribute
Adds a new attribute to an element
uXMLCreateElement
Creates a new element
uXMLDeleteAttribute
Deletes an attribute
uXMLDeleteCurrentElement
Deletes the current element
uXMLDeleteCurrentElementValue
Deletes the value of an element
uXMLDestroy
Destroys an XML object
uXMLGetAttributeCount Returns the number of attributes
uXMLGetAttributeNames Returns the attribute names of an element
Function Names and Categories
25
uXMLGetAttributeValue Returns an attribute value
uXMLGetAttributeValues Returns the attribute values of an element
uXMLGetCurrentElementName
Returns the tag name of the current element
uXMLGetErrorInfo
Returns an error description
uXMLGetValueOfCurrentElement
Returns the value of the current element
uXMLModifyElementValue
Modifies the value of an element
uXMLMoveToFirstChild
Moves the current element pointer to the
first child
uXMLMoveToLastChild
Moves the current element pointer to the last
child
uXMLMoveToNextSibling
Moves the current element pointer to next
sibling
uXMLMoveToParentElement
Moves the current element pointer to the
parent
uXMLMoveToPreviousSibling
Moves the current element pointer to the
previous sibling
uXMLMoveToRootElement
Moves the current element pointer to the
root element
uXMLParse
Parses an XML file
uXMLSetAttributeValue
Sets an attribute value
26
Function Names and Categories
Returned Values
Most of the functions return an integer value upon completion. The
returned values are defined as:
USUCCESS
UFAILURE
The operation was successful.
A failure occurred during the operation; check status
value for the error.
If the function did not execute correctly, test the value of the status
parameter or statusl list to determine which error occurred.
All status and statusl status values are of type USTATUS (or long) and
are defined in the rhlierr.h header file. When an RHLI function fails (it
returns UFAILURE), but the status status value is UENORM, this
typically indicates that the function parameters were not correctly defined
and that the RHLI function could not set the status status value. Refer to
the function description to verify the parameters.
Additional Help
See the Unify DataServer: Error Messages.
Function Names and Categories
27
28
Function Names and Categories
RHLI Application
Basics
29
Chapter
Focus
This chapter describes the features and information that help you write an
RHLI application.
To write an RHLI application, you must have a good understanding of C
language concepts, including structure manipulation and memory
allocation and deallocation.
This chapter contains the following sections:
Include files
Data types and null values
Referencing database objects
ID mapping
Error handling
Transaction kinds: type 0, 1, or 2
Scanning
Compiling and loading
30
RHLI Application Basics
Include Files
Unify DataServer provides two include files that contain definitions for
RHLI database options. Include files are sometimes called header files.
The include files are:
rhli.h
Contains definitions for database options, column data
types and lengths, lock and transaction types, security
privileges and capabilities, return values, and other
database specifications.
rhlierr.h
Contains define statements for all error status values
returned by RHLI functions. When an RHLI function
returns a value of UFAILURE (or 0), it also returns at
least one status value.
The status values can be tested to determine why the
function failed, and if multiple arguments were passed to
the function, which particular argument failed.
In addition, the rhlierr.h file contains brief comments
describing the meaning of each error status value. This
may also be helpful in determining the cause of an error.
uXML.h
Contains definitons used by the XML processing
functions.
You include both the rhli.h and rhlierr.h at the top of an RHLI program,
by using the #include statement. For example:
#include <include/rhli.h>
#include <include/rhlierr.h>
The include files are contained in a directory named include. If the
include directory is not located in the current directory, you have two
ways of specifying to the compiler (and preprocessor) where the
directory is located:
specify the directory path in the –I option on the ucc command
specify the relative path in the include statement itself; use the
angle brackets (<>) to delimit the include directory and file name
RHLI Application Basics
31
Example
To specify the relative path name in the include statement, add the full
relative path and file name in the include statement. Delimit the path and
file name with double quotes (” ”).
#include “../../include/rhli.h”
#include “../../include/rhlierr.h”
The example instructs the preprocessor to search for the include files
beginning in the current directory and apply the ../../ relative path name.
Additional Help
About
32
See
–I option on ucc
Unify DataServer:
Configuration Variable and
Utility Reference
Status values
Unify DataServer: Error
Messages
RHLI Application Basics
Data Types and Null Values
When you define a column, you must specify a data type for the column.
The column data type specifies how that column’s value is stored in the
database and how the column value is displayed. To define a column, use
the uaddtbl function.
A null value is a data value that is unknown or not applicable. While a
null value is a valid value, a column containing a null value is essentially
empty.
The following table compares Interactive SQL/A data types with the
equivalent RHLI representations.
SQL/A and RHLI Column Data Types
Interactive SQL/A
RHLI
SMALLINT
NUMERIC
U_INT
INTEGER
DECIMAL
NUMERIC(5–9)
U_HINT
HUGE INTEGER
U_GINT
FLOAT
U_FLT
AMOUNT
U_AMT
HUGE AMOUNT
U_HAMT
CURRENCY
U_GAMT
DATE
U_DATE
HUGE DATE
U_HDATE
TIME
U_TIME
CHARACTER
U_STR
table continued on next page
RHLI Application Basics
33
SQL/A and RHLI Column Data Types
Interactive SQL/A
RHLI
TEXT
U_VTXT
BINARY
U_VBIN
BYTE
U_BYT
REAL
U_REAL
DOUBLE PRECISION
U_DBL
All RHLI data type declarations are found in the rhli.h header file.
For complete descriptions of the data types, including their precision and
scale, see the DBCOL structure on page 94.
Additional Help
About
34
See
Creating a table and defining
column data types
The uaddtbl function
What the data types are used
for
The “Working With the Data Types
and Null Values” in Unify DataServer:
Writing Interactive SQL/A Queries
UNIPCOLL and UTP_VDDS
The chapter “RHLI Structures”
Null values
The chapter “Working With the Data
Types and Null Values” in Unify
DataServer: Writing Interactive SQL/A
Queries.
RHLI Application Basics
Converting
Internal/External
Data Formats
Before you can display values for columns declared as data types
U_DATE, U_HDATE and U_TIME, you must first convert the column
values from internal to external format: this is because U_DATE,
U_TIME and U_HDATE column values are stored in internal format and
cannot be displayed as such.
The same is true when inserting or updating U_DATE, U_HDATE, and
U_TIME column values into the database: you must convert the external
(display) value into an internal (database storage) format.
The uintext function allows you to convert date and time column values
from internal to external format, and the uextint function converts
external format date and time column values into internal values.
Column values for all data types other than U_DATE, U_HDATE, and
U_TIME do not need to be converted; if the values are converted by
using the uintext or uextint functions, the values remain unchanged.
Converting Internal to External Format
If you want to display date or time data that you have retrieved or fetched
with an RHLI function it is necessary to convert the data from internal to
external format. To convert data, specify the uintext function.
To convert data from internal to external format with the uintext
function, you must first describe the columns you want to retrieve data
from by initializing the internal structure UNIPCOLL.
Converting External to Internal Format
The uextint function converts column values from external data format
to internal format and is used before inserting or updating the column
values into the database with the uinsrow or uupdrow functions.
Before you can convert the date or time data with the uextint function,
you must first describe the external format of the column data you are
updating or inserting by initializing the internal structure UNIPEXT.
RHLI Application Basics
35
Handling String
Data
When storing or retrieving string values from a Unify DataServer
database with RHLI functions, the RHLI function handles string (or data
type U_STR) column values as C language strings. A C language string is
defined as a series of ASCII characters followed by a zero-byte
terminator.
When storing a string value into a column of type U_STR, you must
terminate the end of the string with a zero-byte. A zero-byte at the end of
a string indicates the end of the string value.
However, only the actual string value is stored in the database. Blank
characters at the end of the string, as well as the zero-byte itself, are not
considered part of the string value and are stripped off before the string
value is stored.
When a string column value is retrieved from the database, the RHLI row
retrieval function adds a zero-byte to terminate the string.
A string column of length N requires a maximum of N+1 bytes to return
its value. The extra byte is for the terminating zero-byte.
Handling U_AMT
data
Values that are of data type U_AMT are normally values that represent a
value with a scale of 2. U_AMT values are stored with a default scale of
2.
However, when a U_AMT value is stored into a C variable of type long
integer, the scale is lost. If a U_AMT value is stored into a database
column, the scale is retained. To print U_AMT values that are stored in C
integer values, divide the value by 100 to restore the scale of 2.
36
RHLI Application Basics
Referencing Database Objects
All database objects in Unify DataServer can be referenced with RHLI
functions by either of two methods:
by using a unique numeric identifier that identifies the object;
called the object ID
by using a unique name
The following database objects can be assigned names or IDs:
volumes
databases
tables
columns
column groups
hash tables
B-trees
links
schemas
users
transactions (IDs
only)
Object names other than schema names must be between 1 and 44
characters. All object names must begin with a letter, and cannot include
spaces or any of the following reserved characters:
():.$@#*!’”~‘%^&–+={}[]\|;,<>?
Schema names, however, are limited to a maximum of 18 characters in
length.
Because many database operations performed with RHLI functions
require the object ID, you must ensure that the correct object ID is
specified.
Performance
To improve the performance of name binding, use the name cache. The
name cache keeps a list of current object IDs in local process memory,
where they can be accessed more quickly. The name cache is controlled
by the NAMECACHE configuration variable.
To retrieve an object ID, you bind the object’s name to its current ID.
There are two kinds of name binding:
compile-time name binding
runtime name binding
RHLI Application Basics
37
Compile-Time Name
Binding
To perform compile-time name binding, the object name is embedded
inside the RHLI function call that requires the ID in your RHLI program.
At compile-time, the Unify DataServer C preprocessor upp maps the
object name to the unique object ID and substitutes in the current ID for
that object.
The preprocessor generates code used to detect changes made to the
database object(s) between the time the program was compiled and
eventually run.
If any changes have been made in the given schema, an error code is
returned and the affected modules must be recompiled.
Compile-time name binding can reduce program runtime overhead, but
may require additional compilation and loading steps.
RHLI also features a “remapping” capability that allows you to remap all
compile-time object IDs in the program to their current runtime IDs.
To compile-time name binding, you delimit an object name with special
characters and keywords. When the preprocessor encounters these special
notations in the source code, the object name is replaced with the
appropriate object ID.
The format of compile-time name binding directives is:
$[( class [ : attribute ] )] object_name $
The class indicator specifies the class of object to be addressed.
The attribute indicator specifies the object attribute to be substituted into
the source code. The attribute indicator is optional; if it is not specified,
the object’s ID is substituted into the source code. Each object class has a
unique set of attributes.
The object name is the name of the object.
38
RHLI Application Basics
The following tables lists the class and associated attribute keywords:
Compile-Time Name Binding Keywords
With this class:
You can specify this attribute:
UCOL Object is a column
column’s ID (default
attribute)
TID
column’s table ID
AID
column’s authorization
(schema) ID
DEFID
column’s definition ID
MAPID
column’s ID-mapping ID
COLTYP column’s type
COLLEN column’s internal length
(precision)
COLSCL column’s internal length
(scale)
DSPLEN column’s display length
(precision)
DSPSCL
column’s display length
(scale)
COLDESC column’s description
DSPPICT column’s display picture
clause
QNAME
column’s fully-qualified
name
UTBL Object is a table
table’s ID (default attribute)
table’s authorization
(schema) ID
DEFID
table’s definition ID
MAPID
table’s ID-mapping ID
SEGSZ
table’s segment size
EXPNUM table’s expected number of
rows
TBLBASE table’s base value
TBLDESC table’s description
QNAME
table’s fully-qualified name
UATH Object is an
AID
CID
TID
AID
authorization (schema)
QNAME
authorization’s ID (default
attribute)
authorization’s
fully-qualified name
continued
RHLI Application Basics
39
Compile-Time Name Binding Keywords (continued)
With this class:
UHSH Object is a hash
You can specify this attribute:
HID
index
QNAME
Object is a
B-tree index
UBT
BTID
QNAME
hash index’s ID (default
attribute)
hash index’s fully-qualified
name
B-tree index’s ID (default
attribute)
B-tree index’s fully-qualified
name
ULNK
Object is a
link index
LID
QNAME
UVOL
Object is a
volume
VID
QNAME
UUSR
Object is a user
UID
link index’s ID (default
attribute)
link index’s fully-qualified
name
volume’s ID (default
attribute)
volume’s fully-qualified
name
user’s ID (default attribute)
For example, to retrieve a column’s Table ID, use the following compiler
directive:
$(UCOL:TID)column_name$
When using compiler directives, the class indicator specifies the type of
object. This means that the auxiliary name binding conventions described
in the description for ucc are not needed to identify the object.
40
RHLI Application Basics
Runtime Name
Binding
To perform name binding, specify the object name with one of the
several RHLI name binding functions. The function returns the
appropriate object ID.
To perform name binding on a given object, you must meet one of the
following criteria:
have DBA authority (see the uaddprv function)
be located in the same schema in which the database object resides
(see the ufchath function)
be located in a schema that has been granted schema privileges
that allow you to access the desired object
To perform runtime name binding, you call one of the RHLI object
binding functions in your RHLI program, provide the object name, and it
returns the object ID. Then you pass the ID into the RHLI function that
requires the object ID.
Additional Help
For a list of the name binding functions, see the chapter “Function Names
and Categories”.
RHLI Application Basics
41
ID Mapping
ID mapping provides the option to remap object IDs that are used in an
application to the correct internal set of object IDs.
Each time you refer to a database object in your application programs,
Unify DataServer cross-references its own internal ID table and
substitutes in the correct object ID.
ID mapping alleviates the worry of running your applications on different
database environments. The schema or tables you were able to access in a
previous application are still accessed by the new application, whether or
not the internal structure of the database has been changed.
ID mapping is implemented in one of three ways:
automatic ID mapping happens implicitly when a database is
opened
partial ID mapping
manual ID mapping happens explicitly during execution of the
application
Each time a database is opened, you can specify that all the object IDs
you use in your application are to be remapped before any database
operations begin.
A significant benefit of remapping object IDs when you open a database
is that the object remapping process is all done at once, saving you
processing time later. This feature is particularly helpful for applications
that refer to and access many database objects.
However, manual ID mapping allows you the flexibility to selectively
remapped those objects you feel are critical to the application (or that are
subject to change). The processing of ID mapping is then controlled
locally, only where it is needed.
Manual ID mapping also provides you with the option of choosing a
“custom” object ID that never changes and can be used in your
application programs without having to worry about what the internal
object ID really is. The custom ID is remapped by Unify DataServer to
the correct internal ID each time your custom ID is used to reference an
object.
42
RHLI Application Basics
In either case, once an object ID has been remapping, it stays set until the
database is closed, and is only available to the application program that
initiated the remapping (and opened the database).
Similar to name binding, once an object ID has been remapped, Unify
DataServer assumes you will be accessing the object soon and
consequently places a definition lock on the object.
Object definition locks prevent design changes to the locked objects until
the calling program closes the database and unlocks the objects. This
helps make ID mapping consistent and stable for the duration of the
database session.
Additional Help
For more information about name binding functions, see the “Data
Access and Manipulation” chapter.
Automatic ID
Mapping
Automatic ID mapping remaps all the object ID references you use in
your application programs to runtime IDs when the application opens a
database.
To implement automatic ID mapping, you must:
set the DB_REMAP option each time you open a database in your
application
The DB_REMAP option specifies that all object IDs referenced in
your application programs are to be remapped to their
corresponding runtime object IDs before any processing is allowed
on the database.
use compiler directives in place of each object ID reference in your
application programs
compile and load your application programs by using ucc and uld
Example
The following example shows how to set the DB_REMAP option with the
uopndb function.
/* define uopndb() parameters */
UDBID dbid;
char * dbname = ”/usr/db/parts.db”;
USTATUS status;
RHLI Application Basics
43
if ( uopndb(dbname, DB_REMAP, &dbid, &status) != USUCCESS )
{
printf(”Unable to open the database %s\n”, dbname);
uexit(1);
}
A compiler directive is special syntax that you embed into your
application program(s) wherever a reference to an object ID is made.
Compiler directives are processed by the Unify DataServer compiler, ucc.
When you compile your application programs by using ucc, all compiler
directives embedded in the program code are substituted with a
compile-time object ID.
When your application programs are executed, the compile-time object
IDs that were provided by ucc are then substituted (or remapped) to the
correct runtime object IDs for that particular database.
Compiler directives for automatic ID mapping must always be delimited
with dollar signs ($).
Additional Help
For more information about compiling programs with ucc, see the
“Compiling and Loading” chapter.
The following table shows the compiler directive syntax for specifying a
compile-time object ID.
When specifying an
44
ID for a
The compiler directive syntax for the
compile-time ID is
Schema
$ [ (UATH:AID) ] schema_name $
B-Tree
$ [ (UBT:BTID) ] B-Tree_name $
Column
$ [ (UCOL:CID) ] column_name $
Hash table
$ [ (UHSH:HID) ] hash_table_name $
Link
$ [ (ULNK:LID) ] link_name $
Table
$ [ (UTBL:TID) ] table_name $
Volume
$ [ (UBOL:VID) ] volume_name $
RHLI Application Basics
Example
To refer to a schema named admin, the compiler directive for the
compile-time object ID would be:
$(UATH:AID) admin$
Or, to refer to the table misc contained in schema admin, the compiler
directive for the compile-time object ID would be:
$(UTBL:TID) admin.misc$
This example shows the use of a compiler directive that specifies the
table commissions contained in schema sales.
/* Access table “commissions” using a compiler directive */
if ( ufchrow(tx, $(UTBL:TID)sales.commissions$, USLCK, rid,
&unipcol, statusl, &status) != USUCCESS )
{
printf(”Cannot not access commissions (Table ID=%ld)\n”,
$(UTBL:TID)sales.commissions$);
uexit(99);
}
Partial ID Mapping
Unify DataServer provides for automatic mapping of compile-time
database object IDs referenced in a program to current runtime database
object IDs.
The implementation of partial ID mapping addresses the problem of
assignments of object IDs to a schema change over time or that differ
between application sites.
Automatic ID mapping is accomplished by using the DB_REMAP option
when opening the database with the RHLI function uopndb(). Upon
opening the database, all database objects that are referenced by a
program are remapped.
Automatic ID mapping requires that all of the database objects referenced
by the program be present in the database. Otherwise, the remapping, and
therefore the database open, will fail.
Partial ID mapping eliminates this restriction and defers an error
condition until an unmapped ID is actually used in a later RHLI function.
Partial ID mapping enables delivery of a schema that supports only a
selected set of subsystems of an application. At runtime, the application
is responsible for disabling access to subsystems that will not be
supported.
RHLI Application Basics
45
To implement partial ID mapping:
set the DB_PARTMAP option OR’d with the DB_REMAP option
when using the uopndb() call
use special syntax compiler directives in place of each object ID
referenced in the application program
compile and load the application program using ucc and uld
Manual ID Mapping
Manual ID mapping allows you to selectively remapped compile-time
object IDs to their correct internal IDs.
Unlike automatic ID mapping, manual ID mapping is performed when
you reference the database object, not when the database is first opened.
To implement manual ID mapping, you must:
set the DB_NOLOCK option each time you open a database in your
application
The DB_NOLOCK option specifies that no locking is to be
performed when the database is first opened. This option is
typically used when you want to control which database objects to
lock.
initialize a mapping structure and call the associated mapping
function for each object your application references
compile and load your application programs by using ucc and uld
Remember that when you remapping an object ID, a definition lock is
implicitly placed on that object. Therefore, by remapping object IDs, you
are in effect controlling which objects are protected from other
transaction operations.
By mapping and locking IDs selectively in this manner a minimum of
database objects are tied up at any one time. This allows for greater
concurrency since only the objects your application program uses are
locked.
To use manual ID mapping, you must use the mapping functions. Each
function has an associated structure. The structure must be initialized
before you call a mapping function.
46
RHLI Application Basics
Initializing Mapping Structures
Mapping structures are initialized manually by using a mapping macro.
A mapping macro is a special command that is interpreted by the Unify
DataServer compiler, ucc, and initializes the specified mapping structure
information.
The following table lists the syntax for mapping macros.
Mapping Macro Syntax for Manual ID Mapping
To initialize this
structure:
The mapping macro syntax is:
UATHMAP
INIATHMAP( athnm, aid, –>UATHMAP);
UBTMAP
INIBTMAP( btn, bid, –>UBTMAP);
UCOLMAP
INICOLMAP( colnm, cid, –>UCOLMAP)
UHSHMAP
INIHSHMAP( hshnm, hid, –>UHSHMAP)
ULNKMAP
INILNKMAP(lnknm, tid, –>ULNKMAP);
UTBLMAP
INITBLMAP( tblnm, tid, –>UTBLMAP);
UVOLMAP
INIVOLMAP( volnm, vid, –>UVOLMAP);
where:
athnm
btcnm
colnm
hshnm
lnknm
tblnm
volnm
= schema name
= B-tree name
= column name
= hash table name
= link name
= table name
= volume name
aid
bid
cid
hid
lid
tid
vid
= Authorization ID
= B-tree ID
= Column ID
= Hash Table ID
= Link ID
= Table ID
= Volume ID
The first argument in a mapping macro is the object name: the name of
object is entered (without quotes).
The second argument in a mapping macro is the object ID: you can use a
compiler directive or a custom ID.
The third argument in a mapping macro is a pointer to the structure that
describes the object to be initialized.
RHLI Application Basics
47
Using Compiler Directives
The following example shows the manual remapping of two B-tree IDs,
commissions and revenue, by using compiler directives.
#define NBTMAP
2
/* define umapbt() parameters */
UDBID dbid;
USTATUS
statusl[NBTMAP];
USTATUS
status;
UBTMAP
btmapl[NBTMAP];
/* Initialize UBTMAP structures */
INIBTMAP(sales.commissions, $(UBT:BTID)sales.commissions$,
&btmapl[0]);
INIBTMAP(sales.revenue, $(UBT:BTID)sales.revenue$, &btmapl[1]);
/* Re-map B-trees */
if ( umapbt(dbid, NBTMAP, btmapl, statusl, &status) != USUCCESS )
{
printf(”Unable to map B–tree ID info: status = %ld\n”, status);
uexit(101);
}
When you compile this program (using ucc), the compiler directives
contained in the mapping macros are substituted with B-tree IDs that are
valid at compile-time. The compile-time B-tree ID and the B-tree name
are then used to initialize the UBTMAP structure.
When you execute the program, the function umapbt function uses the
values stored in the structure UBTMAP to find the current, runtime B-tree
IDs.
Using a Custom ID
A custom ID is a unique integer number that you choose to refer to a
database object. Instead of using a compiler directive, you simply use this
“customized” ID number each time you reference an object in the
database.
For example, to initialize the schema admin with a custom ID of 10001,
you simply substitute the aid argument in the mapping macro
INIATHMAP with the value 10001:
INIATHMAP(admin, 10001, &athmapl);
48
RHLI Application Basics
After the umapath function is executed, you can then refer to the schema
admin (with RHLI functions) by using the Authorization ID value 10001.
And the same example, using a compiler directive:
INIATHMAP(admin, $(UATH:AID)admin$, &athmapl);
Example
The following examples shows the remapping of the table manf (found
in the PUBLIC schema), using a custom Table ID.
#define COLNO
18
/* define ’umaptbl()’ arguments */
UDBID
dbid;
UTBLMAP
utblmap;
USTATUS
statusl[COLNO];
USTATUS
status;
/* Initialize UTBLMAP structure */
INITBLMAP(PUBLIC.manf, 1124, &utblmap);
/* Re-map table manf */
if ( umaptbl(dbid, 1, &utblmap, statusl, &status) != USUCCESS)
{
printf(”Mapping of manf failed: status=%ld\n”, status);
uexit(1);
}
/* Access table manf using custom Table ID */
if (ufchrow(tx, 1124, USLCK, rid, &unipcol, statusl,
&status)!= USUCCESS )
{
printf(”Data retrieval failed on Table ID 1124\n”);
uexit(99);
}
Notice the initialization of the compile-time Table ID with the value
1124. This value is then used to reference the table in the ufchrow
function.
Consider these two things if you initialize a compile-time object ID by
using custom initialization:
1. Make sure that the object ID you pick is unique. That is, no two
“custom” object IDs should be the same.
2. Pick a non-zero, positive integer that falls within the acceptable
range for the type of the object ID.
Hopefully, that should be enough to ensure uniqueness Refer to your
system manual to verify the range for a long integer on your machine.
RHLI Application Basics
49
Additional Help
For more examples of how to use manual ID mapping, see the description
for each of the mapping functions.
50
RHLI Application Basics
Error Handling
Errors that occur during execution of RHLI application programs are
located in three areas:
the function itself returns a status value indicating whether or not
the function executed successfully
after each RHLI function executes, a status value is returned; some
functions return a list of status values, each status value
corresponds to an object the function operates on
each system error that occurs is logged to the system file errlog
Each of these is described in this chapter followed by a description of
signal handling.
Status Values of
Function Operations
All RHLI functions return a status value that indicates whether the
function operation was a success or a failure. The return values are:
The status of a function operation can be verified by checking the
function return value.
USUCCESS
The operation was successful.
UFAILURE
A failure occurred during the operation.
If the return value is equal to USUCCESS (or 1), the function operation
was totally successful.
However, a return value of UFAILURE (or 0) indicates that either the
operation failed partially or completely. See Status and Statusl Values on
page 51.
The Status and
Statusl Parameters
If an RHLI function does not execute correctly, the error that occurred is
returned in the status or statusl parameter.
If the function you are executing allows you to specify a list of one or
more objects to be operated on, one or more of the operations involving
these objects may fail: this is considered a partial failure.
RHLI Application Basics
51
Testing for Partial Failure
A partial failure is indicated when the RHLI function returns the value
UEPART into the status parameter. One (or more) of the objects listed in
the object list was operated on and an error occurred.
After each function operation, the statusl list contains a corresponding
status value for each object operation listed in the object list. If a partial
failure occurs, simply check the status value for each element of statusl
to diagnose which object operation failed.
For example, if the first object operation in the object list failed, the first
element in statusl contains the appropriate error status value; if the third
object operation failed, the third element value of statusl contains the
corresponding error status value (and so on).
If an object operation was successful, however, the corresponding statusl
entry contains the status value UENORM.
All status and statusl status values are of type USTATUS (or long).
Example
The following is a sample function (named reterr) that can be used if a
partial failure occurs: the reterr function checks each entry in statusl and
returns a status value for the first error it finds.
#include <include/rhli.h>
#include <include/rhlierr.h>
USTATUS reterr(status, nstat, statusl)
USTATUS status;
/* status value */
int nstat;
/* # of entries in statusl */
USTATUS statusl[]; /* status list */
{
int indx;
/* temp index variable */
/* If the status value is set to UEPART, check each statusl */
/* entry for an error status value. */
if ( status == UEPART )
{
for ( indx = 0; indx < nstat; ++indx )
{
if ( ((status = *(statusl + indx)) != UENORM)
&& (status != UENOWRK) )
{
break;
}
}
}
return(status);
/* return the first error status value */
}
52
RHLI Application Basics
After verifying that status is equal to UEPART, the reterr function checks
for each element in statusl for an error status: UENORM indicates
success, and UENOWRK indicates that no work was done on this object
due to an error elsewhere in the operation.
Once you know the reason for the partial failure, you have the option of
redoing the entire operation (after the current transaction has been
aborted or rolled back), or, to just redo the operation(s) for the object(s)
that failed after you correct any programming errors in the application
that caused the error.
Testing for Complete Failure
If a function operation fails completely, a non-UEPART status value is
returned to the function parameter status.
For example, if the umodath function fails, the status parameter is set to
one of the following values:
UEILTX
Invalid Transaction ID
UEDBCLS
Database is closed
UENOAID
Invalid Authorization ID
UENLONG
Name too long
UEBDNM
Illegal characters in the user name
If status is set to UEPART, then a partial failure occurred.
Additional Help
About
RHLI Application Basics
See
All status and statusl status values
Unify DataServer: Error
Messages, or the rhlierr.h
header file
Partial failures
“Testing for Partial Failure”
on page 52
53
Retrieving a Status Value Message
Once you have a status value, you can check what the error code means
by either:
checking the Unify DataServer: Error Messages manual
checking the rhlierr.h header file
retrieving (and displaying) the error message
The first and second options assume your application programs print (or
store) the status values so that you can look them up.
The third option, however, allows you to retrieve (and if you wish, to
display) the error message text for the status value. This is accomplished
by using the ufchmsg function.
Additional Help
For more information about how to retrieve text for status value error
messages, see the ufchmsg function.
Most Common
RHLI Function
Status Values
This section describes the most commonly occurring status values
returned from each RHLI function. You can use this section to determine
the conditions that you can test for when a function is used in your
application.
The following status codes are the most commonly occurring codes for
all of the functions:
54
UENORM
The function completed successfully; no error condition
is returned.
UEPART
Errors are returned through the status list.
UENOMEM
More (dynamically allocated) memory is needed.
UELMOUT
A locking conflict exists.
UEINTRPT
An interrupt was received.
UESGTERM
A SIGTERM interrupt was received.
RHLI Application Basics
UEDBDOWN
The database is being shut down, gracefully close
database.
UEILTX
An illegal transaction id was encountered.
UENOPRV
Current user does not have privilege required for
operation.
UENOPRIV
Same as UENOPRV.
UEEXCPMP
The database is opened with conditional ID remapping
(DB_REMAP|DB_CONDMAP). It indicates that a
compile-time ID used in the function failed to remap at
the time uopndb() is called. (Note that conditional
mapping defers reporting the error until the ID is used.)
For more information about the status codes, see Unify DataServer:
Error Messages.
The following table lists status codes that are associated with specific
functions. These status codes occur most frequently with the associated
function, in addition to the list of commonly occurring functions listed
above.
Function
Most Frequent Status Codes
uabttx
UENOABRT
uaddath
UENOXID
uaddbt
UEBDNAM
UEDUPNM
UEMXBKL
UENMLONG
UECOLTP
uaddcgp and uaddcnm
UEBDNAM
UEDUPNM
UENMLONG
UENMREQ
uadddb
UEBDNAM
UEDUPNM
UEDLONG
UENMLONG
UERSVNM
uaddhsh
UEBDNAM
UEDUPNM
UENMLONG
uaddlnk
UEBDNAM
UEDUPNM
UENMLONG
table continued on next page
RHLI Application Basics
55
Function
Most Frequent Status Codes
uaddprf
UEDUPPRF
uaddprm
UEDUPK
uaddprv
UENOGRT
uaddtbl
UEBDNAM
UEDUPNM
UENOCOL
UENMLONG
UENOVID
UEDLONG
uaddtnm
UEBDNAM
UEDUPNM
UENMLONG
UENMREQ
uaddusr
UEBDNAM
UEDUPNM
UEDUPUSR
UENMLONG
UENMREQ
uaddvol
UEBDNAM
UEDUPNM
UEEXIST
UENMLONG
UENMREQ
ubegord
UENOSAM
UENOMEM
UEMXSCN
ubegtx
UEUMXTX
ubndath
UENMPRS
UENONAME
ubndbt
UENMPRS
UEAMBIG
UENONAME
ubndcol
UENMPRS
UEAMBIG
UENONAME
ubnddb
UENONAME
ubndhsh
UENMPRS
UEAMBIG
UENONAME
ubndlnk
UENMPRS
UEAMBIG
UENONAME
ubndtbl
UENMPRS
UENONAME
ubndusr
UENONAME
ubndvol
UENONAME
table continued on next page
56
RHLI Application Basics
Function
Most Frequent Status Codes
uclsdb
UETXACTV
udelrow
UEREF
UEBIGLG
udrpath
UENOAID
UENONAME
udrpbt
UENOBT
UENONAME
udrpcgp
UENONAME
UEDRCGP
UENOUNQ
udrpcnm
UENOTID
UENONAME
udrphsh
UENOHID
UENONAME
UENOCID
UENOHSH
udrplnk
UENOLID
UENONAME
UEREF
UENOCID
UENOLNK
udrpprf
UENOVID
UENOPRF
udrpprm
UENOUID
UENOPRM
UENOAID
udrpprv
UEUKNOBJ
UENOOBJ
UEUNPRV
udrptbl
UENOTID
UENONAME
UEVIEW
UENMPRS
udrptnm
UENOTID
UEBDNAM
UEVIEW
UENONAME
udrpusr
UENOUID
UEDBOWN
udrpvol
UENOVID
UEVLACT
UEBDVOL
UENONAME
uextint
UESTRLNG
UECONV
ufchath
UENOAID
UENOPRM
ufchcnm
UENOCID
UENONAME
ufchlnk
UENOCID
UENOREF
UENONAME
UENOLID
table continued on next page
RHLI Application Basics
57
Function
Most Frequent Status Codes
ufchord
UEBDATYP
UENOROW
UENOTID
UENOCOL
ufchrow
UENOTID
UENOCOL
UENOROW
ufchscn
UEBDSZR
UEVDBUF
UEBDBNX
UENOWRK
UEBDFNX
UEBDFTP
UEEOSCN
UECONV
ufchtbl
UECONV
UEVDBUF
UENOWRK
UEEOSCN
UEBDFTP
uinfath
UENOWRK
UENOAID
uinfbt
UENOBID
UENOWRK
uinfcgp
UENOWRK
uinfcol
UENOWRK
uinfdb
UENOWRK
uinflck
UENOLCK
uinflnk
UEPART
uinfsch
UENOLCK
uinftbl
UEPART
uinftx
UEPART
uinfusr
UENOWRK
umapath
UEISMAP
UENONAME
UENOMAP
UENMPRS
UEMNMAP
umapbt
UEISMAP
UENONAME
UEMNMAP
UENMPRS
UEAMBIG
UENOMAP
UEPART
table continued on next page
58
RHLI Application Basics
Function
Most Frequent Status Codes
umapcol
UEISMAP
UENONAME
UEMNMAP
UENOMAP
UENMPRS
UEAMBIG
UEBDMAP
umaphsh
UEISMAP
UENONAME
UEMNMAP
UENMPRS
UEAMBIG
UENOMAP
umaplnk
UEISMAP
UENONAME
UEMNMAP
UENMPRS
UEAMBIG
UENOMAP
umaptbl
UEISMAP
UENONAME
UEBDMAP
UENMPRS
UEMNMAP
UENOMAP
umapvol
UEISMAP
UEMNMAP
UENONAME
UENOMAP
umodath
UENMLONG
UEDUPNM
UEBDNAM
umodbt
UENMREQ
UEBDNAM
UENMLONG
UEDUPNM
umodhsh
UENMREQ
UEBDNAM
UENMLONG
UEDUPNM
umodlnk
UENMREQ
UEBDNAM
UENMLONG
UEDUPNM
umodusr
UENMREQ
UEBDNAM
UENMLONG
UEDUPNM
umodvol
UENMREQ
UEBDNAM
UENMLONG
UEDUPNM
unumcgp
UENOCID
unumchd
UENOTID
UENOVID
unumcol
UENOTID
UENOROW
table continued on next page
RHLI Application Basics
59
60
Function
Most Frequent Status Codes
unumprn
UENOTID
UENOVID
unumrow
UENOTID
unumtbl
UENOAID
uopndb
UEDBOPN
UENDENT
UEINVAL
uopnjrn
UENOENT
UEINBHDR
upkfrow
UENOTID
UENOCID
UENOROW
UENOKEY
UENOCGP
uposord
UEEOSCN
usetitr
UEINVAL
uskrord
UEBDATYP
UEEOSCN
uulkdb
UENOLCK
uulkrow
UENOLCK
UENORID
UENOTID
uulksch
UENOTID
UENOLCK
uulktbl
UENOTID
UENOLCK
uupdrow
UENOTID
UENORID
uXML*
UEDOMEX
UEGENEX
UENTELEM
UENOBIN
UEFILNF
UENONDVL
UENOPELM
UENDNTFD
UEERRXML
UENOCHLD
UENONCOL
UEBADUN
UEXMLEX
UENOSIB
XMNOATTR
UENOROW
UENORID
RHLI Application Basics
System Error Log
File
Located in every application database directory, the system error log file,
dbname.err, is used by Unify DataServer to log system status and error
messages.
Status and error messages are appended to dbname.err each time a major
status event or system error occurs and can be checked by using any
standard Unix system editor, such as vi.
A dbname.err file is implicitly created each time a new database is
created with the uadddb function. While you can delete the contents of
the errlog file, do not remove the file.
Error Log File
All errors and status conditions that occur during the execution of an
RHLI application program that accesses a Unify DataServer database are
written to the system error log file, errlog. Errors and status conditions
are logged to errlog in a format similar to this example:
Error Log File
**************************Wed Sep 7 09:04:56 1988
Program: creatdb
Calling function: bterrlg.c
Offending function: bterrlg.c
Status: 0
Errno: 0
Notes: errlog created*********Wed Sep 7 09:05:05 1988
Program: creatdb
Calling function: bterrlg.c
Offending function: bterrlg.c
Status: 223
Errno: 4096
Notes: writing normal sync record*********Wed Sep 7 09:13:50 1988
Program: fmdmn
Calling function: wrnsnlg.c
Offending function: wrnsnlg.c
Status: 223
Errno: 8192
Notes: writing normal sync record
An errlog file is created each time a new database is created and is
located in your local database directory. Every database directory must
contain an errlog file. To create a database, use the uadddb function.
RHLI Application Basics
61
Transaction Types
RHLI features three types of transactions, each of which enforces a
different level of concurrency and database integrity:
Type 2
Type 1
Type 0
Type 2 transactions are the most restrictive, while Type 0 transactions are
the most lenient in terms of concurrency and preserving maximum
database integrity.
This kind of flexibility allows you to tailor your applications according to
the sensitivity of certain database operations.
You specify the transaction type when you begin a transaction with the
ubegtx or ucbgtx functions.
Type 2 Transactions
A Type 2 transaction strictly enforces any shared or exclusive locks that
the transaction acquires while performing its operations. All locks remain
in place until the transaction commits or aborts.
This type of transaction limits database concurrency but improves data
integrity and provides the highest degree of read reproducability.
Type 2 transactions are especially useful for those operations where
performance is less important but data accuracy and consistency is
critical.
For example, a banking transaction dealing with monetary amounts
would use a Type 2 transaction to perform database updates.
62
RHLI Application Basics
Type 1 Transactions
A Type 1 transaction enforces all locks acquired by the transaction,
except that shared locks can be released successfully at any time during
the transaction. This improves database concurrency but reduces read
reproducability of data.
Type 1 transactions are useful in cases where good performance is
required but data accuracy is less important.
For example, a Type 1 transaction would be useful in an inventory
system, where updates to the inventory tables must be made quickly and
checks for inventory figures can be approximate.
Type 0 Transactions
A Type 0 transaction is able to read uncommitted data locked by other
processes or transactions. This type of transaction cannot be used to
perform any update operations and should be used with caution.
Type 0 transactions are normally used when high performance is required
but the accuracy of the data is not as important.
For example, a Type 0 transaction might be used by a reporting
application that generates statistical reports used to portray data at a
given moment in time (sometimes called “snapshot” reporting).
RHLI Application Basics
63
Scanning
Scanning is a method for retrieving one or more rows from a table. You
determine which rows are retrieved by specifying selection criteria. Unify
DataServer examines the existing access methods for the table and
determines the best possible access method for retrieving the rows.
To perform a scan, follow these general steps.
1. Allocate a scan information structure by calling the ualcscn
function. This structure eventually will contain information about
the table column values that are compared by using the specified
selection criteria.
The ualcscn function returns a pointer to the Scan Information
Structure. This structure is referenced during the remaining scan
operations.
2. Indicate which table the scan is to be performed on by calling the
uinstbl function.
3. Indicate which columns are to be projected by calling the uinsprj
function.
The function uinsprj function must be called once for each
column that is to be included in the projection. The sequence of
columns that are added to the projection list determines the order
that the columns appear in the rows returned from the scan.
4. Allocate a criteria structure by calling the uinsand function.
5. Specify individual selection criteria by calling the uinsor function.
Selection criteria can include column value matches or
comparisons. Multiple criteria for a single column are grouped
together by using “or”, to create one or more “or-groups”.
If there is more than one column being matched or compared, the
resulting “or-groups” are grouped together with “and”.
6. If you want the retrieved rows to be ordered, specify the sort keys
and sort order by calling the uinssrt function.
64
RHLI Application Basics
7. If you want to get DBVAL column structures, call the uinfscn
function.
8. Begin the scan by calling the ubegscn function. The ubegscn
function uses the scan information in the Scan Information
Structure to determine the best method for retrieving the rows: it
selects the rows that meet the criteria specified and returns a Scan
ID that can be used to identify the row(s) selected by the scan.
When calling the ubegscn function, you can specify whether it
should lock the rows returned with the scan by using a shared or an
exclusive lock, or if it should not lock them.
9. Fetch rows from the scan by calling the ufchscn function. Before
rows can be retrieved from the scan, you must allocate space for
the column values that are returned with ufchscn.
This can be done in one of two ways:
by calling the uinfscn function to generate a database
value list based on the projection list and implicitly
allocate space
by manually constructing a database value list that
matches the type and number of columns in the
projection list, and allocating space in your program
The uinfscn function uses the scan projection list information
stored in the Scan Information Structure to generate a database
value list.
The database value list contains the column values and any column
options (such as whether the database value is null, or whether it
should be ignored when converting from internal to external
format and vice versa).
The uinfscn function uses the information in the database value
list to allocate space to receive the column values when retrieving
rows with the ufchscn function.
Rows are then locked and retrieved from the scan by using the
ufchscn function.
10. End the scan by calling the uendscn function.
11. Deallocate the scan information structure by using the ufrescn
function.
In addition, you can specify that the structure only be emptied, so
that you can respecify all new scan criteria without having to
reallocate space by using the ualcscn function.
RHLI Application Basics
65
The steps are indicated in the following example.
Additional Help
About
See
The syntax of the functions
An example
Function reference for each
function
The example in this section performs a scan on a table named table1. The
following diagram indicates the table, column names, data types, and
values used in the scan.
The table1 Table
A
B
C
1
0
2
2
2
2
NORTH
NORTH
WEST
EAST
NORTH
NORTH
3.00000
3.00000
3.00000
3.00000
4.00000
8.00000
CHAR(20)
NUMERIC(9)
FLOAT
The equivalent SQL/A query that the scan performs is:
SELECT A, B, C FROM table1
WHERE A BETWEEN 1 and 100
AND (B = ”NORTH” or B = ”WEST”)
AND C < 7.824;
This query has four conditions; each condition requires a separate call to
the uinsor function. These are the conditions:
Column A is between the values 1 and 100.
Column B is equal to NORTH.
Column B is equal to WEST.
Column C is less than 7.824.
66
RHLI Application Basics
#include <stdio.h>
#include <include/rhli.h>
#include <include/rhlierr.h>
#define N_TABLE1_COL 3
UDBID dbid;
UTXID txid;
USTATUS status[1];
USTATUS statusl[N_TABLE1_COL];
UTXOPT txopt;
char *scaninf;
int scanid;
int prevlck;
URID rid;
UDBVAL search_dbv[5];
UDBVAL *prjvall;
UDBVAL *nulldbv;
UTID tid = $table1.$;
UCID cidl[] = {$table1.A$,$table2.B$,$table3.C$};
long a1,a2;
char b1[20],b2[20];
double
c1;
/*
** INIT_DBVALL
**
** Since these buffers probably only need to be set up once,
** no matter how often you do the query, it is best to
** initialize them in some function once, and if possible
** call it only once. This will save runtime CPU time.
*/
init_dbvall()
{
search_dbv[0].unip.hintp = &a1;
search_dbv[1].unip.hintp = &a2;
search_dbv[2].unip.strp = b1;
search_dbv[3].unip.strp = b2;
search_dbv[4].unip.fltp = &c1;
Step 1
Step 2
Step 3
nulldbv = (UDBVAL *) 0L;
}
main ()
{
init_dbvall();
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
if (uopndb (””,DB_NORMAL,&dbid,status) != USUCCESS)
fatal (”uopndb”);
if (ubegtx (dbid,UROOTTXID,&txid,&txopt,status)
!= USUCCESS)
fatal (”ubegtx”);
if (ualcscn (txid,0,0,0,&scaninf,status) != USUCCESS)
fatal (”ualcscn”);
if (uinstbl (txid,scaninf,tid,status) != USUCCESS)
RHLI Application Basics
67
fatal (”uinstbl”);
if (uinsprj (txid,scaninf,3,cidl,statusl,status)
!= USUCCESS)
fatal (”uinsprj”);
init_criterea();
Step 4
Step 5
if (uinsand (txid,scaninf,4,status) != USUCCESS)
fatal (”uinsand”);
if (uinsor (txid,scaninf,$table1.A$,
URNGCC,&search_dbv[0],&search_dbv[1],status)
!= USUCCESS)
fatal (”uinsor.1”);
if (uinsor (txid,scaninf,$B$,
ULIKE,&search_dbv[2],nulldbv,status)
!=USUCCESS)
fatal (”uinsor.1”);
if (uinsor (txid,scaninf,$table2.B$,
ULIKE,&search_dbv[3],nulldbv,status)
!= USUCCESS)
fatal (”uinsor.2”);
if (uinsor (txid,scaninf,$table3.C$,
ULETST,&search_dbv[4],nulldbv,status)
!= USUCCESS)
fatal (”uinsor.3”);
Step 7
Step 8
Step 9
if (uinfscn (txid,scaninf,&prjvall,status) != USUCCESS)
fatal (”uinfscn”);
if (ubegscn (txid,USLCK,scaninf,&scanid,status)
!= USUCCESS)
fatal (”ubegscn”);
while
(ufchscn(scanid,&rid,prjvall,&prevlck,statusl,status) ==
USUCCESS)
{
fprintf (stdout,”%d | %s | %f\n”,
*(prjvall[0].unip.hintp),
prjvall[1].unip.strp,
*(prjvall[2].unip.fltp));
}
if (*status != UEEOSCN) fatal (”ufchscn”);
Step 10
Step 11
if (uendscn (scanid,status) != USUCCESS)
fatal (”uendscn”);
if (ufrescn (txid,&scaninf,DB_RESET,status) !=
USUCCESS)
fatal (”ufrescn”);
if (ucmttx (txid,status) != USUCCESS)
fatal (”ucmttx”);
if (uclsdb (dbid,DB_NORMAL,status) != USUCCESS)
fatal (”uclsdb”);
uexit (0);
68
/* should bail out here */
RHLI Application Basics
fatal (”uexit”); /* otherwise bail out from fatal */
}
RHLI Application Basics
69
Compiling and Loading
RHLI programs are compiled and loaded in two steps:
Step 1
Compile the program source files by using the Unify DataServer C
compiler ucc.
Step 2
Load the program object file(s) by using the Unify DataServer C program
loader uld.
Before compiling and loading your RHLI program, make sure that you
have:
included the proper header file(s) in your program
used the correct C data types to maintain compatibility with the
Unify DataServer database types
named your program by using a file name of 11 characters or less,
beginning with a character
Compiling With ucc
The Unify DataServer C compiler, ucc, compiles an RHLI source file and
creates an object file. The ucc compiler uses the preprocessor upp and
the system C compiler cc.
The upp preprocessor identifies any database object names in the source
file that need ID mapping or name binding performed. The preprocessor
substitutes appropriate object IDs for objects referenced with name
binding or ID mapping constructs.
The upp preprocessor produces two intermediate files
A file that contains the substituted object IDs for all object
references. The file contains the .u suffix.
A preprocessed file used as input to the cc compiler. The file
contains the .p suffix.
The .u file identifies the objects referenced in the source file and contains
the corresponding definition ID assigned by the database to each table or
column.
70
RHLI Application Basics
The table and column definition IDs are used to identify the given table
or column at that point in time. If any updates are later made to the table
or column in the database, a new definition ID is generated and stored in
the database.
The definition IDs stored in the .u files are compared to current IDs
during runtime to determine whether changes have occurred to the
database that affect the accuracy of the name binding that was performed
earlier.
After the preprocessing phase, ucc renames the .p file by using the
format Ufile.c, where the original source file name is prefixed with “U”
and concluded with “.c”. ucc then passes the Ufile.c files, along with any
other arguments entered in the ucc command line, to the UNIX or host
operating system C language compiler, cc.
The cc compiler is the UNIX or host operating system C language
compiler that compiles the preprocessed source file and generates an
object file. The object file contains the suffix .o.
RHLI Application Basics
71
The Compilation Process
Source File
file.c"
Preprocessor
upp
Intermediate
Data File
file.p"
C Compiler
(This file is created only if the
program references database
tables and columns. It is passed
ontoăthe loader, uld.)
Intermediate
Data File
file.u"
(optional)
1
C Compiler
cc
ucc
Intermediate
Source File
Ufile.c"
1
Object File
Ufile.o"
C Compiler
ucc
Object File
file.o"
The Loading Process
The Unify DataServer program loader, uld, verifies that changes have not
occurred to the referenced database objects since the object files were
compiled, then loads the files by using the UNIX or host operating system
link loader, ld.
ld combines the object file(s) and any archive files specified, resolves
external references, searches libraries specified, and generates the
program executable.
72
RHLI Application Basics
RHLI program object files are loaded by running uld from the operating
system shell, passing the RHLI program object files (.o) as arguments, as
well as any archive files and their corresponding .u files.
During loading, intermediate data files are created to aid in detecting
database changes between compile-time, load-time, and runtime.
The uld utility loads an object file created by the ucc utility. The object
files (.o) and any archive files (.a) are passed as arguments to uld.
If the specified archive files depended on compile-time name binding,
you must specify the corresponding .u file name along with the archive
file name in the uld command line.
If any of the object files performed name-binding at compile-time, there
must be a corresponding .u file existing in the current directory. If one
does not exist, then the source file(s) must be recompiled by using ucc
(or with upp and cc).
For each .o file passed in the command line, uld searches for the
corresponding .u file. For those object files or archive files with a
corresponding .u file, uld interacts with the database to retrieve
information about the tables and columns referenced.
If there are any discrepancies between the information in the .u files and
the database objects in the database, then the objects referenced have
been updated since compilation.
In this event, uld fails and returns an error message stating which object
files contained the invalid references. The invalid object files must then
be recreated by recompiling the corresponding source files.
If no changes have been made to the referenced tables and columns since
compilation, uld generates an intermediate source code file named
Ufile_h.c which contains information that is used when the executable is
run and the database is opened.
The intermediate source file Ufile_h.c is compiled by uld and the
resulting object file is then passed on to the UNIX or host operating
system C loader ld.
ld combines the object files, resolves external references, searches
libraries and produces an executable file. For more information about ld,
see the manual for your UNIX or host operating system C loader.
RHLI Application Basics
73
The following diagrams shows the loading process.
Events That Take Place During Loading
Object File
file.o"
Archive File
file.a"
Intermediate
Data File
file.u"
(optional)
DataServer
C PROGRAM
LOADER
uld
Intermediate
Data File
Ufile_h.c"
UNIX
C PROGRAM
LOADER
ld
RHLI
Program
Executable
file"
74
RHLI Application Basics
The RHLI Structures
75
Chapter
Focus
This chapter describes the structures used with many of the RHLI
functions. This chapter contains the following sections.
About the Structures
Structure Index
Structure Descriptions
76
The RHLI Structures
About the Structures
The structures used by the functions contain information specific to the
operation that the function performs. You must initialize the correct
structure with the appropriate data values before you call an RHLI
function.
The table on page 77 lists the RHLI functions and the structures
associated with each function. Some functions do not require the use of a
structure.
Structures are passed to the RHLI functions as pointers to the structures
rather than as the structures themselves.
All RHLI function structures are declared and defined in the rhli.h header
file. You must specify this file in an INCLUDE statement in your C
program that references RHLI functions
Structure Index
The following table lists the RHLI functions and the associated structures.
Use this table to determine which structure to initialize before calling the
associated function.
Function
Structure
uabttx
uaddath
uaddbt
uaddcgp
uaddcnm
uadddb
uaddhsh
uaddlnk
uaddprf
DBAUTH
DBBTREE
DBCGRP
DBCOLNM
DBINFO
DBHASH
DBLINK
1UDBVAL
None
None
Function
uaddprm
uaddprv
uaddtbl
uaddtnm
uaddusr
uaddvol
ualcscn
ualctbl
uallath
Structure
None
UGRTDS
DBTABLE
DBTBLNM
DBUSER
DBVOLM
None
UNIPCOLL
None
is a member of the UNIPCOLL structure.
continued
The RHLI Structures
77
Function
Structure
uallbt
uallcgp
uallcol
uallhsh
ualllnk
uallpid
ualltbl
ualltx
uallusr
None
None
None
None
None
None
None
None
None
uallvol
ubegord
ubegscn
ubegtx
ubndath
ubndbt
ubndcol
ubnddb
ubndhsh
ubndlnk
ubndtbl
ubndusr
ubndvol
ucbgtx
uclritr
uclsdb
uclsjrn
ucmttx
None
None
None
None
None
None
None
None
ucrypwd
udelrow
udrpath
udrpbt
udrpcgp
udrpcnm
udrphsh
udrplnk
udrpprf
None
uextint
UNIPCOLL,
UNIPEXT
ufchath
ufchcnm
ufchjrn
ufchlnk
ufchmsg
ufchord
ufchrow
None
None
udrpprm
udrpprv
udrptbl
udrptnm
udrpusr
udrpvol
uendord
uendscn
uexit
ufchscn
ufchtbl
ufchtnm
ufrescn
uinfacs
uinfath
uinfbt
uinfcgp
uinfcol
1UDBVAL
UTXOPT
Function
URVKDS
None
DBTBLNM
None
None
None
None
None
UDBVAL1
UNIPCOLL
None
None
UACSINF
UATHINF
UBTINF
UCGPINF
UCOLINF
uinfdb
uinfhsh
uinflck
uinflnk
uinfsch
uinfscn
uinftbl
uinftx
uinfusr
Structure
None
UOACOLS
None
UTXOPT
None
None
None
None
None
None
None
None
None
DBCGRP
DBCOLNM
None
None
None
UJRNINF
UNIPCOLL
None
UNIPCOLL
UNIPCOLL
UDBINF
UHTINF
None
UNLKINF
None
UDBVAL1
UTBLINF
UTXINF
UUSRINF
is a member of the UNIPCOLL structure.
continued
78
The RHLI Structures
Function
Structure
Function
uinfvol
uinimsg
uinsand
uinsbuf
uinsor
uinsprj
uinsrow
uinssrt
UVOLINF
uinstbl
uintext
None
UNIPCOLL
UNIPEXT
None
UNIPCOLL
None
ulckdb
ulckrow
ulcksch
ulcktbl
ulogmsg
None
None
None
None
None
umapath
umapbt
umapcol
umaphsh
umaplnk
umaptbl
umapvol
umodath
umodbt
UATHMAP
UBTMAP
UCOLMAP
UHSHMAP
UNLMAP
UTBLMAP
UVOLMAP
DBAUTH
DBBTREE
umoddb
umodhsh
umodlnk
umodusr
umodvol
unumath
unumcgp
unumchd
unumcol
DBINFO
DBHASH
DBLINK
DBUSER
DBVOLM
unumprn
unumrow
unumtbl
unumusr
unumvol
uopndb
uopnjrn
upkfrow
None
None
None
None
None
None
None
uposord
usetitr
uskrord
uulkdb
uulkrow
uulksch
uulktbl
uupdrow
UDBVAL1
1UDBVAL
The RHLI Structures
None
None
None
Structure
UDBVAL1
UNIPCOLL
None
None
None
None
None
None
None
None
None
None
UNIPCOLL
is a member of the UNIPCOLL structure.
79
The DBAUTH Structure: Schema
Information
The DBAUTH structure has the following declaration.
typedef struct
{
UAID aid;
UXID xid;
char * authnm;
} DBAUTH;
/* Authorization ID (returned)*/
/* reserved for future use
*/
/* pointer to schema name
*/
The DBAUTH structure is used by the uaddath and umodath functions
to describe a schema. The uaddath function adds a new schema. The
umodath function modifies, or changes, a schema name.
The aid member contains the authorization ID of the schema. If the
schema is being added with the uaddath function, Unify DataServer
places the authorization ID in aid. Otherwise, you must supply an
existing authorization ID.
The xid member is reserved for future use. Set xid to UNULLXID.
The authnm member contains a pointer to a buffer containing the name of
the schema. The name can be specified when adding a new schema or
when modifying an existing schema name. If a name is not desired, set
authnm to (char *)0 or to an empty string.
80
The RHLI Structures
The DBBTREE Structure: B-tree Index
Information
The DBBTREE structure has the following declaration.
typedef struct
{
char * btname;
UBTID btid;
UOPTS btopts;
UTID tid;
UVID vid;
int ncol;
UBTCOL * btcoll;
USTATUS * statusl;
} DBBTREE;
/*
/*
/*
/*
/*
/*
/*
/*
name of B-tree
B-tree ID
B-tree options
table B-tree indexes
volume on which to place B-tree
number of columns
list of columns for B-tree key
list of corresponding statuses
*/
*/
*/
*/
*/
*/
*/
*/
The DBBTREE structure is used by the uaddbt and umodbt functions to
specify B-tree information. The uaddbt function adds a new B-tree
index. The umodbt function modifies an existing B-tree index name.
The btname member contains a pointer to a buffer containing the name of
the B-tree. The name must contain the B-tree name only; it cannot
contain the corresponding schema name or table name prefixes. If a name
is not desired, set btname to (char *)0 or an empty string.
The btid member contains the B-tree ID. If the B-tree is being added, the
system returns the B-tree ID in btid. Otherwise, you must supply an
existing B-tree ID.
The umodbt function can modify a B-tree name only; therefore, only the
btname and btid members need to be initialized when calling the umodbt
function.
The btopts member contains the B-tree creation options:
The RHLI Structures
DB_INSCATTER
data may be scattered across volumes
DB_IXUSEVOL
specifies preferred volume to use
DB_DUPNOK
no duplicate keys
DB_DUPSOK
allow duplicate keys
81
DB_NORMAL
DB_DUPNOK is the default value used
The tid member contains the table ID to which all of the columns
comprising the B-tree index belong.
The vid member is reserved for future use.
The ncol member contains the count of the number of entries in the
B-tree index column list (btcoll).
The btcoll member contains a pointer to a list of B-tree index column
structures (UBTCOL) which describe the columns comprising the btree
index. The list contains ncol entries.
The rank (or position) of each column in the B-tree index is implied by
its location in this list; for example, the column described by btcoll[0] is
the most significant column and is of rank 1.
The statusl member contains a pointer to a list of B-tree index column
status buffers. The list contains ncol entries. Upon completion of the
B-tree operation, each entry in the status list contains an error code which
indicates the result of the operation for the corresponding column entry in
the btcoll list.
The UBTCOL Structure
The UBTCOL structure specifies information about a column that makes
up the B-tree. The UBTCOL structure is declared as follows:
typedef struct
{
UCID cid;
UOPTS btcopts;
} UBTCOL;
/* Column ID
/* DB_ASCEND || DB_DESCND
*/
*/
The cid member contains the column ID of a column which is to
comprise the B-tree index.
The btcopts member contains the B-tree column processing options as
they relate to the corresponding column:
DB_ASCEND
ascending key value
DB_DESCND
descending key value
DB_NORMAL DB_ASCEND is the default value used
82
The RHLI Structures
The DBCGRP Structure: Column
Group Information
The DBCGRP structure has the following declaration.
typedef struct
{
UCID grpcid;
DBCMBR * mbrlst;
USTATUS * statusl;
int ncol;
UOPTS colopts;
} DBCGRP;
/*
/*
/*
/*
/*
/*
Column Group ID (returned)
pointer to column group member
column list
array of column status codes
# of columns in ’mbrlst’
group column processing options
*/
*/
*/
*/
*/
*/
The DBCGRP structure is used by the uaddcgp and udrpcg functions to
specify information about a column group.
The grpcid member contains the column group ID. If the column group is
being added, Unify DataServer places the column group ID in grpcid.
Otherwise, you must supply an existing column group ID.
The mbrlst member contains a pointer to a list of DBCMBR column
group member structures which describes the columns which comprise
the column group. The list contains ncol entries. The DBCMBR structure
is described on page 84.
If DB_ORDERD is specified for colopts, the rank (or position) of each
column in the mbrlst member list is implied by its location in this list. For
example, the column described by mbrlst[0] is the most significant
column and is of rank 1. If DB_ORDERD is not specified, Unify
DataServer assigns the rank by ordering the column IDs.
The statusl member contains a pointer to a list of member column status
buffers. The list contains ncol entries. Upon completion of the column
group operation, each entry in the status list contains an error code which
indicates the result of the operation for the corresponding column entry in
the mbrlst list.
The ncol member contains the count of the number of entries in the
column group member column list mbrlst.
The RHLI Structures
83
The colopts member contains the column group options (attributes):
DB_ORDNRY
ordinary column
DB_COLKEY
column is primary key for table
DB_UNIQUE
column must be unique
DB_ORDERD column is ordered
DB_NORMAL DB_ORDNRY is the default value used
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
If DB_COLKEY or DB_UNIQUE is specified, each of the members of the
column group must have been created with the DB_NONULL option.
This option is specified in the DBTABLE structure described on page 98.
If DB_ORDERD is specified, you cannot specify DB_COLKEY or
DB_UNIQUE.
The DBCMBR Structure
The DBCMBR structure specifies information about a column member in
the column group. The DBCMBR structure has the following declaration.
typedef struct
{
UCID mbrcid;
UOPTS mbropts;
} DBCMBR;
/* column group member Column ID
/* column group member options
*/
*/
The mbrcid member contains the column ID of a column that is a member
of a column group.
The mbropts member contains the member column processing options as
they relate to the corresponding column:
DB_ASCEND
ascending key value
DB_DESCND
descending key value
DB_NORMAL DB_ASCEND is the default value used
84
The RHLI Structures
The DBCOLNM Structure: Column
Name Information
The DBCOLNM structure has the following declaration.
typedef struct
{
UCID cid;
char * colnm;
} DBCOLNM;
/* Column ID to bind name to
/* pointer to column name
*/
*/
The DBCOLNM structure is used by the uaddcnm and udrpcnm
functions to specify column names.
The cid member contains the column ID which this structure describes.
The colnm member contains the column name string, zero terminated.
The RHLI Structures
85
The DBHASH Structure: Hash Table
Index Information
The DBHASH structure has the following declaration.
typedef struct
{
char * htname;
UCID * colidl;
UHID hid;
UVID vid;
long htthrsh;
long htovfsz;
int htbchsz;
UOPTS htopts;
int ncol;
} DBHASH;
/*
/*
/*
/*
/*
/*
/*
/*
/*
name of hash table
Column ID list
Hash Table ID
volume on which to place hash tbl
split threshold value
hash table overflow bucket size
# of buckets in hash table cache
hash table options
number of columns
*/
*/
*/
*/
*/
*/
*/
*/
*/
The DBHASH structure is used by the uaddhsh and umodhsh functions
to specify information about hash table indexes.
The htname member contains a pointer to a buffer containing the name of
the hash table. The name must contain the hash table name only; it cannot
contain the corresponding schema name or table name prefixes. If a name
is not desired, set htname to (char *)0 or an empty string.
The colidl member contains a pointer to a list of hash table index column
IDs that describes the columns that comprise the hash table index. The
list contains ncol entries. There is no rank implied in a hash table index.
Columns of U_VTXT or U_VBIN data types cannot be used in a hash
table key.
The hid member contains the hash table ID. If the hash table is being
added, the system places the hash table ID in hid. Otherwise, you must
supply an existing hash table ID.
The umodhsh function can modify a hash table name only; therefore,
only the htname and hid members need to be initialized when calling the
umodhsh function.
The vid member contains the volume ID on which to place the hash table
index. If the hash table can be placed on any volume (no volume
preference exists), the vid member should contain the value UNULLVID.
86
The RHLI Structures
The htthrsh member contains a threshold for splitting hash table buckets.
If this number is set to a low value, hash key retrieval time is kept low at
the cost of disk space. If this number is set to a high value, space in the
hash table index is more fully used at the cost of hash key retrieval time.
A htthrsh value of 20L will keep a hash table index moderately full.
The htovfsz member contains the number of overflow buckets that should
be allocated at one time. A value of 1L means that overflow buckets
should be allocated as they are needed. This value incurs the cost of
having to manage overflow buckets individually. A value of 16L means
that overflow buckets are allocated 16 at a time. This value means that
the unused buckets take up space until they are needed, but it is easier for
the system to manage the buckets.
The htbchsz member is reserved for future use and should be set to 0.
The htopts member contains the hash table processing options:
DB_DUPNOK
no duplicate keys
DB_INSCATTER
data may be scattered across volumes
DB_IXUSEVOL
specifies preferred volume to use
DB_TYPE00
key folding algorithm #0
DB_TYPE01
(deprecated)
DB_TYPE02
(deprecated)
DB_TYPE03
(deprecated)
DB_TYPE04
(deprecated)
DB_TYPE05
(deprecated)
DB_TYPE06
key folding algorithm #6
DB_TYPE07
(deprecated)
DB_TYPE08
key folding algorithm #8
DB_TYPE09
key folding algorithm #9
DB_NORMAL
DB_DUPNOK is the default value used
You can select one of the DB_TYPE options only. If you omit a
DB_TYPE option, DB_TYPE08 is used.
The ncol member contains the count of the number of entries in the hash
table index column list colidl.
The RHLI Structures
87
The DBINFO Structure: Database
Information
The DBINFO structure has the following declaration.
typedef struct
{
DBVOLM * rootvol;
UOPTS dbopts;
/* Operating System
int dbmode;
int dbusrid;
int dbgrpid;
char * descrpt;
char * dbname;
} DBINFO;
/* pointer to root volume info.
/* database creation options
*/
*/
Specific Values (See: chmod, chown)
/* DB file access modes (u/g/o)
/* DB file Owner ID (or –1)
/* DB file Group ID (or –1)
/* pointer to DB description
/* pointer to database name
*/
*/
*/
*/
*/
*/
The DBINFO structure is used by the uadddb and umoddb functions to
specify information about a database.
The rootvol member contains a pointer to a DBVOLM structure that
describes the root volume information. For more information about
defining volumes, see the DBVOLM structure description on page 101
The dbopts member contains the database creation options:
DB_PUBLIC
Normal mode (do not overwrite any existing
databases, create a public database)
DB_OVERWR overwrite existing database
DB_PRIVAT
create private database
DB_NORMAL DB_PUBLIC is the default value used
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
The dbmode member contains the Unix file access modes that all
database files are created with; these modes can be changed by the user if
so desired. For more information, see the chmod(2) description in your
Unix system manual.
88
The RHLI Structures
The dbusrid member is the Unix file owner ID that all database files are
created with; the owner ID can be changed by the user if so desired. If
you specify –1, the current effective user ID is used as the owner ID.
You can also use the VOLUSER configuration variable to set the owner ID.
If you set the dbusrid member to the value of a user other than the current
effective user, you must have the necessary underlying UNIX privileges.
The dbgrpid member is the Unix file group ID that all database files are
created with; the group ID can be changed by the user if so desired. If
you specify –1, the current group ID is used for the group ID. You can
also use the VOLGROUP configuration variable to set the group ID.
The descrpt member contains a pointer to a buffer containing a
description of the database. If a description is not desired, set descrpt to
(char *)0 or an empty string.
The dbname member contains a pointer to a buffer containing the name
of the database. If a name is not desired, set dbname to (char *)0 or an
empty string.
The umoddb function cannot modify the database root volume (rootvol)
or any database creation options (dbopts); therefore, only the dbmode,
dbusrid, dbgrpid, descprt and dbname members can be initialized when
calling the umoddb function.
For more information about user and group IDs, see the chown(2) and
chgrp(2) descriptions in your Unix system manual . For more
information about configuration variables, see Unify DataServer:
Managing a Database
The RHLI Structures
89
The DBLINK Structure: Link
Information
The DBLINK structure has the following declaration.
typedef struct
{
char * lnkname;
UCID * pcolidl;
UCID * ccolidl;
UTID ptblid;
UTID ctblid;
ULID lid;
int ncol;
} DBLINK;
/*
/*
/*
/*
/*
/*
/*
name of link
parent column ID list
child column ID list
parent table ID
child table ID
Link ID
number of columns
*/
*/
*/
*/
*/
*/
*/
The DBLINK structure is used by the uaddlnk and umodlnk functions to
specify information about links.
The lnkname member contains a pointer to a buffer containing the name
of the link. The name must contain the link name only ; it cannot contain
the corresponding schema name or table name prefixes. If a name is not
desired, set lnkname to (char *)0 or an empty string.
The pcolidl member contains a pointer to a list of link index parent
column IDs which describes the columns which comprise the link index.
The list contains ncol entries. Note that there is no rank implied in a link
index.
For the parent of a particular child to be identified, the parent column or
set of columns must be unique. See the uaddtb function for information
on how to specify a uniqueness constraint on a column.
The ccolidl member contains a pointer to a list of link index child column
IDs which describes the columns which comprise the link index. The list
contains ncol entries. Note that there is no rank implied in a link index.
If the link is on more than one column, then the order of column IDs in
the lists indicates which columns are to be linked between the two tables.
Each column in the child list must have the same type as the
corresponding column in the parent list. A column or set of columns can
be the child of no more than one link.
90
The RHLI Structures
The ptblid member contains the table ID of the parent table to which the
columns described by the pcolidl list belong.
The ctblid member contains the table ID of the child table to which the
columns described by the ccolidl list belong.
The child table cannot have the same table ID as the parent table.
The lid member contains the link ID. If the link index is being added,
Unify DataServer places the link ID in lid. Otherwise, the user is required
to supply an existing link ID.
Since the umodlnk function can change a link name only, initialize the
lnkname and lid members only of the DBLINK structure when calling the
umodlnk function.
The ncol member contains the count of the number of entries in the link
index column list pcolidl and ccolidl.
The RHLI Structures
91
The DBTABLE Structure: Table
Information
The DBTABLE structure has the following declaration.
typedef struct
{
UTID tid;
DBCOL * dbcol;
USTATUS * statusl;
UVID vid;
long segsz;
long expnum;
long tblbase;
UOPTS tblopts;
int ncol;
char * tblnm;
char * tbldesc;
} DBTABLE;
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Table ID (returned)
array of column information
array of column status codes
initial preference volume
desired segment size (bytes)
expected number of rows
direct table base value
table processing options
# of entries in dbcol list
pointer to table name
pointer to table description
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
The DBTABLE structure is used by the uaddtbl function to specify
information about a table.
The tid member contains the table ID of the table. If the table is being
added, Unify DataServer places the table ID in tid. Otherwise, you must
supply an existing table ID.
The dbcol member contains a pointer to a list of DBCOL column
information structures, which provide information about the table
columns. The dbcol list contains ncol entries.
The statusl member contains a pointer to a list of status buffers, each
entry of which indicates the success or failure of the corresponding entry
in the column information list. The list contains ncol entries.
The vid member contains the volume ID on which to place the table. If
the table can be placed on any volume (no volume preference exists), set
the vid member to UNULLVID.
The segsz member contains the table’s desired segment size, in bytes. If
you want Unify DataServer to choose an optimal segment size for you,
set segsz to 0L.
92
The RHLI Structures
A segment is a contiguous disk buffer where table rows reside; typically,
a segment’s size corresponds to the table’s row size. This helps minimize
the amount of fragmentation left over in the segment.
The expnum member contains the number of rows, if any, designated
when the table was created. If the DB_FIXSIZE option is specified, the
expnum value specifies a fixed number of rows. The expnum member’s
value is advisory only and does not place any restrictions on the number
of records that can be inserted into the table.
The tblbase member contains the table’s base value, if the table is a direct
table. Otherwise, the value of tblbase is zero (0).
The tblopts member options are:
DB_ORDNRY
create ordinary table
DB_DIRECT
create directĆkeyed table
DB_FIXSIZE
reserved for future use
DB_KEYED
all directĆkey column values are userĆsupplied
DB_RDONLY
reserved for future use
DB_SCATTR
scatter data across volumes
DB_USEVOL
must use specified preference volumes
DB_NORMAL DB_ORDNRY is the default value used
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
If you specify the DB_KEYED option, you must also specify the
DB_DIRECT option.
The DB_USEVOL option indicates that the rows inserted into the table
must be stored on the volume specified by the vid member. If
DB_USEVOL is not specified, then vid is taken as the desired volume, but
other volumes defined for the database are not excluded.
The DB_SCATTR option indicates that rows inserted into the table are to
be scattered evenly over all volumes in the volume preference list (as
space permits). If DB_SCATTR is not specified, then rows are placed in
the first volume in the list until it becomes full, then the second volume
in the list, and so forth. For more information, see the uaddprf function.
The RHLI Structures
93
If no volume is specified in vid, then all volumes defined for the database
are used for scattering.
The ncol member contains the number of columns in the table column
information list dbcol and its corresponding status list statusl. If the value
of ncol is zero (0), the dbcol and statusl members are not allocated and
should not be referenced.
The tblnm member contains a pointer to a buffer containing the name of
the table. If a name is not desired, set tblnm to (char *)0 or an empty
string.
The tbldesc member contains a pointer to a buffer containing the textual
description of the table. If a description is not desired, set tbldesc to
(char *)0 or an empty string.
Performance
When the direct access column values are scattered, the system overhead
for generating the values can be substantial. If your direct access column
values are scattered and you do not want Unify DataServer to generate
the values, specify the DB_KEY option.
The DBCOL Structure
The DBCOL structure specifies column information. The DBCOL
structure has the following declaration.
typedef struct
{
UCID cid;
int coltyp;
int collen;
int colscl;
int dsplen;
int dspscl;
UOPTS colopts;
char * colnm;
char * coldesc;
char * dsppict;
} DBCOL;
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Column ID (returned)
column type
column storage precision (XXX.XXX)
column storage scale (.YYY)
column display precision
column display scale
column processing options
pointer to column name
pointer to column description
pointer to column display picture
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
The cid member contains the column ID of the created table column. If
the column is being added, the system places the column ID in cid.
Otherwise, the user is required to supply an existing column ID.
94
The RHLI Structures
The coltyp member contains the data type of the column. Valid column
types are:
U_INT for SMALLINT (16-bit )
U_HINT for INTEGER (32-bit)
U_GINT for HUGE INTEGER (64-bit)
U_FLT for FLOAT (double precision floating point)
U_DBL for DOUBLE PRECISION (double precision floating point)
U_REAL for REAL (single precision floating point)
U_AMT for AMOUNT
U_HAMT for HUGE AMOUNT
U_GAMT for CURRENCY
U_DATE for DATE
U_HDATE for HUGE DATE
U_TIME for TIME
U_STR for CHARACTER
U_BYT for BYTE
U_VTXT for TEXT
U_VBIN for BINARY
For more information about column data type declaration, see the rhli.h
header file.
The RHLI Structures
95
The collen member contains the internal storage precision, or length, of
the column. The colscl member contains the internal storage scale of the
column, if applicable. The following table shows values allowed for
collen and colscl.
For columns of
this data type:
Valid collen
values are:
Maximum
collen value
defined as:
U_INT
1-4
UIL_INT
0
U_HINT
1-9
UIL_HINT
0
U_GINT
1-19
UIL_GINT
0
U_REAL
32
UIL_REAL
0
U_FLT
64
UIL_FLT
0
U_DBL
64
UIL_DBL
0
U_AMT
3-9
UIL_AMT
2
U_HAMT
3-15
UIL_HAMT
2
U_GAMT
1-19
UIL_GAMT
0–8
U_DATE
0
UIL_DATE
0
U_HDATE
0
UIL_HDATE
0
U_TIME
0
UIL_TIME
0
U_STR
1-256
UIL_STR
0
U_BYT
1-1024
UIL_BYT
0
U_VTXT
0
UIL_VTXT
0
U_VBIN
0
UIL_VBIN
0
Valid colscl
values are:
Except for U_GAMT, a colscl value of 0 indicates that scale is not
applicable to the data type and must be set to 0.
96
The RHLI Structures
The dsplen member contains the external display precision, or length, of
the column. Valid values are shown in the table. You can also set dsplen
to zero (0) which causes the default display precision for that data type
to be used.
For columns of
data type:
Valid dsplen
values are:
Default dsplen
value defined
as:
U_INT
2-5
UDL_INT
0
U_HINT
2-10
UDL_HINT
0
U_GINT
2-20
UDL_GINT
0
U_REAL
1-11
UDL_REAL
0-9
U_FLT
1-17
UDL_FLT
0-15
U_DBL
1–17
UDL_DBL
0-15
U_AMT
4-16
UDL_AMT
2
U_HAMT
4-25
UDL_HAMT
2
U_GAMT
2-22
UDL_GAMT
0-8
U_DATE
8-11
UDL_DATE
0
U_HDATE
8–11
UDL_HDATE
0
U_TIME
5
UDL_TIME
0
U_STR
1–256
UDL_STR
0
U_VTXT
1–256
UDL_VTXT
0
U_VBIN
0
UDL_VBIN
0
U_BYT
1–1024
UDL_BYT
0
Valid dspscl
values are:
Except for U_GAMT, U_REAL, U_FLT, and U_DBL, a colscl value of 0
indicates that scale is not applicable for the data type and must be set
to 0.
The colnm member contains a pointer to a buffer containing the name of
the column. The name must contain only the column name component; it
cannot contain the corresponding schema name or table name prefixes. If
a name is not desired, set colnm to (char *)0 or an empty string.
The RHLI Structures
97
The coldesc member contains a pointer to a buffer containing the textual
description of the column. If a description is not desired, set coldesc to
(char *)0 or an empty string.
The dsppict member contains a pointer to a buffer containing an RPT-like
display picture clause. If a display picture clause is not desired, set
dsppict to (char *)0 or an empty string.
The colopts member contains the various column processing options:
DB_ORDNRY
Indicates that the other processing options are
not specified (all options are at their default
value of FALSE).
DB_COLKEY
Indicates that the column is a primary key for
the table.
DB_DELETE
Reserved for future use.
DB_IMMED
Reserved for future use.
DB_NOLOG
Reserved for future use.
DB_NONULL
Indicates that the column can only contain
nonĆnull values.
DB_RDONLY
Reserved for future use.
DB_UNIQUE
Indicates that the column can only contain
unique values.
DB_NORMAL DB_ORDNRY is the default value used
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
If the DB_UNIQUE option is specified, you must also specify the
DB_NONULL option.
If the DB_COLKEY option is specified, you must also specify the
DB_UNIQUE option.
98
The RHLI Structures
The DBTBLNM Structure: Table Name
Information
The DBTBLNM structure has the following declaration.
typedef struct
{
UTID tid;
/* Table ID to bind name to
char * tblnm; /* pointer to table name
} DBTBLNM;
*/
*/
The DBTBLNM structure is used by the uaddtnm and udrptnm
functions to specify a table name for a table.
The tid member contains the table ID which this structure describes.
The tblnm member contains the table name string, zero terminated.
The RHLI Structures
99
The DBUSER Structure: User and
Default Schema Information
The DBUSER structure has the following declaration.
typedef struct
{
UOID uoid;
UAID aid;
char * usernm;
} DBUSER;
/* User/Owner ID (returned)
/* default Authorization ID (or NULL)
/* pointer to user name
*/
*/
*/
The DBUSER structure is used by the uaddusr and umodusr functions to
specify information about a user and a user’s default schema.
The uoid member contains the user ID. If the user is being added, Unify
DataServer places the user ID in uoid. Otherwise, you must supply an
existing user ID.
The aid member contains the authorization ID that corresponds to the
user’s default schema. If aid is set to UNULLAID, the authorization ID
for the PUBLIC schema is used.
The usernm member contains a pointer to a buffer containing the name of
the user. You must specify a user name.
The user name should match the user’s name as it is known to the Unix
operating system.
100
The RHLI Structures
The DBVOLM Structure: Volume
Information
The DBVOLM structure has the following declaration.
typedef struct
{
UVID vid;
long voloff;
long vollen;
long volpgsz;
UOPTS volopts;
char * volfile;
char * volname;
} DBVOLM;
/* Volume ID (returned/specified)
/* volume offset (bytes)
/* volume length
/* volume page size (bytes)
/* volume processing options
/* pointer to volume file name
/* pointer to volume name
*/
*/
*/
*/
*/
*/
*/
The DBVOLM structure is used by the uaddvol and umodvol functions
to specify information about a volume.
DBVOLM is also a member of the structure DBINFO.
The vid member is used for the volume ID for the volume that this
structure describes. If the volume is being added and the DB_SPECIFY
option is not specified as a volume processing option, the system places a
volume ID in vid. If the volume is being added and the DB_SPECIFY
option is specified, you specify the volume ID for the volume in the vid
member. The volume ID you specify cannot be an existing volume ID. If
the volume is being modified, specify an existing volume ID in the vid
member.
The voloff member is the offset within the physical media in which the
volume resides where data storage for the volume begins. The voloff
value is typically used when a single physical device is used for two or
more volumes; the offset of the second volume would be the address
immediately following the first volume, and so on.
The volume offset is the number of bytes from the beginning of the disk
partition; this value is converted internally into the corresponding number
of blocks. The offset for the root volume must always be zero (0),
although a volume offset of zero does not necessarily identify the root
volume.
The RHLI Structures
101
The vollen member indicates the length of the volume. If DB_BIG is set
in the volopts member, vollen represents the number of pages. Otherwise,
it represents the number of bytes; this value is converted internally into
the corresponding number of blocks. The volume length is used by
volume storage routines to determine how much data can fit onto the disk
partition.
If the volume type is a device or preallocated file, you must specify a
non-zero length. If the volume type is a regular file, you can specify a
non-zero or zero length. A length of zero indicates that the size is
unlimited, A non-zero length indicates a maximum size limit for the
regular file; the file grows until it reaches the size.
The volpgsz member specifies the operating system dependent page size
for the device on which the volume resides. The volpgsz size is expressed
in bytes; that is, the value 2048 represents a page whose size is 2048
bytes long. Note that this value is converted to the internal page size,
which is an integral number of blocks.
The volpgsz value must match the value preset for the Unify DataServer
release. If zero is specified, the value specified by the VOLPGSZ
configuration variable is used.
The volopts member contains various volume processing options.
Options are:
DB_ORDNRY
Indicates that the processing options are
normal. That is, the volume is not a device or
preĆallocated. This is the default setting.
DB_ALLOC
Indicates that the volume is a preallocated file.
DB_CONTIG
Reserved for future use.
DB_DEVICE
Indicates that the volume is a device (character
or blockĆspecial file).
If the volume options include DB_DEVICE, the
device special file must exist before adding a
volume on the device.
DB_FORCE
102
Indicates that if the volume is a regular file, the
UNIX operating system allocates an entire new
segment when the existing segment capacity is
exceeded. If this option is not specified, the
regular files grow in smaller allocations each
time data is added to the file.
The RHLI Structures
DB_RDONLY
Reserved for future use.
DB_SPECIFY
Indicates that the volume ID is specified (rather
than returned) in the vid member. If the
volume ID you specify is not currently being
used, the volume ID is assigned to the volume
being created.
DB_BIG
Indicates that the vollen specification is in pages
rather than bytes.
DB_NORMAL DB_ORDNRY is the default value used
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
The volfile member is the full path name of the file or character device
for the volume, including the file name. If the file name does not end
with the .db suffix, Unify DataServer appends the suffix to the name.
If the volume is a root volume, it must reside in the directory specified by
the DBPATH and DBNAME configuration variables. The path and file
name can be omitted or equal to null (char *)0 ; in this case the value of
the DBPATH and DBNAME configuration variables are used.
If the volume is not a root volume, you must specify the file name. The
path can be omitted; the default path is determined by the DBPATH
configuration variable.
The volname member contains a pointer to a buffer containing the name
of the volume. If a volume name is not desired, set volname to (char *)0
or a null string (””).
If you create a database with a device as the root volume, the device must
exist in the directory specified by the DBPATH configuration variable. The
device must have the name indicated by the DBNAME configuration
variable and the .db file name suffix. This is accomplished by using the
mknod utility the directory specified by DBPATH or symlinking the
device into DBPATH.
To re-use an existing volume that is a device, use the mkvol utility to
create the volume. The mkvol utility marks the volume as deleted.
The volume size information is maintained in terms of bytes. This is
because the user may not know the current database’s block size, and an
incorrect calculation on the user’s part cause damage to the database.
The RHLI Structures
103
Since the umodvol function can change a volume name, initialize only
the volname and vid members only of the DBVOLM structure when
calling the umodvol function.
Additional Help
About
104
See
Symlinking
Your operating system
documentation
Configuration variables
Unify DataServer:
Configuration Variable and
Utility Reference
The RHLI Structures
The UACSINF Structure: Access
Method Information
The UACSINF structure has the following declaration.
typedef struct
{
int scanid;
int acsknd;
UACS acsid;
} UACSINF;
/* scan identifier
/* access type (UBTSCN, etc)
/* access method info structure
*/
*/
*/
The UACSINF structure is used by the uinfacs function to retrieve access
method information about an access.
The scanid member contains the identifier of the access that the structure
describes.
The acsknd member contains a value that identifies the type of access
method being used by the access. Options are:
The btacs Structure
USQSCN
sequential access type
UDKSCN
direct key access type
UBTSCN
BĆtree index access type
UHKSCN
hash index access type
ULKSCN
link index access type
UNULLSCN
no access type, not initialized
The btacs structure of type UBTACS contain information if the acsknd
member is set to UBTSCN. The btacs structure has the following
declaration.
typedef struct
{
UBTID btid;
int nbtcol;
} UBTACS;
/* B-tree Index ID
/* # of btree key columns used
*/
*/
The btid member contains the B-tree ID of the B-tree index used by the
access.
The nbtcol member contains the number of components of the B-tree key
used by the access.
The RHLI Structures
105
The acid Union
The acsid member is a union of type UACS that contains additional
information for certain access types. The acsid union has the following
declaration.
typedef union
{
UBTACS btacs;
UHID hid;
ULID lid;
} UACS;
/* UBTSCN: btree access info
/* UHKSCN: Hash Index ID
/* ULKSCN: Link Index ID
*/
*/
*/
The hid member contains the Hash Table ID of the hash index used by
the access. It will be filled in if the value of acsknd is equal to UHKSCN.
The lid member contains the Link ID of the link index used by the access
if the acsknd member is set to ULKSCN.
106
The RHLI Structures
The UATHINF Structure: Schema
Information
The UATHINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UAID aid;
/* Authorization ID
/* information retrieval class: I (UCLASS1) */
UXID xid;
/* reserved for future use
char authnm[U_ATHNMLN + 1]; /* pointer to the
/* schema name
} UATHINF;
*/
*/
*/
*/
The UATHINF structure is used by the uinfath function to retrieve
information about a schema. A schema is also called an authorization.
The aid member contains the authorization ID of the schema.
The xid member is reserved for future use.
The authnm member contains the name of the schema as it would be
referenced for name-binding.
The RHLI Structures
107
The UATHMAP Structure:
Authorization ID Mapping
The UATHMAP structure has the following declaration.
typedef struct
{
char * athnm;
UAID aid;
UAID remapid;
} UATHMAP;
/* pointer to runtime schema name
/* compile-time Authorization ID
/* runtime Auth. ID (returned)
*/
*/
*/
The UATHMAP structure is used by the umapath function to specify
information about runtime ID-mapping on a compile-time schema.
Tip
Use the INIATHMAP mapping macro to initialize the UATHMAP
structure.
The athnm member contains the runtime name of the schema.
To reset the value of a previously mapped authorization ID, set the value
of athnm to (char *)0 or the null-string (“”).
The aid member contains an authorization ID that uniquely identifies the
schema. The authorization ID can be supplied by you or can be generated
by the ucc compiler.
If you supply the authorization ID (aid), be sure that the number you pick
is compatible with the data type UAID.
To generate a unique compile-time authorization ID by using ucc,
initialize aid with the following compiler directive (athnm is the name of
the schema):
$(UATH:AID)athnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID is
mapped. This value is for internal use only.
108
The RHLI Structures
The UBTINF Structure: B-tree
Information
The UBTINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UBTID btid;
/* B-tree this struct describes
UBTID remapid;
/* logical B-tree ID (if remapped)
*/
*/
/* information retrieval class: I (UCLASS1) */
UOPTS btopts; /* DB_DUPSOK || DB_DUPNOK
UTID tid;
/* Table ID this B-tree indexes
*/
*/
/* information retrieval class: II (UCLASS2) */
int count;
/* length of B-tree column list
UBTCINF *btcinf; /* pointer to UBTCINF structure list
*/
*/
/* information retrieval class: III (UCLASS3) */
char btnm[U_NAMELEN + 1]; /* name of B-tree index
} UBTINF;
*/
The UBTINF structure is used by the uinfbt function to retrieve B-tree
information.
The btid member contains the B-tree index ID that the structure
describes. If the ID represents a remapped btree index, the ID is the
compile-time B-tree index ID (the ID with which the user remapped the
B-tree index).
The remapid member contains the logical B-tree index ID that the
structure describes. If the ID represents a remapped B-tree index, the ID
is the runtime B-tree index ID (the actual Database ID). Otherwise,
remapid is identical to the btid member.
The btopts member contains the B-tree creation options:
DB_DUPNOK no duplicate keys
DB_DUPSOK
allow duplicate keys
DB_NORMAL DB_DUPNOK is the default value used
The tid member contains the table ID to which all of the columns
comprising the B-tree index belong.
The RHLI Structures
109
The count member contains the count of the number of entries in the
B-tree index column information list btcinf.
The btcinf member contains a pointer to a list of UBTCINF B-tree index
column information structures which describes the columns comprising
the B-tree index. The list contains ncol entries.
See the description of the UBTCINF structure below.
The btname member contains the name of the B-tree, if any. If the B-tree
index does not have a name, the member contains an empty string.
The UBTCINF Structure
The UBTCINF structure contains B-tree column information. The
UBTCINF structure has the following declaration.
typedef struct
{
int rank;
UCID cid;
UOPTS btcopts;
} UBTCINF;
/* 0 top rank – lowest rank
/* Column IDs (cid’s)
/* DB_ASCEND || DB_DESCND
*/
*/
*/
The maximum number of columns in the B-tree is 128.
The rank member contains the rank, or position, of the corresponding
column in the B-tree index. The rank value starts at zero, indicating the
most significant column in the B-tree.
The cid member contains the column ID of a column member of the
B-tree index. All column IDs in a single B-tree index belong to the same
table.
The btcopts member contains the B-tree column processing options as
they relate to the corresponding column:
DB_ASCEND
ascending key value
DB_DESCND
descending key value
DB_NORMAL DB_ASCEND is the default value used
110
The RHLI Structures
The UBTMAP Structure: B-tree ID
Mapping
The UBTMAP structure has the following declaration.
typedef struct
{
char * btnm;
UBTID bid;
UBTID remapid;
} UBTMAP;
/* pointer to runtime B-tree name
/* compile-time B-tree ID
/* runtime B-tree ID (returned)
*/
*/
*/
The UBTMAP structure is used by the umapbt function to specify
runtime ID-mapping on a compile-time B-tree object.
Tip
Use the INIBTMAP mapping macro to initialize the UBTMAP structure.
The btnm member contains the runtime name of the B-tree. The
remapping operation fails if the B-tree specified in the btnm member
does not exist in the database.
The bid member contains a B-tree ID that uniquely identifies the B-tree.
The ID can be supplied by you or can be generated by the ucc compiler.
If you supply the ID (bid), be sure that the number you pick is compatible
with the type UBTID.
To generate a unique compile-time B-tree ID using ucc, initialize bid with
the following compiler directive (btnm is the name of the B-tree):
$(UBT:BID)btnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
The RHLI Structures
111
The UCGPINF Structure: Column
Group Information
The UCGPINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UCID cid;
/* its Column ID
int coltyp;
/* data type of column
int ncol;
/* # Column IDs in grpcidl
UCID * grpcidl;
/* list of Column IDs in the group
/* OR the groups the column is a
/* member of
} UCGPINF;
*/
*/
*/
*/
*/
*/
The UCGPINF structure is used by the uinfcgp function to retrieve
information about a column group and its component columns, or for a
column and all of the column groups of which it is a component.
The cid member contains the column ID this structure describes. The
column ID can describe either a column or column group.
The coltyp member contains the column’s Unify DataServer database
type, just as it does for the DBTABLE structure.
The ncol member contains the number of column IDs in the column
group ID list grpcidl. If the value of ncol is zero (0), the grpcidl member
is not allocated and should not be referenced.
The grpcidl member contains the list of column IDs to which the
component column belongs, or the list of column IDs which belong to the
column group.
For column groups successfully retrieved, storage space is allocated by
Unify DataServer for grpcidl. This space should be released after the
retrieval operation is complete by calling the free function.
112
The RHLI Structures
The UCOLINF Structure: Column
Information
The UCOLINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UTID tid;
/* table to which column belongs
UAID aid;
/* authorization/schema of the table
UCID cid;
/* the column’s Column ID
UCID remapid;
/* logical Column ID (if remapped)
*/
*/
*/
*/
/* information retrieval class: I (UCLASS1) */
UDEFID defid;
/* column Definition ID
UDEFID chgid;
/* column Modification ID
UMAPID mapid;
/* column summation ID
int coltyp;
/* Unify DataServer data type
int collen;
/* column storage precision
int colscl;
/* column storage scale
UOPTS colopts;
/* column processing options
*/
*/
*/
*/
*/
*/
*/
/* information retrieval class: II (UCLASS2) */
int dsplen;
* column display precision
int dspscl;
/* column display scale
*/
*/
/* information retrieval class: III (UCLASS3) */
int nbt;
/* # of B-trees the column
/* participates in
int nhsh;
/* # of hash-tables the column
/* belongs to
int nplnk;
/* # of links the column
/* is parent of
int nclnk;
/* # of links the column
/* is child of (0/1)
*/
*/
*/
*/
*/
*/
*/
*/
/* information retrieval class: IV (UCLASS4) */
char * dsppict;
/* pointer to column display picture
/* (or NIL)
char * coldesc;
/* pointer to column description
/* (or NIL)
} UCOLINF;
*/
*/
*/
*/
The UCOLINF structure is used by the uinfcol function to retrieve
information about a column and its attributes.
The cid member contains the column ID that the structure describes. If
the ID represents a remapped column, the ID is the compile-time column
ID (the ID with which the user remapped the column).
The RHLI Structures
113
The remapid member contains the logical column ID that the structure
describes. If the ID represents a remapped column, the ID is the runtime
column ID (the actual Database ID). Otherwise, remapid is identical to
the cid member.
The tid member contains the table ID to which the column belongs.
The aid member contains the authorization ID(schema) to which the
column’s table belongs, and to which the column indirectly belongs.
The defid member contains the column’s current Definition ID. The
Definition ID changes whenever a physical modification is made to the
column, such as modifying the column’s type or length.
The chgid member contains the column’s current Change ID. The Change
ID changes whenever a logical modification is made to the column, such
as modifying the column’s name.
The mapid member contains the column’s current Mapping ID. The
Mapping ID serves as a checksum of the column’s physical attributes,
such as the column’s type and length.
The coltyp member contains the column’s database type. Options are
listed with the coltyp member of the DBCOL description of the DBTABLE
structure on page 92.
The collen and colscl members contain the column’s internal storage
precision and scale, as follows:
U_INT, U_HINT, U_GINT
collen is the number of digits as specified (or
implied) when the column was created; colscl
is 0.
U_DATE, U_TIME, U_HDATE, U_VTXT, U_VBIN
collen and colscl are both 0.
U_REAL, U_FLT, U_DBL
collen is the number of bits of floating point
representation for the internal, or stored, value:
32 for U_REAL and 64 for U_FLT and U_DBL;
colscl is 0.
U_BYT, U_STR
114
collen is the number of bytes or characters
specified (or implied) when the column was
created; colscl is 0.
The RHLI Structures
U_AMT, U_HAMT
collen is the number of digits of precision
(possible digits to the left of the radix point plus
possible digits to the right of the radix point) as
specified. It will be >= to 3. colscl is 2.
U_GAMT
collen is the number of digits of precision
(possible digits to the left of the radix point plus
possible digits to the right of the radix point) as
specified. It will be > colscl.
colscl is the defined scale (0-8); It will be <
collen.
The dsplen member contains the external display precision or length of
the column. Display length can be specified as any length (zero or
greater). A zero (0) display length indicates no display length.
The colopts member contains the column’s processing options. See page
98.
The dspscl member contains the column’s display scale, if applicable, in
characters.
Valid values allowed for dsplen and dspscl are defined in the rhli.h
header file.
The nbt member contains the number of B-trees the column participates
in.
The nhsh member contains the number of hash tables the column
participates in.
The nplnk member contains the number of links the column is a parent
of.
The nclnk member contains the number of links the column is a child of.
Note that nclnk can only contain the values zero (0) or one (1).
The dsppict member contains the column’s display picture clause, if any.
The coldesc member contains the column’s description, if any.
For columns successfully retrieved by specifying the UCLASS4 or
UALLINFO retrieval classes, storage space is allocated by Unify
DataServer for coldesc and dsppict members. This space should be
released after the retrieval operation is complete by calling the free
function.
The RHLI Structures
115
The UCOLMAP Structure: Column ID
Mapping
The UCOLMAP structure has the following declaration.
typedef struct
{
char * colnm;
UCID cid;
UCID remapid;
UDEFID defid;
UMAPID mapid;
} UCOLMAP;
/*
/*
/*
/*
/*
pointer to runtime column name
compile-time Column ID
runtime Column ID (returned)
compile-time column definition
compile-time column summation
*/
*/
*/
*/
*/
The UCOLMAP structure is used by the umapcol function to specify
information about runtime ID-mapping on a compile-time column object.
Tip
It is highly recommended that you use the INICOLMAP mapping macro
to initialize the UCOLMAP structure.
The colnm member contains the runtime name of the column.
The cid member contains the compile-time column ID. The ID can be
supplied by you or can be generated by the ucc compiler.
If you supply the ID (cid), be sure that the number you pick is compatible
with the type UCID.
To generate a unique compile-time ID using ucc, initialize cid with the
following compiler directive (colnm is the name of the column):
$(UCOL:CID)colnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
The defid member contains the table’s compile-time Definition ID, which
is a time-stamped ID that is used by Unify DataServer to verify the
accuracy of remapid.
116
The RHLI Structures
The Definition ID (defid) must be initialized with the following compiler
directive syntax (colnm is the name of the column):
$(UCOL:DEFID)colnm$
The mapid member contains the table’s compile-time Mapping ID, which
is a checksum value that is used by Unify DataServer to verify the
accuracy of remapid. This value is for internal use only.
The Mapping ID (mapid) must be initialized with the following compiler
directive syntax (colnm is the name of the column):
$(UCOL:MAPID)colnm$
The RHLI Structures
117
The UDBINF Structure: Database
Information
The UDBINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UDBID dbid;
/* database ID
int isremote;
/* Is database remote? flag
*/
*/
/* information retrieval class: I (UCLASS1) */
UDEFID defid;
/* database definition ID
*/
/* Operating System Specific Values (See: chmod, chown)
*/
int dbmode;
/* database file access modes (u/g/o)*/
int dbusrid;
/* database file Owner ID
*/
int dbgrpid;
/* database file Group ID
*/
/* information retrieval class: II (UCLASS2) */
long nvol;
/* # of volumes in the database
UVID * uvidlst;
/* pointer to volume information
*/
*/
/* information retrieval class: III (UCLASS3) */
char * descrpt;
/* pointer to database description (or NIL )*/
char ownernm[U_USRNMLN + 1];
/* buffer for the database creator name
*/
char dbname[U_NAMELEN + 1];
/* buffer for the database name
*/
} UDBINF;
The UDBINF structure is used by the uinfdb function to retrieve
information about a database.
The dbid member contains the database ID which is described by the
information in this structure.
The isremote member specifies if the database to be accessed is a remote
database. If the database is remote, isremote will be set to 1; if the
database is local, isremote will be set to 0.
The defid member contains the current Definition ID for the database.
The dbmode member contains the database Unix access modes, as
described in section 2 of your Unix system manual. All database files are
created with these file access permissions.
118
The RHLI Structures
The dbusrid member contains the database Unix owner ID, as described
in section 2 of your Unix system manual. All database files are created
with these file user ownership.
The dbgrpid member contains the database Unix group ID, as described
in section 2 of your Unix system manual. All database files are created
with these file group ownership.
The nvol member contains the number of volumes in the database. A
database always includes at least 1 volume: the root volume.
The uvidlst member contains a list of volume IDs which belong to the
database.
The descrpt member contains the database description.
The ownernm member contains the name of the user who created the
database.
The dbname member is the name of the database as it would be
referenced for name-binding.
The RHLI Structures
119
The UGRTDS Structure: Grant
Privilege Descriptor
The UGRTDS structure has the following declaration.
typedef struct
{
union
{
UAID aid;
UOID uid;
} gte;
UCAPS rqstcaps;
UOBJDS obj;
UCAPS gtecaps;
} UGRTDS;
/*
/*
/*
/*
Grantee
Capabilites to be granted
Object to grant on
Capabilities actually granted
*/
*/
*/
*/
The UGRTDS structure is used by the uaddprv function to specify
information about the privileges to grant.
The aid member contains the authorization ID of a schema to which
schema privileges are to be granted.
The uid member contains the user ID to which permissions are to be
granted.
The gte member contains the ID of the object to which the user authority
is granted. The object to which the privileges are to be granted is known
as the grantee.
Because gte is a union, either a schema or a user can be granted a
privilege, but not both.
The rqstcaps member contains the set of permissions that are to be
granted. The set of permissions determines whether the type of the
grantee is a schema or a user.
When you grant permissions, you can grant only those permissions that
you have permission to grant.
To grant authority, initialize the rqstcaps member as follows:
120
UDBA
for DBA authority
USCH
for SCHEMA authority
UDALL
for both DBA and SCHEMA authority
The RHLI Structures
To grant schema privileges, initialize the rqstcaps member as follows:
USSEL
for SELECT operations
USINS
for INSERT operations
USUPD
for UPDATE operations
USDEL
for DELETE operations
USALL
for all grantable operations (SELECT, INSERT,
UPDATE and DELETE)
UGRTCAP
to specify that the operation (one of the above)
is grantable
If a schema grants schema privileges to another schema, all tables in the
schema granting the privilege are accessible. However, if a schema grants
table privileges to another schema, only the specified tables are
accessible.
To grant table privileges to a schema, initialize the rqstcaps member as
follows:
UTSEL
for SELECT operations
UTINS
for INSERT operations
UTUPD
for UPDATE operations
UTDEL
for DELETE operations
UTALL
for all grantable operations (SELECT, INSERT,
UPDATE and DELETE)
UGRTCAP
to specify that the operation (one of the above)
is grantable
To grant column privileges to a schema, initialize the rqstcaps member as
follows:
The RHLI Structures
UCSEL
for SELECT operations
UCINS
for INSERT operations
UCUPD
for UPDATE operations
UCALL
for all grantable operations (SELECT, INSERT
and UPDATE)
UGRTCAP
to specify that the operation (one of the above)
is grantable
121
You can specify more than one option by separating the options with the
bitwise logical OR operator (|).
The obj member is a structure (UOBJDS) that contains a description of
the object which the privilege affects. See below for a description of the
UOBJDS structure.
The gtecaps member contains the set of privileges actually granted to the
grantee.
That is, if you granted SELECT schema privilege to a table, the value
contained in gtecaps would be equivalent to UTSEL; or, if you granted
SCHEMA authority to a user, if granted successfully, gtecaps would
contain a value equivalent to USCH.
Since the grantor may not have the privilege to grant certain privileges,
only those privileges actually grantable are granted.
For more information about the functionality of each of the operation
privileges, see “Controlling Database Object Access” in Unify
DataServer: Writing Interactive SQL/A Queries.
The UOBJDS Structure
The UOBJDS structure contains information about a database object and
is defined as:
typedef struct
{
UDBOBJ objid;
int objknd;
} UOBJDS;
/* object ID
/* the type of object
*/
*/
The objid member contains a database object ID whose type is described
by the objknd member. Options are:
UAID
Authorization ID
UDBID
Database ID
UCID
Column ID
UTID
Table ID
The objknd member contains a value that indicates what type of ID is
contained in the objid member. Options are:
122
UDBKND
database object
USCHKND
schema object
UTBLKND
table object
The RHLI Structures
UVWKND
view object
UCOLKND
column object
If you are granting a user privilege (DBA or SCHEMA authority), objid
and objknd must be set to the current Database ID (see the uopndb
function) and UDBKND, respectively.
The RHLI Structures
123
The UHSHMAP Structure: Hash Table
ID Mapping
The UHSHMAP structure has the following declaration.
typedef struct
{
char * hshnm;
UHID hid;
UHID remapid;
} UHSHMAP;
/*
/*
/*
/*
pointer to runtime hash
table name
compile-time Hash Table ID
runtime Hash Table ID (returned)
*/
*/
*/
*/
The UHSHMAP structure is used by the umaphsh function to specify
information about runtime ID-mapping on a compile-time hash table
object.
It is highly recommended that you use the INIHSHMAP mapping macro
to initialize the UHSHMAP structure.
The hshnm member contains the runtime name of the hash table.
The hid member contains the compile-time hash table ID.
The hash table ID (hid) can be hardcoded by the programmer (with a
unique custom ID) or be supplied by the Unify DataServer C compiler,
ucc.
If you choose to hardcoded a unique hash table ID (hid), be sure that the
number you pick is compatible with the type UHID.
To generate a unique compile-time hash table ID using ucc, initialize hid
with the following compiler directive (hshnm is the name of the hash
table):
$(UHSH:HID)hshnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
124
The RHLI Structures
The UHTINF Structure: Hash Table
Information
The UHTINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UHID hid;
/* hash table this struct describes
UHID remapid;
/* logical hashtb ID (if remapped)
*/
*/
/* information retrieval class: I (UCLASS1) */
long hthibkt;
/* highest primary bucket
long htsplvl;
/* split level
long hthshvl;
/* primary hash value
long htthrsh;
/* split threshold value
long htovfsz;
/* hash table overflow bucket size
int htbchsz;
/* # of buckets in hash table cache
UOPTS htopts;
/* DB_DUPSOK || DB_DUPNOK
*/
*/
*/
*/
*/
*/
*/
/* information retrieval class: II (UCLASS2) */
long count;
/* length of hash column list
UCID * htloc;
/* pointer to Column ID list
*/
*/
/* information retrieval class: III (UCLASS3) */
char htnm[U_NAMELEN + 1]; /* name of hash table
} UHTINF;
*/
The UHTINF structure is used by the uinfhsh function to retrieve
information about a hash table.
The hid member contains the hash table ID that the structure describes. If
the ID represents a remapped hash table, the ID is the compile-time hash
table ID (the ID with which the user remapped the hash table).
The remapid member contains the logical hash table ID that the structure
describes. If the ID represents a remapped hash table, the ID is the
runtime hash table ID (the actual Database ID). Otherwise, remapid is
identical to the hid member.
The hthibkt member contains the current number of primary buckets in
the hash table; this values increases as rows are added and decreases as
rows are deleted. The value of hthibkt ranges from the value of hthshvl to
twice that value.
The RHLI Structures
125
The htsplvl member contains the number of times the hash table has
doubled in size; the value one (1) means that the hash table is at its
original size.
The hthshvl member contains the base size of the hash table, which is
used to compute the primary bucket address for a given key value. When
the value of hthibkt reaches twice the value of hthshvl, the value of
htsplvl is incremented and the value of hthshvl is doubled.
The htovfsz member contains the size, in blocks, of a segment that
contains overflow buckets. This size corresponds to the number of
overflow buckets that are allocated as a group.
The htthrsh member contains the measurement used to determine when a
primary bucket needs to be split. The value indicates the number of
internal overflow chains of key values that should have been able to fit
into a primary bucket.
The htbchsz member contains the number of buckets that can be cached
in user memory during an atomic hash table operation.
The htopts member contains the hash table processing options. Options
are:
DB_DUPNOK disallow duplicate keys
DB_DUPSOK
allow duplicate keys
DB_NORMAL DB_DUPNOK is the default value used
The count member contains the number of column IDs in the hash table
Member ID list htloc. If the value of count is zero (0), the htloc member
is not allocated and should not be referenced.
The htloc member contains the list of column IDs that comprise the hash
table index.
The htnm member contains the name of the hash table, if any. If the hash
table does not have a name, htnm contains an empty string.
126
The RHLI Structures
The UJRNINF Structure: Journal
Information
The UJRNINF structure has the following declaration.
typedef struct {
UJRNID ids;
UTXID txid;
long txdate;
UTID tid;
URID rid;
short opknd;
union{
IDML insert;
UDML update;
DDML delete;
} txinfo;
} UJRNINF;
/*
/*
/*
/*
/*
/*
/*
Custom log information.
User ID information.
Transaction ID.
Timestamp of transaction.
ID of affected table.
ID of affected row.
Context for the union:
/* Insert DML information.
/* Update DML information.
/* Delete DML information.
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
The UJRNINF structure is used by the ufchjrn function to retrieve
information on the next update operation contained in the transaction
journal.
The UJRNID Structure
The ids member of type UJRNID is a structure identifying the operating
system user ID, database user ID, and schema ID of the user that
performed the update operation. The UJRNID structure has the following
declaration.
typedef struct {
int
uid;
UOID
uoid;
UAID
uaid;
} UJRNID
/*
/*
/*
/*
User ID information.
Unix User ID.
Database User ID.
Database authorization ID.
*/
*/
*/
*/
The txid member is the transaction ID of the transaction that performed
the update operation.
The txdate member is the timestamp at which the transaction performing
the update operation was committed. The txdate member is in the same
format as a value returned by the operating system time function.
The tid member is the table ID of the table updated.
The RHLI Structures
127
The rid member is the row ID of the row updated.
The opknd member identifies the type of operation and thereby
determines the context for the txinfo union. Types of operations consist
of insert, update, and delete. These are identified by the constants
UINSOPR, UUPDOPR, and UDELOPR respectively and are defined as
follows:
#define UINSOPR 1
#define UUPDOPR 2
#define UDELOPR 3
The IDML Structure
/* Insert DML information.
/* New row’s UNIPCOL list.
*/
*/
The update member of type UDML is a structure which contains pointers
to UNIPCOL structures for the before and after images of the row
updated. The UDML structure has the following declaration.
typedef struct {
UNIPCOLL *newucol;
UNIPCOLL *olducol;
} UDML;
The DDML Structure
*/
*/
*/
The insert member of type IDML is a structure which contains a pointer
to a UNIPCOL structure for the after image of the row inserted. The
IDML structure has the following declaration.
typedef struct {
UNIPCOLL *newucol;
} IDML;
The UDML Structure
/* txknd is an insert operation
/* txknd is an update operation
/* txknd is a delete operation
/* Update DML information.
/* New row’s UNIPCOL list.
/* Old row’s UNIPCOL list.
*/
*/
*/
The delete member of type DDML is a structure which contains a pointer
to a UNIPCOL structure for the before image of the row deleted. The
DDML structure has the following declaration.
typedef struct {
UNIPCOLL *olducol;
} DDML;
/* Delete DML information.
/* Old row’s UNIPCOL list.
*/
*/
For a description of the UNIPCOL structure, see page 131.
128
The RHLI Structures
The ULNKINF Structure: Link
Information
The ULNKINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
ULID lid;
/* Link ID
ULID remapid;
/* logical Link ID (if remapped)
*/
*/
/* information retrieval class: I (UCLASS1) */
long count;
/* # of Column IDs in lists
UCID * ploc;
/* pointer to the parent list of
/* Column IDs
UCID * cloc;
/* pointer to the child list of
/* Column IDs
*/
*/
*/
*/
*/
/* information retrieval class: II (UCLASS2) */
char lnknm[U_NAMELEN + 1]; /* name of link
} ULNKINF;
*/
The ULNKINF structure is used by the uinflnk function to retrieve
information about a link.
The lid member contains the link ID that the structure describes. If the ID
represents a remapped link, the ID is the compile-time Link ID (the ID
with which the user remapped the link).
The remapid member contains the logical link ID that the structure
describes. If the ID represents a remapped link, the ID is the runtime link
ID (the actual Database ID). Otherwise, remapid is identical to the lid
member.
The count member contains the number of column IDs in the link
member ID list ploc and cloc. If the value of count is zero (0), the ploc
and cloc members are not allocated and should not be referenced.
The ploc member contains the list of parent column IDs.
The cloc member contains the list of child column IDs.
The lnknm member contains the name of the link, if any. If the link does
not have a name, the member contains an empty string.
The RHLI Structures
129
The ULNKMAP Structure: Link ID
Mapping
The ULNKMAP structure has the following declaration.
typedef struct
{
char * lnknm;
ULID lid;
ULID remapid;
} ULNKMAP;
/* pointer to the runtime link name
/* compile-time Link ID
/* runtime Link ID (returned)
*/
*/
*/
The ULNKMAP structure is used by the umaplnk function to specify
information about runtime ID-mapping on a compile-time link object.
It is highly recommended that you use the INILNKMAP mapping macro
to initialize the ULNKMAP structure.
The lnknm member contains the runtime name of the link.
The lid member contains the compile-time Link ID.
The Link ID (lid) can be hardcoded by the programmer (with a unique
custom ID) or be supplied by the Unify DataServer C compiler, ucc.
If you choose to hardcoded a unique Link ID (lid), be sure that the
number you pick is compatible with the type ULID.
To generate a unique compile-time Link ID using ucc, initialize lid with
the following compiler directive (lnknm is the name of the hash table):
$(ULNK:LID)lnknm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
130
The RHLI Structures
The UNIPCOLL Structure: Column
Access Information
The UNIPCOLL structure describes how and where column data is stored
and manipulated and is used by the following functions:
ualctbl
uextint
ufchlnk
ufchrow
ufchtbl
uinsrow
uintext
upkfrow
uupdrow
The UNIPCOLL structure has the following declaration:
typedef struct
{
UCID * cidl;
UDBVAL * dbvall;
int ncol;
} UNIPCOLL;
/* list of Column IDs
/* list of column values
/* # of entries in cidl/dbvall
*/
*/
*/
The dbvall member contains members that are structures and unions. The
following diagram shows the components of the UNIPCOLL structure.
The RHLI Structures
131
UNIPCOLL
UCID 0
UCID 1
UCID 2
UDBVAL 1
UDBVAL 2
...
UCID n-1
UCID
UDBVAL
ncol (=n)
UDBVAL 0
UNIP
UNIP
UNIP
UOPTS
UOPTS
UOPTS
UDBVAL n-1
...
UNIP
UOPTS
UNIP
UTP_TIME
UTP_DATE
UTP_HDTE
UTP_AMT
UTP_HAMT
UTP_INT
UTP_HINT
UTP_FLT
UTP_GINT
UTP_STRP
UTP_GAMT
UTP_VDDS
Corresponding
Column Data Buffer
val
scale
vd_buf
Data Buffer
vd_filnm
vd_bufnx
vd_nbyts
vd_mode
vd_colnx
Data File
vd_rbyts
vd_colsz
TEXT/BINARY
Column Buffer
132
The RHLI Structures
The ncol member contains the number of entries in the cidl and dbvall
lists. The number of entries in the list can be zero, and for variable-length
data, can exceed the total number of columns that belong to the table.
(See the description for the UTP_VDDS structure on page 136.)
The cidl member contains a pointer to a list of column identifiers. The
size of the list must be identical to the number of columns specified in the
ncol member. All of the identifiers contained in the column identifier list
must belong to the same table.
If the ncol member is zero (0), the cidl member is not examined and may
contain a null pointer.
The dbvall member contains a pointer to a list of UDBVAL data value
structures. The size of the list must be identical to the number of columns
specified in the ncol member. If the member ncol is zero, the dbvall
member is not examined and can contain a null pointer.
The first entry in the column identifier list (cidl) corresponds to the first
entry in the data value list (dbvall), and so forth.
The UDBVAL Structure
The UDBVAL structure describes the column’s data to be inserted,
updated, or retrieved. Each entry in the data value structure list
corresponds to the respective identifier entry in the column identifier list.
The UDBVAL structure has the following declaration.
typedef struct
{
UNIP
unip;
UOPTS
valopts;
} UDBVAL;
/* pointer to column’s value buffer
/* column value options
*/
*/
The valopts member is a set of options that describe the data in the user
data buffer.
It is important to initialize valopts for both retrieval and insert/update
operations. After retrieval operations, the system reinitializes the valopts
member to describe the data that was placed in the user’s buffer. With
insert and update operations, however, column values are only verified;
valopts is not set.
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly. Fetch operations are upkfchrow, ufchlnk, ufchscn,
ufchrow, ufchtbl, and ufchord.
The RHLI Structures
133
The valopts member can contain the following options:
UNORMAL
value is valid & defined
UNULLVAL
value is null
UIGNORE
ignore column value; do not use
URETVAL
return initialized data value
UNOTDEF
reserved for user application use; not a valid
option. Used to indicate that the value is
undefined which is distinct from null.
To specify more than one option, separate multiple options with the
bitwise logical OR operator (|) in the argument list.
The UNORMAL option indicates that the user buffer contains valid or
null data.
The UNULLVAL option indicates that the data in the user buffer is null.
The UIGNORE option indicates that the system is to ignore this structure
entry completely; no work is to be performed. The UIGNORE option is
useful when the user want to selectively activate various columns in the
UNIPCOLL structure without rebuilding the structure.
Every column can have the UIGNORE option set; this is similar to setting
the ncol member’s value to zero.
The URETVAL option indicates that the system is to return to the user’s
buffer the value of the data that was inserted into the database (after DIS
default values have been applied).
The URETVAL option is only applicable for insert and update operations.
This option cannot be used for columns of type TEXT or BINARY.
The URETVAL option can retrieve the default values applied to a column
during an insert operation. This way, you do not have to perform a
retrieval operation after the insert operation completes. If the URETVAL
option is used for this purpose, the UIGNORE option must also be
specified. Otherwise, the buffer is assumed to contain valid data, which
might not be the case.
The option UNORMAL is represented by the bit value 0 and, thus, cannot
be used as a bit mask.
134
The RHLI Structures
Data is defined to be either null or not null. Therefore, specifying the
UNULLVAL option as a bit mask is appropriate, while specifying the
UNORMAL option is not correct. For example, the expression
valopts & UNORMAL
is always false, while the expression
valopts & UNULLVAL
is true if the data is null, or, false, if the data is not null.
The unip Union
The unip member is of type UNIP which contains a union of pointers, one
for each database data type.
The unip points to the user’s buffer where the system either places
retrieved data or acquires the data to be inserted or updated. The structure
is a union of pointers. The compiler accepts the assignment of the actual
pointer to a buffer of the column’s correct data type.
The UNIP union has the following declaration.
typdef union
{
UTP_TIME *
UTP_DATE *
UTP_HDTE *
UTP_AMT *
UTP_HAMT *
UTP_GAMT *
UTP_INT *
UTP_HINT *
UTP_GINT *
UTP_FLT *
UTP_STRP
UTP_BYTP
UTP_REAL *
UTP_DBL *
UTP_VDDS *
} UNIP;
timep;
datep;
ldatep;
amtp;
hamtp;
gamtp;
intp;
hintp;
gintp;
fltp;
strp;
bytp;
realp;
dblp;
vdp;
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
––>
”TIME” column buffer
”DATE” column buffer
”HUGE DATE” column buffer
”AMOUNT” column buffer
”HUGE AMOUNT” column buffer
”CURRENCY” column buffer
”INT” column buffer
”SMALL INT” column buffer
”HUGE INT(64-bit)” col buffer
”FLOAT” column buffer
”STRING” column buffer
”BYTE column buffer
”REAL column buffer
”DOUBLE column buffer
”TEXT/BINARY” column buffer
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
All members of the UNIP union are pointers to a buffer which contains
the column’s corresponding data.
The pointer of the applicable column’s data type is assigned to a buffer of
the same type; mixing pointer and buffer types is not recommended and
may be flagged by the compiler as invalid.
The RHLI Structures
135
Unify DataServer expects the data buffer identified by the UNIP member
to be correctly aligned for the data type of the column. For example, if
the column is of type FLOAT, the buffer to contain the float value should
be correctly aligned for the FLOAT type.
When amtp data is retrieved from a database, the data temporarily loses
the scale of 2. Therefore, AMOUNT data stored in amtp variables change
their scale to zero and record pennies rather than dollars.
If you want to print or display the host variable value, you must divide
the value by 100 to restore the default scale of 2. If the host variable
value is being applied to a database, you do not need to divide the value
by 100; Unify DataServer applies a precision of 2 to AMOUNT values.
Except for UTP_VDDS, all members of the UNIP union are atomic data
types. For example, int, long and char.
UTP_VDDS is a structure that describes variable-length data for use with
data type TEXT or BINARY columns.
The UTP_VDDS
Structure
The UTP_VDDS structure has the following declaration.
typedef struct
{
char * vd_buf;
char * vd_filnm;
long vd_bufnx;
long vd_nbyts;
int vd_mode;
long vd_colnx;
long vd_rbyts;
long vd_colsz;
} UTP_VDDS;
/*
/*
/*
/*
/*
/*
/*
/*
data buffer
file to use as data buffer
starting offset in buffer
# of bytes to fetch/store
update mode
starting offset in database col
# of bytes actually read/written
total size of database column
*/
*/
*/
*/
*/
*/
*/
*/
The UTP_VDDS structure allows you to use a memory buffer or file to
either store variable length data into or read from when manipulating
variable-length data.
If you choose to store or read the variable length data into or from a
buffer, the member vd_buf must be set to point to the buffer that contains
the variable length value. Also, when using a buffer to store or read
variable length data to or from, the member vd_filnm must be set to (char
*)0.
If you want to store or read variable-length data into or from a file
instead of a buffer, vd_buf must be set to (char *)0 and the member
vd_filnm must point to a file name of an existing file that contains or will
contain the variable-length data.
136
The RHLI Structures
To assign a null value to a variable-length member, initialize an empty
UTP_VDDS structure as follows:
dbval.unip.valopts = UNULLVAL;
dbval.unip.vds = (UTP_VDDS *)0;
Variable text data can only be stored in standard Unix files (as opposed to
devices).
The vd_bufnx member specifies the byte offset from the beginning of the
buffer or file that contains the variable length data. To read the buffer or
file from the beginning, set vd_bufnx to 0.
The vd_nbyts member specifies the number of bytes of data to read from
or write to a buffer or file (specified by vd_buf or vd_filnm from offset
position vd_bufnx). The number of bytes are counted beginning at offset
position vd_colnx.
When writing to a file (and you want to retrieve the entire var_len value),
set vd_nbyts to a value that is large enough to fetch all bytes of data. If
you do not know the size of the data, set vd_nbyts to an artificially high
value, such as 2,147,483,647, to ensure that all data is retrieved.
Warning
Make sure that the starting offset plus the number of bytes requested (that
is, vd_bufnx + vd_nbyts), does not exceed the size of the data buffer.
Otherwise, if you read from a buffer that is too small, you will retrieve
“garbage” data; or, if you write to a buffer that is too small, you will
corrupt memory.
Also, an error occurs if vd_bufnx + vd_nbyts exceeds:
the actual file size when reading from a file
the maximum file size when writing to a file
To read a file from the vd_bufnx offset position to “end-of-file,” set
vd_nbyts to –1. This option is used when you are reading data from a file
for insert or update operations.
The –1 option is used when reading from a file only; not to read from a
buffer or the database.
The vd_mode member specifies the update mode to use when operating
on variable length data found in a buffer or file, and the data stored in a
database column.
The RHLI Structures
137
Valid vd_mode values are:
V_TRUNC
Truncates (or removes) a database column
value starting at offset position vd_colnx to the
end of the variable length column value. The
removed data is replaced with vd_nbyts of data
from a buffer or file.
V_OVERWR
Replaces (or overwrites) a database column
value starting at position vd_colnx for a length
of vd_nbyts with data from a buffer or file.
V_APPEND
Appends (or adds) vd_nbyts of data from a
buffer or file to the end of the database column
value.
V_INSERT
Inserts to a database column value, vd_nbyts of
data from a buffer or file, before the byte
pointed to by vd_colnx.
V_DELETE
Deletes (or removes) data from a database
column value starting at position vd_colnx for a
length of vd_nbyts.
V_FETCH
Fetches (or retrieves) vd_nbyts of data from a
database column value starting at position
vd_colnx for a length of vd_nbyts, and writes the
retrieved data into a buffer or file.
Specifying more columns than exist in the table (where the value of ncol
exceeds the actual number of columns in the table), is known as
overloading an operation.
Overloading is most useful for inserting and updating TEXT/BINARY
column operations, where the same column is specified multiple times
and different vd_mode modes within a single database operation may be
applied.
The vd_colnx member specifies a byte offset from the beginning of the
database column value. To set the offset position at the beginning of the
database column value, set vd_colnx to 0.
The vd_rbyts member contains the actual number of bytes read from or
written to a buffer or file. This value is returned after the operation has
completed.
For update modes V_TRUNC, V_OVERWR, V_APPEND, V_INSERT,
when the update is successful vd_rbyts reflects the value of vd_nbyts.
138
The RHLI Structures
For V_DELETE operations, vd_rbyts contains the number of actual bytes
deleted from the database column.
For the fetch mode, V_FETCH, vd_rbyts will contain the actual number
of bytes retrieved. Note that the number of bytes retrieved will be less
than the requested number of bytes, vd_nbyts, if the end of the column
value is reached.
The vd_colsz member contains the number of bytes remaining in the
database column after the database operation has completed.
The RHLI Structures
139
The UNIPEXT Structure: Column
Conversion Information
The UNIPEXT structure is used by the uextint and uintext functions to
specify column storage locations for conversion from internal to external
formats (and vice versa).
The UNIPEXT structure has the following declaration.
typedef struct
{
UNIV
univ;
UOPTS
valopts;
} UNIPEXT;
/* pointer to column’s external value
/* column value options
*/
*/
The UNIPEXT structure is laid out identically to the UDBVAL structure,
except that the UNIP member is named UNIV. See the UDBVAL structure
on page 133.
140
The RHLI Structures
The UOACOLS Structure: Ordered
Access Row Order
The UOACOLS structure has the following declaration.
typedef struct
{
UCID
oacid;
UOPTS
oacopts;
} UOACOLS;
/* column identifier
/* column sort option
*/
*/
The UOACOLS structure is used by the ubegord function to specify the
order to be placed on the rows of a table for ordered access. Specify one
UOACOLS structures for each column to be part of the order.
The oacid member contains the column ID of a column of the order
specification.
The oacopts member contains the order specification for the
corresponding column. Options are:
DB_ASCEND
ascending column value
DB_DESCND
descending column value
DB_NORMAL DB_ASCEND is the default value used
The RHLI Structures
141
The URVKDS Structure: Revoke
Privilege Descriptor
The URVKDS structure has the following declaration.
typedef struct
{
union
{
UAID aid;
UOID uid;
} gte;
UCAPS rvkcaps;
UOBJDS obj;
} URVKDS;
/* Grantee
/* Privileges to be revoked
/* Object to revoke
*/
*/
*/
The URVKDS structure is used by the udrpprv function to specify
information about the privileges to revoke.
The aid member contains the authorization ID from which authorization
privileges are to be revoked.
The uid member contains the user ID from which permissions are to be
revoked.
The gte member contains the ID of the object from which the privilege is
to be revoked. The object to which privileges have been granted is known
as the grantee.
Because gte is a union, either a schema or a user can be revoked a
privilege, but not both.
The rvkcaps member contains the set of privileges that are to be revoked
from the specified object. The set of privileges determines whether the
type of the grantee is a schema or a user.
To revoke authority, initialize the rvkcaps member as follows:
142
UDBA
for DBA authority
USCH
for SCHEMA authority
UDALL
for both DBA and SCHEMA authority
The RHLI Structures
To revoke schema privileges to a schema, initialize the rvkcaps member
as follows:
USSEL
for SELECT operations
USINS
for INSERT operations
USUPD
for UPDATE operations
USDEL
for DELETE operations
UTALL
for all operations (SELECT, INSERT, UPDATE
and DELETE)
If the schema privileges to a schema are revoked, all
tables in the schema are inaccessible.
To revoke schema privileges to a table, initialize the rvkcaps member as
follows:
UTSEL
for SELECT operations
UTINS
for INSERT operations
UTUPD
for UPDATE operations
UTDEL
for DELETE operations
UTALL
for all operations (SELECT, INSERT, UPDATE
and DELETE)
To revoke schema privileges to a column, initialize the rvkcaps member
as follows:
UCSEL
for SELECT operations
UCINS
for INSERT operations
UCUPD
for UPDATE operations
UCALL
for all operations (SELECT, INSERT and
UPDATE)
If you want to revoke more than one operation privilege for the same
object, separate multiple options with the bitwise logical OR operator (|).
The obj member is a structure (UOBJDS) that contains a description of
the object that the privilege affects.
The RHLI Structures
143
The UOBJDS Structure
The UOBJDS structure has the following declaration.
typedef struct
{
UDBOBJ objid;
int objknd;
} UOBJDS;
/* object ID
/* the type of object
*/
*/
The objid member contains a database object ID whose type is described
by the objknd member. Options are:
UAID
Authorization ID
UDBID
Database ID
UCID
Column ID
UTID
Table ID
The objknd member contains a value that indicates what type of ID is
contained in the objid member. Options are:
UDBKND
database object
USCHKND
schema object
UTBLKND
table object
UVWKND
view object
UCOLKND
column object
If you are revoking a user privilege (DBA or SCHEMA authority), objid
and objknd must be set to the current Database ID (see the uopndb
function) and UDBKND, respectively.
After the privileges revoke operation, the rvkcaps element (in the
structure URVKDS), contains the privileges that were revoked.
That is, if you revoke SELECT schema privilege from a table, the value
contained in rvkcaps is equivalent to UTSEL. If you revoked SCHEMA
authority from a user, rvkcaps contains a value equivalent to USCH.
Additional Help
For information about security and privileges, see “Setting Up and
Managing Security” in Unify DataServer: Managing a Database.
144
The RHLI Structures
The UTBLINF Structure: Table
Information
The UTBLINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UTID tid;
/* table this struct describes
UTID remapid;
/* logical Table ID (if remapped)
UAID aid;
/* Authorization ID of this table
*/
*/
*/
/* information retrieval class: I (UCLASS1) */
UDEFID defid;
/* Table Definition ID
UDEFID chgid;
/* Table Modification ID
UMAPID mapid;
/* Table Summation ID
long segsz;
/* desired segment size (bytes)
long tblbase;
/* direct table base value
UOPTS tblopts;
/* table processing options
*/
*/
*/
*/
*/
*/
/* information retrieval class: II (UCLASS2) */
int ncol;
/* # of columns in table
UCID * ucidlst;
/* pointer to table Column ID list
int nbtree;
/* # of btrees in table
UBTID * ubidlst;
/* pointer to table B-tree ID list
int nhsh;
/* # of hash-tables in table
UHID * uhidlst;
/* pointer to the table’s Hash
/* Table ID list
int nlnk;
/* # of links in table
ULID * ulidlst;
/* pointer to the table’s Link ID
/* list
int nkey;
/* # of columns in key column list
UCID * keycidl;
/* primary key Column ID
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/* information retrieval class: III (UCLASS3) */
int nvol;
/* # of volumes specified for table
UVID * uvidlst;
/* pointer to table’s Volume ID list
*/
*/
/* information retrieval class: IV (UCLASS4) */
long expnum;
/* expected number of rows
char * tbldesc;
/* pointer to table description
} UTBLINF;
*/
*/
The UTBLINF structure is used by the uinftbl function to retrieve
information about a table.
The tid member contains the table ID that the structure describes. If the
ID represents a remapped table, the ID is the compile-time table ID (the
ID with which the user remapped the table).
The RHLI Structures
145
The remapid member contains the logical table ID that the structure
describes. If the ID represents a remapped table, the ID is the runtime
table ID (that is, the actual object ID in the database). Otherwise, the
value of remapid is identical to the tid member value.
The aid member contains the authorization ID to which this table
belongs.
The defid member contains the table’s current Definition ID. The
Definition ID changes whenever a physical modification is made to the
table, such as adding or dropping columns.
The chgid member contains the table’s current Change ID. The Change
ID changes whenever a logical modification is made to the table, such as
modifying the table’s name.
The mapid member contains the table’s current Mapping ID. The
Mapping ID serves as a checksum of the table’s physical attributes, such
as the columns contained in the table.
The segsz member contains the table’s designated segment size, if any, in
bytes.
The tblbase member contains the table’s base value, if the table has been
specified as being a direct table. Otherwise, the value of tblbase is zero
(0).
The tblopts member contains one or more of the following options:
DB_ORDNRY
create ordinary table
DB_DIRECT
create directĆkeyed table
DB_RDONLY
table is readĆonly
DB_SCATTR
scatter data across volumes
DB_USEVOL
must use specified preference volumes
DB_FIXSIZE
table size is fixed at value specified by expnum
DB_KEYED
create a primary key
DB_NORMAL DB_ORDNRY is the default value used
The ncol member contains the number of columns in the table column ID
list ucidlst. If the value of ncol is zero (0), the ucidlst member is not
allocated and should not be referenced.
146
The RHLI Structures
The ucidlst member contains a list of column IDs that belong to the table.
The list is sorted in the chronological order in which the columns were
added to the table.
The nbtree member contains the number of B-trees in the B-tree ID list
ubidlst. If the value of nbtree is zero (0), the ubidlst member is not
allocated and should not be referenced.
The ubidlst member contains a list of B-tree IDs that belong to the table.
The nhsh member contains the number of hash tables in the hash table ID
list uhidlst. If the value of nhsh is zero (0), the uhidlst member is not
allocated and should not be referenced.
The uhidlst member contains a list of hash table IDs that belong to the
table.
The nlnk member contains the total number of links in the Link ID list
ulidlst. If the value of nlnk is zero (0), the ulidlst member is not allocated
and should not be referenced.
The ulidlst member contains a list of Link IDs that belong to the table.
Note that the list contains both parent and child Link IDs, and does not
differentiate between the two.
The nkey member contains the number of columns in the table primary
key list keycidl. If the value of nkey is zero (0), the keycidl member is not
allocated and should not be referenced.
The keycidl member contains a list of the column IDs that constitute the
designated primary key for the table. The IDs are sorted in their
designated order.
The nvol member contains the number of volumes in the volume
preference list uvidlst. If the value of nvol is zero (0), the uvidlst member
is not allocated and should not be referenced.
The uvidlst member contains a list of the volume IDs that have been
preferenced for the table.
The expnum member contains the expected number of records, if any,
that was designated when the table was created.
The tbldesc member contains the table’s variable length description, if
any.
The RHLI Structures
147
The UTBLMAP Structure: Table ID
Mapping
The UTBLMAP structure has the following declaration.
typedef struct
{
char * tblnm;
UTID tid;
UTID remapid;
UDEFID defid;
UMAPID mapid;
} UTBLMAP;
/*
/*
/*
/*
/*
pointer to the runtime table name
compile-time Table ID
runtime Table ID (returned)
compile-time table Definition ID
compile-time table Mapping ID
*/
*/
*/
*/
*/
The UTBLMAP structure is used by the umaptbl function to perform
runtime ID-mapping on a compile-time table object.
The tblnm member contains the runtime name of the table.
The tid member contains the compile-time table ID.
The table ID (tid) can be hardcoded by the programmer (with a unique
custom ID) or be supplied by the Unify DataServer C compiler, ucc.
If you choose to hardcoded a unique table ID (tid), be sure that the
number you pick is compatible with the type UTID.
To generate a unique compile-time table ID using ucc, initialize tid with
the following compiler directive (tblnm is the name of the table):
$(UTBL:TID)tblnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
The defid member contains the table’s compile-time Definition ID, which
is a time-stamped ID that is used by Unify DataServer to verify the
accuracy of remapid.
The Definition ID (defid) must be initialized with the following compiler
directive syntax (tblnm is the name of the table):
$(UTBL:DEFID)tblnm$
148
The RHLI Structures
The mapid member contains the table’s compile-time Mapping ID, which
is a checksum value that is used by Unify DataServer to verify the
accuracy of remapid. This value is for internal use only.
The Mapping ID (mapid) must be initialized with the following compiler
directive syntax (tblnm is the name of the table):
$(UTBL:MAPID)tblnm$
Tip
It is highly recommended that you use the INITBLMAP mapping macro
to initialize the UTBLMAP structure.
The RHLI Structures
149
The UTXINF Structure: Transaction
Information
The UTXINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UTXID txid;
/* Transaction ID
int logflag; /* is logging on (1=yes/0=no)
/* information
long nupd;
int txtyp;
int state;
int lckphas;
int nlck;
int nlgpg;
int opsknd;
} UTXINF;
*/
*/
retrieval class: I (UCLASS1) */
/* number of update operations
/* transaction type
/* current state of the transaction
/* Lock phase ascend/descend
/* number of locks held by transact.
/* number of log pages written
/* kind of operations in tx
*/
*/
*/
*/
*/
*/
*/
The UTXINF structure is used by the uinftx function to retrieve
transaction information.
The txid member contains the transaction ID described by this structure.
The logflag member contains a Boolean value that indicates whether
transaction logging is turned on for the user. A value of one (1) indicates
that transaction logging is on, a value of zero (0) indicates that
transaction logging is off.
The nupd member contains the count of the number of update operations
that have been performed on behalf of this transaction. An update
operation is one that does not retrieve data.
The txtyp member contains the transaction type. Options are:
150
UTXTYPE0
Type 0 transactionĊ read only
UTXTYPE1
Type 1 transactionĊupdate, limited
concurrency
UTXTYPE2
Type 2 transactionĊupdate, twoĆphase locking
The RHLI Structures
The state member contains the current state of the system. Options are:
UTXSTRT
Start transaction
UTXACT
Transaction active
UTXSUSP
Suspend transaction
UTXCMT
Commit transaction
UTXPREP
Prepare transaction
UTXCMPL
Complete transaction
UTXEND
End transaction
UTXABRT
Abort transaction
The lckphas member contains an indicator of what phase the transaction
is currently operating under, if the transaction is a type 2 transaction
(two-phase locking). A value of 1 indicates that the transaction is in the
unlock phase, a value of 0 (zero) indicates that the transaction is in the
lock phase.
The nlck member contains the count of the number of row locks, both
shared and exclusive, currently held by the transaction.
The nlgpg member contains the count of the number of log buffers
written to the transaction log for this transaction. This value does not
include any log buffers maintained in shared memory.
The RHLI Structures
151
The UTXOPT Structure: Begin
Transaction Options
The UTXOPT structure has the following declaration.
typedef struct
{
long cmtfreq;
int txknd;
UOPTS waitflg;
} UTXOPT;
/* # of operations before batch commit */
/* Transaction kind
*/
/* wait to start transaction log
*/
The UTXOPT structure is used by the ubegtx and ucbgtx functions to
specify options for beginning a transaction.
The cmtfreq member specifies the number of operations after which the
current batch transaction is to be committed. Also see the description of
the UBATCH option of waitflg.
The txknd member specifies the transaction level. Options are:
UTXTYPE2
Transactions enforce any shared or exclusive
locks acquired by the transaction. No locks are
released until the transaction ends.
UTXTYPE1
Transactions also enforce any shared or
exclusive locks acquired by the transaction;
however, shared locks can be released before
the transaction ends.
UTXTYPE0
Transactions are special purpose transactions
that allow reading of uncommitted data. No
updates are allowed for a transaction of this
type.
UTXTYPE0 is the only valid value for txknd
when the database has been opened in
readĆonly mode (see the uopndb function).
152
The RHLI Structures
The waitflg member contains a value that controls batch transactions and
whether transactions should wait for a resource to become available or to
return immediately in case of insufficient resources. Options are:
UAUTO
Commit a batch transaction if resources are
scarce
UBATCH
Transaction is to operate in batch mode; the
cmtfreq member must be specified
UCOMMIT
Commit transaction on the uclsdb function
UNOWAIT
Do not wait for a resource before starting a
transaction
UWAIT
Wait for an available resource before starting a
transaction
DB_NORMAL UNOWAIT is the default value used
If you specify the UBATCH option, the UCOMMIT option is implicitly
specified.
UAUTO can be used in cases where you want to allow the system to react
to influences from other users that affect database resources. For
example, if shared memory is more than 75% full, or the transaction log
space cannot be reserved, the batch transaction is implicitly committed if
UAUTO is set. If you specify the UAUTO option, you must also specify
the UBATCH option.
UBATCH specifies that the transaction operates in batch mode..
The RHLI Structures
153
The UUSRINF Structure: User
Information
The UUSRINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UOID uoid;
/* User/Owner ID
*/
/* information retrieval class: I (UCLASS1) */
UAID aid;
/* user default Authorization ID
UAID curaid;
/* user current Authorization ID
*/
*/
/* information retrieval class: II (UCLASS2) */
int nauth;
/* # of authorizations in ’aidlst’
UAID * aidlst;
/* pointer to list of valid Auth IDs
/* (schemas) for user
*/
*/
*/
/* information retrieval class: III (UCLASS3) */
char usernm[U_USRNMLN + 1]; /* pointer to user name
} UUSRINF;
*/
The UUSRINF structure is used by the uinfusr function to retrieve
information about a user.
The uoid member contains the user ID described by the information in
this structure.
The aid member contains the authorization ID of the user’s default
schema upon entry to the system.
The curaid member contains the authorization ID of the user’s current
schema.
The nauth member contains the number of entries in the authorization list
aidlst. If the value of nauth is zero (0), aidlst has not been allocated and
should not be referenced.
The aidlst member contains a list of authorization IDs to which the user
has been granted access.
The usernm member is the name of the user as it would be referenced for
name-binding.
154
The RHLI Structures
The UVOLINF Structure: Volume
Information
The UVOLINF structure has the following declaration.
typedef struct
{
/* information always retrieved */
UVID vid;
/* Volume ID
UVID remapid;
/* logical Volume ID (if remapped)
*/
*/
/* information retrieval class: I (UCLASS1) */
long voloff;
/* volume offset (bytes)
long vollen;
/* volume length
long volused;
/* allocated (used) space
long volpgsz;
/* volume page size (bytes)
UOPTS volopts;
/* volume processing options
*/
*/
*/
*/
*/
/* information retrieval class: II (UCLASS2) */
int ntbl;
/* # of tables clustered in volume
UTID * utidlst;
/* pointer to the clustered Table
/* ID list
*/
*/
*/
/* information retrieval class: III (UCLASS3) */
char volfile[U_FILELEN + 1]; /* pointer to the volume
/* file name
char volname[U_NAMELEN + 1]; /* volume name, if any
} UVOLINF;
*/
*/
*/
The UVOLINF structure is used by the uinfvol function to retrieve
information about a volume.
The vid member contains the volume ID that the structure describes. If
the ID represents a remapped volume, the ID is the compile-time volume
ID (the ID with which the user remapped the volume).
The remapid member contains the logical volume ID that the structure
describes. If the ID represents a remapped volume, the ID is the runtime
volume ID (the actual Database ID). Otherwise, the remapid value is
identical to the vid member value.
The voloff member contains the volume’s initial offset in the volume’s
device. If the volume is a regular or contiguous file, voloff is zero (0). A
non-zero value indicates the number of bytes into the device at which the
device can be found.
The RHLI Structures
155
The vollen member indicates the length of the volume. If DB_BIG is set
in the volopts member, vollen represents the number of pages. Otherwise,
it represents the number of bytes; this value is converted internally into
the corresponding number of pages. The volume length is used by
volume storage routines to determine how much data can fit onto the disk
partition. If the volume is a contiguous file or a device, vollen contains a
non-zero value. For a regular file, a zero value (0) indicates that the
volume size is unconstrained and can dynamically grow as needed.
The volused member contains the amount of the volume that is allocated.
The DB_BIG member controls whether this value is specified as pages or
bytes, as for vollen.
The volpgsz member contains the volume’s page size, in bytes.
The volopts member contains the volume’s processing options. Options
are:
DB_ORDNRY
volume is ordinary
DB_DEVICE
volume is a device
DB_RDONLY
reserved for future use
DB_FORCE
force volume preĆallocation
DB_ALLOC
volume is a preĆallocated file
DB_BIG
Indicates that the vollen specification is in pages
rather than bytes.
DB_CONTIG
reserved for future use
DB_NORMAL DB_ORDNRY is the default value used
Your application should test the DB_BIG bit to determine the volume size.
For example:
156
The RHLI Structures
UVOLINF *volinfl; /* ––> vols info list */
int
inx;
/* its for–loop index */
...
if ( (volinfl+inx)–>volopts & DB_BIG )
{
/* lengths are # of 2k pages */
printf(”vollen = %ld KB, ”,
(volinfl+inx)–>vollen *
((volinfl+inx)–>volpgsz/1024));
printf(”volused = %ld KB.”,
(volinfl+inx)–>volused *
((volinfl+inx)–>volpgsz/1024));
}
else /* volume is not > 2 GB */
{
printf(”vollen = %ld bytes, ”,
(volinfl+inx)–>vollen);
printf(”volused = %ld bytes.”,
(volinfl+inx)–>volused);
}
...
The ntbl member contains the number of entries in the table ID list
utidlst. If ntbl contains a zero value (0), utidlst has not been allocated and
should not be referenced.
The utidlst member contains a list of all of the table IDs that have
preferenced this volume. The table’s processing options need to be
examined to determine if the volume is a required or advisory preference.
The volfile member contains the full path name of the volume file or
device.
The volname member contains the name of the volume as it would be
referenced for name-binding.
The RHLI Structures
157
The UVOLMAP Structure: Volume ID
Mapping
The UVOLMAP structure has the following declaration.
typedef struct
{
char * volnm;
UVID vid;
UVID remapid;
} UVOLMAP;
/* pointer to runtime volume name
/* compile-time Volume ID
/* runtime Volume ID (returned)
*/
*/
*/
The UVOLMAP structure is used by the umapvol function to perform
runtime ID-mapping on a compile-time volume object.
It is highly recommended that you use the INIVOLMAP mapping macro
to initialize the UVOLMAP structure.
The volnm member contains the runtime name of the volume.
The vid member contains the compile-time volume ID.
The volume ID (vid) can be hardcoded by the programmer (with a unique
custom ID) or be supplied by the Unify DataServer C compiler, ucc.
If you choose to hardcoded a unique volume ID (vid), be sure that the
number you pick is compatible with the type UVID.
To generate a unique compile-time volume ID using ucc, initialize vid
with the following compiler directive (volnm is the name of the volume.):
$(UVOL:VID)volnm$
The remapid member, upon successful completion of the ID-mapping
operation, contains the runtime ID to which the compile-time ID was
mapped. This value is for internal use only.
158
The RHLI Structures
Function Reference
159
160
Function Reference
uabttx
Abort a transaction
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uabttx( txid, status )
UTXID txid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
status
Returned status of the function
Aborts the specified active transaction and rolls back all database operations
performed during the transaction. Database operations include insert, delete, and
update operations.
An active transaction is a transaction that has not been committed or aborted.
To use this function, transaction logging must be on (that is, the LOGTX configuration
variable must be set to TRUE).
This function releases all locks associated with the transaction and closes all scans
active in the transaction.
Warning
Do not abort a transaction by calling the UNIX kill command. This command can
cause irreversible damage to the database. Use the uabttx function to abort a
transaction.
Security
No privileges needed.
161
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
ubegtx, ucbgtx, ucmttx, uinftx
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
162
uaddath
Add a schema to a database
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddath( txid, nauth, dbauth, statusl, status )
UTXID txid;
int nauth;
DBAUTH *dbauth;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nauth
Number of schemas in the dbauth list
dbauth
List of DBAUTH structures, each describing a separate schema to add
statusl
Returned list of status values, one for each dbauth entry
status
Returned status of the function
Validates the schemas described in the dbauth list and adds the schemas to the
database.
Each DBAUTH structure in the dbauth list contains information about a schema.
For a complete description of the DBAUTH structure, see page 80.
Security
To add a schema, you must have one of the following permissions.
DBA authority
SCHEMA authority
163
To grant DBA and SCHEMA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
udrpath, uallath, ubndath, ufchath, uaddprv, uinfath, umapath, umodath,
unumath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
164
uaddbt
Define a B-tree index
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddbt( txid, nbt, dbbtree, statusl, status )
UTXID txid;
int nbt;
DBBTREE *dbbtree;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nbt
Number of B-trees in the dbbtree list
dbbtree
List of DBBTREE structures, each defining a separate B-tree to add
statusl
Returned list of status values, one for each dbbtree entry
status
Returned status of the function
Validates the B-trees defined in the dbbtree list and adds the B-trees to the database.
B-trees facilitate range searches and random access on one or more columns. B-trees
can be built referencing a composite key made up of the maximum number of
columns allowed (128.)
B-trees are created by specifying any column or combination of columns in a
database table as the indexes, except those columns that are of the data type TEXT
(U_VTXT) or BINARY (U_VBIN).
Each DBBTREE structure in the dbbtree list contains information about a B-tree.
165
For a description of the DBBTREE structure, see page 81.
Security
To define a B-tree for a table, the table must be in the current schema and you must
have one of the following permissions.
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
udrpbt, uinfbt, umodbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using B-trees, see “Choosing an Access Method” and
“Managing the Database Files” in Unify DataServer: Managing a Database.
166
uaddcgp
Add a column group to a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddcgp( txid, ncgrp, dbcgrp, statusl, status )
UTXID txid;
int ncgrp;
DBCGRP *dbcgrp;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ncgrp
Number of column groups in the dbcgrp list
dbcgrp
List of DBCGRP structures, each describing a column group to add
statusl
Returned list of status values, one for each dbcgrp entry
status
Returned status of the function
Validates the column groups listed in dbcgrp and adds the column groups to a table in
the database.
If a column group already exists, this function combines the requested options with
the existing options for that column group.
Each DBCGRP structure in the dbcgrp list contains information about a column
group. For a description of the DBCGRP structure, see page 83.
If the add operation is successful, a column group ID is returned (to DBCGRP
member grpcid) for each added column group in the dbcgrp list.
You cannot specify uniqueness constraints on a column if the column contains data.
167
Security
To add a column group to a table, the table must be in the current schema and you
must have one of the following permissions.
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
The following example uses the uaddcgp function to define a column group for a
table.
/* initialize the DBCGRP structure */
if ( uaddcgp(txid, ncgrp, dbcgrp, statusl, &status) != USUCCESS )
printf(”Couldn’t add column group: status = %ld\n”, status);
See Also
udrpcgp, uinfcgp
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
168
uaddcnm
Add a column name (or synonym)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddcnm( txid, ncol, dbcolnm, statusl, status )
UTXID txid;
int ncol;
DBCOLNM *dbcolnm;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ncol
Number of column names in the dbcolnm list
dbcolnm
List of DBCOLNM structures, each describing a separate column
name to add
statusl
Returned list of status values, one for each dbcolnm entry
status
Returned status of the function
Validates the column names listed in dbcolnm and adds the column names to the
database.
Once a synonym for a column has been added, name binding operations can be
performed by specifying the new column name.
Column groups can also be assigned synonyms by specifying the column group ID
(in place of the column ID) in the dbcolnm list.
Each DBCOLNM structure in the dbcolnm list contains information about a column’s
name.
169
For a description of the DBCOLNM structure, see page 85.
Column names must be unique within a table.
Security
To add a column name to a column, the table containing the column must be in the
current schema, and you must have one of the following permissions.
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddcnm function to add a column synonym to the
part_number column.
dbcolnm.cid = $parts.part_number$;
dbcolnm.colnm = ”p_no”;
...
if (uaddcnm(txid, 1, &dbcolnm, statusl, &status) != USUCCESS )
{
fprintf(stderr,
”Error naming column: status = %ld\n”,status);
}
See Also
udrpcnm
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
170
uadddb
Create a new, empty database
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uadddb( dbinfo, status )
DBINFO *dbinfo;
USTATUS *status;
Arguments
Description
dbinfo
Pointer to a DBINFO structure that describes the database to create
status
Returned status of the function
Creates a root volume and a new, empty database.
The new database is described with a DBINFO structure which contains root volume
information and other database creation options. For a description of the DBINFO
structure, see page 88.
Before you create a database:
If you want the new database to have a configuration file during the creation
process, its configuration file must exist before you create the database.
However, anytime you open the database, it will apply the configuration
variables defined in the configuration file, even if you created that file after the
creating the databse.
You can optionally choose a new set of shared memory keys for the database
by specifying the keys in the new database’s configuration file.
The advantage of choosing a new key is that if one database is corrupted (by a
killed process, for example), the corrupted database does not affect other
databases that have separate shared memory segments. The disadvantage is
that if many databases exist at the same time, they require many shared
memory segments.
171
Security
To create a new database, you need no special privileges.
However, if you want to overwrite an existing database, you must have DBA
authority for the database you are overwriting. (An existing database is overwritten
by setting the member dbopts in the structure DBINFO to DB_OVERWR.)
To grant DBA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uadddb function to create a database.
USTATUS status;
DBINFO dbinfo;
DBVOLM dbvolm;
/* initialize values */
dbvolm.volfile = ”/usr/db/parts.db”;
dbvolm.volopts = DB_BIG;
dbvolm.voloff = 0;
dbvolm.vollen = 20480;
/* actual size is 41943040 bytes */
dbvolm.volpgsz = 2048;
/* 2k is only supported page size */
dbinfo.rootvol = &dbvolm;
dbinfo.descrpt = ”parts database”;
dbinfo.dbopts = (DB_CONFIG | DB_OVERWR);
/* create the database */
if ( uadddb(&dbinfo, &status) != USUCCESS)
fprintf(stdout, ”creation failed; status: %ld\n”, status);
See Also
uopndb, umoddb, uaddvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
172
uaddhsh
Define a hash table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddhsh( txid, nhsh, dbhashl, statusl, status )
UTXID txid;
int nhsh;
DBHASH *dbhashl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Current transaction ID
nhsh
Number of hash tables in the dbhashl list
dbhashl
List of DBHASH structures, each describing a separate hash table to
add
statusl
Returned list of status values, one for each dbhashl entry
status
Returned status of the function
Validates the hash tables defined in the dbhashl list and adds the hash tables to the
database.
Hash table indexes on a set of columns in a table provide very fast access when
ordering is not needed.
Each DBHASH structure in the dbhashl list contains information about a hash table.
For a description of the DBHASH structure, see page 86.
To add a hash table to a table that already contains rows, you must first perform a
complete scan of the table before adding the hash table. This can be a lengthy
operation, depending upon the amount of data in the table.
173
Security
To define a hash table index for a table, the table must be in the current schema and
you must have one of the following permissions.
DBA authority
SCHEMA authority
To specify a volume for a hash table (the vid member in the DBHASH structure), you
must have DBA authority.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddhsh function to create a hash table index on the manf
table.
colidl[0] = $manf.mano$;
dbhash.htname = “#mano_ht”;
dbhash.ncol = 1;
dbhash.colidl = colidl;
dbhash.htopts = DB_NORMAL;
...
if ( uaddhsh(txid, 1, &dbhash, statusl, &status) != USUCCESS )
{
printf(”Error adding a hash index: status = %ld\n”, status);
printf(”hash index status = %ld\n”, *statusl);
}
See Also
udrphsh, uinfhsh, umodhsh
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using hash tables, see “Managing the Database Files,”
“Choosing an Access Method,” and “Tuning the Access Methods” in Unify
DataServer: Managing a Database.
174
uaddlnk
Define a link
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddlnk( txid, nlnks, dblinkl, statusl, status )
UTXID txid;
int nlnks;
DBLINK *dblinkl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nlnks
Number of links in the dblinkl list
dblinkl
List of DBLINK structures, each describing a separate link to add
statusl
Returned list of status values, one for each dblinkl entry
status
Returned status of the function
Validates the link descriptions listed in dblinkl and adds a link for a pair of tables.
Each DBLINK structure in the dblinkl list contains information about a link. For a
description of the DBLINK structure, see page 90.
A link is composed of a parent column (or set of columns) and a corresponding child
column (or set of columns).
When a link exists between two tables, each row in the child table is associated with a
row in the parent table. The association is based on the linked columns’ values. The
child row is associated to the parent row that has the same values in the linked
columns.
175
If a particular column value does not exist in any parent table row, then you cannot
insert a child row with that column value. This characteristic makes links useful for
enforcing referential integrity.
Also, if a null value is allowed in a child table column, the column will not be
associated with a parent column.
Performance
The link access method can also significantly increase the performance of retrieval
operations requiring related information from different tables.
If the link is on more than one column, then the order of column IDs in the lists
indicates which columns are to be linked between the two tables.
A column can be specified only once per link.
Each column in the child list must have the same type as the corresponding column in
the parent list.
Variable-length columns (of data type U_VTXT or U_VBIN) cannot be used in links.
A column or set of columns can be the child of one link only.
To add a link to a table that already contains rows, you must first perform a complete
scan of the table before adding the link. This can be a lengthy operation, depending
upon the amount of data in the table.
Security
To define a link index for a table, you must have one of the following permissions.
DBA authority
SCHEMA authority
Also, the two tables comprising the link definition must be made accessible by one of
these methods:
Make the schema that contains both linked tables current.
If the tables are located in two separate schemas, make the schema that
contains the first table current and have schema access permission to the
schema that contains the second table.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function. To grant schema access permission, see the
uaddprm function.
176
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddlnk function to define a link index on columns in a table.
pcid = $parts.part_number$;
ccid = $orders.p_no$;
...
dblink.lnkname = ”@part_num_link”;
dblink.ptblid = $parts$;
dblink.ctblid = $orders$;
dblink.ncol
= 1;
dblink.pcolidl = &pcid;
dblink.ccolidl = &ccid;
...
if ( uaddlnk(txid, 1, &dblink, statusl, &status) != USUCCESS )
{
printf(”Error adding link: status = %ld\n”, status);
printf(”link status = %ld\n”, *statusl);
}
See Also
udrplnk, umodlnk, uinflnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
177
uaddprf
Add a volume preference for a table
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddprf( txid, tid, nvol, vidl, statusl, status )
UTXID txid;
UTID tid;
int nvol;
UVID *vidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table to add volume preference
nvol
Number of volumes in the vidl list
vidl
List of volume IDs, each ring to a separate volume pence to add
statusl
Returned list of status values, one for each vidl entry
status
Returned status of the function
Registers the volume preferences designated by the list of volumes for the specified
table.
The table ID (tid) and volume IDs (listed in vidl) must be valid existing entries in the
database before calling the uaddprf function.
Security
To add volume preferences for a table, you must be located in the schema that
contains the table, and you must have DBA authority.
178
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddprf function to add a volume preference to a table.
/* Add the volume preferences */
if ( uaddprf(txid, tid, nvol, vidl, statusl, &status) != USUCCESS)
{
printf(“Unable to add volume preference: %ld\n”, status);
for ( i = 0; i < nvol; ++i )
printf(“Entry %d volume: %ld status: %ld\n”, i, vidl[i],statusl[i]);
uexit(1);
}
See Also
uadddb,uaddtbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
179
uaddprm
Grant schema access permission
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddprm( txid, userid, nauth, authl, statusl, status )
UTXID txid;
UOID userid;
int nauth;
UAID authl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
userid
User ID of user to be granted schema access permission
nauth
Number of authorization IDs (associated with schemas) listed in the
authl list
authl
List of authorization IDs, each referring to a schema for which a user
(userid) is to be granted schema access permission
statusl
Returned list of status values, one for each authl entry
status
Returned status of the function
Grants a user schema access permission to one or more schemas.
Schema access permission allows a user (specified by userid) to access the schema
(specified in authl). When a user is first added to the database (with the uaddusr
function), the user is granted schema access permission to the PUBLIC schema only.
To access other schemas in the database, you must use this function to grant schema
access permission for each schema the user needs to access.
180
To revoke schema access permission from a user, use the udrpprm function.
Security
To grant schema access permission to a user, you must DBA authority or both of the
following must be true:
The schema must be the current schema.
You have SCHEMA authority.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uaddprm function to grant schema access permission to user
lcc:
/* define required parameters */
UTXID txid;
UOID userid;
int nauth;
UAID authl;
USTATUS statusl;
USTATUS * status;
/* Retrieve authorization ID (authl) */
...
/* Grant schema access permission */
nauth = 1;
userid = ”lcc”;
if ( uaddprm(txid, userid, nauth, authl, statusl, &status) != USUCCESS)
{
printf(“Unable to add privileges: %ld\n”, status);
uexit(1);
}
See Also
udrpprm, uaddusr, udrpusr, uaddath, udrpath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
181
uaddprv
Grant user authority or schema privileges
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddprv( txid, nrqstds, rqstdsl, statusl, status )
UTXID txid;
int nrqstds;
UGRTDS rqstdsl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nrqstds
Number of privileges described in the rqstdsl list
rqstdsl
List of UGRTDS structures, each describing a separate privilege to
grant
statusl
Returned list of status values, one for each rqstdsl entry
status
Returned status of the function
Grants one or more of the following permissions:
DBA authority
SCHEMA authority
schema privileges to a schema
schema privileges to a table
schema privileges to a column
DBA authority allows a user to create, drop, access, and modify any object in the
database. SCHEMA authority, however, allows a user to create and drop schemas and
objects within those schemas only. Both of these privileges are granted to users only.
182
Schema privileges are privileges granted to a schema. The privileges specify access
to all objects in another schema or a table or column within the schema.
For each set of privileges you want to grant with this function, you must first describe
the privileges by initializing the UGRTDS structure. For a description of the UGRTDS
structure, see page 120.
If a schema grants schema privileges to another schema, all tables in the schema
granting the privilege are accessible. If a schema grants schema privileges to a table,
only the specified table is accessible.
To revoke user or schema privileges, use the udrpprv function.
Security
To grant DBA or SCHEMA authority, you must have DBA authority.
To grant schema privileges to a schema, you must make current the schema that is
granting the privileges.
To grant schema privileges to a table or column, you must make the schema that
contains the table or column to receive the privileges the current schema.
To make a schema current, use the ufchath function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uaddprv function to grant select and insert privileges on the
company table to the admin schema:
/* define required parameters */
UTXID txid;
USATUS status;
/* Retrieve authorization ID (aid) for admin schema */
...
/* Retrieve table ID for company table (tidl) in SQL_books schema */
...
/* Initialize UGRTDS structure elements */
rqstdsl.gte.aid = aid;
rqstdsl.rqstcaps = UTSEL | UTINS;
rqstdsl.obj.objid = tidl.tid;
rqstdsl.obj.objknd = UTBLKND;
/* Grant privileges */
if ( uaddprv(txid, 1, &rqstdsl, statusl, &status) != USUCCESS)
printf(”Unable to grant privileges: status = %ld\n”,status);
183
See Also
uaddath, uaddprm, udrpath, udrpprm, udrpprv
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
184
uaddtbl
Add a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uaddtbl( txid, ntbl, dbtable, statusl, status )
UTXID txid;
int ntbl;
DBTABLE *dbtable;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ntbl
Number of tables described in the dbtable list
dbtable
List of DBTABLE structures, each describing a separate table to add
statusl
Returned list of status values, one for each dbtable entry
status
Returned status of the function
Validates the table described in each DBTABLE structure, pointed to by dbtable, and
add the table to the database.
For a description of the DBTABLE structure, see page 92.
If the add operation is successful, this function returns a table ID (into DBTABLE
member tid) for each added table in the dbtable list.
Storage space for rows within the added table are allocated either on the default
volume or on the preferred volume specified by DBTABLE member vid.
The order of the columns added to the table is undefined. The column order returned
from the uinftbl routine may differ from the order specified in the DBCOL list
(contained in the DBTABLE structure).
185
Security
To add a table to a schema, you schema where you want the table to reside must be
the current schema, and you must have one of the following authority levels:
DBA authority
SCHEMA authority
To specify a volume for a table (the vid member in the DBTABLE structure), you
must have DBA authority.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddtbl function to add a table.
ncol = 2;
/* number of DBCOL column entries */
dbcol[0].coltyp = U_HINT;
/* column type */
dbcol[0].collen = ULD_HINT;
/* column format precision */
dbcol[0].colscl = 0;
/* column format scale */
dbcol[0].dsplen = UDL_HINT;
/* column display precision */
dbcol[0].dspscl = 0;
/* column display scale */
dbcol[0].colopts = DB_NORMAL;
/* column processing options */
dbcol[0].colnm = ”part_number”; /* column name */
dbcol[0].coldesc = ”part number”; /* column description */
dbcol[0].dsppict = ””;
/* column display picture clause */
dbcol[1].coltyp = U_STR;
dbcol[1].collen = UDL_STR;
dbcol[1].colscl = 0;
dbcol[1].dsplen = UDL_HINT;
dbcol[1].dspscl = 0;
dbcol[1].colopts = DB_NORMAL;
dbcol[1].colnm = ”part_name”;
dbcol[1].coldesc = ”part name”;
dbcol[1].dsppict = ””;
/*
ntbl = 1;
186
/* column type */
/* column display length */
/* column format scale */
/* column display precision */
/* column display scale */
/* column processing options */
/* column name */
/* column description */
column display picture clause */
dbtable[0].dbcol = dbcol;
/* array of column information */
dbtable[0].vid = UNULLVID;
/* initial pence volume */
dbtable[0].expnum = 10000L;
/* expected number of rows */
dbtable[0].statusl = statusl; /* array of column status codes */
dbtable[0].tblopts = DB_NORMAL; /* table processing options */
dbtable[0].ncol = ncol;
/* # of columns in ’dbcol’ */
dbtable[0].tblnm = ”parts index”; /* table name */
dbtable[0].tbldesc = ”part index”; /* table description */
/* Add the tables */
if (uaddtbl(txid, ntbl, dbtable, statusl, &status) != USUCCESS)
{
fprintf(stderr,”Unable to create new table: %ld\n”, status);
for ( i = 0; i < ntbl; ++i )
for ( j = 0; j < dbtable[i].ncol; ++j )
printf(”Table %d column %d status: %ld\n”,
i, j, dbtable[i].statusl[j]);
uexit(1);
}
See also Appendix A for more examples.
See Also
udrptbl, uinftbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
187
uaddtnm
Add a table name (or synonym)
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddtnm( txid, ntbl, dbtblnm, statusl, status )
UTXID txid;
int ntbl;
DBTBLNM *dbtblnm;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ntbl
Number of table names in the dbtblnm list
dbtblnm
List of DBTBLNM structures, each describing a separate table name
to add
statusl
Returned list of status values, one for each dbcolnm entry
status
Returned status of the function
Adds an alternate name (or synonym) for the table specified by a DBTBLNM
structure.
Synonyms for a table can be used to reference (and bind to) the same table. This
feature is useful in applications where you need to reference the same table by
different names.
Each DBTBLNM structure in the dbcolnm list contains the table ID and for the table
and the alternate table name. For a description of the DBTBLNM structure, see page
99.
Table names must be unique within a schema.
188
Security
To add a synonym to a table, the schema where the table resides must be current, and
you must have one of the following permissions.
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddtnm function to add a table synonym.
/* Initialize DBTBLNM structure */
dbtblnm.tid = $parts$;
dbtblnm.tblnm = “parts_data”;
if ( uaddtnm(txid, 1, &dbtblnm, statusl, &status) != USUCCESS)
printf(“Error naming table: status = %ld\n”, status);
if ( ubndtbl(txid, 1, &(dbtblnm.tblnm), USLCK, &tid, &status) != USUCCESS)
printf( “Error using new table name: status=%ld\n”,status);
See Also
udrptnm
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
189
uaddusr
Add a user to a database and set a user’s default schema
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddusr( txid, nuser, dbuser, statusl, status )
UTXID txid;
int nuser;
DBUSER *dbuser;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nuser
Number of users in the dbuser list
dbuser
List of DBUSER structures, each describing a separate user to add to
the database
statusl
Returned list of status values, one for each dbuser entry
status
Returned status of the function
Adds the users and user schema defaults described by the dbuser list and adds them
to the database.
Each DBUSER structure in the dbuser list contains information about a user’s name.
For a description of the DBUSER structure, see page 100.
Security
To add a user to a database (grant a user access permission), you must have DBA
authority. When a user is added to a database, the user is granted access to the
database and schema access permission to the PUBLIC schema.
190
To grant DBA and SCHEMA authority, use the uaddprv function. To grant schema
access permission to a schema, use the udrpprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uaddusr function to add two users to the database.
/* define required parameters */
UTXID
txid;
DBUSER * dbuser;
USTATUS statusl[2];
USTATUS status;
int
nuser;
/* Initialize DBUSER structure */
dbuser[0].usernm = ”rick”;
/* owner (login) name #0 */
dbuser[0].aid = UNULLAID;
/* Assume default schema */
dbuser[1].usernm = ”bill”;
/* owner (login) name #1 */
dbuser[1].aid = UNULLAID;
/* Assume default schema */
/* Add the users */
nuser = 2;
if (uaddusr(txid, nuser, dbuser, statusl, &status) != USUCCESS)
{
printf(”Unable to create new users: %ld\n”, status);
for ( i = 0; i < nuser; ++i )
printf(”Entry %d users %s status: %ld\n”,
i, dbuser[i].usernm, statusl[i]);
exit(1);
}
See Also
uaddprm, udrpprm, uaddath, udrpath, uadddb, udrpusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
191
uaddvol
Add a volume
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uaddvol( txid, nvol, dbvolm, statusl, status )
UTXID txid;
int nvol;
DBVOLM *dbvolm;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nvol
Number of volumes in the dbvolm list
dbvolm
List of DBVOLM structures, each describing a separate volume to
add to the database
statusl
Returned list of status values, one for each dbvolm entry
status
Returned status of the function
Adds a new, empty volume to an existing database.
Each DBVOLM structure in the dbvolm list contains information about a volume.
A volume ID is returned into the DBVOLM vid member, and can be used for future
reference to the volume.
For a description of the DBVOLM structure, see “The RHLI Structures.”
Security
To add a volume to a database you must have DBA authority.
To grant DBA authority, use the uaddprv function.
192
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uaddvol function to add a volume to a database.
int nvol;
USTATUS status;
DBVOLM dbvolm;
USTATUS statusl[1];
/* Initialize DBVOLM structure */
nvol = 1;
dbvolm.volfile = ”/dev/rdsk3”;
dbvolm.volopts = DB_DEVICE | DB_BIG;
dbvolm.voloff = 0;
dbvolm.vollen = 20480;
/* actual size is 41943040 bytes */
dbvolm.volpgsz = 2048;
/* 2k is only supported page size */
/* attempt to add volume */
if ( uaddvol(txid, nvol, &dbvolm, statusl, &status) != USUCCESS)
fprintf(stdout, ”Volume addition failed. status: %ld\n”,status);
See Also
umodvol, uaddtbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
193
ualcscn
Allocate a scan information structure
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ualcscn( txid, nsel, nsrt, ncol, scaninf, status )
UTXID txid;
int nsel;
int nsrt;
int ncol;
char **scaninf;
USTATUS *status;
Arguments
Description
txid
Transaction ID.
nsel
Optional; number of OR-groups in selection criteria; this value
represents the number of calls to the uinsor function.
nsrt
Optional; number of sort criteria.
ncol
Optional; number of columns in the projection for the scan.
scaninf
Returned pointer to a scan information structure.
status
Returned status of the function.
Allocates a scan information structure and returns a pointer for future scan
initialization calls.
Performance
If the scan is well defined when the ualcscn function is called, specifying the number
of OR-groups (nsel), sort criteria (nsrt), and projection columns (ncol) can greatly
speed up the scan specification process for complex selection criteria. If you do not
194
know the values for these parameters, specify 0. In this case, portions of the scan
structure are allocated by the uinsor, uinsand, uinssrt, and uinsprj functions.
If the numbers specified for nsel, nsrt, or ncol are larger than those actually used by
the scan, some user memory will be wasted. If the numbers are smaller, calls to the
functions will cause portions of the scan structure to be reallocated. Choosing these
numbers is a tradeoff between user memory and the potential CPU overhead of
reallocating the structures.
When no longer needed, you must free the scan information structure’s memory
allocation by using the ufrescn function.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See appendix A.
See Also
uinsor, uinsand, uinssrt, uinsprj, ufrescn, ubegscn, uendscn, ufchscn
For information about scanning, see page 64.
195
ualctbl
Allocate a UNIPCOLL structure
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ualctbl( txid, ntbl, tidl, unipcol, statusl, status )
UTXID txid;
int ntbl;
UTID *tidl;
UNIPCOLL unipcol[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ntbl
Number of table IDs in the tidl list
tidl
An array of table IDs to allocate column data buffers for
unipcol
An array of UNIPCOLL structures that contain column data buffers
for each corresponding table in the tidl list
statusl
Returned list of status values, one for each tidl entry
status
Returned status of the function
Dynamically allocates the members of a UNIPCOLL structure for columns of each
table listed in the tidl list. When you no longer need the UNIPCOLL structure, you
must free each column buffer and the dbval and cidl structures. When freeing a
dbvall member, be sure to free each data type.
Each UNIPCOLL structure in the tidl list contains information about columns for a
table.
196
If the ncol member of a UNIPCOLL structure is set to zero, you do not need to free
any structures.
For a description of the UNIPCOLL structure, see page 131.
Security
To allocate a UNIPCOLL structure, you must have access to all tables listed in tidl.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
To allocate a UNIPCOLL structure:
#define NTBL 3
/* define required parameters */
UTXID tx;
/* Transaction ID */
int ntbl;
/* # tables listed in tidl */
UTID tidl[NTBL];
/* list of Table IDs */
UNIPCOLL unipcol[NTBL]; /* list of column list info */
USTATUS statusl[NTBL]; /* table status list */
USTATUS status;
/* function status buffer */
/* automatically generate a column list */
ntbl = NTBL;
tidl[0] = $PUBLIC.manf$;
tidl[1] = $PUBLIC.item$;
tidl[2] = $PUBLIC.taxes$;
if (ualctbl(tx, ntbl, tidl, unipcol, statusl, &status) != USUCCESS)
{
printf(“Error allocating UNIPCOLL structure: %ld”, status);
uexit(1);
}
197
To deallocate the allocated UNIPCOLL structure:
/* use existing unipcol values */
int tblidx;
UNIPCOLL * unipcolp;
int colidx;
char * charptr;
for ( tblidx = 0 ; tblidx < ntbl ; ++tblidx )
{
unipcolp = &unipcol[tblidx];
for ( colidx = 0; colidx < unipcolp–>ncol ; ++colidx )
free(unipcolp–>dbvall[colidx].unip.strp);
free((char *)unipcolp–>dbvall);
free((char *)unipcolp–>cidl);
}
See Also
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
198
uallath
Get a list of authorization IDs (schemas)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uallath( txid, lcktype, nauth, aidl, status )
UTXID txid;
int lcktype;
int *nauth;
UAID **aidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
lcktype
Lock type to place on the retrieved authorization IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nauth
Number of authorization IDs returned into aidl
aidl
Returned list of authorization IDs
status
Returned status of the function
Locks and retrieves the authorization IDs for all schemas in the current database.
Locking an authorization ID preserves the integrity of the definition for the associated
schema while the lock is held.
Authorization IDs returned (into aidl) are only valid within the scope of a single
transaction.
Unify DataServer allocates storage for the returned list of authorization IDs (aidl) by
calling the malloc function. After you have retrieved the authorization IDs, you must
recover this storage space by calling the free function.
199
If the number of authorization IDs (nauth) returned is zero (0), the malloc function
was not performed by Unify DataServer and you do not need to call the free function.
Security
Authorization IDs are returned only for schemas you have access to.
You always have access to the current schema. Additionally, you can access other
schemas if you have been granted schema access permission to the schema or if a
schema you can access has schema privileges to another schema (or a table or column
in the schema). If you have DBA authority, you can access any schema in the
database.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function. To grant schema access permission, use the
uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uallath function to retrieve a list of authorization IDs.
/* define required parameters */
UAID * aidl;
int
nauth;
/* Retrieve authorization IDs into aidl*/
if ( uallath(txid, USLCK, &nauth, &aidl, &status) != USUCCESS )
printf(”Unable to get all Auth. IDs: status = %ld\n”,status);
/* free space used for aidl */
if ( nauth > 0 )
free((UAID *)aidl);
See Also
uaddath, ubndath, udrpath, ufchath, uinfath, umodath
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
200
uallbt
Get a list of B-tree IDs
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uallbt( txid, tid, lcktype, nbt, bidl, status )
UTXID txid;
UTID tid;
int lcktype;
int *nbt;
UBTID **bidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table containing the B-trees or UNULLTID
lcktype
Lock type to place on the retrieved B-tree IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nbt
Number of B-tree IDs returned into bidl
bidl
Returned list of B-tree IDs
status
Returned status of the function
Locks and retrieves a list of all B-tree IDs for the specified table. If tid is set to
UNULLTID, B-tree IDs are returned for all tables in the database you have access to.
Locking a B-tree ID preserves the integrity of the definition for the B-tree while the
lock is held.
B-tree IDs returned are valid within the scope of a single transaction only.
201
Unify DataServer allocates storage for the returned list of B-tree IDs (bidl) by calling
the malloc function. After you have retrieved the B-tree IDs, you must recover this
storage space by calling the free function.
If the number of B-tree IDs (nbt) returned is zero (0), the malloc function was not
performed by Unify DataServer and you do not need to call the free function.
Security
B-tree IDs are returned only for B-trees in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uallbt function to retrieve a list of B-tree IDs.
UBTID * bidl;
statusl = (USTATUS *)calloc(1, sizeof(USTATUS));
if ( uallbt(txid, UNULLTID, UNULLLCK, &nbt, &bidl, &status) != USUCCESS)
printf(”Unable to get all B-tree ID info: status = %ld\n”,status);
if ( nbt > 0 )
free((UBTID *)bidl);
See Also
ubndbt, ufchath, uinfbt, umodbt, uaddbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using B-trees, see “Choosing an Access Method” and
“Managing the Database Files” in Unify DataServer: Managing a Database.
202
uallcgp
Get a list of column group IDs
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uallcgp( txid, tid, lcktype, ngrp, cidl, status )
UTXID txid;
UTID tid;
int lcktype;
int *ngrp;
UCID *cidl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table containing the column groups or UNULLTID
lcktype
Lock type to place on the retrieved column group IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
ngrp
Number of column group IDs returned into cidl
cidl
Returned list of column group IDs
status
Returned status of the function
Locks and retrieves a list of all column group IDs for the specified table.
If tid is set to UNULLTID, column group IDs are returned for all tables in the
database that you have access to.
203
Locking a column group ID preserves the integrity of the definition for the column
group while the lock is held.
Column group IDs returned are valid within the scope of a single transaction only.
Unify DataServer allocates storage for the returned list of column group IDs (cidl) by
calling the malloc function. After you have retrieved the column group IDs, you must
recover this storage space by calling the free function.
If the number of column group IDs (ngrp) returned is zero (0), the malloc function
was not performed by Unify DataServer and you do not need to call the free function.
Security
Column group IDs are returned only for column groups in tables that you have access
to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uallcgp function to retrieve a list of column group IDs.
UTXID tx;
UTID tid;
/* Transaction ID
*/
/* Table ID the col group belongs to
/* (or NULLTID) */
int lcktype;/* requested lock type */
int ngrp;
/* # col groups returned in cidl
*/
UCID * cidl;
/* list of all Column Group IDs
USTATUS status; /* returned status */
int indx;
/* temp index variable */
/* attempt to retrieve all column groups for table ’customer’ */
204
*/
*/
tid = $customer.$
if (uallcgp(txid, tid, lcktype, &ngrp, &cidl, &status) != USUCCESS)
{
printf(”Unable to get all column Group ID info: status = %ld\n”,status);
uexit(99);
}
printf(”%d column groups found\n”, ngrp);
for ( indx = 0; indx < ngrp; ++indx )
printf(”column Group ID: %ld\n”, cidl[indx]);
if ( ngrp > 0 )
free((UCID *)cidl);
See Also
uaddcgp, udrpcgp, ufchath, uinfcgp, unumcgp
malloc(3) and free(3) in your UNIX system manual.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
205
uallcol
Get a list of column IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uallcol( txid, tid, lcktype, ncol, cidl, status )
UTXID txid;
UTID tid;
int lcktype;
int *ncol;
UCID **cidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table containing the columns or UNULLTID
lcktype
Lock type to place on the retrieved column IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
ncol
Number of column IDs returned into cidl
cidl
Returned list of column IDs
status
Returned status of the function
Locks and retrieves a list of all column IDs for the specified table.
If tid is set to UNULLTID, column IDs are returned for all tables in the database that
you have access to.
Locking a column ID preserves the integrity of the definition for the column while
the lock is held.
206
Column IDs returned (into cidl) are valid only within the scope of a single
transaction.
Unify DataServer allocates storage for the returned list of column IDs (cidl) by
calling the malloc function. After you have retrieved the column IDs, you must
recover this storage space by calling the free function.
If the number of column IDs (ncol) returned is zero (0), the malloc function was not
performed by Unify DataServer and you do not need to call the free function.
Security
Column IDs are returned only for columns in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA and SCHEMA
authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uallcol function to retrieve a list of column IDs.
UCID * cidl;
if ( uallcol(txid, tid, lcktype, &ncol, &cidl, &status) != USUCCESS )
printf(”Unable to get all Column ID info: status = %ld\n”,status);
if ( ncol > 0 )
free((UCID *)cidl);
See Also
ualltbl, ubndcol, uaddcnm, udrpcnm, uaddtnm, udrptnm, ufchath, uinfcol,
uinftbl
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
207
uallhsh
Get a list of hash table IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uallhsh( txid, tid, lcktype, nhsh, hidl, status )
UTXID txid;
UTID tid;
int lcktype;
int *nhsh;
UHID **hidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table containing the hash tables or UNULLTID
lcktype
Lock type to place on the retrieved hash table IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nhsh
Number of hash table IDs returned into hidl
hidl
Returned list of hash table IDs
status
Returned status of the function
Locks and retrieves a list of all hash table IDs for the specified table.
If tid is set to UNULLTID, hash table IDs are returned for all tables in the database
you have access to.
Locking a hash table ID preserves the integrity of the definition for the hash table
while the lock is held.
Hash table IDs returned (into hidl) are only valid within the scope of a single
transaction.
208
Unify DataServer allocates storage for the returned list of hash table IDs (hidl) by
calling the malloc function. After you have retrieved the hash table IDs, you must
recover this storage space calling the free function.
If the number of hash table IDs (nhsh) returned is zero (0), the malloc function was
not performed by Unify DataServer and you do not need to call the free function.
Security
Hash table IDs are returned only for hash indexes in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This examples uses the uallhsh function to retrieve a list of hash table IDs.
UHID * hidl;
if (uallhsh(txid, tid, lcktype, &nhsh, &hidl, &status) != USUCCESS)
printf(”Unable to get all Hash Table info; status = %ld\n”, status);
if ( nhsh > 0 )
free((UHID *)hidl);
See Also
ubndhsh, uaddhsh, udrphsh, umodhsh, ufchath, uinfhsh
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using hash tables, see “Choosing an Access Method” and
“Tuning the Access Methods” in Unify DataServer: Managing a Database.
209
ualllnk
Get a list of link IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ualllnk( txid, tid, lcktype, nlid, lidl, status )
UTXID txid;
UTID tid;
int lcktype;
int *nlid;
ULID **lidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table containing the links or UNULLTID
lcktype
Lock type to place on the retrieved link IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nlid
Number of link IDs returned into lidl
lidl
Returned list of link IDs
status
Returned status of the function
Locks and retrieves a list of link IDs for the specified table. If tid is set to
UNULLTID, link IDs are returned for all tables in the database you have access to.
Locking a link ID preserves the integrity of the definition for the link while the lock
is held.
Link IDs returned (into lidl) are valid only in the scope of a single transaction.
210
Unify DataServer allocates storage for the returned list of link IDs (lidl) by calling the
malloc function. After you have retrieved the link IDs, you must recover this storage
space by calling the free function.
If the number of link IDs (nlid) returned is zero (0), a malloc was not performed by
Unify DataServer and you do not need to call the free function.
Security
Link IDs are returned only for links in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ualllnk function to retrieve a list of link index IDs.
ULID * lidl;
if (ualllnk(txid, tid, lcktype, &nlid, &lidl, &status) != USUCCESS)
printf(“Can’t get all Link ID info: status = %ld\n”,status);
if ( nlid > 0 )
free((ULID *)lidl);
See Also
ubndlnk, uaddlnk, udrplnk, umodlnk, ufchath, uinflnk
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
211
uallpid
Get a list of process IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uallpid( dbid, npid, pidl, status )
UDBID dbid;
int *npid;
UPROCID **pidl;
USTATUS *status;
Arguments
Description
dbid
Database ID of the database associated with the process IDs
npid
Number of process IDs returned into pidl
pidl
Returned list of process IDs
status
Returned status of the function
Retrieves the set of all process IDs of processes registered with the database.
A process is registered with the database when the database is opened, and
deregistered when the database is closed.
Unify DataServer allocates storage for the returned list of process IDs (pidl) by
calling the malloc function. After you have retrieved the process IDs, you must
recover this storage space by calling the free function.
If the number of process IDs (npid) returned is zero (0), the malloc function was not
performed by Unify DataServer and you do not need to call the free function.
Security
If you have DBA authority, you can retrieve all active process IDs. If you don’t have
DBA authority, you can retrieve your process ID only.
212
To grant DBA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uallpid function to retrieve the list of process IDs.
/* define require parameters */
UDBID
dbid;
int
npid;
UPROCID * pidl;
USTATUS status;
/* Open the database */
...
/* Retrieve process IDs */
if (uallpid(dbid, &npid, &pidl, &status) != USUCCESS)
fprintf(stderr,”Unable to get Process IDs: status = %ld\n”, status);
...
/ * free space allocated for pidl */
if ( npid > 0 )
free((char *) pidl);
See Also
ualltx, uinftx
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
213
ualltbl
Get a list of table IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ualltbl( txid, aid, lcktype, ntbl, tidl, status )
UTXID txid;
UAID aid;
int lcktype;
int *ntbl;
UTID **tidl;
USTATUS *status;
Arguments
txid
Transaction ID
aid
Authorization ID of the schema that contains the tables or
UNULLAID
lcktype
Description
Lock type to place on the retrieved table IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
ntbl
Number of table IDs returned into tidl
tidl
Returned list of table IDs
status
Returned status of the function
Locks and retrieves a list of table IDs.
If aid is set to UNULLAID, table IDs are returned for all schemas in the database you
have access to.
Locking a table ID preserves the integrity of the definition for the table while the lock
is held.
214
Table IDs returned (into tidl) are valid only in the scope of a single transaction.
Unify DataServer allocates storage for the returned list of table IDs (tidl) by calling
the malloc function. After you have retrieved the table IDs, you must recover this
storage space by calling the free function.
If the number of table IDs (ntbl) returned is zero (0), the malloc function was not
called by Unify DataServer and you do not need to call the free function.
Security
Table IDs are returned only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ualltbl function to retrieve a list of table IDs.
UTID * tidl;
aid = UNULLAID;
if (ualltbl(txid, aid, lcktype, &ntbl, &tidl, &status) != USUCCESS )
fprintf(stderr,”Unable to get all Table ID info: status = %ld\n”,status);
if ( ntbl > 0 )
free((UTID *)tidl);
See Also
uallcol, ubndtbl, uinftbl, uinfcol, uaddtnm, udrptnm, ufchath, ufchtnm
malloc(3) and free(3) in your UNIX system manual.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
215
ualltx
Get a list of transaction IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ualltx( dbid, pid, ntx, txidl, status )
UDBID dbid;
UPROCID pid;
int *ntx;
UTXID **txidl;
USTATUS *status;
Arguments
Description
dbid
Database ID of database associated with the transaction IDs
pid
UNIX process ID for the current application (obtained from the UNIX
system call getpid) or UNULLPID
ntx
Number of transaction IDs returned into txidl
txidl
Returned list of transaction IDs
status
Returned status of the function
Retrieves the set of active transaction IDs for the specified process ID.
To specify active transactions for the current application, set pid to UNULLPID;
otherwise, set pid to a specific process ID. You can use the getpid UNIX function to
retrieve the process IDs.
Unify DataServer allocates storage for the returned list of transaction IDs (txidl) by
calling the malloc function. After you have retrieved the transaction IDs, you must
recover this storage space by calling the free function.
If the number of transaction IDs (ntx) returned is zero (0), the malloc function was
not called by Unify DataServer and you do not need to call the free function.
216
Security
If you have DBA authority you can set the process ID (pid) to any valid transaction
process ID for any application currently accessing the database.
If you don’t have DBA authority, transaction IDs can be returned only for transactions
that your application initiated.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uinftx, ubegtx
malloc(3), free(3), and getpid(2) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
217
uallusr
Get a list of user IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uallusr( txid, lcktype, nuser, uoidl, status )
UTXID txid;
int lcktype;
int *nuser;
UOID **uoidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
lcktype
Lock type to place on the retrieved user IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nuser
Number of user IDs returned into uoidl
uoidl
Returned list of user IDs
status
Returned status of the function
Locks and retrieves user IDs for all users who have access to the current database.
Locking a user ID preserves the integrity of the definition for the user while the lock
is held.
User IDs returned (into uoidl) are valid only in the scope of a single transaction.
Unify DataServer allocates storage for the returned list of user IDs (uoidl) by calling
the malloc function. After you have retrieved the user IDs, you must recover this
storage space by calling the free function.
218
If the number of user IDs (nuser) returned is zero (0), the malloc function was not
called by Unify DataServer and you do not need to call the free function.
Security
User IDs are returned as follows:
If you have DBA authority, all user IDs for the database are returned.
If you don’t have DBA authority, only your user ID is returned.
To grant DBA and SCHEMA authority, use the uaddprv function. To grant schema
access permission to a schema, use the udrpprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the uallusr function to retrieve the list of database users.
/ * define required parameters */
UOID
* uoidl;
UTXID
txid;
int
* nuser;
USTATUS status;
/* Retrieve user list (uoidl) */
if (uallusr(txid, USLCK, &nuser, &uoidl, &status) != USUCCESS)
fprintf(stderr,”Unable to get all User IDs: status = %ld\n”,status);
/* free space allocated by uoidl */
if ( nuser > 0 )
free((UOID *)uoidl);
See Also
uaddusr, ubndusr, udrpusr, uinfusr
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
219
uallvol
Get a list of volume IDs
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uallvol( txid, lcktype, nvol, vidl, status )
UTXID txid;
int lcktype;
int *nvol;
UVID **vidl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
lcktype
Lock type to place on the retrieved volume IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nvol
Number of volume IDs returned into vidl
vidl
Returned list of volume IDs
status
Returned status of the function
Locks and retrieves the volume IDs for all volumes registered in the current database.
Locking a volume ID preserves the integrity of the definition for the volume while
the lock is held.
Volume IDs returned (into vidl) are valid only in the scope of a single transaction.
Unify DataServer allocates storage for the returned list of volume IDs (vidl) by
calling the malloc function. After you have retrieved the volume IDs, you must
recover this storage space by calling the free function.
220
If the number of volume IDs (nvol) returned is zero (0), the malloc function was not
called by Unify DataServer and you do not need to call the free function.
Security
To get a list of all volume IDs defined for the current database, you must have DBA
authority.
To grant DBA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uallvol function to retrieve a list of volume IDs.
UVID * vidl;
if (uallvol(txid, USLCK, &nvol, &vidl, &status) != USUCCESS)
fprintf(stderr,”Unable to get all Volume IDs: status = %ld\n”,status);
if ( nvol > 0 )
free((UVID *)vidl);
See Also
uaddvol, ubndvol, udrpvol, ufchath, uinfvol
malloc(3) and free(3) in your UNIX system manual.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
221
ubegord
Begin an ordered access
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ubegord (txid, tid, ncol, uoacols, oaccid, statusl, status)
UTXID txid;
UTID tid;
int ncol;
UOACOLS *uoacols;
UOACCID *oaccid;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the target table for the ordered access
ncol
Number of columns in the uoacols list
uoacols
List of UOACOLS structures, each describing a column comprising
the order
oaccid
Pointer to returned ordered access ID
statusl
Returned status value for each column listed in the oaccid field of
each UOACOLS structure
status
Returned status of the function
Sets up the specified table for ordered access.
The table’s rows are set up for access in ascending or descending order on a set of
columns as specified by the column order list (uoacols).
222
Currently, the specified order must be supported by an underlying B-tree or direct
key. For B-trees, its key columns must match or exceed that specified by the column
order list. That is, the column order list can specify a subset of an actual B-tree index
key as long as the leading columns match. The B-tree index is not opened at this
time. It is opened the first time it is accessed by a ufchord, uposord, or uskrord
function call.
The order specified by UOACOLS can be in either the same or opposite order of that
of the underlying access method. If it is in the opposite order then the B-tree or direct
key is traversed in reverse order.
The returned ordered access ID is specified in future references to the ordered access.
Rows are retrieved from the ordered access with the ufchord function.
The current position is set to just before the first row of the order. The current
position within an ordered access on a table can be changed with the ufchord,
uposord, or uskrord function.
When the ordered access is no longer needed, the uendord function closes the
ordered access and frees up the resources (such as memory) held by the ordered
access.
If the transaction ends before the uendord function is called, the ordered access is
automatically closed, unless the USCAN option is specified to the ucbgtx function.
Security
To begin an ordered access, you must be able to access the table.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, see the ufchath function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
223
Example
See Appendix A.
See Also
uendord, ufchord, uposord
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
224
ubegscn
Begin a scan
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubegscn( txid, lcktype, scaninf, scanid, status )
UTXID txid;
int lcktype;
char *scaninf;
int *scanid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
lcktype
Lock type to place on the scanned rows. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
scaninf
Pointer to a scan information structure
scanid
Pointer to returned scan ID
status
Returned status of the function
Given a fully specified scan, the ubegscn function optimizes the scan information
(contained in scaninf) and returns a scan ID (into scanid).
The returned scan ID can be used for future references to the scan.
Activities that should occur before beginning a scan include:
Allocation of a scan information structure (ualcscn)
Establishing the target table (uinstbl)
Specifying the scan selection criteria (uinsor, uinsand, uinsprj)
Specifying the scan sort criteria (uinssrt)
225
Rows are retrieved from the scan with the ufchscn function.
When the scan is complete, the uendscn function is used to close the scan and free up
the resources (such as memory) held by the scan.
If the transaction ends before the uendscn function is called, the scan is closed.
Security
To begin a scan, one of the following conditions must be true:
You have DBA authority.
The target table is in the current schema.
You have SELECT schema privilege on the target table.
You have SELECT schema privilege on all columns projected from the table.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ualcscn, uendscn, ufchscn, ufrescn, uinsand, uinsor, uinsprj, uinssrt, uinstbl
For information about scanning, see page 64.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
226
ubegtx
Begin a transaction
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubegtx( dbid, prtx, txid, txopt, status )
UDBID dbid;
UTXID prtx;
UTXID *txid;
UTXOPT *txopt;
USTATUS *status;
Arguments
Description
dbid
Database ID (issued by the uopndb function)
prtx
Must be set to UROOTTXID
txid
Returned unique transaction ID issued to the current transaction
txopt
Pointer to UTXOPT structure that describes the new transaction’s
options
status
Returned status of the function
Begins a new transaction and returns a unique transaction ID. The transaction ID is
used in subsequent function calls.
To begin a transaction with this function, a UTXOPT structure (pointed to by txopt)
must first be initialized. The UTXOPT structure describes the new transaction. For a
complete description of the UTXOPT structure, see page 152.
Data definition (DDL) and data manipulation (DML) operations cannot occur in the
same transaction. Use separate transactions for DDL and DML operations.
To commit one transaction and begin another, use the ucbgtx function.
227
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ucbgtx, ucmttx, ualltx, ubegtx, uinftx
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
228
ubndath
Bind a schema name to an authorization ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndath( txid, nauth, authnml, lcktype, aidl, statusl, status )
UTXID txid;
int nauth;
char * authnml[];
int lcktype;
UAID aidl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nauth
Number of schema names in the authnml list
authnml
List of schema names
lcktype
Lock type to place on the retrieved authorization IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
aidl
Returned list of authorization IDs
statusl
Returned list of status values, one for each aidl entry
status
Returned status of the function
Locks and retrieves an authorization ID for each schema name specified in authnml.
Locking an authorization ID preserves the integrity of the name binding while the
lock is held. Also see “Transaction Types” on page 62 of this manual.
229
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the schemas you are binding to.
Therefore, there is no guarantee that the schemas you bound to will be the same or
even exist by the time you commit the transaction.
Security
To bind a schema name to an authorization ID you must have one of the following
permissions:
DBA authority (any authorization ID can be returned)
Schema access to the schema
Access to a schema with a privilege granted on one of the following:
– the schema itself (DELETE, INSERT, SELECT, or UPDATE)
– a table within the schema (DELETE, INSERT, SELECT, or UPDATE)
– a column within the schema (INSERT, SELECT, or UPDATE)
To grant DBA authority and schema privileges, use the uaddprv function. To grant
access permission to a schema, use the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uaddath, uallath, udrpath, uinfath, umodath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
230
ubndbt
Bind a B-tree name to a B-tree ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndbt( txid, tid, nbt, btnml, lcktype, bidl, statusl, status )
UTXID txid;
UTID tid;
int nbt;
char *btnml[];
int lcktype;
UBTID *bidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table the B-tree is defined for or UNULLTID
nbt
The number of B-tree names in the btnml list
btnml
List of B-tree names
lcktype
Lock type to place on the retrieved B-tree IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
bidl
Returned list of nbt B-tree IDs
statusl
Returned list of status values, one for each btnml/bidl entry
status
Returned status of the function
Locks and retrieves a B-tree ID for each B-tree name specified in btnml.
Locking a B-tree ID preserves the integrity of the name binding while the lock is
held.
231
If the table value (tid) is specified as UNULLTID, all tables in the current schema is
assumed.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the B-trees you are binding to.
Therefore, there is no guarantee that the B-trees you bind to will be the same or even
exist by the time you commit the transaction.
Security
To bind a B-tree name to a B-tree ID one of the following must be true:
You have DBA authority (any B-tree ID can be returned).
The B-tree is in the current schema.
The current schema has been granted one of the following schema privileges:
– DELETE, INSERT, SELECT or UPDATE privilege for the schema that
contains the B-tree.
– DELETE, INSERT, SELECT or UPDATE privilege for the table that contains
the B-tree.
– INSERT, SELECT or UPDATE privilege for all the columns that comprise
the B-tree definition.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Example
See Appendix A.
See Also
ualllnk, ubndlnk, uaddlnk, udrplnk, umodlnk, uinflnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
232
ubndcol
Bind a column name to a column ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndcol( txid, tid, ncol, colnml, lcktype, cidl, statusl, status )
UTXID txid;
UTID tid;
int ncol;
char *colnml[];
int lcktype;
UCID *cidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
The table ID of table containing the columns, or, UNULLTID
ncol
The number of column names in the colnml list
colnml
List of column names
lcktype
Lock type to place on the retrieved column IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
cidl
Returned list of ncol column IDs
statusl
Returned list of status values, one for each colnml/cidl entry
status
Returned status of the function
Locks and retrieves a column ID for each column name specified in colnml.
Locking a column ID preserves the integrity of the name binding while the lock is
held.
233
If the table value (tid) is specified as UNULLTID, all tables in the current schema is
assumed.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the columns you are binding to.
Therefore, there is no guarantee that the columns you bound to will be the same or
even exist by the time you commit the transaction.
Security
To bind a column name to a column ID one of the following must be true:
You have DBA authority (any column ID can be returned).
The column is in the current schema.
The current schema has been granted one of the following schema privileges:
– DELETE, INSERT, SELECT or UPDATE privilege for the schema that
contains the column.
– DELETE, INSERT, SELECT or UPDATE privilege for the table that contains
the column.
– INSERT, SELECT or UPDATE privilege for the column.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function. To grant schema access permission, use
the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddcgp, uaddcnm, uallcol, udrpcgp, udrpcnm, ufchcnm, uinfcol, umapcol,
unumcol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
234
ubnddb
Bind a database name to a database ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubnddb( txid, dbname, lcktype, dbid, status )
UTXID txid;
char *dbname;
int lcktype;
UDBID *dbid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
dbname
A database name
lcktype
Lock type to place on the retrieved database ID. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
dbid
Returned database ID
status
Returned status of the function
Locks and retrieves a database ID for the database specified in dbname.
Locking a database preserves the integrity of the name binding while the lock is held.
Binding to a database name does not open or reopen the database.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the database you are binding to.
Therefore, there is no guarantee that the database you bound to (and are currently
accessing) will have the same design or layout when you commit the transaction.
235
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uadddb, uclsdb, uinfdb, uopndb
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
236
ubndhsh
Bind a hash table name to a hash table ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndhsh( txid, tid, nhsh, hshnml, lcktype, hidl, statusl, status )
UTXID txid;
UTID tid;
int nhsh;
char *hshnml[];
int lcktype;
UHID *hidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table the hash table is defined for or UNULLTID
nhsh
Number of hash table names in the hshnml list
hshnml
List of hash table names
lcktype
Lock type to place on the retrieved hash table IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
hidl
Returned list of nhsh hash table IDs
statusl
Returned list of status values, one for each hshnml entry
status
Returned status of the function
Locks and retrieves a hash table ID for each hash table name specified in hshnml.
Locking a hash table ID preserves the integrity of the name binding while the lock is
held.
If the table value (tid) is specified as UNULLTID, all tables in the current schema is
assumed.
237
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the hash tables you are binding to.
Therefore, there is no guarantee that the hash tables you bound to will be the same or
even exist by the time you commit the transaction.
Security
To bind a hash table name to a hash table ID one of the following must be true:
You have DBA authority: any hash table ID can be returned.
The hash table is in the current schema.
The current schema has been granted one of the following schema privileges:
– DELETE, INSERT, SELECT or UPDATE privilege for the schema that
contains the hash table.
– DELETE, INSERT, SELECT or UPDATE privilege for the table that contains
the hash table.
– INSERT, SELECT or UPDATE privilege for all the columns that comprise
the hash table definition.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddhsh, uaddprm, uallhsh, udrphsh, uaddprv, uinfhsh, umaphsh, umodhsh
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
For information about using hash tables, see “Managing the Database Files,”
“Choosing an Access Method,” and “Tuning the Access Methods” in Unify
DataServer: Managing a Database.
238
ubndlnk
Bind a link name to a link ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndlnk( txid, tid, nlnk, lnknml, lcktype, lidl, statusl, status )
UTXID txid;
UTID tid;
int nlnk;
char *lnknml[];
int lcktype;
ULID *lidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table the links are defined for or UNULLTID
nlnk
The number of link names in the lnknml list
lnknml
List of link names
lcktype
Lock type to place on the retrieved link IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
lidl
Returned list of nlnk link IDs
statusl
Returned list of status values, one for each lnknml/lidl entry
status
Returned status of the function
Locks and retrieves a link ID for each link name specified in lnknml. Locking a link
ID preserves the integrity of the name binding while the lock is held.
If the table value (tid) is specified as UNULLTID, all tables in the current schema is
assumed.
239
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the links you are binding to.
Therefore, there is no guarantee that the links you bound to will be the same or even
exist by the time you commit the transaction.
Security
To bind a link name to a link ID one of the following must be true:
You have DBA authority: any link ID can be returned.
Both tables are in the current schema.
Access to a schema with a privilege granted on one of the following:
– DELETE, INSERT, SELECT or UPDATE privilege for the schemas that
contain the linked tables.
– DELETE, INSERT, SELECT or UPDATE privilege for the tables that contain
columns comprising the link definition.
– INSERT, SELECT or UPDATE privilege for all the columns that comprise
the link definition.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
ualllnk, ubndlnk, uaddlnk, udrplnk, umodlnk, uinflnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
For information about using links, see “Choosing an Access Method in Unify
DataServer: Managing a Database.
240
ubndtbl
Bind a table name to a table ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndtbl( txid, aid, ntbl, tblnml, lcktype, tidl, statusl, status )
UTXID txid;
UAID aid;
int ntbl;
char* tblnml[];
int lcktype;
UTID *tidl;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
Transaction ID
aid
The authorization ID of the schema containing the table IDs or
UNULLAID
Description
ntbl
Number of table names in the tblnml list
tblnml
List of table names
lcktype
Lock type to place on the retrieved table IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
tidl
Returned list of ntbl table IDs
statusl
Returned list of status values, one for each tblnml entry
status
Returned status of the function
Locks and retrieves a table ID for each table name specified in tblnml.
The authorization ID (aid) specifies the schema that contains the table. If aid is
specified as UNULLAID, the tables contained in the user’s current schema are used.
241
If a table name (specified in tblnml) contains a prefixed schema name, the schema
specified by aid is overridden.
Locking a table ID preserves the integrity of the name binding while the lock is held.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the tables you are binding to.
Therefore, there is no guarantee that the tables you bound to will be the same or even
exist by the time you commit the transaction.
Security
To bind a table name to a table ID one of the following must be true:
DBA authority: any table ID can be returned.
The table is in the current schema.
Access to a schema with a privilege granted on one of the following:
– DELETE, INSERT, SELECT, or UPDATE privilege for the schema that
contains the table.
– DELETE, INSERT, SELECT, or UPDATE privilege for the table itself.
– INSERT, SELECT, or UPDATE privilege for a column in the table.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ualltbl, ubndcol, uinftbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
242
ubndusr
Bind a user name to a user ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndusr( txid, nuser, usernml, lcktype, uoidl, statusl, status )
UTXID txid;
int nuser;
char *usernml[];
int lcktype;
UOID *uoidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nuser
Number of user names in the usernml list
usernml
List of user names
lcktype
Lock type to place on the retrieved user IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
uoidl
Returned list of user IDs
statusl
Returned list of status values, one for each usernml/uoidl entry
status
Returned status of the function
Locks and retrieves a user ID for each user name specified in usernml. Locking a user
ID preserves the integrity of the name binding while the lock is held.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the users you are binding to.
Therefore, there is no guarantee that the users you bound to will be the same or even
exist by the time you commit the transaction.
243
Security
To bind a user name to a user ID, one of the following conditions occur:
If you have DBA authority, you can specify any user name in usernml.
If you don’t have DBA authority, only your user ID can be returned.
To grant DBA authority, use the uaddprv function. To grant access to a database, use
the uaddusr function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddusr, uallusr, udrpusr, uinfusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
244
ubndvol
Bind a volume name to a volume ID
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ubndvol( txid, nvol, volnml, lcktype, vidl, statusl, status )
UTXID txid;
int nvol;
char* volnml[];
int lcktype;
UVID *vidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nvol
Number of volume names in the volnml list
volnml
List of volume names
lcktype
Lock type to place on the retrieved volume IDs. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
vidl
Returned list of volume IDs
statusl
Returned list of status values, one for each volnml/vidl entry
status
Returned status of the function
Locks and retrieves a volume ID for each volume name specified in volnml. Locking
a volume ID preserves the integrity of the name binding while the lock is held.
If you use a Type 0 transaction (which allows no locking) when performing
name-binding, no definition locks are placed on the volumes you are binding to.
Therefore, there is no guarantee that the volumes you bound to will be the same or
even exist by the time you commit the transaction.
245
Security
To bind a volume name to a volume ID, you must have DBA authority.
To grant DBA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddvol, uallvol, udrpvol, uinfvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database. Also see “Transaction Types” on
page 62 of this manual.
246
ucbgtx
Commit a transaction and begin a new transaction
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ucbgtx( prtx, txid, unlcktype, newtx, txopt, status )
UTXID prtx;
UTXID txid;
int unlcktype;
UTXID *newtx;
UTXOPT *txopt;
USTATUS *status;
Arguments
prtx
Must be set to UROOTTXID
txid
The transaction ID of the transaction that is being committed.
unlcktype
An unlock type for the committing transaction’s locks. The unlcktype
member options controls whether locks are released or inherited by
the new transaction, or scans are closed or inherited by the new
transaction. Options are:
URELEASE
Release all locks
UDEMOTE
Inherit all locks but demote exclusive locks to shared
locks
URETAIN
Inherit all locks without demoting exclusive locks to
shared locks
USCAN
Preserve scans and ordered accesses
When specifying USCAN, you must also specify either UDEMOTE
or URETAIN.
newtx
Returned unique transaction ID issued to the new transaction
txopt
Pointer to a UTXOPT structure that describes the new transaction’s
options
247
status
Description
Returned status of the function
Commits the current active transaction and begins another transaction against the
specified database.
To start a transaction with this function, the UTXOPT structure (pointed to by txopt)
must first be initialized. UTXOPT describes the new transaction.
For a complete description of the UTXOPT structure, see page 152.
Data definition (DDL) and data manipulation (DML) operations cannot use the same
transaction. Use separate transactions for DDL and DML operations.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
ubegtx, ucmttx, uinftx, uabttx, ualltx
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
248
uclritr
Clear a process interrupt
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uclritr( status )
USTATUS *status;
Arguments
status
Description
Allows processing to resume after an interrupt has been set by the usetitr function.
This function should not be called from a signal handler routine; instead, it should be
called from the main program.
Returned status of the function
All child processes are terminated at a point where the database is in a known
consistent state. Process interruption by any other mechanism may require database
recovery and is not recommended.
Before clearing an interrupt with the uclritr function, be sure that a database is open.
If the DB_NOEXIT option was specified when the current database was opened by
calling the uopndb function, all RHLI function calls and Embedded SQL/A
statements fail (with a status value of UEINTRPT) when an interrupt signal is
received by Unify DataServer until the signal is cleared with the uclritr function.
If the database is opened with Embedded SQL/A CONNECT or OPEN DATABASE
statements, DB_NOEXIT option is implicit.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
249
See Also
usetitr
signal(2) in your UNIX system manual
250
uclsdb
Close a database
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uclsdb( dbid, clsopts, status )
UDBID dbid;
UOPTS clsopts;
USTATUS *status;
Arguments
dbid
The database ID of the database you want to close
clsopts
The database close options. Valid options are:
DB_NORMAL Normal operation
DB_ABTTX
status
Description
Abort any active transactions
Returned status of the function
Closes a database opened by the uopndb function and deallocates all the dynamically
allocated memory obtained at the time of the open and during the database access.
If clsopts is specified as DB_NORMAL, this function fails if any transactions are still
active.
However, if the DB_ABTTX option is specified:
and transaction logging is on (the LOGTX configuration parameter is set to
TRUE), all active transactions are aborted before the database is closed.
However, if any transactions were started (by calling the ubegtx or ucbgtx
function) with the UCOMMIT option specified (see the UTXOPT structure
waitflg member), then only those transactions are committed.
and transaction logging is off (the LOGTX configuration variable is set to
FALSE), all active transactions are committed before the database is closed.
251
Before opening another database or ending an application program, any previously
opened database must be closed with a call to the uclsdb function.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uopndb
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
For information about transaction logging, see “Preventing Data Loss” in Unify
DataServer: Managing a Database.
252
uclsjrn
Close transaction journal file.
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uclsjrn (jrnfd, status)
int *jrnfd;
USTATUS *status;
Arguments
jrnfd
Pointer to a returned file descriptor for the opened journal file
status
Returned status of the function
Description
Closes a transaction journal file. All resources associated with processing a journal
file are released.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Security
No privileges required.
Example
See Appendix A.
See Also
ufchjrn, uopnjrn
253
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
For information about transaction logging and using a journal, see “Preventing Data
Loss” in Unify DataServer: Managing a Database.
254
ucmttx
Commit a transaction
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ucmttx( txid, status )
UTXID txid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
status
Returned status of the function
Commits an active transaction. When a transaction is committed, any changes made
during the transaction that affected the database are permanently written to the
database.
Committing a transaction with this function releases all locks acquired during the
transaction and closes any currently active scans against the transaction.
To commit one transaction and begin another, use the ucbgtx function.
Warning
Once a transaction is committed, you cannot rollback any changes that were made to
the database during the transaction.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
255
Example
See Appendix A.
See Also
uabttx, ubegtx, ucbgtx, uinftx, ualltx
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
256
ucrypwd,
Encrypt a password
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ucrypwd( pwd, crywdp, status )
char * pwd;
char **crywdp;
USTATUS * status;
Arguments
Description
pwd
Password to encrypt.
crywdp
Returned pointer to the encrypted password.
The ucrypwd function accepts a password and encrypts it in a format that can be
used for the database user identity, as in, for example, the DBUSER configuration
variable or the dbname argument to the uopndb function.
If the function executes successfully, the memory used for storing the encrypted
password has been allocated using malloc. You must recover the storage space using
free.
If the function does not execute successfully, the memory used for the encrypted
password has not been allocated. In this case, do not call free.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
257
Example
/* encrypt password */
if (ucrypwd(inpass, &outpass, &status) != USUCCESS )
{
(void) printf(”ucrypwd error;”);
if ((errmsg = ufchmsg(status, &msgstat)) == NULL)
printf(”error %ld fetching message \n”, (long) msgstat);
else
printf(”error is ’%s’\n”, errmsg);
exit(1);
} /* endif */
/* put encrypted password to standard output */
(void) printf(”encrypted password is ’%s’\n”, outpass);
free(outpass);
outpass = NULL;
See Also
“Accessing a Remote Database” and “Using the uopndb dbname Argument” in
Unify/Net Guide.
258
udelrow
Delete a row
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udelrow( txid, tid, rid, status )
UTXID txid;
UTID tid;
URID rid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table that contains the row
rid
Row ID of the row to delete
status
Returned status of the function
Deletes the row requested (rid) from the table specified (tid).
A row deletion can fail for any of the following reasons:
The row is referenced as a parent in a link index
The lock on the row could not be obtained
The transaction log is full
Before you can delete a parent row of a link index, you must drop or change the value
of any related rows in the child table. For more information about links, see the
uaddlnk function.
Security
To delete a row from a table, one of the following conditions must be true:
You have DBA authority.
The table is in the current schema.
You have DELETE schema privilege on the table that contains the row.
259
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uinsrow, uupdrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
260
udrpath
Drop a schema
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpath( txid, nauth, authl, statusl, status )
UTXID txid;
int nauth;
UAID *authl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nauth
Number of authorization IDs (schemas) listed in authl
authl
List of authorization IDs associated with the schemas to be dropped
statusl
Returned list of status values, one for each authl list entry
status
Returned status of the function
Validates the authorization IDs listed in authl and drops the associated schemas from
the database.
Before dropping a schema, all tables and views within the schema must be dropped.
When you drop a schema, all privileges associated with the schema are also dropped.
You cannot drop a schema that is in use. For instance, you cannot drop the current
schema or any schema that has privileges being used.
If the schema that is dropped is the default schema for any user, the PUBLIC schema
becomes the new default schema for the user.
Function Reference
261
The PUBLIC schema cannot be dropped from a database. The PUBLIC schema is
removed when the database is removed.
Before dropping any schemas, the udrpath function first attempts to acquire an
exclusive lock on the specified schemas. If the schema is in use, the udrpath
function cannot acquire an exclusive lock on the schema and the drop operation fails.
Security
To drop a schema, you must have one of the following permissions:
DBA authority
SCHEMA authority and schema access permission
For information about granting DBA and SCHEMA authority, see uaddprv; for
information about granting schema access permission, see uaddprm.
To grant DBA and SCHEMA authority, use the uaddprv function. To grant schema
access permission, use the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
262
Function Reference
udrpbt
Drop a B-tree
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpbt( txid, nbt, bidl, statusl, status )
UTXID txid;
int nbt;
UBTID bidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nbt
Number of B-tree IDs listed in bidl
bidl
List of B-tree IDs for B-trees to drop
statusl
Returned list of status values, one for each bidl list entry
status
Returned status of the function
Validates the B-tree IDs listed in bidl and drops the B-trees from the database.
Warning
For B-trees that are stored in separate files instead of the database file, when a B-tree
is dropped, Unify DataServer removes the external B-tree file (named btxxx.idx) and
creates a temporary file (named plxxxxxx) where xxx/xxxxxx are internal index
numbers. Do not remove this temporary file because database corruption can occur.
Security
To drop a B-tree, the schema containing the B-tree must be current, and you must
have one of the following permissions:
DBA authority
SCHEMA authority
Function Reference
263
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uaddbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using B-trees, see “Managing the Database Files” and
“Choosing an Access Method” in Unify DataServer: Managing a Database.
264
Function Reference
udrpcgp
Drop a column group
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpcgp( txid, ncgrp, dbcgrp, statusl, status )
UTXID txid;
int ncgrp;
DBCGRP *dbcgrp;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ncgrp
Number of column groups in the dbcgrp list
dbcgrp
List of DBCGRP structures, each describing a separate column group
statusl
Returned list of status values, one for each dbcgrp entry
status
Returned status of the function
Drops the column groups specified in the dbcgrp list from the database.
Also, this function can be used to modify column group options for a column group.
If all options for a column group are dropped, then the column group is dropped from
the database table.
Each DBCGRP structure in the dbcgrp list contains column group information.
For a description of the DBCGRP structure, see page 83.
Before dropping a column group, the udrpcgp function first acquires an exclusive
lock on each column member of the column group and then drops the column group
specification, leaving the underlying columns unaffected. If any member column is in
use, the exclusive lock attempt fails, and the drop column group operation also fails.
Function Reference
265
Security
To drop a column group, the schema containing the column group definition must be
current, and, you must have one of the following permissions:
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrpcgp function to drop a column group described in the
dbcgrp argument.
if (udrpcgp(txid, ncgrp, dbcgrp, statusl, &status) != USUCCESS)
{
fprintf(stderr,
”Couldn’t drop column groups: status = %ld\n”,status);
}
See Also
uaddcgp
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
266
Function Reference
udrpcnm
Drop a column name (or synonym)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpcnm( txid, ncol, dbcolnm, statusl, status )
UTXID txid;
int ncol;
DBCOLNM *dbcolnm;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ncol
Number of column name descriptors in dbcolnm
dbcolnm
List of DBCOLNM structures, each containing a separate column
name (or synonym) to drop
statusl
Returned list of status values, one for each dbcolnm entry
status
Returned status of the function
Validates the column synonyms listed in dbcolnm and drops the column names from
the database.
Once a column name is dropped, any future reference to the dropped column name
fails.
Each DBCOLNM structure in the dbcolnm list contains column name information.
Column group synonyms can also be dropped by specifying the column group ID (in
place of the column ID) in the dbcolnm list.
For a description of the DBCOLNM structure, see page 85.
Function Reference
267
Security
To drop a column name (or synonym), the schema containing the column must be
current and you must have one of the following privileges:
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddcnm, ufchcnm
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
268
Function Reference
udrphsh
Drop a hash table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrphsh( txid, nhsh, hidl, statusl, status )
UTXID txid;
int nhsh;
UHID *hidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nhsh
Number of hash tables in the hidl list
hidl
List of hash table IDs of the hash tables to drop
statusl
Returned list of status values, one for each hidl entry
status
Returned status of the function
Validates the hash table IDs listed in hidl and drops the associated hash tables from
the database.
Before dropping a hash table, this function attempts to acquire an exclusive lock on
the hash table. If the hash table is in use, the udrphsh function cannot acquire an
exclusive lock on the hash table and the drop operation fails.
Adding or dropping a hash table on a column can have a significant effect on retrieval
times of unordered accesses.
Security
To drop a hash table, the schema containing the hash table definition must be current,
and, you must have one of the following permissions:
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Function Reference
269
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrphsh function to drop a hash table index.
if ( udrphsh(txid, 1, &hid, statusl, &status) != USUCCESS )
printf(”Failure dropping a hash table: status = %ld\n”,status);
See Also
uaddhsh
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using hash tables, see “Managing the Database Files,”
“Choosing an Access Method,” and “Tuning the Access Methods” in Unify
DataServer: Managing a Database.
270
Function Reference
udrplnk
Drop a link
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrplnk( txid, nlnks, lidl, statusl, status )
UTXID txid;
int nlnks;
ULID *lidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nlnks
Number of link IDs in the lidl list
lidl
List of link IDs to drop
statusl
Returned list of status values, one for each hidl entry
status
Returned status of the function
Validates the link IDs listed in lidl and drops the associated links for the parent and
child tables/columns.
Once dropped, a link no longer enforces referential integrity across the two tables.
Before you can delete a parent row, you must first drop or change the value of any
related rows in the child table. Rows are related through links. For more information
about links, see the uaddlnk function. To delete a row, use the udelrow function.
When a link is dropped, Unify DataServer places an exclusive lock on both the linked
parent and the child columns.
Function Reference
271
Security
To drop a link, the current schema must contain one or both of the linked tables and
you must have one of the following permissions:
DBA authority
Schema access permission and SCHEMA authority on the schemas that contain
the tables that comprise the link definition
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function. To grant schema access permission, use
the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This function uses the udrplnk function to drop a link index on a table.
if ( udrplnk(txid, 1, &lid, statusl, &status) != USUCCESS )
printf(”Error dropping a link: status = %ld\n”,status);
See Also
uaddlnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
272
Function Reference
udrpprf
Drop a volume preference for a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpprf( txid, tid, nvol, vidl, statusl, status )
UTXID txid;
UTID tid;
int nvol;
UVID *vidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of table to drop volume preferences for
nvol
Number of volume IDs in the vidl list
vidl
List of volume IDs describing the volume preferences to drop
statusl
Returned list of status values, one for each vidl list entry
status
Returned status of the function
Validates the volume IDs listed in vidl for table tid, and drops the associated volume
preferences from the database.
The table ID and volume preferences listed must be valid existing entries in the
database before the call to the udrpprf function.
Security
Function Reference
To drop a volume preference for a table, the schema containing the table must be
current, and, you must have DBA authority.
273
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrpprf function to drop a volume preference from a table.
/* Drop the volume preferences */
if (udrpprf(txid, tid, nvol, vidl, statusl, &status) != USUCCESS)
{
fprintf(stderr, ”Unable to drop volume preferences: %ld\n”,
status);
for ( i = 0; i < nvol; i++ )
printf(stderr, ”Entry %d volume: %ld status: %ld\n”,
i, vidl[i], statusl[i]);
exit(1);
}
See Also
uadddb, uaddprf, uaddtbl, uaddvol, udrpvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
274
Function Reference
udrpprm
Revoke schema access permission
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpprm( txid, userid, nauth, authl, statusl, status )
UTXID txid;
UOID userid;
int nauth;
UAID authl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
userid
User ID of user from whom to drop schema access permission
nauth
Number of authorization IDs listed in authl
authl
List of authorization IDs for which schema access permission is
dropped
statusl
Returned list of status values, one for each authl list entry
status
Returned status of the function
Revokes schema access permission from a user for the authorization IDs (schemas)
listed in authl. Schema access permission allows a user to access a specified schema.
When a user is first added to the database (by calling the uaddusr function), the user
is granted schema access permission to the PUBLIC schema.
To access other schemas in the database, however, a user must be granted schema
access permission for each schema the user needs to access.
Function Reference
275
If the schema for which schema access permission is being revoked is a user’s default
schema, that user’s default schema is reset to the PUBLIC schema.
Security
To revoke schema access permission from a user, you must have DBA authority or
both of the following must be true:
The schema is current.
You have SCHEMA authority.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function. To grant schema access permission, use
the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the udrpprm function to revoke schema access permission from a
user.
/* define required parameters */
UTXID txid;
UOID
userid;
UAID
athl;
USTATUS statusl;
STATUS * status;
int
nauth;
/* Revoke schema access permission from a user */
if ( udrpprm(txid, userid, nauth, authl, statusl, &status) != USUCCESS )
{
fprintf(stderr, ”Unable to drop privileges: %ld\n”, status);
exit(1);
}
See Also
uadddb, uaddprm, uaddath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
276
Function Reference
udrpprv
Revoke user authority or schema privileges
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpprv( txid, nrqstds, rqstdsl, statusl, status )
UTXID txid;
int nrqstds;
URVKDS rqstdsl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nrqstds
Number of privileges described in the rqstdsl list
rqstdsl
List of URVKDS structures, each describing a separate privilege to
revoke
statusl
Returned list of status values, one for each rqstdsl entry
status
Returned status of the function
Revokes one or more of the following permissions:
DBA authority
SCHEMA authority
Schema privileges to a schema
Schema privileges to a table
Schema privileges to a column
DBA authority allows a user to access and modify any object in the database.
SCHEMA authority, however, allows a user to create and drop schemas only. Both of
these privileges are granted to users only.
Function Reference
277
Schema privileges are privileges granted to a schema. The privileges specify access
to another schema or a table or column within the schema.
For each set of privileges you want to revoke with this function, you must first
describe the privileges by initializing the URVKDS structure. For a description of the
URVKDS structure, see page 142.
To grant user or schema privileges, use the uaddprv function.
Security
To revoke DBA or SCHEMA authority, you must have DBA authority.
To revoke schema privileges, you must make the schema that granted the privileges
the current schema.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the udrpprv function to revoke schema privileges granted to the
company table.
/* define required parameters */
UTXID txid;
UOID
userid;
UAID
uathl;
USTATUS statusl;
STATUS * status;
int
nauth;
/* Retrieve the authorization ID (aid) for schema ”admin” */
...
/* Retrieve the table id (tid) for the company table */
...
/* Initialize URVKDS structure elements */
rqstdsl.aid = aid;
rqstdsl.rvkcaps = UTSEL;
rqstdsl.obj.objknd = UTBLKND;
rqstdsl.obj.objid = tidl.tid;
/* Revoke from schema ”admin” the privilege to perform SELECT
operations on table ”company” */
if (udrpprv(txid, 1, &rqstdsl, statusl, &status) != USUCCESS )
{
fprintf(stderr,
”Unable to revoke SELECT privilege: status = %ld\n”,
status);
}
278
Function Reference
See Also
uaddprv, uaddath, uaddprm, uaddusr, udrpath, udrpprm, udrpusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
Function Reference
279
udrptbl
Drop a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrptbl( txid, ntbl, tidl, statusl, status )
UTXID txid;
int ntbl;
UTID *tidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ntbl
Number of table IDs listed in the tidl list
tidl
List of table IDs to drop
statusl
Returned list of status values, one for each tidl list entry
status
Returned status of the function
Validates the table IDs listed in tidl and drops the associated tables from the database.
When a table is dropped, all privileges, B-trees, hash tables, and links defined for the
table are also dropped.
Before dropping a table, you must remove all Data Integrity Subsystem (DIS)
definitions for the table. For information about editing a DIS file, see Unify
DataServer: Managing a Database
When dropping a table, Unify DataServer acquires an exclusive lock on the specified
tables, then drops them. If the table is in use, this function cannot acquire an
exclusive lock on the table.
280
Function Reference
Security
To drop a table, the schema containing the table must be current, and you must have
one of the following privileges:
DBA authority
SCHEMA authority
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrptbl function to drop a table from the database.
ntbl = 3;
tidl[0] = $qualified_vendors.$;
tidl[1] = $vendor_info.$;
tidl[2] = $vendor_transactions.$;
/* Drop the tables */
if ( udrptbl(txid, ntbl, tidl, statusl, &status) != USUCCESS )
{
fprintf(stderr, ”Unable to drop table: %ld\n”, status);
for ( j = 0; j < ntbl; ++j )
printf(stderr, ”Table %ld status: %ld\n”,tidl[j], statusl[j]);
exit(1);
}
See Also
uaddtbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
Function Reference
281
udrptnm
Drop a table name (or synonym)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrptnm( txid, ntbl, dbtblnm, statusl, status )
UTXID txid;
int ntbl;
DBTBLNM *dbtblnm;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ntbl
Number of table name descriptors in dbtblnm list
dbtblnm
List of DBTBLNM structures, each containing a separate table name
to drop
statusl
Returned list of status values, one for each dbtblnm entry
status
Returned status of the function
Drops the names (or synonyms) for a table. After dropping a table name, any future
references to the dropped table name fail.
If all names for a table are dropped, the table can be referenced by its table ID only.
Each DBTBLNM structure in the dbauth list contains information about each table
name. For a description of the DBTBLNM structure, see page 99.
Security
To drop a table name, the schema containing the table must be current, and, you must
have one of the following privileges:
DBA authority
SCHEMA authority
282
Function Reference
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function. To grant schema access permission, use
the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrptnm function to drop a table synonym.
/* Initialize the DBTBLNM structure */
dbtblnm.tblnm = ”partsdata.”;
dbtblnm.tid = $parts.$;
if (udrptnm(txid, 1, &dbtblnm, statusl, &status) != USUCCESS)
printf(”Error dropping a table name: status = %ld\n”,status);
See Also
uaddtnm
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
Function Reference
283
udrpusr
Drop a user
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpusr( txid, nuser, useridl, statusl, status )
UTXID txid;
int nuser;
UOID *useridl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nuser
Number of user IDs listed in the useridl list
useridl
List of user IDs to drop
statusl
Returned list of status values, one for each useridl list entry
status
Returned status of the function
Validates the user IDs listed in useridl and drops the associated users from the
database.
You cannot drop yourself or any other users currently accessing the database.
Security
To drop a user from the database, you must have DBA authority.
To grant DBA authority, use the uaddprv function.
Status
Values
284
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Function Reference
Example
This example calls the udrpusr function to remove a user from the database.
/* define required parameters */
UTXID txid;
int
nuser, i;
USTATUS statusl;
USTATUS status;
UOID * useridl;
/* Initialize the useridl structure */
...
useridl[0] = usrinf[0].uoid; /* Returned from uinfusr() */
useridl[1] = usrinf[1].uoid;
/* Drop the users */
nuser = 2;
if ( udrpusr(txid, nuser, useridl, statusl, &status) != USUCCESS)
{
fprintf(stderr, ”Unable to drop users: %ld\n”, status);
for ( i = 0; i < nuser; ++i )
printf(stderr, ”Entry %d user %s status: %ld\n”,
i, dbuser[i].usernm, statusl[i]);
exit(1);
}
See Also
uaddusr, uaddath, uadddb, uaddprm, uaddusr, udrpath, udrpprm, uinfusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
Function Reference
285
udrpvol
Drop a volume
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int udrpvol( txid, nvol, vidl, statusl, status )
UTXID txid;
int nvol;
UVID *vidl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nvol
Number of volume IDs listed in the vidl list
vidl
List of volume IDs to drop
statusl
Returned list of status values, one for each vidl list entry
status
Returned status of the function
Validates the volumes listed in vidl and drops the associated volumes from the
database.
The root volume cannot be dropped, and any volume which has active storage
allocated cannot be dropped. Use the uinfvol function to determine if the volume has
any active storage.
Volumes designated as a preference volume for a table cannot be dropped. To drop a
preference volume, you must first drop all of the preferences by calling the udrpprf
function.
Warning
When a volume that is defined as a file is dropped, Unify DataServer removes the
volume file and creates a temporary file (named plxxxxxx, where xxxxxx is an internal
index number). Do not remove this temporary file; database corruption will occur.
286
Function Reference
Security
To drop a volume definition from a database, you must have DBA authority. To grant
DBA authority, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the udrpvol function to drop a volume from the database.
/* Initialize volume specifications */
nvol = 1;
/* number of volumes to drop */
vidl[0] = 2;
/* drop volume #2 */
...
/* Drop the volume */
if (udrpvol(txid, nvol, vidl, statusl, &status) != USUCCESS)
{
fprintf(stderr, ”Unable to drop volumes: %ld\n”, status);
for ( i = 0; i < nvol; ++i )
printf(”Entry %d Volume ID %ld status: %ld\n”,i, vidl[i], statusl[i]);
uexit(1);
}
See Also
uadddb, uaddvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
Function Reference
287
uendord
End an ordered access
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uendord (oaccid, status)
UOACCID oaccid;
USTATUS *status;
Arguments
Description
oaccid
Ordered access ID of the ordered access to end, as returned from the
ubegord function
status
Returned status of the function
Ends (or deactivates) an ordered access (specified by oaccid) and releases temporary
memory allocated for the ordered access.
If a transaction that contains active ordered accesses is ended (with the uabttx,
ucbgtx or ucmttx functions), the active ordered accesses are automatically ended.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ubegord, ufchord, uposord, uskrord
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
288
uendscn
End a scan
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uendscn( scnid, status )
int scnid;
USTATUS *status;
Arguments
Description
scnid
Scan ID of the scan to end, as returned from the ubegscn function
status
Returned status of the function
Ends (or deactivates) a scan (specified by scnid) and releases temporary memory
used for the scan.
If a transaction that contains active scans is ended (by calling the uabttx, ucbgtx or
ucmttx function), the active scans are ended.
To deallocate a scan information structure, use the ufrescn function.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
289
See Also
uabttx, ualcscn, ubegscn, ucbgtx, ucmttx, ufchscn, ufrescn
For information about scanning, see page 64.
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
290
uexit
Terminate a process
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
void uexit( exit_code )
int exit_code;
Arguments
exit_code
Description
Terminates a process with the following consequences:
An integer exit code. This value is passed to the exit operating
system function.
All active read-only (type 0) transactions in the calling process are committed.
All other active update (type 1 or 2) transactions in the calling process are
rolled back.
The open database in the calling process is closed.
The exit operating system function is called.
Failure to use this function to terminate a process will result in the above activities
being performed at a later time. This function, as well as the exit operating system
function, does not return control to the calling procedure.
Security
No privileges required.
Example
See Appendix A.
See Also
fork(2), wait(2), and exit(3) in your UNIX operating system manual
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
291
uextint
Convert column values from external format to internal format
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uextint( txid, tid, unipext, unipcoll, statusl, status )
UTXID txid;
UTID tid;
UNIPEXT *unipext;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table columns contained in UNIPEXT
unipext
A pointer to a UNIPEXT structure that contains column values in
external-format to be converted into internal format
unipcoll
A pointer to a UNIPCOLL structure that will contain the converted
values
statusl
Returned status value for each column listed in the UNIPCOLL
column list cidl
status
Returned status of the function
Converts a list of data values from an external (display) format to an internal database
format.
This function must be used before inserting or updating data into columns of data
type U_DATE, U_HDATE and U_TIME .
To read and display date and time data in a Unify DataServer database, you must first
convert the data into external format by calling the uintext function.
292
For each column in the external format list described by the UNIPEXT structure
(pointed to by unipext), each external column data value is converted to internal
format and stored in a UNIPCOLL structure (pointed to by unipcoll).
The entries in the unipext list must contain the same number of entries as in the
unipcoll list.
For a description of the UNIPEXT and UNIPCOLL structures, see pages 140 and 131.
All columns specified in each UNIPEXT structure must belong to the specified table
ID (tid).
Any valopts member contained in the UNIPCOLL structure that contains a value of
UIGNORE is by-passed and the entry for statusl is set to UENOWRK.
All column values must be converted to internal format before being inserted into the
database. See the uinsrow or uupdrow function for more information.
If the destination column structure value pointer is null, storage space is allocated by
Unify DataServer. This space must later be deallocated by calling the system
subroutine free function. If the value pointer is not null, it is assumed that enough
space exists for the converted value.
A value that cannot be converted is rejected. Check each status value in statusl to
determine which values could not be converted.
Security
To convert column values, you must have access to the column that you want to
convert.
You can always access all columns in the tables in the current schema. Additionally,
you can access tables (or just columns within a table) in other schemas if your current
schema has been granted schema privileges to the other schema. If you have DBA
authority, you can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
293
Example
See Appendix A.
See Also
uintext, uinsrow, ufchrow, uupdrow, udelrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
294
ufchath
Change the current schema
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufchath( txid, authid, status )
UTXID txid;
UAID authid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
authid
Authorization ID (for a schema) obtained from a previous call to the
ubndath function
status
Returned status of the function
Changes a user’s current schema to the schema specified by authid.
The current schema is the schema available to a user. Only one schema can be current
at any given time. If the user has adequate access permission, the user can make
another schema the current schema.
Security
To change a current schema, you must have one of the following permissions.
DBA authority
Schema access permission for the schema you are changing to
To grant DBA authority, use the uaddprv function. To grant schema access
permission, use the uaddprm function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
295
Example
This example calls the ufchath function to make the PUBLIC schema the current
schema.
/* define required parameters */
UTXID
txid;
USTATUS * status;
/* open the database and begin a transaction */
...
/* make the PUBLIC schema the current schema */
if ( ufchath(txid, $PUBLIC..$, &status) != USUCCESS)
printf(”Could not set the current schema: status = %ld\n”, status);
See Appendix A for more examples.
See Also
uaddath, uallath, ubndath, udrpath, uinfath, umapath, umodath, unumath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
296
ufchcnm
Fetch column names (or synonyms)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufchcnm( txid, cid, ncnames, colnml, status )
UTXID txid;
UCID cid;
int *ncnames;
char ***colnml;
USTATUS *status;
Arguments
Description
txid
Transaction ID
cid
Column ID of the column to fetch the name and synonyms from
ncnames
Number of column names returned into the colnml list
colnml
Returned list of column names
status
Returned status of the function
Validates the given column ID and retrieves all names assigned to the column.
Each column can have one or more names associated with the column. See uaddcnm
for more information about adding column names (or synonyms).
All names contained in colnml are zero-byte terminated strings. Also, colnml should
be accessed by specifying an argument like argv[ ][ ].
Unify DataServer allocates storage for the returned list of column names (colnml) by
calling the malloc function. After you have retrieved the column names, you must
recover this storage space by calling the free function.
297
If the number of column names (ncnames) returned is zero (0), the malloc function
was not performed by Unify DataServer and you do not need to call the free function.
Security
Column names are returned only for columns in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ufchcnm function to retrieve all column names associated
with the co_id column in the company table.
/* define required parameters */
char ** colnml;
int * ncnames;
TXID txid;
USTATUS status;
...
/* find all the names the ”co_id” column is known by */
if (ufchcnm(txid, $co_id$, &ncnames, &colnml, &status) != USUCCESS)
{
printf(”Error fetching column names: status = %ld\n”,status);
exit( 3 );
}
...
/* print the column names */
for( idx = 0; idx < ncnames; ++idx )
printf(”%s\n”, colnml[idx]);
...
/* free the space used by colnm */
if ( ncnames > 0 )
free((char *)colnml);
See Also
uaddtnm, udrptnm, uaddcnm, udrpcnm, uaddtbl
298
free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
299
ufchjrn
Retrieve journal information structure
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufchjrn (jrnfd, jrninfo, status)
int jrnfd;
UJRNINF *jrninfo;
USTATUS *status;
Arguments
Description
jrnfd
The file descriptor of the opened journal file
jrninfo
A pointer to a UJRNINF structure that contains the returned journal
information on the next update operation contained in the journal; for
a complete description of the UJRNINF structure, see page 127.
status
Returned status of the function
Retrieves the journal information structure for the next update operation contained in
the journal.
For delete and update operations, the before image of the row is returned in a
UNIPCOL structure. For add and update operations, an after image is returned. For a
description of the UNIPCOL structure, see page 131.
The UNIPCOL structures for the before and after row images are dynamically
allocated by the ufchjrn function. These structures should be freed using the C
function, free, to prevent running out of memory.
Data for variable length data type fields is not returned by the ufchjrn function. All
variable length data is skipped.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
300
Security
To process a journal file, one of the following conditions must be true:
You have DBA authority.
You have schema privilege on all the tables and columns that are referenced in
the journal.
Example
See Appendix A.
See Also
uopnjrn, uclsjrn
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management and using the transaction journal, see
“Managing Transactions and Locks”and “Preventing Data Loss” in Unify
DataServer: Managing a Database.
301
ufchlnk
Fetch the parent row through a link index
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ufchlnk( txid, crid, lid, lcktype, rid, unipcoll, statusl, status )
UTXID txid;
URID crid;
ULID lid;
int lcktype;
URID *rid;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
302
txid
Transaction ID
crid
Row ID of a child row of a link
lid
Link ID of the table to search
lcktype
Lock type to place on the retrieved row ID. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
rid
Returned as the row ID of the parent row retrieved
unipcoll
A pointer to a UNIPCOLL structure specifying the column retrieval
list that corresponds to the parent column
statusl
Returned list of status values, one for each column described in
unipcoll
status
Returned status of the function
Description
Retrieves columns of the parent row from the implied table through a link access
method. All columns specified in the UNIPCOLL structure must belong to the parent
table.
Before fetching the parent row, you must obtain the child row ID and specify this
value in crid.
The UNIPCOLL structure describes the data being retrieved from the database. This
structure contains several lists which describe both the column and the column’s
value. For a description of the UNIPCOLL structure, see page 131.
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly.
Security
A row can be returned for linked tables that you have access to only.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
303
Example
This example uses the ufchlnk function to fetch a row.
#define NCOL
3
/* define required parameters */
UTXID
txid;
URID
crid;
URID
rid;
USTATUS statusl[NCOL];
USTATUS status;
UNIPCOLL unipcoll;
...
/* retrieve crid */
...
/* retrieve the row */
if ( ufchlnk(txid, crid, $ULNK:LIDparts_used$, USLCK, &rid,
&unipcoll, statusl, &status) != USUCCESS)
{
printf(”Cannot fetch parent row: status=%ld\n”, status);
uexit(2);
}
See Also
uaddlnk, ufchtbl, ufchrow, upkfrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
304
ufchmsg
Retrieve the message text corresponding to a status error code
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
char *ufchmsg( errnum, status )
USTATUS errnum;
USTATUS *status;
Arguments
Description
errnum
Status error code of the message to fetch
status
Returned status of the function
Fetches the error message text for the status error code specified by errnum. The
status error code is usually the status code returned by a previous RHLI function call.
Most RHLI functions return a status code into the status argument. This status code
reflects the condition of the function operation. A UENORM status code indicates the
function operated successfully; all other status codes indicate an error condition.
For a listing of status codes and associated mnemonics, see the rhlierr.h header file.
For a complete description of error messages, see Unify DataServer: Error Messages.
If the ufchmsg function is unable to fetch a message for the error code provided, a
status code describing the error is returned into the status argument.
Security
No privileges required.
Return
Values
Returns a pointer to the error message text. If this function cannot retrieve the error
message text, the value (char*) 0 is returned.
305
Example
See Appendix A.
See Also
uinimsg, ulogmsg
For information about error handling, see page 51.
306
ufchord
Fetch a row from within an ordered access
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufchord (txid, oaccid, dir, lcktype, ridp, unipcoll, statusl, status)
UTXID txid;
UOACCID oaccid;
int dir;
int lcktype;
URID *ridp;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
Transaction ID
oaccid
An ordered access ID as returned from the ubegord function
dir
Direction to fetch the row, relative to the current position. Options
are:
lcktype
USAME
Get same (current) row
UFIRST
Get first row
UNEXT
Get next row
UPREV
Get previous row
ULAST
Get last row
Lock type to place on retrieved row. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
307
Description
ridp
Returned as the row ID of the retrieved row
unipcoll
A pointer to a UNIPCOLL structure specifying the column retrieval
list
statusl
Returned list of status values, one for each column value returned
into the unipcoll list
status
Returned status of the function
Retrieves columns of the row indicated by dir from the specified ordered access. The
order in which the rows are retrieved is specified by the column order list
(UOACOLS) for the order access (initiated by the ubegord function).
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly.
The UNIPCOLL structure describes the data being retrieved from the database. This
structure contains several lists which describe both the column and the column’s
value.
If the function returns USUCCESS, the row ID and requested columns are returned
with a lock no lower than the requested lock. The current position within the ordered
access is set to the retrieved row.
The UNEXT option can be specified (instead of UFIRST) immediately after the
ubegord function call to fetch the first row of the table.
The txid specified to the ufchord function may differ from the txid used by the
ubegord function. If a different txid is used for the ufchord function, then the
transaction can be committed to release locks on the current record without affecting
the ordered access.
The direction parameter is the order specified by the UOACOLS structure, not the
physical order of the underlying access method. Therefore, for an ascending order,
UFIRST refers to the row whose columns have the lowest value and ULAST to the
row whose columns have the highest value.
For a descending order, UFIRST refers to the row whose columns have the highest
value and ULAST to the row whose columns have the lowest value.
308
Columns specified in UNIPCOLL must belong to the table associated with the
ordered access.
If the function fails due to the inability to obtain the specified row lock, the current
position is set to the fetched row.
Additional Help
See “Function Structures,” for a description of the structure UNIPCOLL.
Security
To retrieve the column values for the row, one of the following conditions must be
true:
You have DBA authority.
The target table is in the current schema.
You have SELECT schema privilege on the target table.
You have SELECT schema privilege on all columns to be retrieved.
To make a schema current, see the ufchath function; for information about granting
DBA authority and schema privileges, see the uaddprv function.
UEDBCLS
Database is closed
UEBDATYP
Bad access type (not an ordered access ID)
UEBDSCN
Invalid ordered access ID
UENODIR
Invalid direction specification
Example
See Appendix A.
See Also
ubegord, uendord, uposord, uskrord
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
309
ufchrow
Fetch a row
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ufchrow( txid, tid, lcktype, rid, unipcoll, statusl, status )
UTXID txid;
UTID tid;
int lcktype;
URID rid;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table to fetch from
lcktype
Lock type to place on the retrieved row ID. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
rid
Row ID of the row to retrieve
unipcoll
A pointer to a UNIPCOLL structure specifying the column retrieval
list
statusl
Returned list of status values, one for each column specified in the
unipcoll column list
status
Returned status of the function
Given valid table and row IDs, this function retrieves specified columns of the row.
Columns specified in UNIPCOLL must belong to the specified table ID.
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly.
310
The UNIPCOLL structure describes the data retrieved from the database. This
structure contains several lists describing the column and its value. For a description
of the UNIPCOLL structure, see page 131.
Security
A row can only be returned for tables you have access to. You can always access all
tables in the current schema. Additionally, you can access tables (or just columns
within a table) in other schemas if your current schema has been granted schema
privileges to the other schema. If you have DBA authority, you can access any table in
the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ufchrow function to fetch a row from the company table.
#define NCOL 3
/* define required parameters */
UTXID
txid;
URID
rid;
/* Row ID */
USTATUS
status;
/* function status */
USTATUS
statusl[NCOL]; /* status value list */
UNIPCOLL
unipcoll;
...
/* Retrieve rowid of row to be fetched */
...
/* Fetch the row */
if (ufchrow(txid, $company.$, USLCK, rid, &unipcoll, statusl,
&status) != USUCCESS )
{
printf(”data retrieval failed: %ld\n”, status);
uexit(101);
}
See Appendix A for more examples.
See Also
upkfrow, ufchlnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
311
ufchscn
Retrieve the next row from a scan
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ufchscn( scanid, ridp, dbvall, prevlck, statusl, status )
int scanid;
URID *ridp;
UDBVAL *dbvall;
int *prevlck;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
scanid
A scan ID as returned from the ubegscn function
ridp
Returned as a row ID of the retrieved row
dbvall
Pointer to a list of UDBVAL structures, each specifying a different
column retrieval buffer
prevlck
Returned as the previous lock status of the retrieved row
statusl
Returned list of status values, one for each column value returned
into the dbvall list
status
Returned status of the function
Retrieves the next row along the specified scan. The order in which the rows are
retrieved is specified by the sort criteria for the scan.
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly.
312
A list of UDBVAL structures should be allocated to correspond to the elements of the
previously specified projection list. The order of the columns returned is the same as
that of the projection list. The UDBVAL structure can be allocated by the application
or through the uinfscn function. For a description of UDBVAL, found in the structure
UNIPCOLL, see page 131.
If the function returns USUCCESS, the row ID and requested columns are returned
with a lock no lower than the requested lock. The prevlck member is set to the lock
previously held on the row by the calling transaction. If the function returns
UFAILURE, the rowid and column values are undefined. If a row is passed but the
lock could not be granted (STATUS = UELMOUT) then prevlck is set to the
conflicting lock type.
If the application did not call uinsprj (the number of projected columns is zero) then
dbvall and statusl may be null.
When inserting into or updating columns of type U_STR (string), Unify DataServer
adds trailing blanks to values less than the total size defined for the column.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ualcscn, uendscn, ubegscn, ufrescn, uinfscn, ufchscn, uinsprj, uinssrt, uinsor
For information about scanning, see page 64.
313
ufchtbl
Fetch a row sequentially
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ufchtbl( txid, tid, dir, lcktype, rid, unipcoll, statusl, status )
UTXID tx;
UTID tid;
int dir;
int lcktype;
URID *rid;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
Transaction ID
tid
Table ID of the table to fetch from
dir
Direction to fetch the row, relative to the current position. Options
are:
lcktype
rid
314
UFIRST
Get first row
UNEXT
Get next row
UPREV
Get previous row
ULAST
Get last row
Lock type to place on the retrieved row ID. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
The row ID. Used for UNEXT and UPREV operations (specified by
dir), the next or previous row is relative to the row ID passed in. For
all operations the row ID of the row retrieved is returned.
Description
unipcoll
A pointer to a UNIPCOLL structure specifying the column retrieval
list
statusl
Returned list of status values, one for each column specified in the
unipcoll column list
status
Returned status of the function
Retrieves columns of the indicated row from the specified table. Columns specified
in UNIPCOLL must belong to the specified table ID.
The UFIRST option must be used when retrieving the first row of the table. This sets
the current position for subsequent retrievals.
Warning
Column values are verified and valopts is set for all fetch (or retrieval)
operations unless UIGNORE is specified. This is true even if the application has
set valopts explicitly.
The UNIPCOLL structure describes the data retrieved from the database. This
structure contains several lists which describe both the column and the column’s
value. For a description of the UNIPCOLL structure, see page 131.
Security
A row can be returned only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant DBA authority and
schema privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
315
Example
This example uses the ufchtbl function to fetch a row from the company table.
#define NCOL 2
/* define required parameters */
int
dir;
/* fetch direction */
UTXID
txid;
URID
rid;
/* Row ID */
USTATUS
status;
/* function status */
USTATUS
statusl[NCOL]; /* status value list */
UNIPCOLL
unipcoll;
...
/* Retrieve rowid of row to be fetched (rid) */
...
/* Fetch the row */
dir = UFIRST;
if (ufchtbl(txid, $company.$, dir, USLCK, &rid, &unipcoll, statusl,
&status) != USUCCESS)
{
printf(”data retrieval failed: %ld\n”, status);
uexit(101);
}
See Also
ufchlnk, ufchrow, upkfrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
316
ufchtnm
Fetch table names (or synonyms)
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufchtnm( txid, tid, ntnames, tblnml, status )
UTXID txid;
UTID tid;
int *ntnames;
char ***tblnml;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table to fetch names from
ntnames
Number of table names returned to tblnml
tblnml
Returned list of pointers to table names
status
Returned status of the function
Validates the table (specified by tid) and retrieves all names assigned to the table.
Each table can have one or more names associated with the table. See the uaddtnm
function for more information about adding table names (or synonyms).
All table names returned into tblnml are zero byte-terminated strings.
Unify DataServer allocates storage for the returned list of table names (tblnml) by
calling the malloc function. After you have retrieved the table name, you must
recover this storage space by calling the free function.
If the number of table names (ntnames) returned is zero (0), the malloc function was
not called by Unify DataServer and you do not need to call the free function.
317
Security
Table names are returned only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ufchtnm function to fetch and print all names that the
company table is known by.
#define NCOL 2
/* define required parameters */
int
* ntnames;
char
** tblnml;
UTXID
txid;
USTATUS
status;
/* function status */
USTATUS
statusl[NCOL]; /* status value list */
...
}
/* find all the names the ”company” table is known by */
if (ufchtnm(txid, $company$, &ntnames, &tblnml, &status) != USUCCESS)
{
fprintf(stderr,”Error fetching table names: status = %ld\n”,status);
uexit(99);
}
for( idx = 0; idx < ntnames; ++idx )
printf(”%s\n”, tblnml[idx]);
/* free the space used by tblnml */
if ( ntnames > 0 )
free((char *)tblnml);
See Also
uaddcnm, uaddtnm, udrpcnm, udrptnm, ufchcnm
free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
318
ufrescn
Free or clear a scan information structure
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ufrescn( txid, scaninf, rlsopts, status )
UTXID txid;
char **scaninf;
UOPTS rlsopts;
USTATUS *status;
Arguments
txid
Transaction ID
scaninf
A scan information structure to free as returned from the ualcscn
function
rlsopts
Operation indicator; options are:
DB_RESET
Reset the scan structure; do not release.
The DB_RESET option is used to reuse the scan
structure and should not be used with any other
options.
status
DB_RELEAS
Release the scan information structure.
DB_FREPRJ
Release only the projection specification.
DB_FRESEL
Release only the selection criteria.
DB_FRESRT
Release only the sort order specification.
Returned status of the function
Description
Frees the memory belonging to the scan information structure indicated. This
function does not deactivate the scan. A scan stays active until a call is made to the
uendscn function.
Security
No privileges required.
319
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ualcscn, ubegscn, uendscn, ufchscn, uinssrt, uinsprj, uinsor, uinsand
For information about scanning, see page 64.
320
uinfacs
Retrieve access information for a scan or ordered access
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfacs( scnid, acsinfp, status )
int scnid;
UACSINF *acsinfp;
USTATUS *status;
Arguments
Description
scnid
The ID returned by either the ubegscn or ubegord function
acsinfp
UACSINF structure to hold access information
status
Contains a value that indicates the status of the function’s operation.
The uinfacs function should be called after the ubegscn or ubegord function is
called, and before the ufchscn or ufchord function is called.
When a scan or ordered access is initiated with the ubegscn or ubegord function, the
optimizer analyzes the selection and database criteria, and chooses the most efficient
access method. The uinfacs function retrieves this access type information by filling
a UACSINF structure for the given ID. The information includes the access type
chosen by the optimizer, and can be one of the following:
USQSCN
Sequential access
UDKSCN
Direct key access
UBTSCN
BĆtree index access
UHKSCN
Hash index access
ULKSCN
Link index access
UNULLSCN
No access type, not initialized
321
UFAILURE
A failure occurred during the operation; check status value
for the error.
And, depending on access type, may include other information:
UBTSCN
BĆtree ID and number of components used.
UHKSCN
Hash table ID
ULKSCN
Link ID
Other functions may then be used to retrieve additional information about the
particular index chosen by the optimizer. For example:
uinfbt
BĆtree information
uinfhsh
Hash table information
uinflnk
Link information.
Security
Subject to the same restrictions as the scan or ordered access in question.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uinfbt, uinfhsh, uinflnk
For information about scanning, see page 64.
For information about access methods, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
322
uinfath
Retrieve schema information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfath( txid, nauth, athidl, infclas, athinfl, statusl, status )
UTXID txid;
int nauth;
UAID *athidl;
UOPTS infclas;
UATHINF *athinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nauth
Number of authorization IDs in the athidl list
athidl
List of authorization IDs (associated with schemas) to retrieve
information about
infclas
Type of information requested. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UALLINFO
Retrieve all information
athinfl
List of UATHINF structures, each containing retrieved information
about each authorization ID listed in athidl
statusl
Returned list of status values, one for each athidl/athinfl entry
status
Returned status of the function
Returns a UATHINF schema information structure for each authorization ID listed in
athidl. For a description of the UATHINF structure, see “The RHLI Structures”
chapter.
The parameter infclas controls how much schema information is returned to each
UATHINF structure.
323
Information retrieval classes (specified by inflclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UATHINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1 category (which is defined in the structure UATHINF) retrieves the
specified information for that class only.
The UALLINFO option specifies that all the information defined for the UATHINF
structure is to be retrieved.
You can specify more than one retrieval class by separating options with the bitwise
logical OR operator (|).
Security
Schema information is returned only for schemas that you have access to.
You always have access to the current schema. Additionally, you can access other
schemas if you have been granted schema access permission to the schema or if a
schema you can access has schema privileges to another schema (or a table or column
in the schema). If you have DBA authority, you can access any schema in the
database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
324
Example
This example calls the uinfath function to retrieve information about the current
schema.
/* define required parameters */
UTXID
txid;
int
nauth;
UAID
* athidl;
UATHINF * athinfl;
USTATUS
statusl;
STATUS
status;
/* retrieve authorization ID (athidl) */
...
/* retrieve authorization information */
if ( uinfath(txid, 2, athidl, UALLINFO, athinfl, statusl,&status) != USUCCESS)
printf(”Unable to get info on schema: status = %ld\n”,status);
See Also
uaddath, uallath, ubndath, udrpath, ufchath, umapath, umodath, unumath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
325
uinfbt
Retrieve B-tree information for a list of B-trees
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinfbt( txid, nbt, btidl, infclas, btinfl, statusl, status )
UTXID txid;
int nbt;
UBTID *btidl;
UOPTS infclas;
UBTINF *btinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
326
txid
Transaction ID
nbt
Number of B-tree IDs in the btidl list
btidl
List of B-tree IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UALLINFO
Retrieve all information
btinfl
Returned list of UBTINF structures, each containing information
about a separate B-tree (corresponding to the B-tree IDs listed in
btidl)
statusl
Returned list of status values, one for each btinfl entry
status
Returned status of the function
Description
Returns a UBTINF B-tree information structure for each B-tree ID listed in btidl.
The parameter infclas controls how much B-tree information is returned to each
UBTINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UBTINF structure is to be retrieved. No optional information is desired.
The UNOCLASS option information is always retrieved, no matter which retrieval
class you choose.
The UCLASS1, UCLASS2 and UCLASS3 categories (which are described in the
structure UBTINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UBTINF
structure is to be retrieved.
For a description of the UBTINF structure, see “The RHLI Structures” chapter.
Security
B-tree information can be retrieved only for B-trees on tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Volume information is only returned if you have DBA authority.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
327
Example
This example uses the uinfbt function to retrieve B-tree information.
if ((btidl = (UBTID *)calloc(2, sizeof(UBTID))) == NULL)
uexit(1);
if (ubndbt(txid, $parts$, 1, ”part_number”, &btidl[0], &statusl[0],&status)
!= USUCCESS)
{
free (btidl);
uexit(1);
}
if (ubndbt(txid, $parts$, 1, ”ord_number”, &btidl[1], &statusl[1],
&status) != USUCCESS)
{
free (btidl);
uexit(1);
}
if ((btinfl = (UBTINF *)calloc(2, sizeof(UBTINF))) == NULL)
{
free (btidl);
uexit(1);
}
if (uinfbt(txid, 2, btidl, (UCLASS1|UCLASS2), btinfl, statl, &status)
!= USUCCESS)
{
printf(”Unable to get info on B-trees: status = %ld\n”,status);
free (btidl);
free (btinfl);
uexit(1);
}
See Also
ubndbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using B-trees, see “Managing the Database Files” and
“Choosing an Access Method” in Unify DataServer: Managing a Database.
328
uinfcgp
Retrieve column group information for a list of columns
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfcgp( txid, ncol, cidl, infclas, colinfl, statusl, status )
UTXID txid;
int ncol;
UCID *cidl;
UOPTS infclas;
UCGPINF *cgpinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ncol
Number of column IDs in the cidl list
cidl
List of column IDs to retrieve information about
infclas
Information retrieval class. Must be set to UNOCLASS.
cgpinfl
Returned list of UCGPINF structures, each containing information
about a separate column group (corresponding to the cidl list)
statusl
Returned list of status values, one for each cgpinfl entry
status
Returned status of the function
Returns a UCGPINF column group information structure for each column ID listed in
cidl. Any column ID listed in cidl can be either a group member or a group leader.
If a column’s type is U_CGP, the returned list of column IDs is of the component
group members. Otherwise, the list of column IDs is of the column groups the
component participates in.
329
The parameter infclas should be set to UNOCLASS. This indicates that essential
information is to be retrieved. All column group information is essential, and
therefore is retrieved.
The parameter cginfl points to a list of UCGPINF structures that contain the returned
column group information. For a description of the structure UCGPINF, see “The
RHLI Structures” chapter.
For successfully retrieved information structures where the number of column IDs
returned is non-zero, the UCGPINF structure member grpcidl, is allocated storage
space by calling the malloc function. This space should be released when the
information is no longer needed by calling the free function.
Security
Column group information can be retrieved only for columns in tables that you have
access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uinfcgp function to retrieve information about a column
group.
pcol[0] = ”part_number”;
pcol[1] = ”part_name”;
/* Retrieve the Column IDs to get info on */
if (ubndcol(txid, $parts$, 2, pcol, USLCK, &cidl, statusl, &status) !=
USUCCESS)
uexit(1);
if ( uinfcgp(txid,2,cidl,UALLINFO,cgpinfl,statusl,&status) != USUCCESS )
{
printf(”Unable to get info on col. group: status = %ld\n”,status);
uexit(1);
}
330
See Also
uaddcgp, uallcgp, udrpcgp, unumcgp
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
331
uinfcol
Retrieve column information for a list of columns
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinfcol( txid, ncol, cidl, infclas, colinfl, statusl, status )
UTXID txid;
int ncol;
UCID *cidl;
UOPTS infclas;
UCOLINF *colinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
332
txid
Transaction ID.
ncol
Number of column IDs in the cidl list
cidl
List of column IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UCLASS4
Retrieve Class 4 information only
UALLINFO
Retrieve all information
colinfl
Returned list of UCOLINF structures, each containing information
about a separate column (corresponding to the cidl list)
statusl
Returned list of status values, one for each colinfl entry
status
Returned status of the function
Description
Returns a UCOLINF column information structure for each column ID listed in cidl.
The parameter infclas controls how much column information is returned to each
UCOLINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UCOLINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1, UCLASS2, UCLASS3 and UCLASS4 categories (which are defined in
the structure UCOLINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UCOLINF
structure is to be retrieved.
For a description of the UCOLINF structure, see “The RHLI Structures” chapter.
For columns successfully retrieved by specifying UCLASS4 or UALLINFO retrieval
classes, storage space is allocated by Unify DataServer for UCOLINF structure
members coldesc and dsppict calling the malloc function. This space should be
released when the information is no longer needed by calling the free function.
Security
Column information can be retrieved only for columns you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
333
Example
This example uses the uinfcol function to retrieve information about a column.
pcol[0] = ”part_number”;
pcol[1] = ”part_name”;
/* Retrieve the Column IDs to get info on */
if (ubndcol(txid, $parts$, 2, pcol, USLCK, &cidl, statl, &status) != USUCCESS)
uexit(1);
if (uinfcol(txid,2,cidl,UALLINFO,colinfl,statusl,&status) != USUCCESS)
{
printf(”Unable to get info on columns: status = %ld\n”,status);
uexit(1);
}
See Also
ubndtbl, ubndcol
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
334
uinfdb
Retrieve database information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfdb( txid, ndb, dbidl, infclas, dbinfl, statusl, status )
UTXID txid;
int ndb;
UDBID *dbidl;
UOPTS infclas;
UDBINF *dbinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
ndb
The number of database IDs in the dbidl list
dbidl
List of database IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UALLINFO
Retrieve all information
dbinfl
Returned list of UDBINF structures, each containing information
about a separate database (corresponding to the dbidl list)
statusl
Returned list of status values, one for each dbinfl entry
status
Returned status of the function
Returns a UDBINF database information structure for each valid database ID.
The parameter infclas controls how much database information is returned to each
UDBINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
335
Information retrieval classes are ordered according to system overhead usage:
UNOCLASS information uses the least amount of overhead, while UALLINFO uses
the most.
The UNOCLASS option specifies that only essential information defined by the
UDBINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1, UCLASS2 and UCLASS3 categories, which are defined in the
structure UDBINF, retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UDBINF
structure is to be retrieved.
For a description of the UDBIN structure, see “The RHLI Structures” chapter.
For columns successfully retrieved by specifying UCLASS2, UCLASS3 or
UALLINFO retrieval classes, storage space is allocated by Unify DataServer for
UDBINF structure members uvidlst and descrpt by calling malloc function. This
space should be released when the information is no longer needed by calling the free
function.
Security
No privileges required.
However, volume information is only returned if you have DBA authority.
For information about granting DBA authority, see uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
336
Example
This example uses the uinfdb function to retrieve information about the current
database.
if (uinfdb(txid,ndb,dbidl,UALLINFO,dbinfl,statusl,&status) != USUCCESS)
{
printf(”Unable to get info on database: status = %ld\n”,status);
uexit(1);
}
else {
for(dbindx=0; dbindx < ndb; ++dbindx)
{
prdbinf(&dbinfl[dbindx]);
for(volindx=0; volindx < dbinfl[dbindx].nvol; ++volindx)
prvolin(&(dbinfl[dbindx].uinfvol[volindx]));
if ( ndb > 0 )
free(dbinfl[dbindx].uinfvol);
}
}
See Also
uadddb, ubnddb, uclsdb, ulckdb, umoddb, uopndb
chmod(2), chown(2), malloc(3), and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
337
uinfhsh
Retrieve hash index information
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinfhsh( txid, nht, hidl, infclas, hinfl, statusl, status )
UTXID txid;
int nht;
UHID *hidl;
UOPTS infclas;
UHTINF *hinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nht
Number of hash table IDs in the hidl list
hidl
List of hash table IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UALLINFO
Retrieve all information
hinfl
Returned list of UHTINF structures, each containing information
about a separate hash table (corresponding to the hidl list)
statusl
Returned list of status values, one for each hinfl entry
status
Returned status of the function
Returns a UHTINF hash table information structure for each hash table ID listed in
hidl.
The parameter infclas controls how much hash table information is returned to each
UHTINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
338
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UHTINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1, UCLASS2 and UCLASS3 categories (which are defined in the
structure UHTINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UHTINF
structure is to be retrieved.
For a description of the UHTINF structure, see “The RHLI Structures” chapter.
For columns successfully retrieved by specifying UCLASS2 or UALLINFO retrieval
classes, storage space is allocated by Unify DataServer for UHTINF structure
member htloc by calling the malloc function. This space should be released (by
calling the free function) when the information is no longer needed.
Security
Hash table information can be retrieved only for hash indexes on tables that you have
access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Volume information is only returned if you have DBA authority.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
339
Example
This example uses the uinfhsh function to retrieve information about a hash index.
if (ubndhsh(txid, $parts$, 1, ”part_number”, &hidl[0], &statusl[0],
&status) != USUCCESS)
uexit(1);
if (ubndhsh(txid, $parts$, 1, ”ord_number”, &hidl[1], &statusl[1],
&status) != USUCCESS)
uexit(1);
if (uinfhsh(txid,2,hidl,UALLINFO,hinfl,statusl,&status) != USUCCESS)
{
printf(”Unable to get info on hash tables: status = %ld\n”,status);
uexit(1);
}
See Also
uaddhsh, uallhsh, ubndath, udrphsh, umaphsh, umodhsh
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using hash tables, see “Managing the Database Files,”
“Choosing an Access Method,” and “Tuning the Access Methods” in Unify
DataServer: Managing a Database.
340
uinflck
Retrieve data lock information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinflck( txid, tid, rid, lcktype, status )
UTXID txid;
UTID tid;
URID rid;
int *lcktype;
USTATUS *status;
Arguments
txid
The current transaction ID
tid
The table ID of the row’s table or UNULLTID
rid
The row ID of the row whose locking status is checked or
UNULLRID
lcktype
status
Description
Returned lock type of the object. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
Returned status of the function
Retrieves data lock information for a row, table, or database. The lock type is
returned into lcktype.
To retrieve lock information for a row, set tid to the row table ID and rid to the row
ID.
To retrieve data lock information for a table, set tid to the row’s table ID and rid to
UNULLRID.
341
To retrieve data lock information for a database, set tid to UNULLTID and rid to
UNULLRID.
The lock information being retrieved must match exactly with the lock placed on the
object. For example, if a row lock is promoted to a table lock and you retrieve lock
information for a row in that table, uinflck function returns an error.
To retrieve definition lock information for a table, use the uinfsch function.
Security
Table data lock information can be retrieved only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uinflck function to retrieve information about row, table, and
database locks.
/* define required parameters */
int lcktype
URID rid;
int prevlck;
USTATUS fstatus;
UTXID txid;
USTATUS status;
...
/* open the database */
...
/* retrieve row ID */
...
/* retrieve row lock information */
if (uinflck(txid, $company.$, rid, &lcktype, &status) != USUCCESS)
{
printf(”row is not locked\n”);
uexit(101);
}
printf(”row is locked with type %d\n”, lcktype);
342
/* retrieve table lock information */
if (uinflck(txid, $company.$, UNULLRID, &lcktype, &status) != USUCCESS)
{
printf(”table is not locked\n”);
uexit(102);
}
printf(”table is locked with type %d\n”, lcktype);
/* retrieve database lock information */
if (uinflck(txid, UNULLTID, UNULLRID, &lcktype, &status) != USUCCESS)
{
printf(”database is not locked\n”);
uexit(103);
}
printf(”database is locked with type %d\n”, lcktype);
See Also
uinfsch, ulckdb, ulckrow, ulcksch, ulcktbl, uulkdb, uulkrow, uulksch, uulktbl
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
343
uinflnk
Retrieve link information
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinflnk( txid, nlnk, lidl, infclas, lnkinfl, statusl, status )
UTXID txid;
int nlnk;
ULID *lidl;
UOPTS infclas;
ULNKINF *lnkinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
344
txid
Transaction ID
nlnk
Number of Link IDs in the lidl list
lidl
List of Link IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UALLINFO
Retrieve all information
lnkinfl
Returned list of ULNKINF structures, each containing information
about a separate link (corresponding to the lidl list)
statusl
Returned list of status values, one for each lnkinfl entry
status
Returned status of the function
Description
Returns a ULNKINF link information structure for each valid Link ID listed in lidl.
The parameter infclas controls how much link information is returned to each
ULNKINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
ULNKINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1 and UCLASS2 categories (which are defined in the structure
ULNKINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the ULNKINF
structure is to be retrieved.
For a description of the ULNKINF structure, see “The RHLI Structures” chapter.
For columns successfully retrieved by specifying UCLASS1 or UALLINFO retrieval
classes, storage space is allocated by Unify DataServer for UHTINF structure
members ploc and cloc by calling the malloc function. This space should be released
(by calling the free function) when the information is no longer needed.
Security
Link information is returned only for links on tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
345
Example
This example uses the uinflnk function to retrieve link information.
if (ubndlnk(txid, $parts$, 1, ”part_number”, &lidl[0], &statusl[0],&status)
!= USUCCESS)
{
uexit(1);
}
if (ubndlnk(txid, $parts$, 1, ”ord_number”, &lidl[1], &statusl[1],
&status) != USUCCESS)
if ((lnkinfl = (ULNKINF *)calloc(2, sizeof(ULNKINF))) == NULL)
{
uexit(1);
{
if (uinflnk(txid,2,lidl,UALLINFO,lnkinfl,statusl,&status) != USUCCESS )
{
fprintf(stderr,”Unable to get info on links: status = %ld\n”,status);
uexit(1);
}
See Also
uaddlnk, ualllnk, ubndlnk, udrplnk, ufchlnk, umaplnk, umodlnk
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
346
uinfsch
Retrieve definition lock information for a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfsch( txid, tid, lcktype, status )
UTXID txid;
UTID tid;
int *lcktype;
USTATUS *status;
Arguments
txid
The current transaction ID
tid
The table ID for the table you are inquiring about
lcktype
Returned lock type of the table. Options are:
status
Description
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
Returned status of the function
Retrieves the current definition lock type (lcktype) on the specified table (tid).
A definition lock prevents any other transactions from changing the definition of the
table. A data lock, however, prevents other operations from changing data contained
in the table rows.
To retrieve data lock information for a table, use the uinflck function.
Security
Table definition lock information can be retrieved only for tables you have access to.
347
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uinfsch function to retrieve information about object
definition locks on the company table. The lock type is printed.
/* define required parameters */
int lcktype
UTXID txid;
USTATUS status;
...
/* retrieve table definition lock information */
if (uinfsch(txid, $company.$, &lcktype, &status) != USUCCESS )
printf(”Table definition is not locked\n”);
else
printf(”Table definition is locked with type %d\n”, lcktype);
See Also
uinflck, ulcksch, uulksch
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
348
uinfscn
Create a list used for scan data retrieval
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfscn( txid, scaninf, dbvallp, status )
UTXID txid;
char *scaninf;
UDBVAL **dbvallp;
USTATUS *status;
Arguments
Description
txid
Transaction ID
scaninf
Pointer to a scan information structure
dbvallp
Location for storing the pointer to the allocated UDBVAL list
status
Returned status of the function
Builds a database value list from a pre-established scan projection list.
The scaninf member points to the scan information structure created by the ualcscn
function. The projection criteria for the scan must be specified (by calling the uinsprj
function) before calling the uinfscn function.
The uinfscn function allocates a UDBVAL list (and column value buffers) that
matches the projection criteria specified in scaninf. The pointer to the allocated
UDBVAL list is returned in the location pointed to by dbvallp. The UDBVAL items
appear in the same order that the columns were specified in the uinsproj function
reference.
The allocated UDBVAL list is used in future calls to the ufchscn function. When the
scan is completed, you must free the memory that was allocated for the UDBVAL list.
For a description of the UDBVAL structure, see the UNIPCOLL structure description
on “The RHLI Structures” chapter.
349
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uinsor, uinsand, uinssrt, uinsprj, ufchscn, ufrescn, ubegscn, uendscn, ufchscn
For information about scanning, see page 64.
350
uinftbl
Retrieve table information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinftbl( txid, ntbl, tidl, infclas, tblinfl, statusl, status )
UTXID txid;
int ntbl;
UTID *tidl;
UOPTS infclas;
UTBLINF *tblinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
Transaction ID
ntbl
Number of table IDs in the tidl list
tidl
List of table IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UCLASS4
Retrieve Class 4 information only
UALLINFO
Retrieve all information
tblinfl
Returned list of UTBLINF structures, each containing information
about a separate table (corresponding to the tidl list)
statusl
Returned list of status values, one for each tblinfl entry
status
Returned status of the function
351
Description
Returns a UTBLINF table information structure for each valid table ID in the tidl list.
The parameter infclas controls how much table information is returned to each
UTBLINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UTBLINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS option information is always retrieved, no matter which retrieval
class you choose.
The UCLASS1, UCLASS2, UCLASS3 and UCLASS4 categories, (which are defined in
the structure UTBLINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UTBLINF
structure is to be retrieved.
For a description of the UTBLINF structure, see “The RHLI Structures” chapter.
For table successfully retrieved by specifying UCLASS2, UCLASS3, UCLASS4 or
UALLINFO retrieval classes, storage space is allocated byUnify DataServer for
UTBLINF structure members ucidlst, ubidlst, uhidlst, ulidlst, keycidl and uvidlst by
calling the malloc function. This space should be released (by calling free function)
when the information is no longer needed.
Security
Table information can be retrieved only for tables and access methods you have
access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Volume information is only returned if you have DBA authority.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
352
Example
The following example uses the uinftbl function to retrieve table information.
#define FREEIT(nitem, sptr) if (nitem > 0) free(sptr);
if (ualltbl(txid, UNULLAID, USLCK, &ntbl, tidl, &status) != USUCCESS)
uexit(1);
if ((tblinfl = (UTBLINF *)calloc(ntbl, sizeof(UTBLINF))) == NULL)
uexit(1);}
if (uinftbl(txid, ntbl, tidl, UALLINFO, tblinfl, statusl, &status)!=USUCCESS)
{
printf(”Unable to retrieve info on tables: status = %ld\n”,status);
FREEIT(ntbl, tblinfl)
FREEIT(ntbl, statusl)
uexit(1);
}
/* Print contents of TBLINF structure and deallocate space */
for ( tblindx = 0; tblindx < ntbl; ++tblindx )
{
/* Print table information */
prtblinf(&tblinfl[tblindx]);
for ( colindx = 0; colindx < tblinfl[tblindx].ncol; ++colindx )
/* Print column information */
prcolin(tblinfl[tblindx].ucidlst[colindx]);
FREEIT(colindx, tblinfl[tblindx].ucidlst)
for ( volindx = 0; volindx < tblinfl[tblindx].nvol; ++volindx )
/* Print volume information */
prvolin(tblinfl[tblindx].uvidlst[volindx]));
FREEIT(volindx, tblinfl[tblindx].uvidlst)
FREEIT(tblinfl[tblindx].nbtree, tblinfl[tblindx].ubidlst)
FREEIT(tblinfl[tblindx].nhsh, tblinfl[tblindx].uhidlst)
FREEIT(tblinfl[tblindx].nlnk, tblinfl[tblindx].ulidlst)
FREEIT(tblinfl[tblindx].nkey, tblinfl[tblindx].keycidl)
FREEIT(ntbl, statusl)
}
See Also
uaddtbl, ualltbl, ubndtbl, udrptbl, ufchtbl, uinfsch, uinstbl, ulcktbl, umaptbl,
unumtbl, uulktbl
malloc(3) and free(3) in your UNIX system manual
353
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
354
uinftx
Retrieve transaction information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinftx( dbid, ntx, txl, infclas, txinfl, statusl, status )
UDBID dbid;
int ntx;
UTXID *txl;
UOPTS infclas;
UTXINF *txinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
The database ID (issued by the uopndb function)
ntx
Number of transaction IDs in the txl list
txl
List of transaction IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve transaction ID and whether logging is on
UCLASS1
Retrieve Class 1 information
UALLINFO
Retrieve all information
txinfl
Returned list of UTXINF structures, each containing information
about a separate transaction (corresponding to the txl list) for the
current database (specified by dbid)
statusl
Returned list of status values, one for each txinfl entry
status
Returned status of the function
Returns a UTXINF transaction information structure for each valid transaction ID in
the txl list.
The infclas parameter controls how much transaction information is returned to each
UTXINF structure. You can specify more than one option by separating the options
with the bitwise logical OR operator (|).
355
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1 category, retrieves the specified information for that class only. See
the UTXINF structure for a list of the UCLASS1 retrieved information.
The information retrieval classes (specified by infclas) require different amounts of
system overhead usage: UNOCLASS information uses the least amount of overhead,
while UALLINFO uses the most.
For a description of the UTXINF structure, see “The RHLI Structures” chapter.
You must allocate the storage space required for the transaction information
structures. When the space is no longer needed, you must free the space.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uabttx, ualltx, ubegtx, ucbgtx, ucmttx
For information about transaction management, see “Managing Transactions and
Locks” in Unify DataServer: Managing a Database.
356
uinfusr
Retrieve user information
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinfusr( txid, nuser, usridl, infclas, usrinfl, statusl, status )
UTXID txid;
int nuser;
UOID *usridl;
UOPTS infclas;
UUSRINF *usrinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nuser
Number of user IDs in the usridl list
usridl
List of user IDs to retrieve information about or UNULLUID
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UALLINFO
Retrieve all information
usrinfl
Returned list of UUSRINF structures, each containing information
about a separate user (corresponding to the usridl list)
statusl
Returned list of status values, one for each usrinfl entry
status
Returned status of the function
Returns a UUSRINF user information structure for each valid user ID. Returns curaid
in usrinfl only for the current user, and UNULLAID for other users. For a description
of the UUSRINF structure, see “The RHLI Structures” chapter.
The parameter infclas controls how much user information is returned to each
UUSRINF structure.
357
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UUSRINF structure is to be retrieved. No optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1, UCLASS2 and UCLASS3 categories (which are defined in the
structure UUSRINF), retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UUSRINF
structure is to be retrieved.
You can combine retrieval classes by OR’ing the infclas values together, separated by
single bars (|).
If the usridl member points to UNULLUID, this function returns information about
the current user.
For columns successfully retrieved by specifying UCLASS2 or UALLINFO retrieval
classes, storage space is allocated by Unify DataServer for UUSRINF structure
member aidlst by calling malloc function. This space should be released (by calling
the free function) when the information is no longer needed.
Security
User information is returned as follows:
If you have DBA authority, information about any user is available.
If you don’t have DBA authority, only information about your user ID is
available.
For information about granting DBA authority, see the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
358
Example
This example calls the uinfusr function to retrieve user information.
/* define required parameters */
UTXID
txid;
UOID
* usridl;
UUSRINF * usrinfl;
USTATUS
statusl;
USTATUS
status;
/* Retrieve user ID (usridl) */
...
/* Fetch user information */
if (uinfusr(txid, 2, usridl, UALLINFO, usrinfl, statusl, &status) != USUCCESS)
fprintf(stderr,”Unable to get info on user: status = %ld\n”, status);
See Also
uaddusr, uallusr, ubndusr, udrpusr, umodusr, unumusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
359
uinfvol
Retrieve volume information
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinfvol( txid, nvol, vidl, infclas, volinfl, statusl, status )
UTXID txid;
int nvol;
UVID *vidl;
UOPTS infclas;
UVOLINF *volinfl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
nvol
Number of volume IDs in the vidl list
vidl
List of volume IDs to retrieve information about
infclas
Information retrieval class. Options are:
UNOCLASS
Retrieve essential information only
UCLASS1
Retrieve Class 1 information only
UCLASS2
Retrieve Class 2 information only
UCLASS3
Retrieve Class 3 information only
UALLINFO
Retrieve all information
volinfl
Returned list of UVOLINF structures, each containing information
about a separate volume (corresponding to the vidl list)
statusl
Returned list of status values, one for each volinfl entry
status
Returned status of the function
Returns a UVOLINF volume information structure for each valid volume ID.
The parameter infclas controls how much volume information is returned to each
UVOLINF structure. You can specify more than one option by separating the options
with the bitwise logical operator (|).
360
Information retrieval classes (specified by infclas) are ordered according to system
overhead usage: UNOCLASS information uses the least amount of overhead, while
UALLINFO uses the most.
The UNOCLASS option specifies that only essential information defined by the
UVOLINF structure is to be retrieved. no optional information is retrieved.
The UNOCLASS information is always retrieved, no matter which retrieval class you
choose.
The UCLASS1, UCLASS2 and UCLASS3 categories, which are defined in the
structure UVOLINF, retrieve the specified information for that class only.
The UALLINFO option specifies that all the information defined for the UVOLINF
structure is to be retrieved.
For a description of the UVOLINF structure, see “The RHLI Structures” chapter.
For columns successfully retrieved by specifying UCLASS2 or UALLINFO retrieval
classes, storage space is allocated by Unify DataServer for UVOLINF structure
member utidlst by calling the malloc function. This space should be released (by
calling the free function) when the information is no longer needed.
The volume length number (vollen) of volinf will be in bytes, wherever the volume
size is less than 2 GB. Otherwise, DB_BIG will be set in volopts, and vollen will
represent the number of pages.
Security
You must have DBA authority to retrieve volume information.
For information about granting DBA authority, see the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
The following example uses the uinfvol function to retrieve volume information.
if (uinfvol(txid, nvol, vidl, UALLINFO, volinfl, statusl,&status) != USUCCESS)
printf(“Unable to retrieve info on volumes: status = %ld\n”,status);
361
See Also
uadddb, uaddvol, uallvol, ubndvol, udrpvol, umapvol, umodvol, unumvol
malloc(3) and free(3) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
362
uinimsg
Initialize the message-logging facilities
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinimsg( prgnm, status )
char *prgnm;
USTATUS *status;
Arguments
Description
prgnm
The name of the current application’s executable, typically argv[0]
status
Returned status of the function
Initializes the error-logging facilities of the database. Error logging is explicitly
accomplished by calling the ulogmsg function. Error logging also happens when a
serious error is encountered while performing a database operation.
If you do not call the uinimsg function, messages written to the error log do not
contain the executable name.
You normally call the uinimsg function once to perform one-time-only initialization
operations. Subsequent calls to the uinimsg function can change the current
executable name.
The uinimsg function should be called prior to opening a database.
Security
No privileges required.
363
Example
This example uses the uinimsg function to initialize the error-logging file (errlog).
Error messages are logged to the errlog file by using the ulogmsg function.
/* define required RHLI parameters */
USTATUS status;
USTATUS lstats;
...
/* initialize the logging facilities */
if ( uinimsg(argv[0], &status) != USUCCESS))
{
printf (”error initializing error logging with program name;”);
if ((errmsg = ufchmsg(status, &fstatus)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is : %s\n”,errmsg);
}
/* open the database */
if ( uopndb ( dbname, DB_NORMAL, &dbid, &status) != USUCCESS )
{
printf (”unable to open the database;”);
if ((errmsg = ufchmsg(status, &fstatus)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is : %s\n”,errmsg);
}
/* log error messages
...
*/
See Appendix A for more examples.
See Also
ufchmsg, ulogmsg
For information about message handling, see “Error Handling” on page 51.
364
uinsand
Allocate a criteria structure for a scan
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinsand( txid, scaninf, numexp, status )
UTXID txid;
char *scaninf;
int numexp;
USTATUS *status;
Arguments
Description
txid
Transaction ID
scaninf
Pointer to the scan information structure
numexp
Number of expressions in conditions associated with the query that
builds the scan
status
Returned status of the function
Allocates the storage for a criteria structure. The criteria structure is determined by
the uinsor function.
You must call this function before you call the uinsor function.
The numexp parameter specifies the number of expressions in the OR-groups
associated with the scan.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
365
Example
See Appendix A.
See Also
uinsprj, ualcscn, ufrescn, uinssrt, uinsor
366
uinsbuf
Allocate buffer
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinsbuf( txid, scaninf, rmtbufsz, status )
UTXID txid;
char * scaninf;
long rmtbufsz;
USTATUS * status;
Arguments
Description
txid
The current Transaction ID.
scaninf
Pointer to the scan information structure
rmtbufsz
Remote row buffer size in number of rows
status
Pointer to the value that indicates the status of the function’s
operation
The remote buffer size is the number of rows to buffer. If uinsbuf is not used to
specify the remote row buffer size, the value of the shared configuration variable
RMTROWBUFSZ is used to determine this size.
Any required locking occurs when the rows are placed in the buffer.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
367
Example
The following example shows how to use uinsbuf.
USTATUS
status; /*
USTATUS
fchstat; /*
UDBID
dbid;
/*
UTXID
txid;
/*
char
* scaninf; /*
UDBVAL
tstval;
UDBVAL
* prjvall;
USTATUS
statusl[4];
UTP_HINT
monumv;
int
scnid;
URID
rowid;
int
prevlck;
status returned by RHLI functions */
status returned by ufchmsg( ) */
Database ID from uopndb( ) */
Transaction ID */
scan descriptor */
/* Allocating a Scan Structure */
if ( ualcscn(txid, 2, 0, 3, &scaninf, &status) == UFAILURE )
{
printf(”ualcscn( ) failed;\n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
/* Adding selection criteria */
if ( uinstbl(txid, scaninf, $model.$, &status) == UFAILURE )
{
printf(”uinstbl( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
/* set remote scan buffer size */
if ( uinsbuf(txid, scaninf, 20L, &status) == UFAILURE )
{
printf(”uinsbuf( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
if ( (uinsprj(txid,scaninf,$model.monum$,&status) == UFAILURE)
||
(uinsprj(txid,scaninf,$model.momano$,&status) == UFAILURE)
||
(uinsprj(txid,scaninf,$model.mdes$,&status) == UFAILURE) )
368
{
printf(”uinsprj( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
if ( uinsand(txid, scaninf, 1, &status) == UFAILURE )
{
printf(”uinsand( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
tstval.unip.hintp = &monumv;
tst.val.unip.valopt = UNORMAL
monumv = 5;
if ( uinsor(txid, scaninf, $model.monum$, UGTTST, &tstval,
(UDBVAL *)0, &status) == UFAILURE )
{
printf(”uinsor( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
if ( uinsand(txid, scaninf, 1, &status) == UFAILURE )
{
printf(”uinsand( ) failed:\n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
monumv = 17;
if ( uinsor(txid, scaninf, $model.monum$, ULTTST, &tstval,
(UDBVAL *)0, &status) == UFAILURE )
{
printf(”uinsor( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
369
if ( uinfscn(txid, scaninf, &prjvall, &status) == UFAILURE )
{
printf(”uinfscn( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
if ( ubegscn(txid,USLCK,scaninf,&scnid,&status) == UFAILURE )
{
printf(”ubegscn( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
printf(”Scanning for ’monum’ values between 5 and 17\n”);
while ( ufchscn(scnid, &rowid, prjvall, &prevlck, statusl,
&status) != UFAILURE )
{
printf(”rowid = %ld\n”, rowid);
printf(”monum = %ld\n”, *prjvall[0].unip.hintp);
printf(”momano = %d\n”, *prjvall[1].unip.intp);
}
if ( uendscn(scnid, &status) == UFAILURE )
{
printf(”uendscn( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
free((char
free((char
free((char
free((char
*)prjvall[0].unip.hintp);
*)prjvall[1].unip.intp);
*)prjvall[2].unip.strp);
*)prjvall);
/* Resetting the Scan Info. Structure */
if ( ufrescn(txid, scaninf, DB_RESET, &status) == UFAILURE )
{
printf(”ufrescn( ) failed: \n”);
if ((errmsg = ufchmsg(status, &fchstat)) == NULL)
printf(”error fetching message\n”);
else
printf(”error is %s\n”, errmsg);
uexit(1);
}
370
See Also
ualcscn, ufrescn, uinsand, uinsor, uinsprj, uinssrt, uinstbl, ualcscn.
RMTROWBUFSZ configuration variable description in Unify DataServer:
Configuration Variable and Utility Reference.
371
uinsor
Insert an expression into an OR group of the scan selection criteria
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uinsor( txid, scaninf, cid, rop, val1, val2, status )
UTXID txid;
char *scaninf;
UCID cid;
int rop;
UDBVAL *val1;
UDBVAL *val2;
USTATUS *status;
Arguments
Description
txid
Transaction ID
scaninf
Pointer to the scan information structure
cid
Column ID of the column to be compared
rop
A value indicating the relational operator for the comparison
val1
Pointer to a UDBVAL structure that contains the first value to
compare against column values for the selection criteria
val2
Pointer to a UDBVAL structure that contains the second value to
compare against column values for the selection criteria
status
Returned status of the function
Adds a unary, binary, or range expression to the selection criteria for a column.
The values cid, rop, and optionally val1 and val2 make up a selection criterion. If you
specify more than one selection criterion on the same column, the criteria are grouped
to form a logical OR-group.
372
If more than one OR-group exists, the OR-groups are logically ANDed to comprise
the selection criteria.
To initialize the selection criteria for a scan, call the uinsand function. The target
table must be established by calling the uinstbl function before calling the uinsor
function.
By using this function, you can represent most database queries. Queries that can be
expressed on a single form of an ACCELL/SQL application can be performed using a
single scan. Other queries require more than one scan.
Performance
If the number of expressions passed into the uinsand function (numexp) is greater
than zero (which reflects the number of calls to the uinsor function), all the storage
space is pre-allocated for maximum performance. To further enhance performance,
specify the total number of OR-groups when calling the ualcscn function.
The value of rop indicates a unary, binary or a range selection criterion. Unary
operators are the following null value tests:
UISNULL
Null value
UNOTNULL
Not a null value
UTTST
Always true
UFTST
Always false
Binary operators require only val1 to be passed in. Valid binary operators for rop are:
UEQTST
Equal
UNETST
Not equal
ULTTST
Less than
ULETST
Less than or equal
UGTTST
Greater than
UGETST
Greater than or equal
ULIKE
Like pattern matching
%" matches 0 or more characters
_" matches a single character
\" escapes any character
UREGEXP
Regular expression pattern matching
373
UGLOB
GLOB pattern matching (GLOB is a UNIX pattern matching
operation)
For more information about pattern matching, see the “Selecting Rows and Columns”
chapter in Unify DataServer: Writing Interactive SQL/A Queries.
Range operators require both val1 and val2 and specification of end point inclusion.
Valid range operators for rop are:
URNGOO
Range: points(open,open)
URNGOC
Range: points(open,closed)
URNGCO
Range: points(closed,open)
URNGCC
Range: points(closed,closed)
Open end points mean that the end point value is not included in the test range.
Closed end points mean that the end point value is included in the test range.
Parameters val1 and val2 are pointers to separate UDBVAL structures that contain
comparison values. For a description of the UDBVAL structure, see “The RHLI
Structures” chapter.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See appendix A.
See Also
ualcscn, ufrescn, uinsand, uinsprj, uinssrt, uinstbl
374
uinsprj
Add a column to the projection list of a scan
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinsprj( txid, scaninf, ncol, cidl, statusl, status )
UTXID txid;
char *scaninf;
int ncol;
UCID *cidl;
USTATUS *statusl;
USTATUS *status;
Arguments
Description
txid
Transaction ID
scaninf
Pointer to the scan information structure
ncol
Number of columns in the column ID list
cidl
Column ID list to add in the projection
status
Returned status of the function
Adds a column to the projection list of columns from rows returned from a scan. The
uinsprj function must be used for each column that is to be included in the
projection.
The order in which columns are added to the projection by calling the uinsprj
function defines the order of the columns in the rows returned from the scan.
Multiple calls to the same scan are allowed.
The target table must be established by calling the uinstbl function before calling the
uinsprj function.
Security
No privileges required.
375
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uinssrt, ufrescn, ualcscn, uinsor, uinsand
376
uinsrow
Insert a row into a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinsrow( txid, tid, rid, unipcoll, statusl, status )
UTXID txid;
UTID tid;
URID *rid;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table
rid
Row ID of the newly created row
unipcoll
A pointer to a UNIPCOLL structure which specifies the values of the
columns of the row to insert
statusl
Returned status value for each column listed in the UNIPCOLL
column list cidl
status
Returned status of the function.
Creates a new row and initializes the row’s column values with the values passed in
from the UNIPCOLL structure. The UNIPCOLL structure (pointed to by unipcoll)
describes the data being inserted into or retrieved from the database. This structure
contains several lists which describe both the column and the column’s value.
All of the columns specified in UNIPCOLL must belong to the table ID specified in
tid. For a description of the UNIPCOLL structure, see “The RHLI Structures” chapter.
377
If no initial value is specified for a column and the column is not defined as a direct
key, Unify DataServer checks the Data Integrity Subsystem (DIS) file for a default
value. For more information about DIS, see Unify DataServer: Managing a Database.
If the non-initialized column is defined as a direct key, Unify DataServer assigns the
next consecutive value to the column.
If no DIS value is defined for column (or the column is not a direct key), then the
non-initialized column is set to a null value.
If a primary key has been specified for the table, a value for the key column must be
defined (in UNIPCOLL) or the new row is rejected. If any portion of the row insert is
in error, the entire row is rejected and an error is generated.
When inserting into or updating columns of type U_STR (string), Unify DataServer
adds trailing blanks to values less than the total size defined for the column.
Security
A row can be inserted into a table that you have access to only.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted insert schema privileges to the other schema. If you have DBA authority,
you can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
udelrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about the data integrity subsystem (DIS), see “Initializing a
Database” in Unify DataServer: Managing a Database.
378
uinssrt
Insert a column to the sort criteria
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinssrt( txid, scaninf, cid, ascflg, status )
UTXID txid;
char *scaninf;
UCID cid;
int ascflg;
USTATUS *status;
Arguments
txid
Transaction ID
scaninf
Pointer to the scan information structure
cid
Column ID of the column to be a sort key
ascflg
Specifies the order of comparison for the key. Options are:
status
Description
DB_ASCEND
Ascending key value
DB_DESCND
Descending key value
Returned status of the function
Adds a column to the sort criteria, specifying the comparison order.
The column ID specified (as cid) is added as a sort key of the order in which the
ufchscn function returns a projection from a scan.
The uinssrt function adds each column to the sort criteria in calling order. The first
call to the uinssrt function defines the primary sort key, the second call defines the
secondary sort key, and so on.
This function must be used for each column that is to be included in the sort key.
Before calling the uinssrt function, you must establish the target table by calling the
uinstbl function.
379
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uinsprj, ualcscn, ufrescn, uinsor, uinsand
For information about scanning, see page 64.
380
uinstbl
Specify the target table for a scan.
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uinstbl( txid, scaninf, tid, status )
UTXID txid;
char *scaninf;
UTID tid;
USTATUS *status;
Arguments
Description
txid
Transaction ID
scaninf
Pointer to the scan information structure
tid
Table ID of the target table for the scan
status
Returned status of the function
Establishes the target table for a scan.
If a target table has already been set, an error occurs. The uinstbl function must be
called before any calls to the uinsor, uinsprj, uinssrt, or ubegscn functions.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ualcscn, ufrescn, uinsand, uinsor, uinsprj, uinssrt
For information about scanning, see page 64.
381
uintext
Convert column values from internal format to external format
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uintext( txid, tid, unipcoll, unipext, statusl, status )
UTXID txid;
UTID tid;
UNIPCOLL *unipcoll;
UNIPEXT *unipext;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table columns contained in UNIPCOLL
unipcoll
A pointer to a UNIPCOLL structure containing column values in
internal format to be converted into external format
unipext
A pointer to a UNIPEXT structure that is to contain the converted
column values from internal to external format. This list must
contain the same number of entries as the number of internal format
entries in UNIPCOLL (pointed to by unipcoll).
statusl
Returned status value for each column listed in the UNIPCOLL
column list cidl
status
Returned status of the function
Converts a list of data values from an internal format to the external format used by
the database.
To read and display data contained in columns of data type U_DATE, U_HDATE and
U_TIME it is necessary to first convert the data from internal (database) format to
external (display) format.
382
To update or insert date and time data into a Unify DataServer database, you must
first convert the data into internal format by calling the uextint function.
For each column in the internal format list described by the structure UNIPCOLL
(pointed to by unipcoll), each internal column data value is converted to external
format and stored in a UNIPEXT structure (pointed to by unipext).
For a description of the UNIPEXT and UNIPCOLL structures, see “The RHLI
Structures” chapter.
All columns specified in each UNIPCOLL structure must belong to the specified table
ID (tid).
Any valopts member contained in the UNIPCOLL structure that contains a value of
UIGNORE is bypassed; no value is converted for that entry. Also, the entry for statusl
is set to UENOWRK.
All column values must be converted to external format after being retrieved from the
database. See the ufchrow function for more information.
If the destination column structure value pointer is null, storage space is allocated by
Unify DataServer. This space must then be deallocated by calling the system
subroutine free function. If the value pointer is not null, it is assumed that enough
space exists for the converted value.
A value that cannot be converted is rejected. Check each status value in statusl to
determine which values could not be converted.
Security
To convert column values, you must have access to the column value that you want to
convert.
You can always access all columns in the tables in the current schema. Additionally,
you can access tables (or just columns within a table) in other schemas if your current
schema has been granted schema privileges to the other schema. If you have DBA
authority, you can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
383
Example
See Appendix A.
See Also
uextint, uinsrow, ufchrow, uupdrow
free(3) in your UNIX system manual
For information about converting from internal to external formats, see page 35.
384
ulckdb
Lock a database
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ulckdb( txid, lcktype, nretry, prevlck, status )
UTXID txid;
int lcktype;
long nretry;
int *prevlck;
USTATUS *status;
Arguments
Description
txid
Transaction ID
lcktype
The lock type to place on the database. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nretry
The number of times to attempt acquiring the lock before failing; if
set to 0L, then the value set by the LMNRETRY configuration variable
is used
prevlck
Pointer to the previous lock type. If the database lock was not
granted, the lock type returned is the conflicting lock value.
status
Returned status of the function
Locks the database associated with the transaction. No changes can be made to the
database by other transactions while the lock is held. A database lock locks all tables
and rows for that database.
If the database lock is granted, the previous lock type is returned into prevlck;
otherwise, the conflicting lock value is returned.
385
You cannot acquire an exclusive lock on the database unless all users have opened the
database (by calling the uopndb function) with the DB_NOLOCK option. You may
not be able to acquire an exclusive lock if data definition locks placed by Unify
DataServer conflict with database lock requests.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ulckdb function to acquire a shared lock on the database
associated with the dbid value.
/* define required parameters */
UTXID
txid;
UDBID
dbid;
int
lcktype;
long
nretry;
int
prevlck;
USTATUS status;
...
/* open the database and begin a transaction */
...
/* lock the database */
lcktype = USLCK;
nretry = 10;
if ( ulckdb(txid,lcktype, nretry, &prevlck, &status) != USUCCESS )
{
printf(”Unable to get database lock: status = %ld\n”,status);
uexit(99);
}
See Also
ulcksch, uulksch, ulckrow, uulkrow, ulcktbl, uulktbl, uulkdb
For more information about setting configuration variables, see Unify DataServer:
Configuration Variable and Utility Reference.
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
386
ulckrow
Lock a row
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int ulckrow(txid, tid, rid, lcktype, nretry, prevlck, status)
UTXID txid;
UTID tid;
URID rid;
int lcktype;
long nretry;
int *prevlck;
USTATUS *status;
Arguments
txid
Transaction ID
tid
Table of the row to lock
rid
Row ID of the row to lock
lcktype
The lock type to place on the row. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nretry
The number of times to attempt acquiring the lock before failing; if
set to 0L, then the value set by the LMNRETRY configuration variable
is used
prevlck
Pointer to the previous lock type. If the lock was not granted, the
lock type returned is the conflicting lock value.
status
Returned status of the function.
387
Description
Locks the row associated with the row ID for the specified table. No changes can be
made to the row data by other transactions while the lock is held.
If the row lock is granted, the previous lock type is returned into prevlck; otherwise,
the conflicting lock value is returned.
Security
Rows can be locked only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ulckrow function to acquire a shared lock on the row in the
company table with a rowid of 3.
/* define required parameters */
UTXID
txid;
URID
rid;
int
lcktype;
long
nretry;
int
prevlck;
USTATUS status;
...
/* open the database and begin a transaction */
...
/* lock the row */
lcktype = USLCK;
nretry = 10;
rid = 3;
if ( ulckrow(txid, $company.$, rid, lcktype, nretry, &prevlck,&status)
!= USUCCESS )
{
printf(”Unable to get a row lock: status = %ld\n”,status);
uexit(99);
}
...
388
See Also
uulkrow, ulcktbl, uulktbl, ulckdb, uulkdb
For more information about setting configuration variables, see Unify DataServer:
Configuration Variable and Utility Reference.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
389
ulcksch
Lock a table definition
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
bool ulcksch( txid, tid, lcktype, nretry, prevlck, status )
UTXID txid;
UTID tid;
int lcktype;
long nretry;
int *prevlck;
USTATUS *status;
Arguments
Description
txid
Current transaction ID
tid
Table ID of the table to lock
lcktype
The lock type to place on the table. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nretry
The number of times to attempt acquiring the lock before failing; if
set to 0L, then the value set by the LMNRETRY configuration variable
is used
prevlck
Pointer to the previous lock type. If the lock was not granted, the
lock type returned is the conflicting lock value.
status
Returned status of the function
Locks the definition for a table. A definition lock prevents any other transaction from
changing or deleting the definition for a table while table data is being accessed.
A table definition lock is separate from and does not interfere with data locks. To
acquire a data lock see the ulcktbl or the ulckrow function.
390
If the table definition lock is granted, the previous lock type is returned into prevlck;
otherwise, the conflicting lock value is returned.
To remove a table definition lock, call the uulksch function.
Security
Definition locks can only be acquired on tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ulcksch function to acquire an object definition lock on the
company table.
/* define required parameters */
UTXID
txid;
int
lcktype;
int
prevlck;
USTATUS status;
...
/* lock the table definition */
if (ulcksch(txid, $company.$, USLCK, 0L, &prevlck, &status) != USUCCESS)
{
printf(”SLOCK of company table failed—%ld\n”,status);
uexit(99);
}
See Also
uulksch
For more information about setting configuration variables, see the Unify
DataServer: Configuration Variable and Utility Reference.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
391
ulcktbl
Lock a table
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ulcktbl( txid, tid, lcktype, nretry, prevlck, status )
UTXID txid;
UTID tid;
int lcktype;
long nretry;
int *prevlck;
USTATUS *status;
Arguments
Description
txid
Transaction ID
tid
Table ID of the table to lock
lcktype
The lock type to place on the table. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
nretry
The number of times to attempt acquiring the lock before failing; if
set to 0L, then the value set by the LMNRETRY configuration variable
is used
prevlck
Pointer to the previous lock type. If the lock was not granted, the
lock type returned is the conflicting lock value.
status
Returned status of the function
Locks all rows in the table. No changes can be made to the table data by other
transactions while the lock is held.
If the table lock is granted, the previous lock type is returned into prevlck; otherwise,
the conflicting lock value is returned.
392
Security
Only tables you have access to can be data locked.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the ulcktbl function to acquire a lock on the company table.
/* define RHLI interface required parameters */
UTXID
txid;
UDBID
dbid;
int
lcktype;
long
nretry;
int
prevlck;
USTATUS status;
...
/* open the database and begin a transaction */
...
/* lock the table */
lcktype = USLCK;
nretry = 10;
if ( ulcktbl(txid, $parts.$, lcktype, nretry, &prevlck, &status) != USUCCESS )
{
printf(”Unable to get table lock: status = %ld\n”, status);
uexit(100);
}
See Also
uulkrow, ulckrow, uulktbl, ulckdb, uulkdb
For more information about setting configuration variables, see the Unify
DataServer: Configuration Variable and Utility Reference.
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about lock management, see “Managing Transactions and Locks” in
Unify DataServer: Managing a Database.
393
ulogmsg
Append a message to the error log
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int ulogmsg( callfnm, errnum, xtrainfo, status )
char *callfnm;
USTATUS errnum;
char *xtrainfo;
USTATUS *status;
Arguments
Description
txid
Transaction ID
callfnm
Name of the function from which the error logging is performed
errnum
The status error code
xtrainfo
Pointer to a character string containing any other relevant
information, or a null pointer if there is no other information
status
Returned status of this function
Appends the status error code (errnum), a corresponding error message, and related
information to the error log file DBNAME.err.
The error log file is searched for in the directory specified by the DBPATH
configuration variable. If the file is not found, error messages are written to the file
errlog. The error file DBNAME.err is usually linked to the file errlog.
If errlog cannot be found or cannot be opened or written to, this function fails.
Use the uinimsg function to initialize the error logging facilities.
Security
No privileges required.
394
Example
This example uses the ulogmsg function to log error messages to the errlog file. The
errlog file is initialized by using the uinimsg function.
See function uinimsg for the code.
See Appendix A for more examples.
See Also
ufchmsg, uinimsg
For information about error handling, see page 51.
395
umapath
Map a compile-time authorization ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umapath( dbid, nath, athmapl, statusl, status )
UDBID dbid;
int nath;
UATHMAP athmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by the uopndb function
nath
Number of authorization IDs in the athmapl list
athmapl
List of UATHMAP structures, each containing information about a
separate schema
statusl
Returned list of status values, one for each athmapl entry
status
Returned status of the function
Maps the compile-time authorization IDs stored in each UATHMAP structure to
runtime authorization IDs. Each UATHMAP structure must be initialized with schema
information. To initialize the UATHMAP structure, use the mapping macro command
INIATHMAP. For a description of the UATHMAP structure, see “The RHLI
Structures” chapter.
The mapping operation fails in these cases:
The schema specified in the athnm member of the UATHMAP structure does
not exist in the database.
The schema’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime authorization ID.
396
To map the value of an authorization ID that is already mapped, you must reset the
athnm member to (char *)0 or the null-string (“”). You cannot reset the ID of a
schema which has not been mapped.
Cross-mapping of authorization IDs is allowed.
The runtime authorization ID to which a compile-time authorization ID has been
mapped can also be obtained by calling the uinfath function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
Authorization IDs can be re-mapped only for schemas you have access to.
You always have access to the current schema. Additionally, you can access other
schemas if you have been granted schema access permission to the schema or if a
schema you can access has schema privileges to another schema (or a table or column
in the schema). If you have DBA authority, you can access any schema in the
database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uaddath, uallath, ubndath, udrpath, ufchath, uinfath, umodath, unumath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
397
umapbt
Map a compile-time B-tree ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umapbt( dbid, nbt, btmapl, statusl, status )
UDBID dbid;
int nbt;
UBTMAP btmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by calling the uopndb function
nbt
Number of B-tree IDs in the btmapl list
btmapl
List of UBTMAP structures, each containing information about a
separate B-tree
statusl
Returned list of status values, one for each btmapl entry
status
Returned status of the function.
Maps the compile-time B-tree IDs stored in each UBTMAP structure to runtime
B-tree IDs. Each UBTMAP structure must be initialized with B-tree information. To
initialize UBTMAP, use the mapping macro command INIBTMAP.
For a description of the UBTMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The B-tree specified in the UBTMAP member btnm does not exist in the
database.
The B-tree’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime B-tree ID.
398
You cannot map the value of a B-tree that is already mapped, or reset the ID of a
B-tree which has not been mapped.
To reset the value of a previously mapped B-tree ID, set the value of UBTMAP
member btnm to (char *)0 or the null-string (“”).
Cross-mapping of B-tree IDs is allowed.
The runtime B-tree ID to which a compile-time B-tree ID has been mapped can also
be obtained by calling the uinfbt function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
B-tree IDs can be re-mapped only for B-trees on tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddbt, uallbt, ubndbt, udrpbt, uinfbt, umodbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
399
umapcol
Map a compile-time column ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umapcol( dbid, ncol, colmapl, statusl, status )
UDBID dbid;
int ncol;
UCOLMAP colmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by the uopndb function
ncol
Number of column IDs in the colmapl list
colmapl
List of UCOLMAP structures, each containing information about a
separate column
statusl
Returned list of status values, one for each colmapl entry
status
Returned status of the function
Maps the compile-time column IDs stored in each UCOLMAP structure to runtime
column IDs. Each UCOLMAP structure must be initialized with column information
that is used to re-map a compile-time column ID to its runtime equivalent.
To initialize UCOLMAP, use the mapping macro command INICOLMAP. For a
description of the UCOLMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The column specified in the UCOLMAP member colnm does not exist in the
database.
The column’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime authorization ID.
400
You cannot map the value of a column that is already mapped, or reset the ID of a
column which has not been mapped.
To reset the value of a previously mapped column ID, set the value of UCOLMAP
member colnm to (char *)0 or the null-string (“”) .
Cross-mapping of column IDs is allowed.
The runtime column ID to which a compile-time column ID has been mapped can
also be obtained by calling the uinfcol function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
Column IDs can be re-mapped only for columns in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uaddcnm, uallcol, ubndcol, udrpcnm, uextint, ufchcnm, uinfcol, uintext,
umapcol, unumcol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
401
umaphsh
Map a compile-time hash table ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umaphsh( dbid, nhsh, hshmapl, statusl, status )
UDBID dbid;
int nhsh;
UHSHMAP hshmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by the uopndb function
nhsh
Number of hash table IDs in the hshmapl list
hshmapl
List of UHSHMAP structures, each containing information about a
separate hash table
statusl
Returned list of status values, one for each hshmapl entry
status
Returned status of the function
Maps the compile-time hash table IDs stored in each UHSHMAP structure to runtime
hash table IDs. Each UHSHMAP structure must be initialized with hash table
information that is used to re-map a compile-time hash table ID to its runtime
equivalent.
To initialize UHSHMAP, use the mapping macro command INIHSHMAP. For a
description of the UHSHMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The hash table specified in the UHSHMAP member hshnm does not exist in the
database.
The hash table’s runtime mapping ID specified in the member remapid does
not match the compile-time mapping ID.
Multiple values are mapped to the same runtime hash table ID.
402
You cannot map the value of a hash table that is already mapped, or reset the ID of a
hash table which has not been mapped. To reset the value of a previously mapped
hash table IDset the value of UHSHMAP member hshnm to (char *)0 or the
null-string (””). Cross-mapping of hash table IDs is allowed.
The runtime hash table ID to which a compile-time hash table ID has been mapped
can also be obtained by calling the uinfhsh function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
Hash table IDs can be re-mapped only for hash tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddhsh, uallhsh, undhsh, udrphsh, uinfhsh, umodhsh
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
403
umaplnk
Map a compile-time link ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umaplnk( dbid, nlnk, lnkmapl, statusl, status )
UDBID dbid;
int nlnk;
ULNKMAP lnkmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by the uopndb function
nlnk
Number of Link IDs in the lnkmapl list
lnkmapl
List of ULNKMAP structures, each containing information about a
separate link
statusl
Returned list of status values, one for each lnkmapl entry
status
Returned status of the function
Maps the compile-time Link IDs stored in each ULNKMAP structure to runtime Link
IDs. Each ULNKMAP structure must be initialized with link information. To initialize
ULNKMAP, use the mapping macro command INILNKMAP. For a description of the
ULNKMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The link specified in the ULNKMAP member lnknm does not exist in the
database.
The link’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime link ID.
404
You cannot map the value of a link that is already mapped, or reset the ID of a link
which has not been mapped.
To reset the value of a previously mapped link ID, set the value of ULNKMAP
member lnknm to (char *)0 or the null-string (“”) .
Cross-mapping of Link IDs is allowed.
The runtime Link ID to which a compile-time Link ID has been mapped can also be
obtained by calling the uinflnk function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
Link IDs can be re-mapped only for links in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddlnk, ualllnk, ubndlnk, udrplnk, ufchlnk, uinflnk, umodlnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
405
umaptbl
Map a compile-time table ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umaptbl( dbid, ntbl, tblmapl, statusl, status )
UDBID dbid;
int ntbl;
UTBLMAP tblmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by the uopndb function
ntbl
Number of table IDs in the tblmapl list
tblmapl
List of UTBLMAP structures, each containing information about a
separate table
statusl
Returned list of status values, one for each tblmapl entry
status
Returned status of the function
Maps the compile-time table IDs stored in each UTBLMAP structure to runtime table
IDs. Each UTBLMAP structure must be initialized with table information. To
initialize UTBLMAP, use the mapping macro command INITBLMAP. For a
description of the UTBLMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The table specified in the UTBLMAP member tblnm does not exist in the
database.
The table’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime table ID.
406
You cannot map the value of a table that is already mapped, or reset the ID of a table
which has not been mapped.
To reset the value of a previously mapped table ID, set the value of UTBLMAP
member tblnm to (char *)0 or the null-string (“”) .
Cross-mapping of table IDs is allowed.
The runtime table ID to which a compile-time table ID has been mapped can also be
obtained by calling the uinftbl function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
Table IDs can be re-mapped only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
uaddtbl, uaddtnm, ualltbl, ubndtbl, udrptbl, udrptnm, ufchtnm, uinftbl,
ulcksch, ulcktbl, unumtbl, uulksch, uulktbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
407
umapvol
Map a compile-time volume ID to its runtime equivalent
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umapvol( dbid, nvol, volmapl, statusl, status )
UDBID dbid;
int nvol;
UVOLMAP volmapl[];
USTATUS statusl[];
USTATUS *status;
Arguments
Description
dbid
Database ID issued by uopndb function
ntbl
Number of volume IDs in the volmapl list
volmapl
List of UVOLMAP structures, each containing information about a
separate table
statusl
Returned list of status values, one for each volmapl entry
status
Returned status of the function
Maps the compile-time volume IDs stored in each UVOLMAP structure to runtime
volume IDs. Each UVOLMAP structure must be initialized with volume information.
To initialize UVOLMAP, use the mapping macro command INIVOLMAP. For a
description of the UVOLMAP structure, see “The RHLI Structures” chapter.
The mapping operation fails in these cases:
The volume specified in the UVOLMAP member volnm does not exist in the
database.
The volume’s runtime mapping ID specified in the member remapid does not
match the compile-time mapping ID.
Multiple values are mapped to the same runtime volume ID.
408
You cannot map the value of a volume that is already mapped, or reset the ID of a
volume which has not been mapped.
To reset the value of a previously mapped volume ID, set the value of UVOLMAP
member volnm to (char *)0 or the null-string (“”) .
Cross-mapping of volume IDs is allowed.
The runtime volume ID to which a compile-time volume ID has been mapped can
also be obtained by calling the uinfvol function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Security
You must have DBA authority to re-map a volume ID.
For information about granting DBA authority, see uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uaddprf, uaddvol, uallvol, ubndvol, udrpprf, udrpvol, uinfvol, umodvol,
unumvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
409
umodath
Modify a schema name
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodath( txid, nauth, dbauthl, statusl, status )
UTXID txid;
int nauth;
DBAUTH *dbauthl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nauth
Number of schemas in the dbauthl list
dbauthl
List of DBAUTH structures, each describing a separate schema to
modify
statusl
Returned list of status values, one for each dbauthl entry
status
Returned status of the function
Modifies the schema name for one or more schemas listed in the dbauthl list. Each
DBAUTH structure in the dbauthl list contains information about a schema. For a
description of the DBAUTH structure, see “The RHLI Structures” chapter.
Schema names specified in the dbauthl list must be unique within the database.
Security
To modify a schema name, you must have one of the following permissions.
DBA authority: the name for any schema in the database can be changed
SCHEMA authority and schema access permission: the name for the current
schema only can be changed
410
For information about granting DBA and SCHEMA authority, see the uaddprv
function; for information about granting schema access permission, see the uaddprm
function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umodath function to change a schema name.
if ( ubndath(txid, 1, &argv[1], USLCK, &aid, statusl, &status) != UFAILURE )
{
dbauthl.authnm = argv[2];
/* Change schema name */
dbauthl.aid = aid;
/* Authorization ID */
/* Modify the schema */
if ( umodath(txid, 1, &dbauthl, &statusl, &status) != USUCCESS)
{
fprintf(stderr, ”Unable to modify schema: %ld\n”,status);
fprintf(stderr,”Schema name %s Auth. ID. %ld status: %ld\n”,
dbauthl.authnm, dbauthl.aid, statusl);
uexit(1);
}
}
else
fprintf(stderr, ”Schema %s not in database\n”, argv[1]);
See Also
uaddath, uallath, ubndath, udrpath, ufchath, uinfath, umapath, unumath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
411
umodbt
Modify a B-tree name
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodbt( txid, nbt, dbbtl, statusl, status )
UTXID txid;
int nbt;
DBBTREE *dbbtl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nbt
Number of B-trees in the dbbtl list
dbbtl
List of DBBTREE structures, each describing a separate B-tree to
modify
statusl
Returned list of status values, one for each dbbtl entry
status
Returned status of the function
Modifies the B-tree name for one or more B-trees listed in the dbbtl list. Each
DBBTREE structure in the dbbtl list must be specified with the new B-tree name.
Because the umodbt function can change only a B-tree name, initialize the
DBBTREE structure members btname and btid only. For a description of the
DBBTREE structure, see “The RHLI Structures” chapter.
B-tree names specified in the dbbtl list must be unique within a table.
Security
To modify the name for a B-tree, the B-tree must be in the current schema and you
must have one of the following permissions.
DBA authority
SCHEMA authority
412
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
If the database was opened with the DB_REMAP or DB_PARTMAP options,
compileĆtime IDs are automatically mapped to their runtime equivalents for all
database objects. Therefore, you do not need to map the object IDs by calling
the mapping functions. If you do call a mapping function for an already mapped
object, the UEISMAP error is returned. You can ignore this error.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umodbt function to change the name of a B-tree index.
if ((dbbtl = (DBBTREE *)calloc(1, sizeof(DBBTREE))) == NULL)
uexit(1);
dbbtl.btid
= $parts.*part_num_btree$;
dbbtl.btname = ”PARTS”;
if ((dbbtl.statusl = (USTATUS *)calloc(1, sizeof(USTATUS))) == NULL)
{
free (dbbtl);
uexit(1);
}
if ( umodbt(txid, 1, dbbtl, statusl, &status) != USUCCESS )
{
fprintf(stderr,”Failure modifying B-tree name: status = %ld\n”,status);
free (dbbtl);
uexit(1);
}
See Also
uaddbt, ubndbt, udrpbt
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about ID mapping, see page 42.
413
umoddb
Modify a database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umoddb( txid, dbinfo, status )
UTXID txid;
DBINFO *dbinfo;
USTATUS *status;
Arguments
Description
txid
The transaction ID
dbinfo
Database information descriptor
status
Returned status of the function.
Modifies the following attributes of a database:
file access mode (dbmode)
file owner ID (dbusrid)
file group ID (dbgrpid)
database description (descprt)
database name (dbname)
Database parameters are modified by initializing a DBINFO structure (pointed to by
dbinfo). For a description of the DBINFO structure, see “The RHLI Structures”
chapter.
The variable name following each parameter in the list above is the corresponding
DBINFO structure member to initialize.
Security
You must have DBA authority to modify a database. For information about granting
DBA authority, see uaddprv function.
414
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umoddb function to modify database attributes.
dbinfo.dbmode
dbinfo.dbusrid
dbinfo.dbgrpid
dbinfo.descrpt
database”;
dbinfo.dbname
=
=
=
=
0666;
0;
/* owned by root (see /etc/passwd) */
0;
/* group root (see /etc/group) */
”Inventory, capacity, & production planning
= ”parts_data_base”;
if ( umoddb(txid, &dbinfo, &status) != USUCCESS )
fprintf(stderr,”Failure modifying database: status = %ld\n”,status);
See Also
uadddb, udrpdb
chmod(2) and chown(2) in your UNIX system manual
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
415
umodhsh
Modify a hash table name
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodhsh( txid, nmods, dbhashl, statusl, status )
UTXID txid;
int nmods;
DBHASH *dbhashl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nmods
Number hash tables in the dbhashl list
dbhashl
List of DBHASH structures, each describing a separate hash table to
modify
statusl
Returned list of status values, one for each dbhashl entry
status
Returned status of the function
Modifies the hash table name for one or more hash tables listed in the dbhashl list.
Each DBHASH structure in the dbhashl list must be specified with the new hash table
name. Hash table names specified in the dbhashl list must be unique within a table.
Because the umodhsh function can change only a hash table name, initialize the
DBHASH structure members htname and hid only. For a description of the DBHASH
structure, see “The RHLI Structures” chapter.
Security
To modify the name for a hash table, the hash table must be in the current schema and
you must have one of the following permissions.
DBA authority
SCHEMA authority
416
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umodhsh function to change the hash table name.
dbhash.hid
dbhash.htname
= $manf.#mano_ht$;
= ”mano_hshtbl”;
if ( umodhsh(txid, 1, &dbhash, statusl, &status) != USUCCESS )
{
fprintf(stderr,”Failure modifying a hash index: status = %ld\n”,status);
fprintf(stderr, ”index status = %ld\n”, *statusl);
}
See Also
uaddhsh, ubndhsh, udrphsh
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
417
umodlnk
Modify a link name
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodlnk( txid, nlnks, dblinkl, statusl, status )
UTXID txid;
int nlnks;
DBLINK *dblinkl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nlnks
Number of links in the dblinkl list
dblinkl
List of DBLINK structures, each describing a separate link to modify
statusl
Returned list of status values, one for each dblinkl entry
status
Returned status of the function.
Modifies the link name for one or more links listed in the dblinkl list. Each DBLINK
structure in the dblinkl list must be specified with the new link name.
Because the umodlnk function can change a link name only, initialize only the
DBLINK structure members lnkname and lid. For a description of the DBLINK
structure, see “The RHLI Structures” chapter.
The new link name must be unique within both the parent and child tables.
Security
To modify a link, the link must be in the current schema and you must have one of
the following permissions.
DBA authority
SCHEMA authority
418
Also, the two tables comprising the link definition must be made accessible by one of
these methods:
Make the schema that contains both tables current.
If the tables are located in two separate schemas, make the schema that
contains the first table current and have schema access to the schema that
contains the second table.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umodlnk function to modify the link index name.
dblink.lid
= $parts.@part_num_link$;
dblink.lnkname = ”part_number_link”;
if ( umodlnk(txid, 1, &dblink, statusl, &status) != USUCCESS )
{
fprintf(stderr,
”Error modifying link: status = %ld\n”, status);
fprintf(stderr, ”link status = %ld\n”, *statusl);
}
See Also
uaddlnk, ubndlnk, udrplnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
419
umodusr
Modify a user name and default schema
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodusr( txid, nuser, dbuserl, statusl, status )
UTXID txid;
int nuser;
DBUSER *dbuserl;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nuser
Number of users in the dbuserl list
dbuserl
List of DBUSER structures, each describing a separate user’s
information to modify
statusl
Returned list of status values, one for each dbuserl entry
status
Returned status of the function
Modifies the name and default schema for each user listed in the dbuserl list. Each
DBUSER structure in the dbuserl list must be specified with the new user or default
schema name information; one of these items may be omitted by specifying a null
value.
For a description of the DBUSER structure, see “The RHLI Structures” chapter.
Security
A user’s name and default schema can be modified only under the following
conditions:
If you have DBA authority, any user name or default schema can be modified.
If you don’t have DBA authority, only your user name can be modified; the
default schema can be changed only if you have schema access permission to
the new schema.
To grant DBA authority, use the uaddprv function. To grant schema access
permission, use the uaddprm function.
420
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the umodusr function to change a user name.
/* define required parameters */
UTXID
txid;
DBUSER * dbuserl;
USTATUS statusl;
USTATUS status;
/ * Retrieve user ID (uoid) */
...
/* Initialize DBUSER structure */
dbuserl.uoid = uoid; /* User ID to change */
dbuserl.usernm = argv[2]; /* New user name */
dbuserl.aid = UNULLAID; /* Keep same default schema */
/* Modify the user information */
if (umodusr(txid, 1, &dbuserl, &statusl, &status) != USUCCESS){
fprintf(stderr, ”Unable to modify user: %ld\n”, status);
fprintf(stderr, ”Users %s auth. id. %ld status: %ld\n”,
dbuserl.usernm, dbuserl.aid, statusl);
uexit(1);
}
else
fprintf(stderr, ”User %s not registered in database\n”,argv[1]);
See Also
uaddusr, udrpusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
421
umodvol
Modify a volume name
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int umodvol( txid, nmods, dbvolml, statusl, status )
UTXID txid;
int nmods;
DBVOLM *dbvolml;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
The transaction ID
nmods
Number of volumes in the dbvolml list
dbvolml
List of DBVOLM structures, each describing a separate volume to
modify
statusl
Returned list of status values, one for each dbvolml entry
status
Returned status of the function.
Modifies the volume name for each volume listed in the dbvolml list. Each DBVOLM
structure in the dbvolml list contains information about a volume.
Because the umodvol function can change a volume name only, initialize only the
DBVOLM structure members volname and vid. For a description of the DBVOLM
structure, see “The RHLI Structures” chapter.
The new volume name must be unique within the current database.
Security
You must have DBA authority to modify a volume. For information about granting
DBA authority, see the uaddprv function.
422
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the umodvol function to change a volume name.
dbvolml.volname = ”master parts database”;
if ( umodvol(txid, 1, &dbvolml, statusl, &status) != USUCCESS )
{
fprintf(stderr,
”Failure modifying a volume: status = %ld\n”,status);
fprintf(stderr, ”volume status = %ld\n”, *statusl);
}
See Also
uaddvol, udrpvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
423
unumath
Retrieve the number of schemas in the database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumath( txid, count, status )
UTXID txid;
long *count;
USTATUS *status;
Arguments
txid
The transaction ID
count
Pointer to the number of schemas currently in the database
status
Returned status of the function
Description
Returns the number of schemas registered in the database.
Security
The number of schemas is returned only for schemas to which you have access.
You always have access to the current schema. Additionally, you can access other
schemas if you have been granted schema access permission to the schema or if a
schema you can access has schema privileges to another schema (or a table or column
in the schema). If you have DBA authority, you can access any schema in the
database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
424
Example
This example calls the unumath function to retrieve the number of accessible
schemas.
/* define required parameters */
UTXID
txid;
long
count;
USTATUS status;
/* open the database and begin a transaction */
...
/* Retrieve number of accessible schemas */
if (unumath(txid, &count, &status) != USUCCESS)
{
printf(”Cannot get the auth. count: status = %ld\n”,
status);
}
See Also
uinfath, ubndath
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
425
unumcgp
Retrieve the number of columns in a column group
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumcgp( txid, cid, ngid, status )
UTXID txid;
UCID cid;
long *ngid;
USTATUS *status;
Arguments
Description
txid
The transaction ID
cid
Column ID of a column
ngid
Pointer to a buffer which contains the number of columns in the
column group, or, if the specified column is not a column group, the
number of column groups to which this column belongs
status
Returned status of the function.
If the column ID (specified by cid) is member of a column group, the unumcgp
function returns the total number of members in that column group that are available.
Otherwise, the number of column groups to which the ordinary column belongs is
returned.
There is no indication as to which count is returned; for further information on how
to identify the type of column, see the uinfcol function.
426
Security
The unumcgp function counts and returns the number of columns in column groups
of tables that you have access to only.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the unumcgp function to retrieve the number of column groups in
the parts table.
/* define RHLI interface required parameters */
UTXID
txid;
long
count;
USTATUS status;
if (unumcgp(txid, $parts.$, &count, &status) != USUCCESS)
{
printf(”Could not get the number of column groups:”);
printf(” status = %ld\n”, status);
uexit(101);
}
See Also
unumtbl, unumrow, ubndtbl, uinfcol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
427
unumchd
Retrieve the number of child rows for a link
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumchd( txid, ptid, prid, lid, nchild, status )
UTXID txid;
UTID ptid;
URID prid;
ULID lid;
long *nchild;
USTATUS *status;
Arguments
txid
The transaction ID
ptid
Table ID of the parent row of the link
prid
Row ID of the parent row of the link
lid
Link ID of the link
nchild
Pointer to the number of rows that are children of the known parent
row
status
Returned status of the function.
Description
Given a parent row ID, returns the number of rows that are children of the specified
parent row of a link. Because multiple links can exist on a given parent table, the
Link ID is used to determine the child table to query.
Security
Link information is returned only for links in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
428
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function. To grant schema access, use the uaddprm
function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the unumchd function to retrieve the number of child rows in the
link index.
/* define RHLI interface required parameters */
UTXID
txid;
URID
prid;
long
nchild;
USTATUS status;
/* this assumes a database is open & a transaction begun */
if ( unumchd(txid, $parts.$, prid, $@parts_avail$, &nchild,
&status) != USUCCESS )
{
printf(”Cannot get the child row count: status = %ld\n”,
status);
uexit(99);
}
See Also
uaddlnk, ubndtbl, udrplnk, unumcol, unumprn
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
429
unumcol
Retrieve the number of columns in a table
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumcol( txid, tid, ncol, status )
UTXID txid;
UTID tid;
long *ncol;
USTATUS *status;
Arguments
txid
The transaction ID
tid
Table ID of the table containing the columns
ncol
Pointer to the number of columns in the table specified
status
Returned status of the function.
Description
Returns the number of available columns for the specified table.
Security
Column information can be retrieved only for columns in tables that you have access
to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
430
Example
This example uses the unumcol function to retrieve the number of accessible
columns in the parts table.
/* define RHLI interface required parameters */
UTXID
txid;
long
ncol;
USTATUS status;
if ( unumcol(txid, $parts.$, &ncol, &status) != USUCCESS)
{
printf(”Could not get the number of columns:”);
printf(” status = %ld\n”, status);
uexit(99);
}
See Also
unumtbl, unumrow, ubndtbl, uinftbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
431
unumprn
Retrieve the number of parent rows for a link
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumprn( txid, ctid, crid, lid, nparent, status )
UTXID txid;
UTID ctid;
URID crid;
ULID lid;
int *nparent;
USTATUS *status;
Arguments
Description
txid
The transaction ID
ctid
Table ID of the child row of the link
crid
Row ID of the child row of the link
lid
Link ID of the link
nparent
Pointer to the number of parent rows
status
Returned status of the function.
Given a child row ID, returns the number of rows (0 or 1) that are parents of the
specified child row of the link.
A return value of zero for nparent implies the child row link column has a null value.
Because multiple links can exist on a given parent table, the Link ID must be
specified to determine the parent table to query.
A child row can have only zero or one parent.
432
Security
Link information is returned only for links in tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the unumprn function to determine if a row is a parent row in a
link index.
/* define required parameters */
UTXID
txid;
URID
crid;
long
nparent;
USTATUS status;
if ( unumprn(txid, $parts.$, crid, $@parts_used$, &nparent,
&status) != USUCCESS)
{
printf(”Cannot get the parent row count: status = %ld\n”,
status);
uexit(99);
}
See Also
uaddlnk, udrplnk, unumcol, unumchd
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about using links, see “Choosing an Access Method” in Unify
DataServer: Managing a Database.
433
unumrow
Retrieve the number of rows in a table
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumrow( txid, tid, count, status )
UTXID txid;
UTID tid;
long *count;
USTATUS *status;
Arguments
txid
The transaction ID
tid
Table ID of the table
count
Pointer to the number of rows currently in the table
status
Returned status of the function.
Description
Returns the number of available rows in the specified table.
Security
Row information is returned only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
434
Example
This example uses the unumrow function to return the number of accessible rows.
/* define required parameters */
UTXID
txid;
long
count;
USTATUS status;
/* this assumes a database is open & a transaction begun */
if ( unumrow(txid, $parts.$, &count, &status) != USUCCESS)
{
printf(”Cannot get the row count: status = %ld\n”,
status);
uexit(99);
}
See Also
unumcol, unumtbl, ubndtbl
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
435
unumtbl
Retrieve the number of tables in the database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumtbl( txid, aid, ntbl, status )
UTXID txid;
UAID aid;
long *ntbl;
USTATUS *status;
Arguments
Description
txid
The transaction ID
aid
A valid authorization ID for a schema or UNULLAID
ntbl
Pointer to the number of tables currently in the database
status
Returned status of the function.
Returns the number of available tables in the database.
If aid is set to UNULLAID, the unumtbl function returns the total number of tables
the current schema has access to; otherwise, if aid is set to an authorization ID for a
schema, the number of tables that are accessible to the specified schema is returned.
Security
The count is returned for tables that you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
To make a schema current, use the ufchath function. To grant authority or schema
privileges, use the uaddprv function.
436
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the unumtbl function to return the number of accessible tables.
/* define required parameters */
UTXID
txid;
long
ntbl;
USTATUS status;
if ( unumtbl(txid, aid, &ntbl, &status) != USUCCESS)
{
printf(”Cannot get the table count: status = %ld\n”,
status);
uexit(99);
}
printf(”There are currently %ld tables in the database.\n”,
ntbl);
See Also
unumcol, unumrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
437
unumusr
Retrieve the number of users in the database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumusr( txid, nuser, status )
UTXID txid;
long *nuser;
USTATUS *status;
Arguments
txid
The transaction ID
nuser
Pointer to the number of users currently in the database
status
Returned status of the function
Description
Returns the number of users registered in the database.
Security
The number of users are returned as follows:
If you have DBA authority, the count of all users currently accessing the
database is returned.
If you don’t have DBA authority, only your user ID is counted.
For information about granting DBA authority, see the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
438
Example
This example calls the unumusr function to return the number of database users.
/* define required parameters */
UTXID
txid;
long
nuser;
USTATUS status;
/* open the database and begin a transaction */
...
/* retrieve number of users */
if ( unumusr(txid, &nuser, &status) != USUCCESS )
{
printf(”Cannot get the user count: status = %ld\n”,
status);
uexit(99);
}
See Also
unumrow, unumcol, unumtbl, unumvol
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
439
unumvol
Retrieve the number of volumes in the database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int unumvol( txid, nvol, status )
UTXID txid;
int *nvol;
USTATUS *status;
Arguments
txid
The transaction ID
nvol
Number of volumes currently in the database
status
Returned status of the function.
Description
Counts the number of volumes in the database.
Security
You must have DBA authority to retrieve the number of volumes in the database. For
information about granting DBA authority, see the uaddprv function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the unumvol function to retrieve the number of active volumes in
the database:
/* define RHLI interface required parameters */
UTXID
txid;
long
nvol;
USTATUS status;
440
/* this assumes a database is open & a transaction begun */
if ( unumvol(txid, &nvol, &status) != USUCCESS )
{
printf(”Cannot get the volume count: status = %ld\n”,
status);
uexit(99);
}
See Also
unumrow, unumcol, unumtbl, unumusr
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about managing database volumes, see “Managing the Database
Files” in Unify DataServer: Managing a Database.
441
uopndb
Open a database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uopndb( db_name, opnopts, dbid, status )
char *db_name;
UOPTS opnopts;
UDBID *dbid;
USTATUS *status;
Arguments
Description
db_name
A fully-qualified database name. If parts of the fully-qualified name
are omitted (or have the value (char *)0), the values in the DBHOST,
DBUSER, DBPATH, and DBNAME configuration variables determine
the missing part.
opnopts
Database open options; see the following sections
dbid
Pointer to a returned database ID that uniquely describes this
database
status
Returned status value of the operation
Opens the database specified by database name. The values of the DBNAME, DBPATH,
DBHOST, and DBUSER configuration variables affect the default database as described
in Unify DataServer: Configuration Variable and Utility Reference.
When a database is opened, a database ID is returned (pointed to by dbid). This
database ID should be used for all future references to the database.
A database opened during the execution of a program must be closed (by calling the
uclsdb function) before the program terminates.
Only one database can be opened at a time. Be sure to close an open database (by
calling the uclsdb function) before opening a new one.
442
When the uopndb function is called for the first time, several daemons that Unify
DataServer uses to manage database operations are started up. These daemons stay
running until the database is shut down (by using the shutdb utility).
Once the daemons have been started, all subsequent calls to the uopndb function (by
any transaction) do not have to re-start the daemons, causing the database to be
opened faster than the first time.
1. Database Valid opnopts values are described below. To specify more than one option,
Open Options separate options in the argument list with the bitwise logical OR operator (|).
DB_NORMAL Normal mode; default actions are taken for all categories of options
described below. If DB_NORMAL is combined with any other
option, that option overrides the default behavior in its category.
Definition Lock Options
DB_LCKSCH
Lock all table definitions in the database regardless of whether or not
the object is referenced. If you specify this option, no data definition
operations can be performed in the database. That is, no adding or
dropping of tables, columns, or indexes is allowed.
DB_NOLOCK Do not lock any table definitions. If you specify this option, your
transaction can perform data definition operations in the database.
You can acquire and release definition locks explicitly at runtime by
calling the ulcksch and uulksch functions. You can use the name
binding functions to perform all name binding at runtime.
If no definition lock options are specified, the DB_NORMAL option places shared
locks only on object definitions that are referenced at compile time by your
application. These locks prevent all transactions (including your own) from
redefining any of these database objects while this application has the database open.
Unify DataServer uses an object ID list created by the Unify DataServer linker, uld,
to lock objects referenced at compile time when the DB_NORMAL option is chosen.
If you do not use ucc and uld to compile and link your application programs, no
definition locks are acquired.
Definition locks acquired by the DB_NORMAL option are released only when the
database is closed.
443
If you specify DB_NOLOCK, you cannot also specify DB_REMAP. You cannot
specify both DB_NOLOCK and DB_LCKSCH.
Signal Handling Options
DB_NOEXIT
Do not exit when an interrupt occurs; interrupt signals should be
handled by Unify DataServer. When an interrupt signal is received,
all RHLI functions after the signal fail with a status value of
UEINTRPT until the signal is cleared with the uclritr function.
The effect of DB_NOEXIT is ignored in these cases:
The DB_NOSIGS option is also specified.
The DB_EXIT option was specified on a previous usetitr call.
DB_NOSIGS
Do not install signal handlers when you open the database. Possible
reasons for wanting to use the DB_NOSIGS option are:
You are certain that stray interrupt signals from other users will
not occur.
You want to handle interrupt signals yourself.
You want increased performance when opening the database since
the signal handlers do not need to be installed.
The signal handlers monitor and handle interrupt signals while the
database is opening. For example, if a “kill” signal is received (such
as a kill –3), Unify DataServer makes every attempt to bring the
database to a consistent state (by ending transactions, releasing locks,
writing updates to the disk, etc.) before aborting the current
operation.
Warning
Some signals, if not handled by your application, can corrupt your
database. Use DB_NOSIGS with caution.
Compile-time ID Mapping Options
DB_REMAP
Remap compile-time objects produced during compile-time
name-binding, to runtime object IDs. This runtime feature is useful
for cases where your application is run on machines where the
database may have been redefined, causing the original object IDs to
have changed.
When specifying the DB_REMAP option, your application must be
loaded by using the Unify DataServer loader, uld.
444
If you specify DB_REMAP, you cannot also specify DB_NOLOCK.
DB_PARTMAP Used with the DB_REMAP option to perform partial ID-mapping.
You must also specify the DB_REMAP option. You must use the
special syntax compiler directives in place of each object ID
referenced in the application program.
DB_CONDMAP Used with the DB_PARTMAP option to indicate conditional
ID-mapping. You must also specify the DB_REMAP option.
Performance
Specifying the DB_REMAP option can impact performance when opening a database
since remapping is performed on all object IDs defined for the database, whether or
not the IDs are accessed.
Database Update Options
The DB_RDONLY option means that only non-update, insert, or delete operations are
allowed. The database can be opened with DB_RDONLY mode even if other
processes have opened the database for update operations.
If DB_RDONLY is not specified, DB_NORMAL opens the database in read/write
mode.
Security
To open a database, one of the following conditions must be true:
You are the creator of the database.
You have access to the database.
For information about creating a database, see the uadddb function; for information
about granting database access, see the uaddusr function.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
445
Example
This example uses the uopndb function to open the database.
/* define required parameters */
UDBID
dbid;
char * dbname = ”parts.db”;
USTATUS status;
...
/* open ’parts.db’ database */
if ( uopndb(dbname, DB_NORMAL, &dbid, &status) != USUCCESS)
{
printf(”Unable to open parts database %s\n”, dbname);
uexit(1);
}
See Appendix A for more examples.
See Also
ubegtx, uclsdb, uinfdb, ulcksch
fflush(3) in your UNIX system manual
AUTOSTART configuration variable in Unify DataServer: Configuration Variable and
Utility Reference
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
446
uopnjrn
Open a journal file
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uopnjrn(dbname, jrnname, jrnfd, sequence, status)
char *dbname;
char *jrnname;
int *jrnfd;
long *sequence;
USTATUS *status;
Arguments
Description
dbname
Pointer to the path name of the database associated with the journal
jrnname
Pointer to the path name of the journal file to open
jrnfd
Pointer to the returned file descriptor for the opened journal file
sequence
Pointer to the returned journal sequence number of the journal header
status
Returned status of the function
Opens the specified journal file. The uopnjrn function call returns a file descriptor of
the opened journal file and the journal sequence number contained in the journal
header.
The sequence number is a unique number assigned to each journal file when it is
created. The first journal created following a backup of the database is assigned a
sequence number of 1. The sequence number is incremented for each subsequent
journal file.
Information in the journal can then be read using the ufchjrn function call. After
processing the journal file, the uclsjrn function closes the journal and frees up
resources.
447
The uopnjrn function implicitly opens and closes the database in order to extract
schema information needed to process the journal file. Therefore the database cannot
be opened at the time that the uopnjrn function call is called.
Only one journal file can be open at a time.
Security
To open and process the journal, one of the following conditions must be true:
You have DBA authority.
You have access to the tables and columns that are referenced in the journal.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
See Appendix A.
See Also
ufchjrn, uclsjrn
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction management and using the transaction journal, see
“Managing Transactions and Locks”and “Preventing Data Loss” in Unify
DataServer: Managing a Database.
448
upkfrow
Fetch a row by the value of its primary key
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int upkfrow(txid, tid, lcktype, rid, keycoll, unipcoll, statusl, status)
UTXID txid;
UTID tid;
int lcktype;
URID *rid;
UNIPCOLL *keycoll;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
The transaction ID
tid
Table ID of the table that contains the row to fetch
lcktype
Lock type to place on the fetched row. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
rid
Returned row ID of the retrieved row
keycoll
A pointer to a UNIPCOLL structure that specifies the primary key
column list
unipcoll
A pointer to a UNIPCOLL structure that specifies the column
retrieval list
statusl
Returned list of status values, one for each keycoll/unipcoll list entry
status
Returned status of the function
449
Description
Retrieves columns of the indicated row from the specified table by using the supplied
primary key.
For the keycoll argument, specify any multiple key column values in any order. A
primary key column cannot be a null value.
UNIPCOLL contains several lists that describe both the column and the column’s
value. All of the columns specified in the column list structure must belong to the
table ID specified. For a description of how to initialize the UNIPCOLL structure, see
“The RHLI Structures” chapter.
Security
A row can be returned only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
ufchrow, ufchtbl, ufchlnk
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
450
uposord
Position by values to a row within an ordered access
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uposord (txid, oaccid, rop, keyvall, lcktype, ridp, statusl, status)
UTXID txid;
UOACCID oaccid;
int rop;
UDBVAL *keyvall;
int lcktype;
URID *ridp;
USTATUS statusl[];
USTATUS *status;
Arguments
txid
Current transaction ID
oaccid
An ordered access ID as returned from the ubegord function
rop
A value indicating the relational operator (in comparison with the
beginning of the order) for the comparison. Options are:
ULTTST
Greatest value less than.
ULETST
Greatest value less than or equal to.
UEQTST
Equal to.
UGETST
Least value greater than or equal to.
UGTTST
Least value greater than.
keyvall
A pointer to a list of UDBVAL structures, one for each key column
whose value is to be positioned to.
lcktype
Lock type to place on row positioned to. Options are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
451
Description
ridp
Returned as the row ID of the new current row
statusl
Returned list of status values, one for each column value specified in
the keyvall list
status
Returned status of the operation
Alters the current position within the ordered access specified by oaccid.
If the function returns USUCCESS, the current position is set to the row whose
column values in conjunction with the relational operator match the column values
specified by the keyvall list. The row is locked with a lock no lower than the
requested lock.
The relational operator is in terms of the order specified by the UOACOLS structure
list passed to the ubegord function, not the physical order of the underlying access
method. For example, for an ascending order with values 1, 2, 3, 3, 3, 4, and 5,
UGTTST on value 3 will position to value 4. For the same values with a descending
order (5, 4, 3, 3, 3, 2, 1) UGTTST on value 3 will position to value 2.
A call to the ufchord function with a direction parameter of USAME, UNEXT, or
UPREV immediately following a call to the uposord function returns the row
positioned to by the uposord function.
If the function returns USUCCESS, the row ID of the new current row is returned with
a lock no lower than the requested lock.
If the function fails due to the inability to obtain the specified row lock, the current
position does not change. The position remains set to the position before the uposord
function was called.
Security
No privileges required.
Example
See Appendix A.
See Also
ubegord, uendord, ufchord, uskrord
452
usetitr
Set an interrupt; disallow database operations
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int usetitr( itropts, status )
UOPTS itropts;
USTATUS status;
Arguments
itropts
Process interrupt option. Options are:
DB_EXIT
Gracefully exit the application after an interrupt has
occurred
DB_NORMAL Return to the application after an interrupt has
occurred
DB_NOEXIT
status
Description
Do not exit when an interrupt occurs
Returned status of the function
Causes the current process to disallow database operations both in RHLI and in
Embedded SQL/A. The usetitr function should be called only when an interrupt
signal has been caught by a signal handler routine in your application program.
All database operations are disallowed while the interrupt is set, with the exception of
certain operations providing for process termination and closing of the database.
The database interrupts are not implemented through the UNIX signal function
interfaces.
Once an interrupt is set, all Unify DataServer-managed child processes are terminated
at a point where the database is in a known consistent state. Process interruption by
any other mechanism may require database recovery and is not recommended.
Before setting an interrupt with usetitr, be sure that a database is currently open.
453
If a database is opened by specifying the DB_NOEXIT option to the uopndb
function, or if the database is opened by using the Embedded SQL/A CONNECT or
OPEN DATABASE statements, the current application does not exit when an interrupt
occurs. However, if you specify the DB_EXIT option (for itropts) when calling the
usetitr function, the uopndb function DB_NOEXIT option is overridden, and the
application exits on this interrupt.
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example calls the usetitr function when the SIGQUIT signal occurs.
/* add include files */
#include <stdio.h>
#include <signal.h>
#include <include/rhli.h>
/* a signal handler routine */
void syncsig(syssig)
int syssig;
/* signal value received */
{
USTATUS status;
/* function status */
...
(void)signal(syssig, syncsig);
/* determine the signal type */
switch ( syssig )
{
case SIGHUP:
{
syncprt(); /* print statistics */
break;
}
case SIGQUIT:
{
usetitr(DB_EXIT, &status); /* exit application */
break;
}
case SIGUSR1:
{
sleeptm = 1;
/* reset global sleep time */
break;
454
}
default:
{
printf(”unknown signal caught: %d\n”, syssig);
break;
}
}
return;
}
See Also
uclritr
signal(2) in your UNIX system manual
455
uskrord
Alter the current position within the ordered access
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uskrord (txid, oaccid, lcktype, rid, status)
UTXID txid;
UOACCID oaccid;
int lcktype;
URID rid;
USTATUS *status;
Arguments
Description
txid
Current transaction ID (from the ubegtx or ucbgtx functions)
oaccid
An ordered access ID as returned from the ubegord function
lcktype
Lock type to place on row positioned to. Valid lock type values are:
UNULLLCK
No lock
USLCK
Shared lock
UXLCK
Exclusive lock
rid
Row ID of the row to seek to
status
Returned status of the operation
Given a valid Row ID, the uskrord function alters the current position within the
ordered access specified by oaccid. The current position is set to the row specified by
rid.
If the function fails due to the inability to obtain the specified row lock, the current
position does not change. The position remains set to the position before the uposord
function was called.
456
A call to the ufchord function with a direction parameter of USAME, UNEXT, or
UPREV immediately following a call to the uskrord function returns the row
positioned to by the uskrord function.
If the function returns USUCCESS, the row is locked with a lock no lower than the
requested lock.
Security
No privileges required.
Example
See Appendix A.
See Also
ubegord, uendord, ufchord, uposord
457
utrnctbl
Truncate a table
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int utrnctbl( txid, tid, status)
UTXID txid;
UTID tid;
USTATUS *status;
Arguments
txid
Transaction ID
tid
Table ID of the table to be truncated. The table cannot be a child in a link
index and it can only be a parent in a link index if the child tables are
empty. The table cannot have any B-trees stored in external files
(.idx)
status
Description
Returned status of the function
The utrnctbl function deallocates the allocated segments for the specified table and
returns the segments to the volume free space. All data in the table and in its indexes
is permanently dropped. The table definition and any index definitions that the table
has, however, are retained. Any triggers on the table are not executed and any DIS
definitions for the table are ignored.
Use the utrnctbl function when you want to quickly free up the segments being used
by a table but retain the table definition for future use. (The udrptbl function also
frees the allocated segments but does not retain the table definition.)
Although this is a DML operation, it is not recoverable. The table truncation is
logged however, and therefore replayable by the irma utility.
The utrnctbl function must be performed within its own transaction and the
transaction cannot be rolled back.
458
If the table being truncated contains variable-length data, the space held in the
variable–length data volumes must be released. For information on how to do this,
see the entry titled “Reclaim utility is no longer available” in the Unify DataServer
README.
The utrnctbl() function is not available with remote access.
Security
To use this statement, one of the following conditions must be true:
you have DBA authority
the table is in the current schema
the table is in another schema and the current schema has DELETE privilege
on the table or the schema containing the table
Example
The following example uses the utrnctbl() function to truncate a table.
/* define required parameters */
UTXID
txid;
USTATUS status;
...
/* start a new transaction */
...
/* xlock the table to be truncated */
...
/* truncate table scratchTbl */
if ( utrnctbl(txid, $scratchTbl.$, &status) != SUCCESS )
{
/* handle error */
fprintf(stderr, “Error truncating scratchTbl: status = %ld\n”,
status);
...
}
/* commit the transaction */
...
459
uulkdb
Unlock a database
#include <include/rhli.h>
#include <include/rhlierr.h>
Syntax
int uulkdb( txid, status )
UTXID txid;
USTATUS *status;
Arguments
Description
txid
The transaction ID.
status
Returned status of the function
Unlocks the database that acquired a lock during the specified transaction. Unlocking
a database releases all locks on the tables and rows in the database.
An exclusive lock is not released until the transaction that acquired the exclusive lock
is committed or aborted (by calling the ucmttx, ucbgtx, or uabttx function).
Security
No privileges required.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Example
This example uses the uulkdb function to unlock the database.
if ( uulkdb(txid, &status) != USUCCESS ) {
printf(”Unable to unlock database: status = %ld\n”, status);
uexit(99);
}
See Also
ulckrow, uulkrow, ulcktbl, uulktbl, ulckdb, ubegtx
For information about transaction and lock management, see “Managing Transactions
and Locks” in Unify DataServer: Managing a Database.
460
uulkrow
Unlock a row
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uulkrow( txid, tid, rid, status )
UTXID txid;
UTID tid;
URID rid;
USTATUS *status;
Arguments
Description
txid
The transaction ID.
tid
Table ID of the table containing the row to unlock
rid
Row ID of the row to unlock
status
Returned status of the function
Unlocks the row ID for the specified table so that other transactions can change the
row’s column data.
An exclusive lock is not released until the transaction that acquired the exclusive lock
is committed or aborted (by calling the ucmttx, ucbgtx, or uabttx function).
Security
Rows can be unlocked only for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
461
Example
This example uses the uulkrow function to unlock a row (with a rowid of 3) in the
company table.
/* define RHLI interface required parameters
UTXID
txid;
URID
rid;
USTATUS status;
/* open the database and begin a transaction
...
/* unlock the row */
rid = 3;
if ( uulkrow(txid, $company.$, rid, &status)
{
printf(”Unable to unlock row %ld: status
status);
uexit(99);
}
See Also
*/
*/
!= USUCCESS )
= %ld\n”, rid,
ulckdb, ulckrow, ulcktbl, uulktbl, uulkdb
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction and lock management, see “Managing Transactions
and Locks” in Unify DataServer: Managing a Database.
462
uulksch
Unlock a table definition
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
bool uulksch( txid, tid, status )
UTXID txid;
UTID tid;
USTATUS *status;
Arguments
Description
txid
Current transaction ID
tid
Table ID of the table to unlock
status
Returned status of the function
Unlocks (or releases) a table definition lock placed by the ulcksch function. A table
definition lock prevents any other transactions from changing or deleting the
definition for a table while table data is being accessed.
A table definition lock is separate from and does not interfere with a data lock. To
release a data lock, see the uulktbl or uulkrow function.
Security
Definition locks can only be released on tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
463
Example
This example uses the uulksch function to release a table definition lock for the
company table.
/* define RHLI interface required parameters */
UTXID
txid;
USTATUS status;
/* open the database and begin a transaction */
...
/* Unlock the table definition lock */
if (uulksch(txid, $company.$, &status) != USUCCESS)
{
printf(”definition unlock of company table failed—%ld\n”,
status);
uexit(99);
}
See Also
ulcksch, uinfsch
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction and lock management, see “Managing Transactions
and Locks” in Unify DataServer: Managing a Database.
464
uulktbl
Unlock a table
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uulktbl( txid, tid, status )
UTXID txid;
UTID tid;
USTATUS *status;
Arguments
Description
txid
Current transaction ID
tid
Table ID of the table to unlock
status
Returned status of the function
Unlocks all rows in that table specified by the table ID.
An exclusive lock is not released until the transaction that acquired the exclusive lock
is committed or aborted (by calling the ucmttx, ucbgtx or uabttx function).
Security
Only tables that you have access to can be unlocked.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
465
Example
This example uses the uulktbl function to unlock the company table.
/* define RHLI interface required parameters */
UTXID
txid;
USTATUS status;
/* open the database and begin a transaction */
...
/* lock the table */
if ( uulktbl(txid, $company.$, &status) != USUCCESS )
{
printf(”Unable to unlock table: status = %ld\n”,
status);
uexit(99);
}
See Also
ulckrow, uulkrow, ulcktbl, ulckdb, uulkdb
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
For information about transaction and lock management, see “Managing Transactions
and Locks” in Unify DataServer: Managing a Database.
466
uupdrow
Update a row
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
int uupdrow( txid, tid, rid, unipcoll, statusl, status )
UTXID txid;
UTID tid;
URID rid;
UNIPCOLL *unipcoll;
USTATUS statusl[];
USTATUS *status;
Arguments
Description
txid
Current transaction ID
tid
Table ID of the table containing the row to update
rid
Row ID of the row to update
unipcoll
A pointer to a UNIPCOLL structure specifying the column update list
statusl
Returned list of status values, one for each of the columns listed in
unipcoll
status
Returned status of the function
Updates a row according to the column values specified by the structure UNIPCOLL.
Columns specified in UNIPCOLL must belong to the table ID specified by tid.
UNIPCOLL contains several lists which describe both the column and the column
value. For a description of how to initialize the UNIPCOLL structure, see “The RHLI
Structures” chapter.
If any column has legal values defined by the Data Integrity Subsystem (DIS), the
valid DIS value is checked before any update is allowed. If any column value is
rejected, the entire row remains unmodified. For more information about DIS, see
Unify DataServer: Managing a Database.
467
When inserting into or updating columns of type U_STR (string), Unify DataServer
adds trailing blanks to values less than the total size defined for the column.
Security
Rows can only be updated for tables you have access to.
You can always access all tables in the current schema. Additionally, you can access
tables (or just columns within a table) in other schemas if your current schema has
been granted schema privileges to the other schema. If you have DBA authority, you
can access any table in the database.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
See Also
uinsrow, udelrow
For information about database security, see “Setting Up and Managing Security” in
Unify DataServer: Managing a Database.
468
uXMLAddAttribute()
Adds a new attribute to an element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLAddAttribute ( xmlObj, xmlStatus, attributeName, attributeValue )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* attributeName;
const char* attributeValue;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
attributeName Name of the new attribute to be added
attributeValue Value of the new attribute
Description
Adds a new attribute and its value to the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
469
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const char* attributeName= “mothername”;
const char* attributeValue= “Maria”;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” for wellformedness,
parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program adds a new attribute to the current element. If
the current element pointer for element is at “<name>” , and
attributeName=”mothername” and attributeValue=”Maria”, then the XML becomes:
<_>
<name surname=”anderson” fathername=”mike”
mothername=”Maria”>Jack</name>
<_>
result = uXMLAddAttribute(xmlObj,&xmlStatus,attributeName,attributeValue);
See Also
uXMLCreateElement
470
uXMLCreateElement()
Creates a new element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLCreateElement ( xmlObj, xmlStatus, elementName, elementValue )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* elementName;
const char* elementValue;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
elementName
Name of the element
elementValue
Value of the element
Description
Creates a new element and appends it as child element to the current element. The
value of the child element is set to the specified elementValue.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
471
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const char* elementName= “country”;
const char* elementValue= “USA”;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” for wellformedness,
parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program adds a new element to the current document
as a child element of the current element. If the current element pointer is at
<person>, elementName=”country” and elementValue=”USA”, then XML document
after the function is called becomes:
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
<country>USA</country>
</person>
result =uXMLCreateElement(xmlObj,&xmlStatus,elementName,elementValue);
See Also
uXMLAddAttribute
472
uXMLDeleteAttribute()
Deletes an attribute
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLDeleteAttribute( xmlObj, xmlStatus, attributeName )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* attributeName;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function attribute
Name
Name of the attribute to be deleted
Description
Deletes the specified attribute from the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information can be obtained by calling getErrorInfo().
Security
No privileges needed.
The following lines in the person.xml file define a person element.
473
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* xmlfile=”person.xml”;
xml_obj xmlObj;
int result = 0;
const char* attributeName= fathername ;
USTATUS xmlStatus;
....
The following lines in an RHLI program checks the person.xml file for
wellformedness, parses it, and prints the result.
result = uXMLParse( &xmlObj, &xmlStatus, xmlfile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program deletes the attribute of the current element. If
the current element pointer is set to <name> and the function is called with
attributeName= fathername”, the XML becomes:
<&>
<name surname=”anderson” >Jack</name>
<&. >
result =uXMLDeleteAttribute(xmlObj,&xmlStatus,attributeName);
See Also
uXMLChangeAttributeValue
474
uXMLDeleteCurrentElement()
Deletes the current element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLDeleteCurrentElement ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function.
Description
Deletes the current element from the document and sets the current element pointer to
the parent element of the deleted element. If this function is called with the current
element set to the root element of the document, then the entire underlying document
structure is removed.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
USTATUS xmlStatus;
....
475
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program deletes the current element from the
document. If the current element pointer is at element <name>, and the function
uXMLDeleteCurrentElement() is called, it deletes the <name> element from the
document. The XML document becomes:
<person>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
result =uXMLDeleteCurrentElement(xmlObj,&xmlStatus);
See Also
uXMLDeleteElementValue, uXMLModifyElementValue, uXMLDeleteAttribute
476
uXMLDeleteCurrentElementValue()
Deletes the value of an element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLDeleteCurrentElementValue ( xmlObj, xmlStatu s)
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function.
Description
Deletes the value of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const* char elementName= “name”;
USTATUS xmlStatus;
....
477
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the results.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following lines in an RHLI program delete the value of the current element. If
the current element pointer is at element <age> then the
uXMLDeleteCurrentElementValue() function deletes the value for the element
<age>. The document becomes
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”></age>
<me>John</me>
</person>
result =uXMLDeleteCurrentElementValue(xmlObj, &xmlStatus);
478
uXMLDestroy
Destroys an XML object
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <uXML.h>
int uXMLDestroy (xmlObj, xmlStatus)
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
Pointer to Object reference
xmlStatus
Returned status of the function.
Description
Destroys the given xmlObj Reference.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Security
No privileges needed.
Example
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the results.
479
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
result =uXMLDestroy(&xmlObj, &xmlStatus);
480
uXMLGetAttributeCount()
Returns the number of attributes
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetAttributeCount ( xmlObj, xmlStatus, count )
xml_obj* xmlObj;
USTATUS xmlStatus;
int* count;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
count
Returned count of attributes of an element
Description
Returns the count of attributes associated with the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
int count;
char* name;
USTATUS xmlStatus;
....
481
The following lines in an RHLI program checks the “person.xml” file for
wellformedness, parses it, and prints the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program returns the number (integer value) of
attributes associated with current element. If the current element is <name> then the
uXMLGetAttributeCount() function sets the count variable to 2.
result = uXMLGetAttributeCount( xmlObj, &xmlStatus, &count );
See Also
uXMLGetAttributeNames, uXMLGetAttributeValues.
482
uXMLGetAttributeNames()
Returns the attribute names of an element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetAttributeNames ( xmlObj, xmlStatus, attributeNames )
xml_obj* xmlObj;
USTATUS xmlStatus;
char*** attributeNames;
Arguments
xmlObj
Object reference
xmlStatus
Returned status of the function
attributeNames Pointer to an array of attribute names, which are allocated and
returned by the function. The array is terminated by a NIL string.
Description
The function allocates an array of attribute names as strings.
The calling program is responsible to free the memory occupied by the array.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
483
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char * attributeNames;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” for wellformedness,
parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program assigns the list of the attribute names to
“result”. If the current element pointer is at <name>,the function returns
attributeNames as an array of character pointers terminated by NIL(char):
surname, fathername.
result = uXMLGetAttributeNames(xmlObj, &xmlStatus, &attributeNames);
...
/* use attributeNames */
char ** name = attributeNames;
printf(”\nThe attribute names are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeNames);
attributeNames = 0;
See Also
uXMLGetAttributeValues, uXMLGetAttributeCount
484
uXMLGetAttributeValue()
Returns an attribute value
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetAttributeValue ( xmlObj, xmlStatus, attributeName,
attributeValue )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* attributeName;
char** attributeValue;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
attributeName Name of the attribute whose value you want to retrieve
attributeValue Returned value of attribute
Description
Returns the value of the specified attribute (attributeName) of the current element.
The calling program is responsible to free the memory occupied by the attributeValue
variable.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
For a list of the most commonly occurring function status values, see the status code
at beginning of this document. For a complete list of status returns and the associated
error messages with their explanations and corrections, see Unify DataServer: Error
messages.
485
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const char* attributeName= “fathername”;
char* attributeValue;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” for wellformedness,
parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program returns the value of an attribute of the current
element. If the current element pointer is set to <name> and the
uXMLGetAttributeValue() function is called with attributeName=”fathername”, the
returned attribute value is ”mike”.
result = uXMLGetAttributeValue(xmlObj, &xmlStatus, attributeName,
&attributeValue)
See Also
uXMLGetAttributeValues, uXMLGetAttributeNames
486
uXMLGetAttributeValues()
Returns the attribute values of an element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetAttributeValues ( xmlObj, xmlStatus, attributeValues )
xml_obj* xmlObj;
USTATUS xmlStatus;
char** attributeValues;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
attributeValues Pointer to an array of attribute values, which are allocated and
returned by the function. the array is terminated by a NIL string.
Description
This function allocates an array of attribute names as strings.
The calling program is responsible to free the memory occupied by the
attributeValues variable.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
487
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* attributeValues;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” for wellformedness,
parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program assigns the list of the attribute values to
“result”. If the current element pointer is at <name>, the function returns the values
of all attributes as an array of character pointers terminated by NIL(char), such as:
Sanderson, mike
result=uXMLSetAttributeValues(xmlObj, &xmlStatus, &attributeValues);
...
/* use attributeNames */
char ** name = attributeValues;
printf(”\n the attribute values are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeValues);
attributeValues = 0;
}
See Also
uXMLGetAttributeNames, uXMLGetAttributeCount
488
uXMLGetCurrentElementName()
Returns the tag name of the current element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetCurrentElementName ( xmlObj, xmlStatus, name )
xml_obj* xmlObj;
USTATUS xmlStatus,
char** name;
Arguments
Description
xmlObj
DOM object reference
xmlStatus
Returned status of the function
name
Returned tag name (allocated)
Returns the tag name of the current element in the name argument.
The calling program is responsible to free the memory occupied by name.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
489
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parse it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following lines in an RHLI program print the current element name. If the
current element pointer is at element <person>, the uXMLGetCurrentElementName
function sets the name to “person”.
result = uXMLGetCurrentElementName( xmlObj, &xmlStatus, &name );
printf( ”\n name of element = %s \n”, name );
free (name);
490
uXMLGetErrorInfo()
Returns an error description
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetErrorInfo ( xmlObj, xmlStatus, errorInfo )
xml_obj* xmlObj;
USTATUS xmlStatus;
char** errorInfo;
Arguments
Description
xmlObj
DOM object reference
xmlStatus
Returned status of the function.
errorInfo
Returned error information
Returns a description (errorInfo) about the last error that occurred during XML
processing.
The calling program is responsible to free the memory occupied by errorInfo.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
491
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
char* errorInfo;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the results.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program provide the information about the last error;
the errorInfo variable has the information on the error.
result =uXMLGetErrorInfo(xmlObj,&xmlStatus,&errorInfo);
492
uXMLGetValueOfCurrentElement()
Returns the value of the current element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLGetValueOfCurrentElement( xmlObj, xmlStatus, elementValue )
xml_obj* xmlObj;
USTATUS xmlStatus;
char** elementValue;
Arguments
Description
xmlObj
DOM object reference
xmlStatus
Returned status of the function
elementValue
Returned value of the current element
Returns the value of the current element in the elementValue argument.
The caller is responsible to free the memory occupied by the elementValue variable.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
493
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* elementValue;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parses it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following lines in an RHLI program print the current element name. If the
current element pointer is at element <me>, the uXMLGetCurrentElementName()
function sets the name variable to “John”.
result = uXMLGetValueOfCurrentElement( xmlObj, &xmlStatus,
&elementValue );
printf( ”\n name of element = %s \n”, elementValue );
free (elementValue);
See Also
uXMLGetCurrentElementName
494
uXMLModifyElementValue()
Modifies the value of an element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLModifyElementValue ( xmlObj, xmlStatus, elementValue )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* elementValue;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
elementValue
New value of the element
Description
Modifies the current value of an element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
495
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me></person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const char* elementValue=”Joseph”;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and then print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program sets the new value to the current element. If
the current element pointer is set to <me>, and the function is called with a new
element value of “Joseph” (elementValue=”Joseph”), the function modifies the
document as:
<_>
<me>Joseph</me>
<_>
result =uXMLModifyElementValue(xmlObj,&xmlStatus,elementValue);
See Also
uXMLDeleteCurrentElement, uXMLCreateElement, uXMLDeleteElementValue
496
uXMLMoveToFirstChild()
Moves the current element pointer to the first child
Syntax
Arguments
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToFirstChild ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element pointer to the first child of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
497
The following lines in an RHLI program check the “person.xml” file or
wellformedness and parse it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following lines in an RHLI program move the current element pointer to the first
child of current element. If the current element is <person>, the
uXMLMoveToFirstChild() function sets the current element pointer to <name>.
result = uXMLMoveToFirstChild( xmlObj, &xmlStatus );
See Also
uXMLMoveToLastChild, uXMLMoveToNextSibling,
uXMLMoveToPreviousSibling, uXMLMoveToParentElement
498
uXMLMoveToLastChild()
Moves the current element pointer to the last child
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToLastChild ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element pointer to the last child of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
499
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parse it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program moves the current element pointer to the last
child of current element. If the current element is <person>, the
uXMLMoveToLastChild() function sets the current element pointer to <me>.
result = uXMLMoveToLastChild( xmlObj, &xmlStatus );
See Also
uXMLMoveToNextSibling,uXMLMoveToPreviousSibling,
uXMLMoveToFirstChild, uXMLMoveToParentElement
500
uXMLMoveToNextSibling()
Moves the current element pointer to next sibling
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToNextSibling ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element pointer to the next sibling of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
501
The following lines in an RHLI program checks the “person.xml” file for
wellformedness, parses it, and prints the result status.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program moves the current element pointer to the next
sibling of the current element. If the current element is <name>, the
uXMLMoveToNextSibling() function sets the current element pointer to <age>.
result = uXMLMoveToNextSibling( xmlObj, &xmlStatus );
See Also
uXMLMoveToLastChild, uXMLMoveToPreviousSibling,
uXMLMoveToFirstChild, uXMLMoveToParentElement
502
uXMLMoveToParentElement()
Moves the current element pointer to the parent
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToParentElement ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element pointer to the parent of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
For a list of the most commonly occurring function status values, see the status code
at beginning of this document. For a complete list of status returns and the associated
error messages with their explanations and corrections, see Unify DataServer: Error
messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
503
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program moves the current element pointer to the
parent element of current element. If the current element is <me> the
uXMLMoveToParentElement() function sets the current element pointer to <person>.
result = uXMLMoveToParentElement( xmlObj, &xmlStatus );
See Also
uXMLMoveToLastChild, uXMLMoveToNextSibling, uXMLMoveToFirstChild,
uXMLMoveToPreviousSibling
504
uXMLMoveToPreviousSibling()
Moves the current element pointer to the previous sibling
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToPreviousSibling ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element pointer to the pervious sibling of the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
505
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parse it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program moves the current element pointer to the
previous sibling of the current element. If the current element is <me>, the
uXMLMoveToPreviousSibling() function sets the current element pointer to <age>.
result = uXMLMoveToPreviousSibling( xmlObj, &xmlStatus );
See Also
uXMLMoveToLastChild, uXMLMoveToNextSibling, uXMLMoveToFirstChild,
uXMLMoveToParentElement
506
uXMLMoveToRootElement()
Moves the current element pointer to the root element
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLMoveToRootElement ( xmlObj, xmlStatus )
xml_obj* xmlObj;
USTATUS xmlStatus;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
Description
Moves the current element cursor to the root element of the XML.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
char* name;
USTATUS xmlStatus;
....
507
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parse it.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following lines in an RHLI program move the current element pointer to the root
element of the XML file. If the root element is <person>, the
uXMLMoveToRootElement() function sets the current element pointer to <person>.
result = uXMLMoveToRootElement( xmlObj, &xmlStatus );
508
uXMLParse()
Parses an XML file
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLParse ( xmlObj, xmlStatus, gXmlFile )
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* gXmlfile;
Arguments
Description
xmlObj
DOM object reference
xmlStatus
Returned status of the function
gXmlfile
XML file name and absolute path
Parses the specified XML file (gXmlfile) and checks it for wellformedness.
The return value is 1 for success and 0 for failure.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”
>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
509
The following lines in an RHLI program check the “person.xml” file for
wellformedness and parse it:
const char* gXmlfile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
USTATUS xmlStatus;
....
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
510
uXMLSetAttributeValue()
Sets an attribute value
Syntax
#include <include/rhli.h>
#include <include/rhlierr.h>
#include <include/uXML.h>
int uXMLSetAttributeValue ( xmlObj, xmlStatus, attributeName,
attributeValue)
xml_obj* xmlObj;
USTATUS xmlStatus;
const char* attributeName;
const char* attributeValue;
Arguments
xmlObj
DOM object reference
xmlStatus
Returned status of the function
attributeName Name of the attribute whose value you want to change
attributeValue New value of the attribute
Description
Sets the attribute value (attributeValue) of the specified attribute (attributeName) of
the current element.
Status
Values
For a list of the most commonly occurring function status values, see page 54.
For a complete list of status returns and the associated error messages with their
explanations and corrections, Unify DataServer: Error Messages.
Additional information, if any, can be obtained by calling uXMLGetErrorInfo().
Security
No privileges needed.
511
Example
The following lines in the “person.xml” file define a person element.
<person>
<name surname=”anderson” fathername=”mike”>Jack</name>
<age dob=”12–12–1980” birth_place=”Sacramento”>20</age>
<me>John</me>
</person>
const char* gXmlFile=”person.xml”;
xml_obj* xmlObj;
int result = 0;
const char* attributeName= “fathername”;
const char* attributeValue= “Benjamin Martin”;
USTATUS xmlStatus;
....
The following lines in an RHLI program check the “person.xml” file for
wellformedness, parse it, and print the result.
result = uXMLParse( &xmlObj, &xmlStatus, gXmlFile );
printf( ”\n Parsed file result = %d:\n”, result );
....
The following line in an RHLI program modifies the value of the attribute of the
current element. If the current element pointer is set to <name> and the
uXMLSetAttributeValue() function is called with attributeName=”surname” and
attribute value=”Sanderson”, the XML becomes:
<_>
<name surname=”Sanderson” fathername=”mike”>Joseph</name>
<_>
result =uXMLSetAttributeValue(xmlObj,&xmlStatus,attributeName,
attributeValue );
See Also
uXMLDeleteAttribute
512
Appendixes
513
514
Appendix A:
Examples
This appendix contains complete and partial examples related to the
following areas:
Transaction handling
Scanning
An ordered access
Name binding
ID mapping
Transaction journalling
DDL
Text conversion
XML
All the RHLI functions used are listed before the examples.
Additional Help
For information about the structures used in the examples, see “The RHLI
Structures” on page 75.
515
Transaction Handling
This example performs various database transactions by using the
following RHLI functions: ualltx, ubegtx, uclsdb, ucmttx, ufchmsg,
uinftx, uinimsg, ulogmsg, and uopndb.
#include <rhli.h>
#include <rhlierr.h>
#define n_tx 10
main(argc, argv)
int argc;
char **argv;
{
int ntx = 2;
USTATUS status;
USTATUS fstatus;
USTATUS statusl[n_tx];
USTATUS lstats;
UDBID dbid;
char *dbname = ”file.db”;
UTXID txid, *txl;
UTXOPT txopt;
UTXID *txidl;
UTXINF txinfl[n_tx];
char *errmsg;
/* initialize the logging facilities */
if ( uinimsg(argv[0], &status) != USUCCESS)
{
printf (”error logging messages; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
516
Appendix A: Examples
/* open the database */
if ( uopndb ( dbname, DB_NORMAL, &dbid, &status) != USUCCESS )
{
printf (”unable to open the database; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
};
if (ulogmsg(”uopndb”, status, ”Opening database
DB_NORMAL”, &lstats) != USUCCESS)
{
printf (”error logging message; ”);
if ((errmsg = ufchmsg(lstats, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
}
else
printf (”Database is open.\n”);
/* begin a transaction */
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
if ( ubegtx (dbid, UROOTTXID, &txid, &txopt, &status) !=
USUCCESS )
{
printf (”unable to begin a transaction; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
uexit(1);
}
else
printf (”Transaction has begun. The transaction ID is: %d\n”,
txid);
Appendix A: Examples
517
/* retrieve information about the current transaction */
if (ualltx(dbid, UNULLPID, &ntx, &txidl, &status) != USUCCESS)
{
printf (”unable to get tx list; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
uexit(1);
}
printf (”%d\n”, ntx);
printf (”%d\n”, txidl[1]);
printf (”%d\n”, txidl[0]);
if (uinftx(dbid, ntx, txidl, UCLASS1, txinfl, statusl, &status)
!= USUCCESS)
{
printf (”unable to get tx information; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
free((UTXID *) txidl);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
free((UTXID *) txidl);
uexit(1);
};
}
else
printf (”The state of the first transaction is : %d\n”,
txinfl[0].state);
free((UTXID *) txidl);
518
Appendix A: Examples
/* end the transaction */
if ( ucmttx
(txid, &status) != USUCCESS )
{
printf (”unable to end transaction, ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
else
printf (”Transaction is committed.\n”);
/* close the database */
if ( uclsdb(dbid, DB_NORMAL, &status) != USUCCESS )
{
printf (”unable to close the database; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
else
printf (”Database is closed.\n”);
}
Appendix A: Examples
519
Scanning
This example uses the following RHLI functions: ualcscn, ubegscn,
ubegtx, uclsdb, ucmttx, uendscn, ufchmsg, ufchscn, ufrescn, uinfacs,
uinfscn, uinsand, uinsor, uinsprj, uinssrt, uinstbl, and uopndb.
This example performs the following scan:
select nv_number,nv_description where
nv_number between 5000 and 5100 and
(nv_description=”Bookcase, Steel” or
nv_description=”Bookends, oak”);
where
a1 = 5000, a2 = 5100, b1 = ”Bookcase, Steel”,
and b2 = ”Bookends, oak”
#include <rhli.h>
#include <rhlierr.h>
#include <stdio.h>
#define N_TABLE1_COL 6
UDBID dbid;
UTXID txid;
USTATUS status;
USTATUS statusl[N_TABLE1_COL];
UTXOPT txopt;
URID rid;
char *scaninf;
int scanid;
int prevlck;
UDBVAL search_dbv[5];
UDBVAL *prjvall;
UDBVAL *nulldbv;
UACSINF *acsinf;
UTID tid = $SQL_books.nvntry.$;
UCID cidl[] = {$SQL_books.nvntry.nv_number$,
$SQL_books.nvntry.nv_description$};
long a1,a2;
char b1[15],b2[15];
main ()
{
/* initialization */
init_dbvall();
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
520
Appendix A: Examples
/* open the database */
if (uopndb (””,DB_NORMAL,&dbid,&status) != USUCCESS)
fatal (”uopndb”);
/* begin a transaction */
if (ubegtx (dbid,UROOTTXID,&txid,&txopt,&status) != USUCCESS)
fatal (”ubegtx”);
/* perform scan */
if (ualcscn (txid,0,0,0,&scaninf,&status) != USUCCESS)
fatal (”ualcscn”);
if (uinstbl (txid,scaninf,tid,&status) != USUCCESS)
fatal (”uinstbl”);
if (uinsprj (txid,scaninf,2,cidl,statusl,&status) != USUCCESS)
fatal (”uinsprj”);
init_criteria();
if (uinsand (txid,scaninf,4,&status) != USUCCESS)
fatal (”uinsand”);
if (uinsor (txid,scaninf,$SQL_books.nvntry.nv_number$,URNGCC,
&search_dbv[0],&search_dbv[1], &status) != USUCCESS)
fatal (”uinsor”);
if (uinsor(txid,scaninf,$SQL_books.nvntry.nv_description$,ULIKE,
&search_dbv[2],nulldbv,&status) != USUCCESS)
fatal (”uinsor”);
if (uinsor(txid,scaninf,$SQL_books.nvntry.nv_description$,ULIKE,
&search_dbv[3], nulldbv,&status) != USUCCESS)
fatal (”uinsor”);
if (uinfscn (txid,scaninf,&prjvall,&status) != USUCCESS)
fatal (”uinfscn”);
/* define sort criteria */
if (uinssrt (txid, scaninf, $SQL_books.nvntry.nv_description$,
DB_ASCEND, &status) != USUCCESS)
fatal (”uinssrt”);
/* begin scan */
if (ubegscn (txid,USLCK,scaninf,&scanid,&status) != USUCCESS)
fatal (”ubegscn”);
Appendix A: Examples
521
/* retrieve access method type */
if (uinfacs (scanid, &acsinf, &status) != USUCCESS)
fatal (”uinfacs”);
else
printf (”Scan using : ”);
switch(acsinf.acsknd)
{
case USQSCN:
printf (”sequential access.\n”);
break;
case UBTSCN:
printf (”btree access.\n”);
break;
case UDKSCN:
printf (”direct access.\n”);
break;
case UHKSCN:
printf (”hash–key access.\n”);
break;
case ULKSCN:
printf (”link access.\n”);
break;
case UNULLSCN:
printf (”scan not initialized.\n”);
break;
default: printf (”undefined return from infacs.\n”);
}
while (ufchscn(scanid,&rid,prjvall,&prevlck,statusl,&status)
== USUCCESS)
printf (”%d | %s \n”, *(prjvall[0].unip.hintp),
prjvall[1].unip.strp);
if (status != UEEOSCN)
fatal (”ufchscn”);
if (uendscn (scanid,&status) != USUCCESS)
fatal (”uendscn”);
if (ufrescn (txid,&scaninf,DB_RESET,&status) != USUCCESS)
fatal (”ufrescn”);
if (ucmttx (txid,&status) != USUCCESS)
fatal (”ucmttx”);
if (uclsdb (dbid,DB_NORMAL,&status) != USUCCESS)
fatal (”uclsdb”);
uexit (0);
}
522
Appendix A: Examples
/* Since these buffers probably only need to be set up once,
no matter how often you do the query, it is best to initialize
them in some function once, and if possible call it only once.
This will save runtime CPU time.
*/
init_dbvall()
{
search_dbv[0].unip.hintp = &a1;
search_dbv[0].valopts = UNORMAL;
search_dbv[1].unip.hintp = &a2;
search_dbv[1].valopts = UNORMAL;
search_dbv[2].unip.strp = b1;
search_dbv[2].valopts = UNORMAL;
search_dbv[3].unip.strp = b2;
search_dbv[3].valopts = UNORMAL
nulldbv = (UDBVAL *) 0L;
}
/* The actual query is set up in terms of variables, not
constants.So the query reads: select nv_number,nv_description where
nv_number between a1 and a2
and (nv_description = b1 or nv_description = b2) ;
*/
init_criteria()
{
a1 = 5000;
a2 = 5100;
strcpy (b1,”Bookcase, Steel”);
strcpy (b2,”Bookends, oak”);
}
/* A simple error routine */
fatal (fn)
char *fn;
{
char
*errmsg;
USTATUS
fchstats;
printf (”An error occurred in %s;”, fn);
if ((errmsg = ufchmsg(status, &fchstats)) == (char *) 0)
printf (”error fetching message: %ld\n”, fchstats);
else
printf (”error is %s \n”, errmsg);
uexit(99);
}
Appendix A: Examples
523
An Ordered Access
The following example uses all ordered access functions ufchord,
uendord, uposord, and uskrord. ubegtx, uclsdb, ucmttx, and uopndb
are also called.
#include
#include
<rhli.h>
<rhlierr.h>
main(argc, argv)
int argc;
char **argv;
{
/* define required parameters */
UTXID
txid;
/* Transaction ID
UTID
tid;
/* Table ID
URID
rid;
/* Row ID
UOACCID
oaccid;
/* Order Access ID
UOACOLS
UNIPEXT
UNIPCOLL
UCID
UDBVAL
UTP_HINT
*/
URID
UDBVAL
USTATUS
USTATUS
ord_list[2]; /* column sort order list
unipext[3];
unipcoll;
cidl[3];
/* list of Column IDs
dbvall[3];
/* list of column values
maxsalesrep = 0; /* maximum company salesrep
*/
svrid = 0;
keyvall[2];
statusl[3];
status;
*/
/* Define
char
char
ETP_HINT
external and internal data types */
extaddress2[30];
extaddress1[30];
extsalesrep;
char
char
UTP_HINT
intaddress2[30];
intaddress1[30];
intsalesrep;
char
UTXOPT
UDBID
/* save area for Row ID
*/
*/
/* status value list
*/
/* status returned by RHLI functions */
*dbname;
txopt;
dbid;
/* Set up for ordered
ord_list[0].oacid
=
ord_list[0].oacopts =
ord_list[1].oacid
=
ord_list[1].oacopts =
524
*/
*/
*/
*/
access on the address */
$SQL_books.company.co_address_2$;
DB_ASCEND;
$SQL_books.company.co_address_1$;
DB_ASCEND;
Appendix A: Examples
dbname = ”file.db”;
if ( uopndb ( dbname, DB_NORMAL, &dbid, &status) != USUCCESS )
{
printf (”unable to open the database; ”);
uexit(1);
}
else
printf (”Database is open.\n”);
/* begin a transaction */
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
if (ubegtx (dbid, UROOTTXID, &txid, &txopt, &status)
!= USUCCESS )
{
printf (”unable to begin a transaction; ”);
uexit(1);
}
else
printf (”Transaction has begun. The transaction ID is:%ld\n”,
txid);
/* Begin ordered access on table company */
if ( ubegord (txid, $SQL_books.company.$, 2, ord_list, &oaccid,
statusl, &status) != USUCCESS )
{
printf(”ubegord failed. \n”);
uexit(1);
}
/* Position to second half of the alphabet */
keyvall[0].unip.strp = ”M”;
keyvall[1].unip.strp = ”A”;
if ( uposord (txid, oaccid, UGETST, keyvall, USLCK, &rid, statusl,
&status) != USUCCESS )
{
printf(”uposord failed. \n”);
uexit(1);
}
/* Initialize UNIPCOLL structure components */
unipcoll.ncol = 3;
unipcoll.cidl = cidl;
unipcoll.dbvall = dbvall;
/* Initialize (at compile–time) Column IDs list */
cidl[0] = $SQL_books.company.co_address_2$;
cidl[1] = $SQL_books.company.co_address_1$;
cidl[2] = $SQL_books.company.co_sales_rep$;
Appendix A: Examples
525
/* Define the internal–format buffer addresses */
dbvall[0].unip.strp = intaddress2;
dbvall[1].unip.strp = intaddress1;
dbvall[2].unip.hintp = &intsalesrep;
dbvall[0].valopts = UNORMAL;
dbvall[1].valopts = UNORMAL;
dbvall[2].valopts = UNORMAL;
/* Read each row looking for highest salesrep */
while ( ufchord(txid, oaccid, UNEXT, USLCK, &rid, &unipcoll,
statusl, &status) != UFAILURE )
{
if ( intsalesrep > maxsalesrep )
{
maxsalesrep = intsalesrep;
svrid = rid;
}
/* Reset valopts for next fetch */
unipcoll.dbvall[0].valopts = UNORMAL;
unipcoll.dbvall[1].valopts = UNORMAL;
unipcoll.dbvall[2].valopts = UNORMAL;
}
/* Error if other than end of file was returned */
if ( status != UEEOSCN )
{
printf(”ufchord failed. \n”);
uexit(1);
}
/* Seek row with highest salesrep */
if ( uskrord (txid, oaccid, USLCK, svrid, &status) != USUCCESS )
{
printf(”uskrord failed. \n”);
uexit(1);
}
/* Now fetch the address of the company and its salesrep */
if ( ufchord(txid, oaccid, USAME, &rid, &unipcoll, USLCK, statusl,
&status) != USUCCESS )
{
printf(”ufchord failed. \n”);
uexit(1);
}
/* Define the external–format buffer addresses */
unipext[0].univ.strp = extaddress2;
unipext[1].univ.strp = extaddress1;
unipext[2].univ.hintp = &extsalesrep;
/* Display external–format data */
printf(”Highest salesrep in M through Z locates at:\n %s\n%s\n”,
extaddress1, extaddress2);
printf(” with a salesrep of %ld\n”, extsalesrep);
526
Appendix A: Examples
/* End the ordered access and release resources */
if ( uendord (oaccid, &status) != USUCCESS )
{
printf(”uendord failed \n”);
uexit(1);
}
/* end the transaction */
if ( ucmttx (txid, &status) != USUCCESS )
{
printf (”unable to end transaction \n ”);
uexit(1);
}
else
printf (”Transaction is committed.\n”);
/* close the database */
if ( uclsdb(dbid, DB_NORMAL, &status) != USUCCESS )
{
printf (”unable to close the database \n ”);
uexit(1);
}
else
printf (”Database is closed.\n”);
}
Appendix A: Examples
527
Name Binding
This example performs name binding with the following function calls
involved: ubegtx, ubndath, ubndtbl, uclsdb, ucmttx, ufchath,
ufchmsg, ulogmsg, and uopndb.
#include <rhli.h>
#include <rhlierr.h>
main(argc, argv)
int argc;
char **argv;
{
USTATUS status;
USTATUS fstatus;
USTATUS statusl[3];
USTATUS lstats;
UDBID dbid;
char *dbname = ”file.db”;
UTXID txid;
UTXID *txl;
UTXOPT txopt;
UTXID *txidl;
UTXINF *txinfl;
int nauth;
char *authnml;
int ntbl = 3;
int i;
char * tblnml[3];
UTID *tidl[3];
UAID aid;
char * db_name;
DBUSER *dbuser;
int nuser;
char *errmsg;
528
Appendix A: Examples
/* open the database */
if ( uopndb ( dbname, DB_NORMAL, &dbid, &status) != USUCCESS )
{
printf (”unable to open the database; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
if (ulogmsg(”uopndb”, status, ”Opening database DB_NORMAL”,
&lstats) != USUCCESS)
{
printf (”error logging message; ”);
if ((errmsg = ufchmsg(lstats, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
}
else
printf (”Database is open.\n”);
/* begin a transaction */
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
if (
ubegtx (dbid, UROOTTXID, &txid, &txopt, &status)
!= USUCCESS )
{
printf (”unable to begin a transaction; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
else
printf (”Transaction has begun. The transaction ID is:%d\n”,
txid);
Appendix A: Examples
529
authnml = ”SQL_books”;
if ( ubndath(txid, 1, &authnml, USLCK, &aid, statusl,
&status) != USUCCESS )
{
printf(”Unable to get Auth.ID by name: status = %ld\n”, status);
uexit(1);
}
/* aid = UNULLAID; */
/* set schema to SQL_books */
if (ufchath(txid, aid, &status) != USUCCESS) {
printf(”Unable to change current schema.\n”);
uexit(1);
}
/* bind the table names to IDs */
tblnml[0] = ”company”;
tblnml[1] = ”orders”;
tblnml[2] = ”nvntry”;
if (ubndtbl(txid, aid, ntbl, tblnml, USLCK, tidl, statusl,
&status) != USUCCESS)
{
printf (”Unable to get tables ids; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
for (i = 0; i < ntbl; ++i)
printf (”The table ID is : %ld\n”, tidl[i]);
/* end the transaction */
if ( ucmttx (txid, &status) != USUCCESS )
{
printf (”unable to end transaction, ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
else
printf (”Transaction is committed.\n”);
530
Appendix A: Examples
/* close the database */
if ( uclsdb(dbid, DB_NORMAL, &status) != USUCCESS )
{
printf (”unable to close the database; ”);
if ((errmsg = ufchmsg(status, &fstatus)) == (char *) 0)
{
printf(”error %ld fetching message \n”, fstatus);
uexit(1);
}
else
{
printf(”error is %s \n”, errmsg);
uexit(1);
};
}
else
printf (”Database is closed.\n”);
}
Appendix A: Examples
531
ID Mapping
The following example uses the functions umapath, umapcol, and
umaptbl to map compile-time IDs to their runtime equivalents.
#define NATH 4
/* # of schemas in the database */
/* define required parameters */
USTATUS statusl[NATH]; /* schema status list */
USTATUS status;
/* function status */
UDBID dbid;
/* database ID */
UATHMAP uathmap[NATH]; /* schema mapping structure */
...
/* re-map compile-time Authorization IDs –> runtime IDs */
INIATHMAP(manf_schema, aidl[1], &uathmap[0]);
INIATHMAP(model_schema, aidl[2], &uathmap[1]);
INIATHMAP(item_schema, aidl[3], &uathmap[2]);
if (umapath(dbid, 3, uathmap, statusl, &status) != USUCCESS)
{
printf(”Auth. ID re-mapping error: status=%ld\n”, status);
uexit(99);
}
The following example uses the umapcol function to map a compile-time
ID to its runtime equivalent.
#define NCOL 3
#define NCOLMAP 3
#define NTBLMAP 2
/* define required parameters */
UTXID txid;
/* Transaction ID */
USTATUS
status;
/* function status */
...
/* define umapcok requirements */
UCOLMAP
colmapl[NCOLMAP]; /* column mapping structure */
USTATUS
cmapstl[NCOLMAP]; /* column status value list */
...
/* re-map compile-time Column IDs –> runtime IDs */
INICOLMAP(sales.revenues.cust_name,
$(UCOL:CID)sales.revenues.cust_name$,
&colmapl[0]);
INICOLMAP(sales.revenues.cust_id,
$(UCOL:CID)sales.revenues.cust_id$,
&colmapl[1]);
INICOLMAP(sales.revenues.sale_date,
$(UCOL:CID)sales.revenues.sale_date$,
&colmapl[2]);
532
Appendix A: Examples
if (umapcol(dbid, NCOLMAP, colmapl, cmapstl, &status) != USUCCESS)
{
printf(“Unable to re-map Column ID: status = %ld\n”,
status);
uexit(101);
}
/* re-map compile-time Table IDs –> runtime IDs */
INITBLMAP(sales.commissions, $(UTBL:TID)sales.commissions$,
&tblmapl[0]);
INITBLMAP(sales.revenues, $(UTBL:TID)sales.revenues$,
&tblmapl[1]);
if (umaptbl(dbid, NTBLMAP, tblmapl, tmapstl, &status) != USUCCESS)
{
printf(“Unable to re-map Table ID: status = %ld\n”, status);
uexit(101);
}
Appendix A: Examples
533
Transaction Journaling
This example uses the journaling functions uclsjrn, ufchjrn, and
uopnjrn to manipulate the journal file.
/* define required parameters */
char
*dbname = “”; /* use DBPATH */
int
jrnfd;
/* returned journal file descriptor */
long
seqn;
/* sequence number */
UJRNINF
jrninfo;
/* journal oper info structure */
USTATUS
status; /* status returned by uxxxjrn */
USTATUS
fchstat;
/* status returned by ufchmsg */
/* open journal file */
if (uopnjrn(dbname, “/usr/user/linda/db/file.jn”, &jrnfd, &seqn,
&status) != USUCCESS)
{
printf ( “uopnjrn failed: \n”);
uexit( 1 );
}
/* fetch journal information */
while ( ufchjrn ( jrnfd, &jrninfo, &status ) == USUCCESS)
{
switch ( jrninfo.opknd )
{
case UINSOPR:
printf (“Insert to table %ld by user %ld\n”,jrninfo.tid,
jrninfo.ids.uid );
free ( jrninfo.txinfo.insert.newucol );
break;
case UUPDOPR:
printf (“Update to table %ld by user%ld\n”,
jrninfo.tid,jrninfo.ids.uid );
free ( jrninfo.txinfo.update.newucol );
free ( jrninfo.txinfo.update.olducol ); break;
case UDELOPR:
printf (“Delete to table %ld by user,%ld\n”,
jrninfo.tid, jrninfo.ids.uid );
free ( jrninfo.txinfo.delete.olducol );
break;
}
}
534
Appendix A: Examples
if ( status != UENORM && status != UEJNEOTP )
{
printf (”ufchjrn() failed: \n”);
uexit( 1 );
}
/* close journal files */
if ( uclsjrn(jrnfd, &status) == UFAILURE )
{
printf (“uclsjrn() failed: \n”);
uexit( 1 );
}
Appendix A: Examples
535
DDL
This example creates a table named member.
The RHLI functions used are uaddtbl, ubegtx, ubndbt, uclsdb, ucmttx,
udrpbt, and uopndb.
#include <rhli.h>
#include <rhlierr.h>
UDBID dbid;
UTXID txid;
USTATUS status;
USTATUS statusl[4];
UTXOPT txopt;
DBCOL
dbcoll[4];
DBTABLE dbtablel[1];
int
i;
main(argc, argv)
int argc;
char **argv;
{
/* open the database */
if (uopndb ((char *) 0,DB_NORMAL,&dbid,&status) != USUCCESS)
fatal (”uopndb”, status);
printf(”Database opened.\n”);
/* begin a transaction */
txopt.txknd = UTXTYPE2;
txopt.waitflg = UWAIT;
if (ubegtx (dbid,UROOTTXID,&txid,&txopt,&status) != USUCCESS)
fatal (”ubegtx”, status);
printf(”Transaction begun.\n”);
/* add a table */
dbcoll[0].coltyp = U_INT;
dbcoll[0].collen = UIL_INT;
dbcoll[0].colscl = 0;
dbcoll[0].dsplen = UDL_INT;
dbcoll[0].dspscl = 0;
dbcoll[0].colopts = DB_NORMAL;
dbcoll[0].colnm = ”mem_id”;
dbcoll[0].coldesc = (char *) 0;
dbcoll[0].dsppict = (char *) 0;
dbcoll[1].coltyp = U_STR;
dbcoll[1].collen = 20;
536
Appendix A: Examples
dbcoll[1].colscl = 0;
dbcoll[1].dsplen = 20;
dbcoll[1].dspscl = 0;
dbcoll[1].colopts = DB_NONULL;
dbcoll[1].colnm = ”mem_name”;
dbcoll[1].coldesc = (char *) 0;
dbcoll[1].dsppict = (char *) 0;
dbcoll[2].coltyp = U_AMT;
dbcoll[2].collen = 9;
dbcoll[2].colscl = 2;
dbcoll[2].dsplen = 9;
dbcoll[2].dspscl = 0;
dbcoll[2].colopts = DB_NORMAL;
dbcoll[2].colnm = ”mem_sal”;
dbcoll[2].coldesc = (char *) 0;
dbcoll[2].dsppict = (char *) 0;
dbcoll[3].coltyp = U_HDATE;
dbcoll[3].collen = 0;
dbcoll[3].colscl = 0;
dbcoll[3].dsplen = 10;
dbcoll[3].dspscl = 0;
dbcoll[3].colopts = DB_NONULL;
dbcoll[3].colnm = ”mem_date”;
dbcoll[3].coldesc = (char *) 0;
dbcoll[3].dsppict = (char *) 0;
dbtablel[0].dbcol = dbcoll;
dbtablel[0].vid = UNULLVID;
dbtablel[0].segsz = 0L;
dbtablel[0].expnum = 1000;
dbtablel[0].statusl = statusl;
dbtablel[0].tblopts = DB_NORMAL;
dbtablel[0].ncol = 4;
dbtablel[0].tblnm = ”member”;
dbtablel[0].tbldesc = (char *) 0;
if (uaddtbl(txid, 1, dbtablel, statusl, &status) != USUCCESS)
{
for (i=0; i<4; i++)
printf(”Column %d status: %ld\n”, i, statusl[i]);
fatal (”uaddtbl”, status);
}
printf(”Table added. \n”);
/* commit the transaction and close the database */
if (ucmttx (txid, &status) != USUCCESS)
fatal (”ucmttx”, status);
printf(”Transaction committed.\n”);
if (uclsdb (dbid,DB_NORMAL, &status) != USUCCESS)
fatal (”uclsdb”, status);
printf(”Database closed.\n”);
uexit (0);
}
Appendix A: Examples
537
/* A simple error routine that prints out the function name and
the errorstatus of the last RHLI call that failed, and exit */
fatal (fctname, status)
char * fctname;
USTATUS status;
{
int i;
printf (”Fatal error on %s;”, fctname);
printf (”status is %d\n”, status);
uexit(1);
}
The following example drops two B-tree indexes.
/* allocate storage for the B-tree and status list */
bidl = (UBTID *)calloc(2, sizeof(UBTID));
statusl = (USTATUS *)calloc(2, sizeof(USTATUS));
...
/* bind the B-tree named ’part_number’ */
ubndbt(txid, $parts$, 1, ”part_number”, USLCK, &bidl[0],
&statusl[0], &status);
...
/* bind to the B-tree named ’ord_number’ */
ubndbt(txid, $parts$, 1, ”ord_number”, USLCK, &bidl[1],
&statusl[1], &status);
...
/* drop both B-trees */
if ( udrpbt(txid, 2, bidl, statusl, &status) != USUCCES)
{
fprintf(stderr,
”B-trees could not be dropped: status=%ld\n”,
status);
}
538
Appendix A: Examples
Text Conversion
This example uses the uextint function to convert data values before they
are inserted into a row by calling uinsrow.
#define NCOL 3
/* define external data types
ETP_INT
extpnum;
/*
ETP_STRP
extpnam[80];
/*
ETP_DATE
extpdat;
/*
*/
external–format part number */
external–format part name */
external–format part date */
/* define internal data types
UTP_INT
intpnum;
/*
char
intpnam[80];
/*
UTP_DATE
intpdat;
/*
*/
internal–format part number */
internal–format part name */
internal–format part date */
/* define RHLI interface required parameters */
URID
rid;
USTATUS
status;
USTATUS
statusl[NCOL];
UTXID
UNIPCOLL
UNIPEXT
UCID
UDBVAL
txid;
unipcoll;
unipext[NCOL];
cidl[NCOL];
dbvall[NCOL];
/* initialize UNIPCOLL structure components */
unipcoll.ncol = NCOL;
unipcoll.cidl = cidl;
unipcoll.dbvall = dbvall;
/* initialize (at compile–time) Column IDs list */
cidl[0] = $parts.part_name$;
cidl[1] = $parts.part_number$;
cidl[2] = $parts.part_date$;
/* define the internal–format buffer addresses */
dbvall[0].unip.strp = intpnam;
dbvall[1].unip.intp = &intpnum;
dbvall[2].unip.datep = &intpdat;
/* define the external–format buffer address */
unipext[0].univ.strp = extpnam;
unipext[0].valopts = UNORMAL;
Appendix A: Examples
539
unipext[1].univ.intp = &extpnum;
unipext[1].valopts = UNORMAL;
unipext[2].univ.datep = &extpdat;
unipext[2].valopts = UNORMAL;
/* define the external data values to be converted to internal
format */
sprintf(extpnam, ”Ronnieco %s”, ”Wedg–o–matic”);
extpnum = 1995;
extpdat.month = 12;
/* manufacture month */
extpdat.day
= 31;
/* manufacture day */
extpdat.year = 1987;
/* manufacture year */
/* this assumes the database is open & a transaction begun */
if (uextint(txid, $parts.$, unipext, &unipcoll, statusl,
&status) != USUCCESS)
{
printf(”data conversion failed: %ld\n”, status);
uexit(100);
}
/* insert the data into the database */
if (uinsrow(txid, $parts.$, &rid, &unipcoll, statusl,
&status) != USUCCESS)
{
printf(”data insertion failed: %ld\n”, status);
uexit(101);
}
The next example calls ufchrow to retrieve a row from a database table,
and uses the uintext function to convert data from internal format to
external format.
#define
NCOL
3
/* define external data types */
ETP_INT
extpnum;
/* external–format part number */
char
extpnam[80]; /* external–format part name */
ETP_DATE
extpdat;
/* external–format part date */
...
/* define internal data types */
UTP_INT
intpnum;
/* internal–format part number */
char
intpnam[80]; /* internal–format part name */
UTP_DATE
intpdat;
/* internal–format part date */
...
/* define required parameters */
UTXID
txid;
URID
rid;
USTATUS
status;
USTATUS
statusl[NCOL];
UNIPCOLL
unipcoll;
UNIPEXT
unipext[NCOL];
UCID
cidl[NCOL];
UDBVAL
dbvall[NCOL];
540
Appendix A: Examples
/* initialize UNIPCOLL structure components */
unipcoll.ncol = NCOL;
unipcoll.cidl = cidl;
unipcoll.dbvall = dbvall;
...
/* initialize (at compile–time) Column IDs list */
cidl[0] = $parts.part_name$;
cidl[1] = $parts.part_number$;
cidl[2] = $parts.part_date$;
...
/* define the internal–format buffer addresses */
dbvall[0].unip.strp = intpnam;
dbvall[0].valopts = UNORMAL;
dbvall[1].unip.intp = &intpnum;
dbvall[1].valopts = UNORMAL;
dbvall[2].unip.datep = &intpdat;
dbvall[2].valopts = UNORMAL;
...
/* define the external–format buffer address */
unipext[0].univ.strp = extpnam;
unipext[1].univ.intp = &extpnum;
unipext[2].univ.datep = &extpdat;
/* retrieve the internal–format data from the database */
if (ufchrow(txid, $parts.$, USLCK, rid, &unipcoll, statusl,
&status) != USUCCESS)
{
printf(”data retrieval failed: %ld\n”, status);
uexit(101);
}
...
/* convert the internal format data to external format */
if (uintext(txid, $parts.$, &unipcoll, &unipext, statusl,
&status) != USUCCESS)
{
printf(”data conversion failed: %ld\n”, status);
uexit(100);
}
/* now display the external–format data */
printf(”part–number: %d\n”, extpnum);
printf(”part–name:
%s\n”, extpnam);
printf(”part–date:
%02d/%02d/%02d\n”,
extpdat.month, extpdat.day, extpdat.year);
Appendix A: Examples
541
XML example
This example uses the XML processing RHLI functions to parse an XML
file. The XML file could be the result a previous select operation that
specified the AS XML clause or it could be from another source.
#include <stdio.h>
#include <def/globdefs.h>
#include <def/rhli.h>
#include <def/uXML.h>
int main(int argc,char* argv[])
{
const char *xmlFile = ”person.xml”;
xml_obj xmlObj = 0;
int
count;
char** attributeNames = 0;
char** attributeValues = 0;
int
result = 0;
char* attributeValue;
char* elementValue;
USTATUS xmlStatus;
char* elementName = 0;
if ( ! uXMLParse(&xmlObj, &xmlStatus, xmlFile) )
{
printf(”Error opening or parsing file ’%s’ error code=%d\n”,
xmlFile, xmlStatus);
exit(1);
}
542
Appendix A: Examples
if( ! uXMLMoveToRootElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToRootElement”, xmlStatus);
uXMLDestroy(&xmlObj, &xmlStatus);
exit(1);
}
/*
* The current element cursor now points to root element.
*/
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
printf(”\n name of root element = %s \n”, elementName);
free(elementName);
}
if ( ! uXMLMoveToFirstChild(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToFirstChild”, xmlStatus);
}
/*
* The current element cursor now points to first child of root element.
*/
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
printf(”\n name of first child =%s \n”, elementName);
free(elementName);
}
Appendix A: Examples
543
if ( ! uXMLGetAttributeNames(xmlObj, &xmlStatus, &attributeNames) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeNames”, xmlStatus);
}
else
{
/*
* The variable ”attributeNames” contains attribute names of
* current element i.e. ”name”, The variable attributeNames will
* contain ”surname, fathername”
*/
char ** name = attributeNames;
printf(”\nThe attribute names are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeNames);
attributeNames = 0;
}
if ( ! uXMLGetAttributeValues(xmlObj, &xmlStatus, &attributeValues) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeValues”, xmlStatus);
}
else
{
/*
* The variable ”attributeValues” conatins attribute values of
* current element i.e. ”name”, the varibale attributeValues
* will contain ”anderson, mike”.
*/
char ** name = attributeValues;
printf(”\n the attribute values are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeValues);
attributeValues = 0;
}
544
Appendix A: Examples
/* Get attribute count of an element */
if ( ! uXMLGetAttributeCount(xmlObj, &xmlStatus, &count) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeCount”, xmlStatus);
}
else
{
/* The variable ”count” should contain value 2 */
printf(”\n number of attributes are :%d ”, count);
}
if ( ! uXMLAddAttribute(xmlObj, &xmlStatus, ”mothername”, ”Maria”) )
{
printf(”Error in %s error code=%d\n”, ”uXMLAddAttribute”, xmlStatus);
}
if ( ! uXMLGetAttributeNames(xmlObj, &xmlStatus, &attributeNames) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeNames”, xmlStatus);
}
else
{
/*
* THE VARIABLE ”attributeNames” CONATINS ATTRIBUTE NAMES OF
* CURRENT ELEMENT i.e. ”name”, THE VARIBALE ”attributeNames” WILL
* CONTAIN ”surname, fathername, mothername”
*/
char ** name = attributeNames;
printf(”\nThe attribute names are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeNames);
attributeNames = 0;
}
if ( ! uXMLMoveToNextSibling(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToNextSibling”, xmlStatus);
}
Appendix A: Examples
545
/* THE CURRENT ELEMENT CURSOR NOW POINTS TO NEXT SIBLING i.e.”age” */
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
/* THE TAG NAME OF CURRENT ELEMENT i.e. ”age” */
printf(”\n the next sibling is= %s \n”, elementName);
free(elementName);
}
/* DELETE THE VALUE OF CURRENT ELEMENT i.e. ”age”
DELETES THE VALUE OF CURRENT ELEMENT i.e. 20 */
if ( ! uXMLDeleteCurrentElementValue(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLDeleteCurrentElementValue”, xmlStatus);
}
if ( ! uXMLMoveToParentElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToParentElement”, xmlStatus);
}
if ( ! uXMLMoveToLastChild(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToLastChild”, xmlStatus);
}
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
printf(”\n name of last child = %s \n”, elementName);
free(elementName);
}
/* THE VALUE OF CURRENT ELEMENT i.e. ”me” IS ”john” */
if ( ! uXMLGetValueOfCurrentElement(xmlObj, &xmlStatus, &elementValue) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetValueOfCurrentElement”, xmlStatus);
}
else
{
printf(”\n the value of current element is = %s \n”, elementValue);
free(elementValue);
}
546
Appendix A: Examples
/* MODIFY THE VALUE OF CURRENBT ELEMENT i.e. ”me” FROM ”john”
TO ”Joseph”
*/
if ( ! uXMLModifyElementValue(xmlObj, &xmlStatus, ”Joseph”) )
{
printf(”Error in %s error code=%d\n”,
”uXMLModifyElementValue”, xmlStatus);
}
if ( ! uXMLGetValueOfCurrentElement(xmlObj, &xmlStatus, &elementValue) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetValueOfCurrentElement”, xmlStatus);
}
else
{
printf(”\n the new value is = %s \n”, elementValue);
free(elementValue);
}
if ( ! uXMLMoveToPreviousSibling(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToPreviousSibling”, xmlStatus);
}
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
/* THE CURRENT ELEMENT CURSOR NOW POINTS TO PreviousSIBLING i.e.”age” */
printf(”\n the previous sibling is = %s \n”, elementName);
free(elementName);
}
if ( ! uXMLMoveToNextSibling(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToNextSibling”, xmlStatus);
}
if ( ! uXMLMoveToParentElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToParentElement”, xmlStatus);
}
Appendix A: Examples
547
/*
* THE CURRENT ELEMENT CURSOR NOW POINTS TO PARENT ELEMENT
* i.e. person
*/
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
printf(”\n The parent element is = %s \n”, elementName);
free(elementName);
}
if ( ! uXMLMoveToFirstChild(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToFirstChild”, xmlStatus);
}
/* THE CURRENT ELEMENT CURSOR IS AT <name> TAG, THE VARIABLE
”attributeValue” will contain the value OF ATTRIBUTE
”fathername” i.e. ”mike”
*/
if ( ! uXMLGetAttributeValue(xmlObj, &xmlStatus,
”fathername”, &attributeValue) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeValue”, xmlStatus);
}
else
{
printf(”\n the attribute value is = %s \n”, attributeValue);
free(attributeValue);
}
/* TO DELETE AN ATTRIBUTE */
if ( ! uXMLDeleteAttribute(xmlObj, &xmlStatus,”mothername”) )
{
printf(”Error in %s error code=%d\n”,
”uXMLDeleteAttribute”, xmlStatus);
}
if ( ! uXMLDeleteAttribute(xmlObj, &xmlStatus, ”fathername”) )
{
printf(”Error in %s error code=%d\n”,
”uXMLDeleteAttribute”, xmlStatus);
}
548
Appendix A: Examples
if ( ! uXMLGetAttributeNames(xmlObj, &xmlStatus, &attributeNames) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeNames”, xmlStatus);
}
else
{
/* THE VARIABLE ”attributeNames” CONATINS ATTRIBUTE NAMES OF CURRENT
ELEMENT i.e. ”name”, THE VARIBALE attributeNames WILL CONTAIN
”surname”
*/
char ** name = attributeNames;
printf(”\nThe attribute names are:\n”);
for( ; *name != NIL(char); ++name )
{
printf(”\t%s\n”, *name);
free(*name);
}
free(attributeNames);
attributeNames = 0;
}
/* CHECKED TO SET ATTRIBUTE VALUE */
if ( ! uXMLSetAttributeValue(xmlObj, &xmlStatus, ”surname”, ”Sanderson”))
{
printf(”Error in %s error code=%d\n”,
”uXMLSetAttributeValue”, xmlStatus);
}
/* THE NEW ATTRIBUTE VALUE */
if ( ! uXMLGetAttributeValue(xmlObj, &xmlStatus, ”surname”, &attributeValue))
{
printf(”Error in %s error code=%d\n”,
”uXMLGetAttributeValue”, xmlStatus);
}
else
{
printf(”\n the attribute value is = %s \n”, attributeValue);
free(attributeValue);
}
if ( ! uXMLMoveToParentElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToParentElement”, xmlStatus);
}
/* CREATE ELEMENT country=’USA’ */
if ( ! uXMLCreateElement(xmlObj, &xmlStatus, ”country”, ”USA”) )
{
printf(”Error in %s error code=%d\n”,
”uXMLCreateElement”, xmlStatus);
}
Appendix A: Examples
549
/* THE CURRENT ELEMENT CURSOR POINTS TO TAG ”country” */
if ( ! uXMLGetCurrentElementName(xmlObj, &xmlStatus, &elementName) )
{
printf(”Error in %s error code=%d\n”,
”uXMLGetCurrentElementName”, xmlStatus);
}
else
{
/* THE TAG NAME OF CURRENT ELEMENT i.e. ”country” */
printf(”\n name of last child = %s \n”, elementName);
free(elementName);
}
if ( ! uXMLMoveToParentElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToParentElement”, xmlStatus);
}
if ( ! uXMLMoveToFirstChild(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLMoveToFirstChild”, xmlStatus);
}
if ( ! uXMLDeleteCurrentElement(xmlObj, &xmlStatus) )
{
printf(”Error in %s error code=%d\n”,
”uXMLDeleteCurrentElement”, xmlStatus);
}
/*DELETES THE CURRENT ELEMENT,
POINTS TO ”person” */
THE CURRENT ELEMENT CURSOR NOW
uXMLDestroy(&xmlObj, &xmlStatus);
exit(0);
}
550
Appendix A: Examples